feat(M09-D2): 完成商品订单与库存占用生命周期

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

@@ -0,0 +1,30 @@
+# 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 语义错误码。