# 用户使用流程图 — 佣金与结算

> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
>
> **分层说明**: 🏠 页面 → 🔗 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` | 退款汇总 | 退款统计 |
| 定时任务：佣金自动结算 | 系统自动 | 定期结算待处理佣金 |