feat: add commission settlement workflow

docs/refactor/backend-capability-status.md

@@ -141,7 +141,8 @@
 | 销售统计/客户列表/团队 | 可联调 | `/api/referral/sales-*`、`team` |
 | CRM 配置/队列 | 可联调 | `/api/crm/config`、`/api/crm/queue` |
 | 真实 CRM webhook worker | 待补齐 | 钉钉/飞书/企微发送、签名、重试、死信 |
-| 分佣结算 | 待补齐 | 缺佣金规则、结算单、审核、导出 |
+| 分佣结算基础闭环 | 可联调 | `/api/commission/settings`、`member-rate`、`summary`、`orders`、`settlements`、`settlements/generate`、`settlements/status`；支持订单/激活码归因、批次/成员/默认比例优先级、北京时间账期、结算单生成、审核、打款状态、已打款锁定、销售/代理本人范围和租户隔离 |
+| 分佣打款增强 | 待补齐 | 银行/微信/支付宝真实打款、结算导出、发票/凭证、财务复核和分佣看板 |
 
 ## 内容导入与迁移
 

docs/refactor/backend-progress.md

@@ -12,7 +12,7 @@
   - `scoreline`：分数线字段、院校、专业、记录、趋势、年份。
   - `video`：题目视频讲解、批量预加载、通用视频搜索。
   - `commerce`：订单创建/列表/详情/状态轮询、支付确认、支付 provider/webhook、激活码预检查/兑换、优惠券领取/抵扣、权益查询。
-  - `referral`：销售/代理邀请码、首绑客资保护、销售统计、团队关系、CRM 队列。
+  - `referral`：销售/代理邀请码、首绑客资保护、销售统计、团队关系、CRM 队列、分佣设置、佣金来源汇总、结算单和审核/打款状态。
   - `platform-admin`：平台方租户管理、SaaS 套餐、订阅、账单、服务费收款、使用量。
   - `tenant-admin`：租户资料、品牌、公开设置、域名、支付账户、登录 provider、私密密钥掩码、活动内容、考试日期、题目反馈处理、激活码批次、优惠券、成员管理、角色模板、班级/学生/教师范围权限、权限矩阵、审计查询。
   - `tenant-content`：租户后台内容入口、任意深度分类树、考试意向标记、题目集合、练习蓝图、题目、视频、分数线、单词、知识手册、资料资源、题目/单词/知识手册 JSON 导入维护。
@@ -149,6 +149,14 @@ POST /api/referral/manual-bind
 GET  /api/referral/team
 PUT  /api/referral/team
 POST /api/referral/qrcode
+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
 GET  /api/crm/config
 PUT  /api/crm/config
 GET  /api/crm/queue

docs/refactor/frontend-handoff-index.md

@@ -45,7 +45,7 @@
 - 真实短信、微信登录、QQ 登录、微信支付、支付宝支付 provider 还未正式接完。
 - 对象存储已完成签名 provider，但 PDF 预览、防盗链、视频水印、上传后校验还要补。
 - 大批量 Excel/CSV、分数线、视频导入和异步 worker 还未完成。
-- 数据看板、分佣结算、AI 择校、主题模板市场等仍是后续商用增强项。
+- 数据看板和分佣结算基础 API 已可联调；分佣真实打款/导出/凭证、AI 择校、主题模板市场等仍是后续商用增强项。
 
 ## 前后端协作建议
 

docs/refactor/legacy-feature-gap-matrix.md

@@ -43,7 +43,7 @@
 | 旧功能/组件 | 新后端状态 | 待补齐 |
 | --- | --- | --- |
 | 用户管理 | 已覆盖 | 租户成员、学生列表、学生资料、批量学生 upsert、禁用/恢复、批量分班、学生备注、跟进任务已实现；批量 CRM 推送、补绑、学习督导自动化待补 |
-| 销售/代理管理 | 部分覆盖 | referral/team/stats 有；缺分佣比例、结算单、审核、导出 |
+| 销售/代理管理 | 部分覆盖 | referral/team/stats 已有；分佣设置、订单/激活码归因、结算单生成、审核、打款状态和本人/全局权限范围已覆盖；还缺真实打款、导出、发票/凭证和分佣看板 |
 | 班级/教师管理 | 已覆盖 | 班级、班级成员、教师/班主任/助教/学生范围权限已有；可视化 UI 和更细数据范围组合待补 |
 | 数据看板 | 部分覆盖 | 租户 dashboard 聚合 API 已覆盖收益、注册、答题、活跃、题型、科目、题量、套餐销量、运营动态、24h 活跃和激活码使用；后续补预聚合 worker、销售转化和分佣结算看板 |
 | 地区管理 | 部分覆盖 | 地区和内容入口已有；平台公共题库已可按 SaaS 套餐/租户授权并由租户采纳；还缺更完整的全国/单地区套餐 UI 和版本同步策略 |
@@ -100,7 +100,7 @@
 3. 题库导出：PDF/Word/JSON 导出、水印、导出审计和权限控制。
 4. 导入扩展：Excel/CSV、分数线、视频批量导入和大批量异步 worker。
 5. 公共题库商业化：平台公共/地区题库授权和租户快照采纳已完成基础闭环；还需版本同步、租户自改冲突处理和运营后台 UI。
-6. CRM/销售结算：真实 CRM worker、轮询/定向分配、分佣规则、结算单、审核和导出。
+6. CRM/销售结算：分佣规则、结算单、审核和打款状态基础闭环已完成；仍缺真实 CRM worker、轮询/定向分配、打款导出、凭证和销售结算看板。
 7. 题目反馈增强：处理通知、消息提醒、问题聚合统计和内容修复闭环。
 8. 积分活动增强：积分兑换、活动任务、连续签到奖励规则和风控。
 

docs/refactor/next-development-todo.md

@@ -101,13 +101,19 @@
 9. 数据看板
    - 已完成首版实时聚合接口，覆盖收益、注册趋势、答题次数、收入趋势、题型分布、科目数量、题目总量、套餐销量、运营动态、24h 活跃度和激活码使用情况。
    - 继续补日/周/月预聚合 worker、缓存策略、慢 SQL 监控和大租户性能压测。
-   - 继续补销售/代理转化、分佣结算、客资跟进效果看板。
+   - 分佣结算基础闭环已完成；继续补销售/代理转化、结算导出、真实打款、凭证和客资跟进效果看板。
 
-10. 学生运营管理
+10. 销售/代理分佣
+   - 已完成租户默认分佣比例、成员分佣比例、激活码批次分佣比例。
+   - 已完成订单和激活码两类来源的佣金归因，且只统计客资绑定后的成交。
+   - 已完成结算单生成、重复结算拦截、审核、打款状态、已打款锁定、租户隔离和销售/代理本人范围权限。
+   - 继续补结算导出、真实打款 provider、发票/凭证、财务复核流、销售团队分佣看板和异常调整单。
+
+11. 学生运营管理
    - 已完成学生列表、学生资料维护、班级分组、教师范围可见、学生批量导入、禁用/恢复、批量分班、学生备注和跟进任务。
    - 继续补批量 CRM 推送、学习督导自动化、跟进效果统计和前端 UI。
 
-11. AI 择校推荐
+12. AI 择校推荐
    - 地区考试数据上下文。
    - 学生输入 schema。
    - AI 返回 JSON schema。

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`、连续正确、掌握状态和每日复习计划。