Codex
31 lines
1.9 KiB
Markdown
31 lines
1.9 KiB
Markdown
# 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 语义错误码。
|