feat(M08-A): 接入权益和余额下单抵扣

2026-06-25 22:39:02 +08:00
parent 3d885852cd
commit dda2b3cbc6
20 changed files with 555 additions and 243 deletions
@@ -9,3 +9,18 @@
  - 鉴权：微信支付平台证书签名和 AES-GCM 资源解密。
  - 行为：按 `out_trade_no` 定位充值单，校验金额，写入 `qipai_payment_callbacks` 幂等记录，成功后给钱包现金/赠送余额入账。
  - 隐私：通知 payload 入库前移除 `payer` 等敏感对象。
+
+## M08-A 权益与余额下单抵扣
+
+- `POST /app-api/orders/reserve`
+  - 新增可选 `benefits` 对象：`couponGrantId`、`packageHoldingId`、`packageMinutes`、`packageCreditCents`、`clientRequestId`。
+  - 行为：只接受权益 ID 和请求幂等号，不接受客户端自报总价；后端按报价、权益规则和剩余量重新计算 `discountCents`、`packageCreditCents` 与订单 `totalCents`。
+  - 返回：保留原订单预占结构，新增 `benefitReservation`，包含冻结状态、抵扣金额、套餐抵扣金额、分钟和使用记录。
+
+- `POST /app-api/payments`
+  - `provider` 继续支持 `WECHAT`、`TEST`，新增顾客端 `BALANCE` 实际扣款闭环。
+  - `BALANCE` 行为：按当前订单应付金额创建支付单，在同一事务内从门店钱包按赠送余额优先、现金余额补足扣款；成功后支付单状态为 `SUCCEEDED`，订单满足金额时推进为 `PAID` 并确认冻结权益。
+  - `WECHAT`/`TEST` 成功路径：支付通知或测试回调成功后统一确认冻结优惠券和套餐；重复通知保持幂等。
+
+- `POST /app-api/orders/:orderId/cancel`
+  - 行为补充：订单取消释放房间预占和访问权限时，同时释放仍处于 `FROZEN` 的优惠券和套餐持有记录。