docs: 新增佣金结算流程图 — 两级推荐佣金+提现+结算全链路

docs/flows/commission-flow.md

@@ -0,0 +1,349 @@
+# 用户使用流程图 — 佣金与结算
+
+> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
+>
+> **分层说明**: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体
+
+## 佣金体系概述
+
+系统采用**两级推荐佣金**（L1+L2）机制：
+
+| 层级 | 说明 | 佣金来源 | 适用场景 |
+|------|------|---------|---------|
+| L1（一级） | 买家的直接推荐人 | 商品利润分成 / 服务费率 / 会员费率 | 所有订单 |
+| L2（二级） | 推荐人的推荐人 | 会员订单费率 | 仅会员订阅订单 |
+| DAN结算 | 测评师/规划师服务费 | 测评订单服务费 | DAN测评服务 |
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef page fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
+    classDef api fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef service fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef data fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef external fill:#fce4ec,stroke:#d32f2f,stroke-width:1px,stroke-dasharray:3 2
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,stroke-dasharray:5 3
+
+    %% ============ 角色 ============
+    A0(("👤 推荐人")):::actor
+    B0(("👤 被推荐人(买家)")):::actor
+    C0(("📋 规划师/管家")):::actor
+    D0(("🖥 管理员")):::actor
+
+    %% ================================================================
+    %% 阶段一：推荐关系绑定
+    %% ================================================================
+    subgraph 阶段一[阶段一：推荐关系绑定]
+        direction TB
+
+        P1["🏠 新用户注册页"]:::page
+        P1 -->|"输入邀请码"| A1["🔗 注册流程中调用<br>CommissionService.bindReferral()"]:::api
+        A1 -->|"用户ID, 邀请码"| S1["⚙️ CommissionService.bindReferral()"]:::service
+        S1 -->|"校验邀请码有效性"| S1a{"邀请码是否有效?"}:::service
+        S1a -->|"无效"| D1a["📦 返回错误: 邀请码无效"]:::data
+        S1a -->|"已绑定"| D1b["📦 返回错误: 已绑定推荐人"]:::data
+        S1a -->|"有效"| S1b["⚙️ 更新用户 referrerId<br>+ 推荐人 directCount++"]:::service
+        S1b -->|"写入关系"| D1["📦 users 表<br>referrer_id 关联"]:::data
+        S1b -->|"触发里程碑检查"| S1c["⚙️ InviteMilestoneService<br>checkMilestones()"]:::service
+        S1b -->|"更新排行榜"| S1d["⚙️ ReferralLeaderboardService<br>incrementCount()"]:::service
+    end
+
+    %% ================================================================
+    %% 阶段二：佣金生成（订单支付触发）
+    %% ================================================================
+    subgraph 阶段二[阶段二：佣金生成]
+        D2["📦 订单支付成功<br>product_orders/<br>assessment_orders"]:::data
+        D2 -->|"订单ID, 订单类型, 买家ID, 金额, 商品ID"| S2["⚙️ CommissionService.settleTwoLevel()"]:::service
+        S2 -->|"查询买家推荐人"| S2a{"买家有推荐人?"}:::service
+        S2a -->|"无"| D2a["📦 无佣金, 跳过"]:::data
+        S2a -->|"有 L1 推荐人"| S2b["⚙️ 计算 L1 佣金"]:::service
+
+        S2b -->|"会员订单"| S2c["⚙️ 费率: commission_member_l1_rate<br>默认 20%"]:::service
+        S2b -->|"非会员订单"| S2d["⚙️ 判断商品利润模式"]:::service
+        S2d -->|"有 P-point 配置"| S2e["⚙️ 利润分成: 订单金额×P-point<br>×profit_share_bps"]:::service
+        S2d -->|"有 product.profitRate"| S2f["⚙️ 利润分成: 订单金额×利润率<br>×profit_share_bps"]:::service
+        S2d -->|"无利润配置"| S2g["⚙️ 服务费率: commission_service_rate<br>默认 10%"]:::service
+
+        S2c -->|"L1金额>0"| S2h["⚙️ 创建 L1 佣金记录<br>+ 更新家庭公共账户"]:::service
+        S2e -->|"L1金额>0"| S2h
+        S2f -->|"L1金额>0"| S2h
+        S2g -->|"L1金额>0"| S2h
+        S2h -->|"写入记录"| D2b["📦 commission_records 表<br>level=1, status=settled"]:::data
+        S2h -->|"推广等级倍率加成"| S2i["⚙️ PromotionTierService<br>applyTierBoost()"]:::service
+
+        S2b -->|"L1推荐人也有推荐人<br>且是会员订单"| S2j["⚙️ 计算 L2 佣金"]:::service
+        S2j -->|"费率: commission_member_l2_rate<br>默认 5%"| S2k["⚙️ 创建 L2 佣金记录"]:::service
+        S2k -->|"写入记录"| D2c["📦 commission_records 表<br>level=2, status=settled"]:::data
+        S2k -->|"L1推荐人 indirectCount++"| S2l["⚙️ 更新推荐人间接推荐数"]:::service
+    end
+
+    %% ================================================================
+    %% 阶段三：DAN测评服务结算
+    %% ================================================================
+    subgraph 阶段三[阶段三：DAN测评服务结算]
+        D2 -->|"测评订单支付"| P3["📋 测评师/规划师：结算记录"]:::page
+        P3 --> A3["🔗 POST /api/admin/dan-settlement/list"]:::api
+        A3 -->|"状态筛选"| S3["⚙️ DanSettlementService<br>getAllSettlements()"]:::service
+        S3 -->|"查询结算记录"| D3["📦 service_settlements 表"]:::data
+
+        D3 --> P3a["🖥 管理员：结算审核页"]:::page
+        P3a -->|"确认打款"| A3a["🔗 POST /api/admin/dan-settlement/confirm/{settlementId}"]:::api
+        A3a -->|"结算ID"| S3a["⚙️ 更新状态=settled"]:::service
+        S3a -->|"标记已结算"| D3a["📦 service_settlements 表<br>状态更新"]:::data
+
+        P3a -->|"查看统计"| A3b["🔗 POST /api/admin/dan-settlement/stats"]:::api
+        A3b -->|"无参数"| S3b["⚙️ DanSettlementService<br>getSettlementStats()"]:::service
+        S3b -->|"统计汇总"| D3b["📦 总金额, 待结算, 已结算"]:::data
+    end
+
+    %% ================================================================
+    %% 阶段四：佣金查询与管理
+    %% ================================================================
+    subgraph 阶段四[阶段四：佣金查询与管理]
+        D2b --> P4["📋 规划师/管家：佣金面板"]:::page
+        P4 -->|"查看汇总"| A4["🔗 POST /api/commission/summary"]:::api
+        A4 -->|"用户ID"| S4["⚙️ CommissionService.getSummary()"]:::service
+        S4 -->|"汇总数据"| D4["📦 可提现, 已结算, 待结算, 总佣金"]:::data
+
+        P4 -->|"查看流水"| A4a["🔗 POST /api/commission/list"]:::api
+        A4a -->|"页码, 页大小"| S4a["⚙️ CommissionService.getList()"]:::service
+        S4a -->|"分页列表"| D4a["📦 commission_records 分页"]:::data
+
+        P4 -->|"团队统计"| A4b["🔗 POST /api/commission/team"]:::api
+        A4b -->|"用户ID"| S4b["⚙️ CommissionService.getTeamStats()"]:::service
+        S4b -->|"L1/L2人数, 团队佣金"| D4b["📦 团队统计数据"]:::data
+
+        P4 -->|"可提现余额"| A4c["🔗 POST /api/commission/balance"]:::api
+        A4c -->|"用户ID"| S4c["⚙️ CommissionService.getSummary()"]:::service
+        S4c -->|"可用余额详情"| D4c["📦 available, settled, pending, withdrawn"]:::data
+
+        P4 -->|"佣金漏斗"| A4d["🔗 POST /api/commission/funnel"]:::api
+        A4d -->|"用户ID"| S4d["⚙️ CommissionService.getCommissionFunnel()"]:::service
+        S4d -->|"漏斗数据"| D4d["📦 转化漏斗各阶段数据"]:::data
+
+        P4 -->|"被推荐人列表"| A4e["🔗 POST /api/commission/my-referrals"]:::api
+        A4e -->|"页码, 页大小"| S4e["⚙️ CommissionService.getMyReferrals()"]:::service
+        S4e -->|"分页列表"| D4e["📦 被推荐人用户列表"]:::data
+    end
+
+    %% ================================================================
+    %% 阶段五：提现
+    %% ================================================================
+    subgraph 阶段五[阶段五：佣金提现]
+        D4c -->|"可提现余额"| P5["📋 规划师/管家：提现页"]:::page
+        P5 -->|"输入金额, 账户信息"| A5["🔗 POST /api/withdrawal/apply"]:::api
+        A5 -->|"提现金额, 账户信息"| S5["⚙️ WithdrawalService.apply()"]:::service
+        S5 -->|"校验余额充足"| S5a{"余额 >= 提现金额?"}:::service
+        S5a -->|"不足"| D5a["📦 返回错误: 余额不足"]:::data
+        S5a -->|"充足"| S5b["⚙️ 冻结金额, 写入申请"]:::service
+        S5b -->|"写入提现申请"| D5["📦 withdrawal_requests 表<br>status=pending"]:::data
+
+        D5 --> P5a["🖥 管理员：提现审核页"]:::page
+        P5a -->|"查看待审核列表"| A5a["🔗 POST /api/admin/commission/withdrawals"]:::api
+        A5a -->|"状态筛选"| S5c["⚙️ WithdrawalService.getAdminList()"]:::service
+        S5c -->|"分页列表"| D5a["📦 withdrawal_requests 分页"]:::data
+
+        P5a -->|"审核通过"| A5b["🔗 POST /api/admin/commission/audit<br>status=approved"]:::api
+        A5b -->|"提现ID, 审核结果"| S5d["⚙️ WithdrawalService.audit()"]:::service
+        S5d -->|"更新状态=approved"| D5b["📦 withdrawal_requests 表<br>状态更新"]:::data
+
+        P5a -->|"审核驳回"| A5c["🔗 POST /api/admin/commission/audit<br>status=rejected"]:::api
+        A5c -->|"提现ID, 驳回原因"| S5e["⚙️ WithdrawalService.audit()"]:::service
+        S5e -->|"解冻金额, 状态=rejected"| D5c["📦 withdrawal_requests 表<br>状态更新, 余额解冻"]:::data
+    end
+
+    %% ================================================================
+    %% 阶段六：管理员佣金配置
+    %% ================================================================
+    subgraph 阶段六[阶段六：管理员佣金配置]
+        P6["🖥 管理员：佣金配置页"]:::page
+        P6 -->|"查看配置"| A6["🔗 POST /api/admin/commission/config"]:::api
+        A6 -->|"无参数"| S6["⚙️ 查询佣金配置表"]:::service
+        S6 -->|"配置列表"| D6["📦 rebate_commission_config 表"]:::data
+
+        P6 -->|"更新配置"| A6a["🔗 POST /api/admin/commission/config/update"]:::api
+        A6a -->|"配置ID, 费率, 启用状态"| S6a["⚙️ 更新佣金配置"]:::service
+        S6a -->|"更新记录"| D6a["📦 rebate_commission_config 表"]:::data
+
+        P6 -->|"设置商品利润率"| A6b["🔗 POST /api/admin/commission/update-profit-rate"]:::api
+        A6b -->|"商品ID, 利润率(千分比)"| S6b["⚙️ 更新 product.profitRate"]:::service
+        S6b -->|"更新商品表"| D6b["📦 products 表<br>profit_rate 字段"]:::data
+
+        P6 -->|"手动结算"| A6c["🔗 POST /api/admin/commission/settle"]:::api
+        A6c -->|"结算参数"| S6c["⚙️ 提交结算任务"]:::service
+        S6c -->|"创建结算任务"| D6c["📦 结算任务已提交"]:::data
+
+        P6 -->|"佣金退款处理"| A6d["🔗 POST /api/admin/commission/refund"]:::api
+        A6d -->|"退款参数"| S6d["⚙️ 处理佣金退款"]:::service
+        S6d -->|"更新佣金记录"| D6d["📦 commission_records 表<br>退款状态更新"]:::data
+    end
+
+    %% ================================================================
+    %% 角色关联
+    %% ================================================================
+    A0 -.- P1
+    B0 -.- P1
+    C0 -.- P4
+    C0 -.- P5
+    D0 -.- P5a
+    D0 -.- P6
+    D0 -.- P3a
+```
+
+## 端点明细
+
+### 推荐关系
+
+| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
+|------|------|------|---------|---------|
+| `POST /api/commission/bind-referral` | 绑定推荐关系 | ⚙️系统 | 用户ID, 邀请码 | 成功/失败 |
+| `POST /api/commission/my-referrals` | 我的被推荐人列表 | 📱小程序 | 页码, 页大小 | 分页被推荐人列表 |
+
+### 佣金查询
+
+| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
+|------|------|------|---------|---------|
+| `POST /api/commission/summary` | 佣金汇总 | 📋规划师 | 用户ID | 可提现/已结算/待结算/总佣金 |
+| `POST /api/commission/list` | 佣金流水 | 📋规划师 | 页码, 页大小 | 分页佣金记录 |
+| `POST /api/commission/stats` | 佣金统计面板 | 📋规划师 | 用户ID | 今日/本月/累计/可提现 |
+| `POST /api/commission/balance` | 可提现余额详情 | 📋规划师 | 用户ID | 可用/已结算/待结算/已提现 |
+| `POST /api/commission/team` | 团队统计 | 📋规划师 | 用户ID | L1/L2人数, 团队佣金 |
+| `POST /api/commission/team/list` | 团队成员列表 | 📋规划师 | 页码, 页大小, 层级 | 分页成员列表 |
+| `POST /api/commission/funnel` | 佣金转化漏斗 | 📋规划师 | 用户ID | 各阶段漏斗数据 |
+
+### 提现
+
+| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
+|------|------|------|---------|---------|
+| `POST /api/withdrawal/apply` | 申请提现 | 📋规划师 | 提现金额, 账户信息 | 成功/失败 |
+| `POST /api/withdrawal/history` | 提现记录 | 📋规划师 | 页码, 页大小 | 分页提现记录 |
+
+### 管理员审核
+
+| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
+|------|------|------|---------|---------|
+| `POST /api/admin/commission/withdrawals` | 提现列表 | 🖥管理后台 | 状态, 页码, 页大小 | 分页提现申请 |
+| `POST /api/admin/commission/audit` | 审核提现 | 🖥管理后台 | 提现ID, 状态(approved/rejected), 备注 | 成功/失败 |
+| `POST /api/admin/commission/config` | 佣金配置列表 | 🖥管理后台 | 无 | 佣金配置列表 |
+| `POST /api/admin/commission/config/update` | 更新佣金配置 | 🖥管理后台 | 配置ID, 费率, 启用状态 | 成功/失败 |
+| `POST /api/admin/commission/update-profit-rate` | 设置商品利润率 | 🖥管理后台 | 商品ID, 利润率 | 成功/失败 |
+| `POST /api/admin/commission/settle` | 手动结算 | 🖥管理后台 | 结算参数 | 结算任务已提交 |
+| `POST /api/admin/commission/refund` | 佣金退款 | 🖥管理后台 | 退款参数 | 退款已处理 |
+| `POST /api/admin/commission/records` | 佣金记录查询 | 🖥管理后台 | 无 | 佣金记录列表 |
+
+### DAN测评结算
+
+| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
+|------|------|------|---------|---------|
+| `POST /api/admin/dan-settlement/list` | 结算记录列表 | 🖥管理后台 | 状态筛选 | 结算记录列表 |
+| `POST /api/admin/dan-settlement/detail/{settlementId}` | 结算详情 | 🖥管理后台 | 路径: 结算ID | 结算单详情 |
+| `POST /api/admin/dan-settlement/confirm/{settlementId}` | 确认打款 | 🖥管理后台 | 路径: 结算ID | 成功/失败 |
+| `POST /api/admin/dan-settlement/stats` | 结算统计 | 🖥管理后台 | 无 | 总金额/待结算/已结算 |
+
+### 推广佣金
+
+| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
+|------|------|------|---------|---------|
+| `POST /api/promotion/commission/record` | 记录推广佣金 | ⚙️系统 | 佣金对象 | 成功/失败 |
+| `POST /api/promotion/commission/family-total` | 家庭总佣金 | ⚙️系统 | 家庭ID | 总佣金金额 |
+
+## 数据实体关系
+
+```mermaid
+erDiagram
+    User ||--o{ CommissionRecord : "推荐人获得佣金"
+    User ||--o{ WithdrawalRequest : "申请提现"
+    ProductOrder ||--o{ CommissionRecord : "订单触发佣金"
+    CommissionRecord ||--o{ FamilyEarnings : "佣金计入家庭账户"
+
+    User {
+        Long id PK
+        Long referrerId FK "推荐人ID"
+        string referralCode UK "我的邀请码"
+        int directCount "直接推荐人数"
+        int indirectCount "间接推荐人数"
+        Long totalCommissionEarned "累计佣金"
+    }
+
+    CommissionRecord {
+        Long id PK
+        Long orderId FK "来源订单ID"
+        string orderType "product/membership/assessment"
+        Long referrerId FK "获得佣金者"
+        Long buyerId FK "买家ID"
+        string commissionType "member/profit/service"
+        int orderAmount "订单金额"
+        int commissionAmount "佣金金额"
+        int level "1=L1, 2=L2"
+        string status "settled/frozen/cancelled/refunded"
+        Long familyId "关联家庭"
+        datetime settledAt
+        datetime createdAt
+    }
+
+    WithdrawalRequest {
+        Long id PK
+        Long userId FK
+        int amount "提现金额"
+        string accountInfo "账户信息"
+        string status "pending/approved/rejected/completed"
+        Long auditBy "审核人"
+        string auditRemark "审核备注"
+        datetime createdAt
+        datetime processedAt
+    }
+
+    RebateCommissionConfig {
+        Long id PK
+        string configKey "费率key"
+        int rateBps "费率(基点)"
+        string description
+        int enabled
+        datetime createdAt
+        datetime updatedAt
+    }
+
+    ServiceSettlement {
+        Long id PK
+        Long orderId FK
+        Long providerId "服务提供者ID"
+        string providerType "assessor/planner"
+        int amount "结算金额"
+        string status "pending/settled/failed"
+        datetime createdAt
+        datetime settledAt
+    }
+```
+
+## 完整性分析
+
+### 流程完整性
+- ✅ 推荐关系绑定→佣金生成→查询→提现→审核全链路覆盖
+- ✅ L1+L2 两级佣金计算
+- ✅ 多种佣金类型（会员/利润分成/服务费）
+- ✅ DAN测评服务结算
+- ✅ 管理员佣金配置管理
+
+### 异常路径
+- ❌ 佣金结算失败的重试机制未标注
+- ❌ 订单退款时佣金回滚的处理未标注
+- ❌ 提现打款失败的处理（已审核但打款失败）
+- ❌ 推广等级变更对佣金的影响未标注
+
+### 角色覆盖
+- ✅ 推荐人（查看佣金、提现）
+- ✅ 被推荐人（注册时绑定）
+- ✅ 规划师/管家（佣金面板、团队、提现）
+- ✅ 管理员（审核提现、配置佣金、管理结算）
+
+### 数据流向
+- ✅ 绑定推荐人 → 订单支付 → 计算佣金 → 写入记录 → 可提现 → 申请提现 → 审核 → 打款
+- ✅ 测评订单 → 服务结算 → 管理员确认 → 打款
+
+### 遗漏端点
+| 端点 | 说明 | 建议补充 |
+|------|------|---------|
+| `POST /api/admin/commission/refunds/pending` | 待处理退款列表 | 退款佣金处理流程 |
+| `POST /api/admin/commission/refunds/cancel` | 中止退款 | 退款异常处理 |
+| `POST /api/admin/commission/refunds/summary` | 退款汇总 | 退款统计 |
+| 定时任务：佣金自动结算 | 系统自动 | 定期结算待处理佣金 |