# 用户使用流程图 — 推广分销

> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
>
> **分层说明**: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体

```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

    %% ============ 角色 ============
    ROLE_PARENT(("👤 家长/推广员")):::actor
    ROLE_TEACHER(("📋 规划师")):::actor
    ROLE_ADMIN(("🖥 管理员")):::actor

    %% ================================================================
    %% 阶段一：推广关系绑定
    %% ================================================================
    subgraph 阶段一[阶段一：推广关系绑定]
        P1["🏠 推广端：推广首页"]:::page
        P1 -->|"输入邀请码, promoterFamilyId"| A1["🔗 POST /api/promotion/bind"]:::api
        A1 -->|"inviteCode, promoterFamilyId"| S1["⚙️ FamilyCommissionService.bindByInviteCode()"]:::service
        S1 -->|"写入推广绑定关系"| D_BIND["📦 promotion_binding 表"]:::data

        P1 -->|"查看绑定列表"| A2["🔗 POST /api/promotion/bindings/list"]:::api
        A2 -->|"familyId"| S2["⚙️ FamilyCommissionService.getBindings()"]:::service
        S2 -->|"该家庭的所有绑定记录"| D_BIND

        P1 -->|"查看佣金列表"| A3["🔗 POST /api/promotion/commission/list"]:::api
        A3 -->|"familyId, page, size"| S3["⚙️ FamilyCommissionService.getCommissionList()"]:::service
        S3 -->|"分页佣金记录"| D_FC["📦 family_commission 表"]:::data
    end

    %% ================================================================
    %% 阶段二：邀请码与虚拟团队
    %% ================================================================
    subgraph 阶段二[阶段二：邀请码与虚拟团队]
        P2["🏠 推广端：销售邀请页"]:::page
        P2 -->|"生成邀请码"| A4["🔗 POST /api/distribution/invite/generate"]:::api
        A4 -->|"systemId, userId"| S4["⚙️ DistributionService.generateInviteCode()"]:::service
        S4 -->|"生成唯一邀请码"| D_RELATION["📦 distribution_relations 表"]:::data
        S4 -->|"虚拟团队信息"| D_SYSTEM["📦 distribution_systems 表"]:::data

        P2 -->|"校验邀请码"| A5["🔗 POST /api/distribution/invite/validate"]:::api
        A5 -->|"inviteCode"| S5["⚙️ DistributionService.findByInviteCode()"]:::service
        S5 -->|"inviterId, systemId, teamName"| D_RELATION

        P2 -->|"查看虚拟团队"| A6["🔗 POST /api/distribution/invite/my-teams"]:::api
        A6 -->|"userId"| S6["⚙️ DistributionService.getUserTeams()"]:::service
        S6 -->|"我参与的所有虚拟团队"| D_SYSTEM

        P2 -->|"查看团队位置"| A7["🔗 POST /api/distribution/invite/my-position"]:::api
        A7 -->|"systemId, userId"| S7["⚙️ DistributionService.getUserPosition()"]:::service
        S7 -->|"上级, 下级, 深度"| D_RELATION
    end

    %% ================================================================
    %% 阶段三：佣金总览
    %% ================================================================
    subgraph 阶段三[阶段三：佣金总览]
        P3["🏠 推广端：佣金中心"]:::page
        P3 -->|"获取佣金汇总"| A8["🔗 POST /api/commission/summary"]:::api
        A8 -->|"userId"| S8["⚙️ CommissionService.getSummary()"]:::service
        S8 -->|"累计佣金, 可提现, 待结算, 已提现"| D_SUMMARY["📦 CommissionSummaryDTO"]:::data

        P3 -->|"获取佣金统计"| A9["🔗 POST /api/commission/stats"]:::api
        A9 -->|"userId"| S9["⚙️ CommissionService.getCommissionStats()"]:::service
        S9 -->|"今日/本月/累计/L1/L2等面板数据"| D_STATS["📦 统计聚合（内存）"]:::data

        P3 -->|"获取可提现余额"| A10["🔗 POST /api/commission/balance"]:::api
        A10 -->|"userId"| S10["⚙️ CommissionService.getSummary()"]:::service
        S10 -->|"availableAmount, settledAmount, pendingAmount"| D_SUMMARY
    end

    %% ================================================================
    %% 阶段四：佣金明细与团队
    %% ================================================================
    subgraph 阶段四[阶段四：佣金明细与团队]
        P3 -->|"查看佣金明细"| A11["🔗 POST /api/commission/list"]:::api
        A11 -->|"userId, page, size"| S11["⚙️ CommissionService.getList()"]:::service
        S11 -->|"分页佣金记录"| D_RECORDS["📦 commission_records 表"]:::data

        P3 -->|"查看团队统计"| A12["🔗 POST /api/commission/team"]:::api
        A12 -->|"userId"| S12["⚙️ CommissionService.getTeamStats()"]:::service
        S12 -->|"L1/L2人数, 团队佣金"| D_RECORDS

        P3 -->|"查看团队列表"| A13["🔗 POST /api/commission/team/list"]:::api
        A13 -->|"userId, level, page, size"| S13["⚙️ CommissionService.getTeamList()"]:::service
        S13 -->|"分页团队成员"| D_RECORDS

        P3 -->|"查看转化漏斗"| A14["🔗 POST /api/commission/funnel"]:::api
        A14 -->|"userId"| S14["⚙️ CommissionService.getCommissionFunnel()"]:::service
        S14 -->|"转化各阶段人数/金额"| D_STATS

        P1 -->|"记录佣金"| A15["🔗 POST /api/promotion/commission/record"]:::api
        A15 -->|"Commission对象"| S15["⚙️ PromotionCommissionService.recordCommission()"]:::service
        S15 -->|"写入佣金记录"| D_COMM["📦 promotion_commission 表"]:::data

        P1 -->|"家庭佣金汇总"| A16["🔗 POST /api/promotion/commission/family-total"]:::api
        A16 -->|"familyId"| S16["⚙️ PromotionCommissionService.getFamilyTotal()"]:::service
        S16 -->|"该家庭佣金总额"| D_COMM
    end

    %% ================================================================
    %% 阶段五：推广素材管理
    %% ================================================================
    subgraph 阶段五[阶段五：推广素材管理]
        P4["🏠 推广端：素材中心"]:::page
        P4 -->|"素材列表"| A17["🔗 POST /api/promotion/material/list"]:::api
        A17 -->|"materialType, usageScenario, keyword"| S17["⚙️ PromotionMaterialService.getMaterials()"]:::service
        S17 -->|"分页素材列表"| D_MAT["📦 promotion_materials 表"]:::data

        P4 -->|"素材详情"| A18["🔗 POST /api/promotion/material/detail"]:::api
        A18 -->|"id"| S18["⚙️ PromotionMaterialService.getById()"]:::service
        S18 -->|"素材完整信息"| D_MAT

        P4 -->|"按场景获取"| A19["🔗 POST /api/promotion/material/by-scenario"]:::api
        A19 -->|"scenario"| S19["⚙️ PromotionMaterialService.getByScenario()"]:::service
        S19 -->|"该场景下的所有素材"| D_MAT

        P4 -->|"管理员：创建素材"| A20["🔗 POST /api/promotion/material/create"]:::api
        A20 -->|"PromotionMaterial对象"| S20["⚙️ PromotionMaterialService.createMaterial()"]:::service
        S20 -->|"新建素材记录"| D_MAT

        P4 -->|"管理员：更新素材"| A21["🔗 POST /api/promotion/material/update"]:::api
        A21 -->|"PromotionMaterial对象(id必填)"| S21["⚙️ PromotionMaterialService.updateMaterial()"]:::service
        S21 -->|"更新素材记录"| D_MAT

        P4 -->|"管理员：删除素材"| A22["🔗 POST /api/promotion/material/delete"]:::api
        A22 -->|"id"| S22["⚙️ PromotionMaterialService.deleteMaterial()"]:::service
        S22 -->|"删除素材记录"| D_MAT
    end

    %% ================================================================
    %% 阶段六：提现
    %% ================================================================
    subgraph 阶段六[阶段六：提现]
        P3 -->|"申请提现"| A23["🔗 POST /api/withdrawal/apply"]:::api
        A23 -->|"amount, accountInfo"| S23["⚙️ WithdrawalService.apply()"]:::service
        S23 -->|"新建提现申请（待审核）"| D_WITHDRAW["📦 withdrawal_requests 表"]:::data

        P3 -->|"提现记录"| A24["🔗 POST /api/withdrawal/history"]:::api
        A24 -->|"page, size"| S24["⚙️ WithdrawalService.getHistory()"]:::service
        S24 -->|"该用户的历史提现记录"| D_WITHDRAW

        P5["🖥 管理后台：佣金审核页"]:::page
        P5 -->|"提现列表"| A25["🔗 POST /api/admin/commission/withdrawals"]:::api
        A25 -->|"status, page, size"| S25["⚙️ WithdrawalService.getAdminList()"]:::service
        S25 -->|"全平台提现申请"| D_WITHDRAW

        P5 -->|"审核提现"| A26["🔗 POST /api/admin/commission/audit"]:::api
        A26 -->|"requestId, status, remark"| S26["⚙️ WithdrawalService.audit()"]:::service
        S26 -->|"更新提现状态(approved/rejected)"| D_WITHDRAW

        P5 -->|"退款记录"| A27["🔗 POST /api/admin/commission/refunds/pending"]:::api
        A27 -->|"status, orderType, page, size"| S27["⚙️ PendingRefundService.getAllPendingRefunds()"]:::service
        S27 -->|"待处理退款列表"| D_REFUND["📦 pending_refunds 表"]:::data

        P5 -->|"中止退款"| A28["🔗 POST /api/admin/commission/refunds/cancel"]:::api
        A28 -->|"refundId"| S28["⚙️ PendingRefundService.cancelPendingRefund()"]:::service
        S28 -->|"取消退款流程"| D_REFUND
    end

    %% ================================================================
    %% 阶段七：排行榜与里程碑
    %% ================================================================
    subgraph 阶段七[阶段七：排行榜与里程碑]
        P1 -->|"查看排行榜"| A29["🔗 POST /api/leaderboard/top"]:::api
        A29 -->|"weekStart"| S29["⚙️ ReferralLeaderboardService.getTopUsers()"]:::service
        S29 -->|"推广排行前20名"| D_RANK["📦 排行聚合（内存）"]:::data

        P1 -->|"我的排名"| A30["🔗 POST /api/leaderboard/my-rank"]:::api
        A30 -->|"userId, weekStart"| S30["⚙️ ReferralLeaderboardService.getMyRank()"]:::service
        S30 -->|"当前用户排名及上下级差"| D_RANK

        P1 -->|"里程碑列表"| A31["🔗 POST /api/invite/milestone/list"]:::api
        A31 -->|"userId"| S31["⚙️ InviteMilestoneService.getMilestones()"]:::service
        S31 -->|"已达成/未达成的里程碑"| D_MILESTONE["📦 invite_milestones 表"]:::data

        P1 -->|"领取里程碑奖励"| A32["🔗 POST /api/invite/milestone/claim"]:::api
        A32 -->|"userId, milestone"| S32["⚙️ InviteMilestoneService.claimReward()"]:::service
        S32 -->|"发放奖励, 更新状态"| D_MILESTONE
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    ROLE_PARENT -.- P1
    ROLE_PARENT -.- P2
    ROLE_PARENT -.- P3
    ROLE_PARENT -.- P4
    ROLE_TEACHER -.- P2
    ROLE_ADMIN -.- P5
```

## 端点明细

### 推广绑定

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/promotion/bind` | 绑定推广关系 | 📱小程序 | `{inviteCode, promoterFamilyId}` | `PromotionBinding` 对象 |
| `POST /api/promotion/commission/list` | 家庭佣金列表 | 📱小程序 | `{familyId, page, size}` | `{records, total, page, size}` |
| `POST /api/promotion/bindings/list` | 绑定列表 | 📱小程序 | `{familyId}` | `List<PromotionBinding>` |
| `POST /api/promotion/commission/record` | 记录佣金 | ⚙️系统自动 | `Commission` 对象（含familyId, guideId, amount, type, source） | `boolean` |
| `POST /api/promotion/commission/family-total` | 家庭佣金总额 | 📱小程序 | `{familyId}` | `Integer`（总金额） |

### 销售邀请

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/distribution/invite/generate` | 生成销售邀请码 | 📱小程序 | `{systemId}` | `String`（邀请码） |
| `POST /api/distribution/invite/validate` | 校验邀请码有效性 | 📱小程序 | `{inviteCode}` | `{valid, inviteCode, systemId, inviterId, teamName}` |
| `POST /api/distribution/invite/my-teams` | 我的虚拟团队列表 | 📱小程序 | —（从token取userId） | `List<DistributionSystem>` |
| `POST /api/distribution/invite/my-position` | 团队中的位置 | 📱小程序 | `{systemId}` | `{parentId, children, depth, ...}` |

### 佣金中心

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/commission/summary` | 佣金汇总 | 📱小程序 | —（从token取userId） | `CommissionSummaryDTO`（累计/可提现/待结算/已提现） |
| `POST /api/commission/list` | 佣金明细 | 📱小程序 | `{page, size}` | `Page<CommissionRecord>` |
| `POST /api/commission/team` | 团队统计 | 📱小程序 | —（从token取userId） | `{l1Count, l2Count, teamCommission, ...}` |
| `POST /api/commission/stats` | 佣金统计面板 | 📱小程序 | —（从token取userId） | `{todayAmount, monthlyAmount, totalAmount, ...}` |
| `POST /api/commission/balance` | 可提现余额 | 📱小程序 | —（从token取userId） | `{availableAmount, settledAmount, pendingAmount, totalCommission, withdrawnAmount}` |
| `POST /api/commission/team/list` | 团队成员列表 | 📱小程序 | `{level, page, size}` | `{members, total, page, size}` |
| `POST /api/commission/funnel` | 转化漏斗 | 📱小程序 | —（从token取userId） | `{各阶段转化人数/金额}` |

### 推广素材

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/promotion/material/list` | 素材列表 | 📱小程序 | `{materialType, usageScenario, keyword, pageNum, pageSize}` | `Page<PromotionMaterial>` |
| `POST /api/promotion/material/detail` | 素材详情 | 📱小程序 | `{id}` | `PromotionMaterial` |
| `POST /api/promotion/material/by-scenario` | 按场景获取素材 | 📱小程序 | `{scenario}` | `List<PromotionMaterial>` |
| `POST /api/promotion/material/create` | 创建素材（管理员） | 🖥管理后台 | `PromotionMaterial`（含title, materialType, coverUrl, ...） | `PromotionMaterial` |
| `POST /api/promotion/material/update` | 更新素材（管理员） | 🖥管理后台 | `PromotionMaterial`（id必填） | `null` |
| `POST /api/promotion/material/delete` | 删除素材（管理员） | 🖥管理后台 | `{id}` | `null` |

### 提现

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/withdrawal/apply` | 申请提现 | 📱小程序 | `{amount, accountInfo}` | `String`（成功/失败信息） |
| `POST /api/withdrawal/history` | 提现记录 | 📱小程序 | `{page, size}` | `Page<WithdrawalRequest>` |

### 排行榜与里程碑

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/leaderboard/top` | 推广排行榜 | 📱小程序 | `{weekStart}` | `List<{rank, userId, count, ...}>`（前20名） |
| `POST /api/leaderboard/my-rank` | 我的排名 | 📱小程序 | `{weekStart}` | `{rank, totalCount, aheadCount, behindCount}` |
| `POST /api/invite/milestone/list` | 里程碑列表 | 📱小程序 | —（从token取userId） | `List<InviteMilestone>` |
| `POST /api/invite/milestone/claim` | 领取里程碑奖励 | 📱小程序 | `{milestone}` | `String`（成功/失败信息） |

### 管理后台 — 佣金审核

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/admin/commission/withdrawals` | 提现列表 | 🖥管理后台 | `{status, page, size}` | `Page<WithdrawalRequest>` |
| `POST /api/admin/commission/audit` | 审核提现 | 🖥管理后台 | `{requestId, status, remark}` | `String`（已通过/已拒绝） |
| `POST /api/admin/commission/update-profit-rate` | 设置商品利润率 | 🖥管理后台 | `{productId, profitRate}` | `String`（设置成功） |
| `POST /api/admin/commission/refunds/pending` | 待处理退款 | 🖥管理后台 | `{status, orderType, page, size}` | `Page<PendingRefund>` |
| `POST /api/admin/commission/refunds/summary` | 退款汇总 | 🖥管理后台 | — | `{totalPendingAmount}` |
| `POST /api/admin/commission/refunds/cancel` | 中止退款 | 🖥管理后台 | `{refundId}` | `String`（已中止退款） |

## 数据实体关系

```
推广绑定 → 佣金记录 → 提现申请
邀请码 → 虚拟团队 → 分销关系
```

| 表名 | 主键 | 核心字段 | 说明 |
|------|------|---------|------|
| `promotion_binding` | `id` | promoterFamilyId, inviteeFamilyId, inviteCode, bindingType, status | 家庭间推广绑定关系 |
| `family_commission` | `id` | promoterFamilyId, buyerFamilyId, orderId, amount, commissionRate, commissionAmount, status | 家庭级佣金记录 |
| `promotion_commission` | `id` | familyId, guideId, memberId, amount, type(register/purchase/invite), source, status | 推广佣金明细 |
| `commission_records` | `id` | orderId, orderType, referrerId, buyerId, commissionType, commissionAmount, status, level(1/2) | 统一佣金记录（含层级） |
| `distribution_systems` | `id` | name, ownerId, profitRate, enabled | 虚拟团队/分销体系配置 |
| `distribution_relations` | `id` | systemId, userId, parentId, depth, inviteCode | 分销关系树 |
| `promotion_materials` | `id` | title, materialType, coverUrl, fileUrl, usageScenario, status | 推广素材 |
| `withdrawal_requests` | `id` | userId, amount, accountInfo, status, adminId, remark | 提现申请记录 |
| `invite_milestones` | `id` | userId, milestone, status, reward | 邀请里程碑 |

## 完整性分析

| # | 维度 | 评估 | 说明 |
|---|------|------|------|
| 1 | **流程完整性** | ✅ 完整 | 覆盖推广绑定、邀请码、佣金总览/明细/团队、素材管理、提现、排行榜、里程碑共7个阶段，涵盖6个Controller |
| 2 | **异常路径** | ⚠️ 部分覆盖 | 邀请码无效（`validate`返回404）、提现审核拒绝已覆盖；佣金结算失败、退款异常等业务逻辑在Service层处理，图中未展开 |
| 3 | **端点覆盖** | ✅ 完整 | 30个端点全部映射到流程图中，与PromotionController、CommissionController、DistributionInviteController、WithdrawalController、ReferralLeaderboardController、PromotionMaterialController、InviteMilestoneController、AdminCommissionController的`@PostMapping`一致 |
| 4 | **角色覆盖** | ✅ 完整 | 家长（推广员）为推广核心用户，可完成全部推广操作；规划师可生成邀请码；管理员在后台审核提现、管理素材、设置利润率 |
| 5 | **数据实体** | ✅ 完整 | 9张核心表均在图中映射，覆盖推广绑定（promotion_binding）、佣金（family_commission/promotion_commission/commission_records）、分销体系（distribution_systems/relations）、素材（promotion_materials）、提现（withdrawal_requests）、里程碑（invite_milestones） |
| 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与实际Controller（PromotionController、CommissionController、DistributionInviteController、WithdrawalController、ReferralLeaderboardController、PromotionMaterialController、InviteMilestoneController、AdminCommissionController）的`@PostMapping`匹配 |