cfc/docs/flows/promotion-flow.md

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

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

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

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匹配