feat: improve commerce checkout flow

docs/refactor/taro-frontend-integration.md

@@ -168,9 +168,9 @@ tenant:<tenantId>:theme
 | 知识手册 | `/api/catalog/handbook-subjects`、`handbook-chapters`、`handbook-entries` |
 | 分数线 | `/api/scoreline/fields`、`schools`、`majors`、`records`、`trend`、`years` |
 | 资料下载 | `/api/catalog/assets`、`/api/catalog/assets/download` |
-| 商城 | `/api/catalog/svip-plans`、`POST /api/commerce/orders`、`POST /api/commerce/payments/create` |
-| 订单/权益 | `/api/commerce/orders`、`/api/commerce/entitlements` |
-| 激活码兑换 | `POST /api/commerce/activation-codes/redeem` |
+| 商城 | `/api/catalog/svip-plans`、`POST /api/commerce/coupons/claim`、`POST /api/commerce/orders`、`POST /api/commerce/payments/create` |
+| 订单/权益 | `/api/commerce/orders`、`/api/commerce/orders/detail`、`/api/commerce/orders/status`、`/api/commerce/entitlements` |
+| 激活码 | `POST /api/commerce/activation-codes/check`、`POST /api/commerce/activation-codes/redeem` |
 | 个人中心 | `GET/PATCH /api/profile/me`、`POST /api/profile/check-in`、`GET /api/profile/score-events`、`GET /api/profile/exam-countdowns` |
 | 销售分享 | `/api/referral/resolve`、`track-event`、`bind` |
 | 租户班级 | `GET/PUT /api/tenant-admin/classes`、`POST /api/tenant-admin/classes/disable` |
@@ -597,11 +597,28 @@ body: {
   "quantity": 1,
   "payProvider": "wechat_pay | alipay",
   "payMethod": "jsapi | wap",
+  "regionId": "<regionId>",
+  "couponCode": "<可选，优惠券码>",
+  "couponRedemptionId": "<可选，已领取优惠券 redemptionId>"
+}
+```
+
+前端可以先领取优惠券，再下单：
+
+```text
+POST /api/commerce/coupons/claim
+body: {
+  "code": "<couponCode>",
+  "planId": "<svipPlanId>",
   "regionId": "<regionId>"
 }
 ```
 
-返回 `orderNo` 后，再创建支付参数：
+`coupons/claim` 对同一用户同一优惠券是幂等的；已使用的券会返回 `COUPON_ALREADY_USED`。下单时后端会重新计算套餐原价、优惠金额和最终应付，前端展示金额只能使用接口返回的 `originalAmountCents`、`discountCents`、`amountCents`。
+
+如果优惠后 `amountCents=0`，后端会立即把订单置为 `paid` 并发放权益，前端不要再调用 `payments/create`。
+
+返回未支付 `orderNo` 后，再创建支付参数：
 
 ```text
 POST /api/commerce/payments/create
@@ -634,10 +651,36 @@ H5 可以跳转到该 URL。小程序端如果后续要接支付宝小程序，
 支付完成后前端不要自行开通会员。前端应轮询或重新请求：
 
 ```text
-GET /api/commerce/orders
+GET /api/commerce/orders/status?orderNo=<orderNo>
+GET /api/commerce/orders/detail?orderNo=<orderNo>
 GET /api/commerce/entitlements
 ```
 
+订单详情会返回 `pricing`、`payments`、`items`、`couponRedemptions`，可用于收银台、订单详情页和售后排查。订单状态轮询页只需消费 `status/payment`，避免频繁拉取全量明细。
+
+### 激活码预检查与兑换
+
+兑换前建议先调用：
+
+```text
+POST /api/commerce/activation-codes/check
+body: {
+  "code": "<activationCode>",
+  "regionId": "<regionId>"
+}
+```
+
+可根据返回的 `valid/reasonCode/days/regionName/saleType` 展示确认弹窗。常见 `reasonCode`：
+
+```text
+ACTIVATION_CODE_NOT_FOUND
+ACTIVATION_CODE_USED
+ACTIVATION_CODE_SELF_REDEEM_FORBIDDEN
+ACTIVATION_CODE_REGION_MISMATCH
+```
+
+用户确认后再调用 `POST /api/commerce/activation-codes/redeem`。兑换成功后重新请求 `/api/commerce/entitlements` 和个人中心，不要在前端本地伪造会员状态。
+
 后端支付回调地址由租户支付账户配置：
 
 ```text
@@ -649,6 +692,7 @@ GET /api/commerce/entitlements
 
 - 传入自定义金额。
 - 伪造支付成功状态。
+- 调用 `/api/commerce/payments/manual-confirm`；这个接口只给租户后台线下收款/迁移期使用，后端要求 `tenant:payment:write`。
 - 保存商户号私钥、API v3 key、支付宝应用私钥。
 - 在页面里实现 webhook 验签或权益开通。