feat: add commission settlement workflow

docs/refactor/taro-frontend-integration.md

@@ -162,6 +162,7 @@ tenant:<tenantId>:theme
 | 学习排行榜 | `GET /api/learning/leaderboard?metric=questions&period=all` |
 | 题目视频 | `GET /api/questions/{questionId}/videos`、`POST /api/questions/videos/batch`、`POST /api/videos/play` |
 | 题目反馈 | `POST /api/profile/feedbacks`、`GET /api/profile/feedbacks` |
+| 分佣结算 | `GET /api/commission/settings`、`PUT /api/commission/settings`、`PUT /api/commission/member-rate`、`GET /api/commission/summary`、`GET /api/commission/orders`、`GET /api/commission/settlements`、`POST /api/commission/settlements/generate`、`POST /api/commission/settlements/status` |
 | 背单词 | `/api/catalog/vocabulary-units`、`/api/catalog/vocabulary-words` |
 | 单词进度/计划 | `/api/learning/vocabulary/progress`、`/api/learning/vocabulary/stats`、`/api/learning/vocabulary/review-plan`、`POST /api/learning/vocabulary/review` |
 | 单词收藏 | `/api/learning/vocabulary/favorites` |
@@ -395,6 +396,57 @@ GET /api/tenant-admin/dashboard?timeRange=30d&regionId=<可选地区ID>&limit=10
 - `recentActivities.details` 只包含可展示的低敏汇总信息，不包含手机号、支付密钥、对象存储 key 等敏感字段。
 - 大租户正式上线后会补预聚合 worker，前端不应依赖任何临时 SQL 口径或自己维护缓存口径。
 
+### 销售/代理分佣结算
+
+分佣结算由后端统一计算，前端不要读取订单、激活码或客资后自行算佣金。当前后端已支持订单和激活码两类来源，并且只统计客资首绑保护后的成交，避免后绑抢单。
+
+常用接口：
+
+| 页面/动作 | 接口 | 权限 |
+| --- | --- | --- |
+| 查看租户分佣设置 | `GET /api/commission/settings` | `commission:read` |
+| 修改默认分佣设置 | `PUT /api/commission/settings` | `commission:write` |
+| 设置销售/代理个人比例 | `PUT /api/commission/member-rate` | `commission:write` |
+| 分佣汇总 | `GET /api/commission/summary?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&referrerUserId=...` | `commission:read` 或 `commission:self` |
+| 分佣来源明细 | `GET /api/commission/orders?...` | `commission:read` 或 `commission:self` |
+| 结算单列表 | `GET /api/commission/settlements?...` | `commission:read` 或 `commission:self` |
+| 生成结算单 | `POST /api/commission/settlements/generate` | `commission:write` |
+| 审核/打款状态 | `POST /api/commission/settlements/status` | `commission:review` |
+
+金额字段统一为分：
+
+```text
+grossAmountCents
+commissionAmountCents
+minSettlementCents
+```
+
+比例字段统一为 0 到 1 的数字：
+
+```text
+defaultRate = 0.2
+commissionRate = 0.35
+```
+
+结算状态：
+
+```text
+draft -> pending_review -> approved -> paid
+pending_review -> rejected/cancelled
+approved -> cancelled
+```
+
+前端处理规则：
+
+- 销售/代理默认只有 `commission:self`，只能查看自己的分佣；租户运营/管理员拥有 `commission:read` 才能查看全局。
+- `startDate/endDate` 使用 `YYYY-MM-DD`，后端按 `Asia/Shanghai` 业务日计算账期。
+- 分佣比例优先级由后端处理：激活码批次比例 > 成员个人比例 > 租户默认比例。
+- `sourceType=order` 表示学生订单；`sourceType=activation_code` 表示激活码兑换。
+- 已进入结算单的来源会返回 `settlementId/settlementStatus`，前端不要重复发起生成。
+- 已打款结算单不可再修改状态；遇到 `COMMISSION_SETTLEMENT_LOCKED` 展示“已打款，不可变更”。
+- `COMMISSION_NO_UNSETTLED_SOURCES` 表示当前账期无未结算来源，不是系统异常。
+- 当前版本仅支持线下打款状态登记；真实银行/微信/支付宝打款、导出、发票/凭证和财务复核后续由 worker/provider 增强。
+
 ### 背单词计划与复习上报
 
 背单词页面分三类数据：单元列表、每日计划、单词进度。前端不需要计算下次复习日期，只提交“认识/不认识”，由后端统一更新 `nextReviewDate`、连续正确、掌握状态和每日复习计划。