qipai/docs/api-changelog/2026-08-11-M09-D2-product-orders.md

2026-08-11 M09-D2 商品订单 API

顾客接口

• POST /app-api/product-orders
• GET /app-api/product-orders
• GET /app-api/product-orders/:orderId
• POST /app-api/product-orders/:orderId/cancel

创建请求包含门店、幂等 requestId、履约方式、订单备注和 SKU 数量/备注。服务端从当前目录和门店售价生成不可变快照并复算金额，不接受客户端价格。顾客列表、详情和取消只允许订单本人访问。

管理接口

以下接口同时提供 /admin-api 与 /app-api/management 前缀：

• GET /product-orders?storeId=...
• GET /product-orders/:orderId
• POST /product-orders/:orderId/actions

动作限定为 ACCEPT、START_DELIVERY、MARK_READY、COMPLETE、CANCEL、REFUND，服务端按履约方式和当前状态执行合法转换。读取要求 goods.order.read，写入要求 goods.order.manage；STAFF、STORE_ADMIN 必须在授权门店范围内，租户边界在查询和写事务中重复校验。

支付与退款适配边界

• 非生产且显式启用测试适配器时，注册顾客测试支付创建/完成和管理测试退款完成接口。
• 生产环境不注册任何 test-complete 路由；真实微信支付/退款适配器调用 confirmPayment / confirmRefund 领域入口，并提供 provider callbackId、服务端金额和验签后的脱敏 payload。
• 回调按 provider/callbackId 和 payload 指纹幂等；金额或 provider 不匹配不推进订单。死锁/锁等待冲突由完整事务有限重试，库存、支付、订单和事件保持原子一致。

状态与错误边界

订单状态为 PENDING_PAYMENT、PAID、ACCEPTED、DELIVERING、READY_FOR_SELF_SERVICE、COMPLETED、CANCELLED、REFUNDING、REFUNDED、REFUND_FAILED。未找到返回 404，权限/门店范围返回 403，版本、状态或幂等冲突返回 409，输入、销售关闭、库存或履约前置失败返回 400 语义错误码。