feat: add coupon rule reporting

docs/refactor/taro-frontend-integration.md

@@ -565,7 +565,7 @@ POST /api/learning/answers
 推荐流程：
 
 1. `GET /api/catalog/svip-plans` 加载可购买套餐。
-2. 如有优惠券，先调 `POST /api/commerce/coupons/claim`，仅用于领取和展示预计抵扣。
+2. 如有优惠券，先调 `POST /api/commerce/coupons/claim`，仅用于领取、占用一个未核销 redemption 和展示预计抵扣。
 3. 调 `POST /api/commerce/orders` 创建订单，后端会重新计算最终金额和抵扣。
 4. 非零元订单调 `POST /api/commerce/payments/create` 获取支付参数。
 5. H5 支付可跳转 provider 返回的 URL；微信小程序支付用 provider 返回参数调用 `Taro.requestPayment`。
@@ -1745,7 +1745,55 @@ body: {
 }
 ```
 
-`coupons/claim` 对同一用户同一优惠券是幂等的；已使用的券会返回 `COUPON_ALREADY_USED`。下单时后端会重新计算套餐原价、优惠金额和最终应付，前端展示金额只能使用接口返回的 `originalAmountCents`、`discountCents`、`amountCents`。
+`coupons/claim` 对同一用户同一优惠券的未核销记录是幂等的；如果优惠券允许 `perUserLimit > 1`，前一次 redemption 已经下单核销后，用户可以再次领取直到达到限额。已超过单用户限额会返回 `COUPON_ALREADY_USED` 或 `COUPON_USER_LIMIT_REACHED`。下单时后端会重新计算套餐原价、优惠金额和最终应付，前端展示金额只能使用接口返回的 `originalAmountCents`、`discountCents`、`amountCents`。
+
+优惠券规则由后端执行，前端只做展示和提示：
+
+```text
+COUPON_DISABLED                   优惠券已停用或归档
+COUPON_NOT_STARTED                未到开始时间
+COUPON_EXPIRED                    已过期
+COUPON_QUOTA_EXHAUSTED            总库存已用完
+COUPON_PLAN_MISMATCH              不适用当前套餐
+COUPON_REGION_MISMATCH            不适用当前地区
+COUPON_MIN_ORDER_AMOUNT_NOT_MET   未达到最低订单金额
+COUPON_FIRST_ORDER_ONLY           仅限首单
+COUPON_USER_LIMIT_REACHED         已达到单用户可用次数
+```
+
+租户后台优惠券配置字段：
+
+```json
+{
+  "code": "SUMMER80",
+  "planId": "<默认绑定套餐，可选>",
+  "discountType": "fixed | percent",
+  "discountValue": 800,
+  "status": "active | disabled | archived",
+  "campaignName": "暑期活动",
+  "minOrderAmountCents": 3000,
+  "maxDiscountCents": 1000,
+  "perUserLimit": 2,
+  "firstOrderOnly": false,
+  "allowedPlanIds": ["<svipPlanId>"],
+  "allowedRegionIds": ["<regionId>"],
+  "maxUses": 500,
+  "metadata": {
+    "channel": "poster"
+  }
+}
+```
+
+租户后台核销和报表：
+
+```text
+GET /api/tenant-admin/coupons?status=active&campaignName=暑期活动
+GET /api/tenant-admin/coupons/redemptions?couponId=<couponId>&status=used
+GET /api/tenant-admin/coupons/report?startDate=2026-06-01&endDate=2026-06-29&campaignName=暑期活动
+权限：`coupons:read` 可查看配置，`coupons:write` 可维护配置，核销明细和报表需要 `coupons:redemptions:read`
+```
+
+`coupons/report` 返回 `claimCount/usedCount/discountCents/paidAmountCents/conversionRate/byCoupon/byCampaign/daily`。金额均为分，报表只读；前端不要用报表数据反向修改订单、支付、权益或优惠券使用次数。
 
 如果优惠后 `amountCents=0`，后端会立即把订单置为 `paid` 并发放权益，前端不要再调用 `payments/create`。
 
@@ -2376,7 +2424,7 @@ GET /api/ai/school-recommendations/detail?reportId=<reportId>
 - 内容入口/分类树/题目集合/练习蓝图
 - 题目/单词/知识手册/分数线/视频维护
 - 题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 导入 preview/import/issues、字段映射、模板下载和导入后复检
-- Banner/FAQ/公告/激活码/优惠券
+- Banner/FAQ/公告/激活码/优惠券，优惠券后台应接 `GET/PUT /api/tenant-admin/coupons`、`GET /api/tenant-admin/coupons/redemptions`、`GET /api/tenant-admin/coupons/report`，用于配置复杂规则、查看核销明细和活动效果。
 - 勋章：`GET/PUT /api/tenant-admin/badges`、`GET/POST /api/tenant-admin/badge-grants`
 - 考试日期：`GET/PUT /api/tenant-admin/exam-dates`
 - 题目反馈：`GET /api/tenant-admin/feedbacks`、`POST /api/tenant-admin/feedbacks/status`、`GET /api/tenant-admin/feedbacks/events`