cfc/docs/flows/commission-flow.md

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

端口说明: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动

分层说明: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体

佣金体系概述

系统采用两级推荐佣金（L1+L2）机制：

层级	说明	佣金来源	适用场景
L1（一级）	买家的直接推荐人	商品利润分成 / 服务费率 / 会员费率	所有订单
L2（二级）	推荐人的推荐人	会员订单费率	仅会员订阅订单
DAN结算	测评师/规划师服务费	测评订单服务费	DAN测评服务

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	总佣金金额

数据实体关系

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	退款汇总	退款统计
定时任务：佣金自动结算	系统自动	定期结算待处理佣金