团队层级树与推荐关系可视化设计

版本: v1.0 日期: 2026-09-09 状态: 待审查 关联需求: 用户需求记录

一、概述

用户故事：

作为家长用户，我想在「我的」页面查看我的推荐人、分享人数、团队层级树（从下往上生长）、团队总消费额、直推成员的消费额和我获得的 CF 值，以便直观了解我的推广成果与团队结构。

核心目标：

去掉富页面的推荐码展示
我的页面新增「我的推荐人」卡片
我的页面新增「团队层级」入口，跳转独立树形页面（从下往上生长）
树形页面展示：团队总消费额（默认 3 级，后台可配）、直推成员列表含消费额+我获得的 CF 值
后端新增/扩展接口支撑上述功能

二、验收标准

2.1 富页面

删除「我的邀请码」横条（referral-code-bar 区块）
保留「邀请人数」显示

2.2 我的页面

新增「我的推荐人」卡片（显示推荐人昵称、头像、邀请码、绑定时间）
新增「团队层级」入口按钮，点击跳转树形页面
保留现有「推广收益」成就卡片

2.3 团队层级树页面（新建 `/pages/profile/team-tree`）

树形结构从下往上生长（根节点在底部，分支向上延伸）
顶部展示：团队总消费额（默认统计 3 级）、团队人数
支持折叠/展开每个节点
每个节点显示：头像、昵称、层级标识（L1/L2/L3）、消费额、我的 CF 获得
点击成员可查看详情（预留）

2.4 后端接口

POST /api/commission/team/list 扩展：返回中每个成员新增 memberConsumption、myCfEarnedFromMember
POST /api/commission/team/consumption 新增：团队总消费额分级汇总
POST /api/commission/my-referrer 新增：获取我的推荐人信息
POST /api/commission/team/tree 新增：团队树形扁平数据（含层级、父子关系）

2.5 配置化

后台可配置团队消费统计最大层级（默认 3 级）

三、技术方案

3.1 数据模型关系

表	关键字段	用途
`users`	`id`, `referrerId`, `referralCode`, `nickname`, `avatar`, `created_at`	用户与推荐关系
`referral_tree`	`parentId`, `childId`, `level`, `path`	物化全层级推荐树
`product_orders`	`buyerId`, `totalAmount`, `status`, `fulfillStatus`, `paidAt`	消费订单（fulfillStatus=completed 表示已完成履约）
`commission_records`	`referrerId`, `buyerId`, `commissionAmount`, `level`, `status`	佣金记录（L1/L2；status=settled/cancelled）
`user_platform_balance`	`userId`, `totalEarned`, `available`, `frozen`, `withdrawn`	CF 值钱包（现有，本需求不直接读）
`cf_rate_tier`	`minTeamSize`, `ratePercent`, `enabled`	返佣阶梯（现有，复用其 maxLevel 配置）

注：referral_tree.level = 代际差（1=直推，2=间推...）；commission_records.level = 1/2（仅 L1/L2 结算佣金）；订单完成以 fulfillStatus = 'completed' 为准。

3.2 后端接口设计

3.2.1 扩展 `/api/commission/team/list`

请求： { page, size, level }（level: ALL/L1/L2）

响应扩展字段：

{
  "records": [
    {
      "userId": 123,
      "nickname": "用户名",
      "avatarUrl": "https://...",
      "createdAt": "2026-01-01",
      "orderCount": 5,
      "commissionEarned": 15000,
      "memberConsumption": 32000,       // 新增：该成员 completed 订单总额
      "myCfEarnedFromMember": 9600      // 新增：我从该成员消费获得的 CF(佣金)总额
    }
  ],
  "total": 10,
  "page": 1,
  "size": 20
}

实现逻辑：

memberConsumption：查 product_orders 表 buyerId = 该成员 且 fulfillStatus = 'completed' 的 totalAmount 总和（仅统计已完成履约的订单）
myCfEarnedFromMember：查 commission_records 表 referrerId = 我 且 buyerId = 该成员 且 status != 'cancelled' 的 commissionAmount 总和（含 settled + pending）

3.2.2 新增 `/api/commission/team/consumption`

请求： { maxLevel: 3 }（默认 3，可选）

响应：

{
  "totalConsumption": 125000,
  "levelBreakdown": [
    { "level": 1, "memberCount": 5, "consumption": 80000 },
    { "level": 2, "memberCount": 12, "consumption": 35000 },
    { "level": 3, "memberCount": 8, "consumption": 10000 }
  ],
  "totalMembers": 25,
  "maxLevel": 3
}

实现逻辑：

查 referral_tree 表 parentId = 我 且 level <= maxLevel 的所有 childId
按 level 分组统计 memberCount
查这些 childId 的 product_orders（fulfillStatus = 'completed'）totalAmount 总和，按 level 汇总

配置化：

读取 cf_rate_tier 表中 enabled=1 的记录，或新增 commission_config 表存储 team_consumption_max_level（默认 3）
后端管理接口：POST /api/admin/cf-rate-tier/setting（扩展现有）或新增

3.2.3 新增 `/api/commission/my-referrer`

请求： 空

响应：

{
  "referrerId": 456,
  "nickname": "推荐人昵称",
  "avatar": "https://...",
  "referralCode": "ABC123XY",
  "bindTime": "2026-01-15 10:30:00"
}

实现逻辑：

查 users 表 id = 当前用户.referrerId
若 referrerId 为空，返回 { hasReferrer: false }

3.2.4 新增 `/api/commission/team/tree`

请求： { maxLevel: 3 }（默认 3）

响应：

{
  "nodes": [
    { "userId": 101, "nickname": "直推A", "avatar": "https://...", "level": 1, "parentId": 100, "referrerId": 100, "memberConsumption": 32000, "myCfEarnedFromMember": 9600 },
    { "userId": 102, "nickname": "间推B", "avatar": "https://...", "level": 2, "parentId": 101, "referrerId": 101, "memberConsumption": 8000, "myCfEarnedFromMember": 2400 },
    { "userId": 103, "nickname": "直推C", "avatar": "https://...", "level": 1, "parentId": 100, "referrerId": 100, "memberConsumption": 15000, "myCfEarnedFromMember": 4500 }
  ],
  "totalMembers": 3,
  "maxLevel": 3
}

说明： nodes 数组不包含根节点（"我"）——仅包含 team 成员（level >= 1）；根节点仅用于前端统计/上下文。每个节点已包含 memberConsumption（该成员自身已完成履约订单总额）和 myCfEarnedFromMember（我从该成员消费获得的 CF 总额）。前端按 parentId 递归构建树，level 用于层级标签与缩进。

3.3 前端改动清单

文件	变更类型	详情
`pages/wealth/index.vue`	删除	移除 `referral-code-bar`（第 161-165 行）
`pages/profile-main/profile.vue`	新增	1.「我的推荐人」卡片 2.「团队层级」入口按钮 → `navigateTo('/pages/profile/team-tree')`
`pages/profile/team-tree.vue`	新建	树形页面： - 顶部统计卡（总消费、人数） - 树形组件（从下往上生长，flex column-reverse + 递归） - 节点组件：头像、昵称、层级标签、消费额、我的 CF 获得 - 折叠/展开交互
`utils/api.js`	新增	`getTeamConsumption(maxLevel)`、`getMyReferrer()`、`getTeamTree(maxLevel)`、`getTeamList` 扩展字段
`pages.json`	注册	新增 `pages/profile/team-tree` 页面

树形 UI 实现思路（从下往上生长）：

<!-- 树形容器：flex column-reverse，L1节点在底部，分支向上延伸 -->
<view class="tree-container" style="flex-direction: column-reverse;">
  <!-- L1节点作为根：扁平 nodes 先按 parentId 组装为树，再渲染 -->
  <TreeNode v-for="root in level1Roots" :key="root.userId" :node="root" :level="1" :maxLevel="maxLevel" />
</view>

<!-- TreeNode.vue -->
<view class="tree-node" :style="{ 'padding-left': (level - 1) * 30 + 'rpx' }">
  <view class="node-main" @click="toggle">
    <image :src="node.avatar" />
    <text>{{ node.nickname }}</text>
    <tag>L{{ node.level }}</tag>
    <text class="consumption">消费: ¥{{ (node.memberConsumption/100).toFixed(2) }}</text>
    <text class="my-cf">我得CF: ¥{{ (node.myCfEarnedFromMember/100).toFixed(2) }}</text>
    <icon :name="expanded ? 'up' : 'down'" />
  </view>
  <!-- 子节点：因为父容器 column-reverse，子节点会在上方渲染 -->
  <view v-if="expanded && node.children" class="children">
    <TreeNode v-for="child in node.children" :key="child.userId" :node="child" :level="level+1" :maxLevel="maxLevel" />
  </view>
  <!-- 连接线：::before 画竖线，父节点中心向上 -->
</view>

3.4 后端实现要点

新增 Service 方法（CommissionService）：

// 1. 团队消费统计
public Map<String, Object> getTeamConsumption(Long userId, Integer maxLevel)

// 2. 我的推荐人
public Map<String, Object> getMyReferrer(Long userId)

// 3. 团队树形数据
public Map<String, Object> getTeamTree(Long userId, Integer maxLevel)

// 4. 扩展 getTeamList：查询 memberConsumption、myCfEarnedFromMember

依赖注入需补充：

ProductOrderMapper
ReferralTreeMapper
UserPlatformBalanceMapper（如需）

新增 Controller 方法（CommissionController）：

@PostMapping("/team/consumption")
public Result<Map<String, Object>> teamConsumption(@RequestAttribute("userId") Long userId,
                                                    @RequestBody Map<String, Object> params)

@PostMapping("/my-referrer")
public Result<Map<String, Object>> myReferrer(@RequestAttribute("userId") Long userId)

@PostMapping("/team/tree")
public Result<Map<String, Object>> teamTree(@RequestAttribute("userId") Long userId,
                                            @RequestBody Map<String, Object> params)

四、API 设计汇总

接口	方法	请求体	响应关键字段	备注
`/api/commission/team/list`	POST	`{page,size,level}`	`records[].memberConsumption`, `records[].myCfEarnedFromMember`	扩展现有
`/api/commission/team/consumption`	POST	`{maxLevel}`	`totalConsumption`, `levelBreakdown[]`, `totalMembers`	新增
`/api/commission/my-referrer`	POST	`{}`	`referrerId`, `nickname`, `avatar`, `referralCode`, `bindTime`	新增
`/api/commission/team/tree`	POST	`{maxLevel}`	`nodes[]`, `totalMembers`	新增

五、配置项

配置键	默认值	说明	维护位置
`team_consumption_max_level`	3	团队消费统计最大层级	后台管理 - CF返佣阶梯配置扩展

建议复用 AdminCfRateTierController 新增设置接口，或新增 CommissionConfigController

六、边界情况处理

场景	处理
用户无推荐人（`referrerId` 为空）	我的推荐人卡片显示"暂无推荐人"，不显示邀请码
团队成员无消费订单	消费额显示 0，CF 获得显示 0
`maxLevel` 超过实际层级	按实际最大层级统计
`referral_tree` 数据不一致	以 `users.referrerId` 为准，`referral_tree` 为辅助加速查询
订单状态：仅统计已完成履约	高

七、测试用例

用例	输入	预期输出
无推荐人用户访问我的页面	登录用户，referrerId=null	推荐人卡片显示"暂无推荐人"
有推荐人用户访问我的页面	登录用户，referrerId=456	显示推荐人昵称、头像、邀请码、绑定时间
空团队访问树形页面	无下级	仅显示根节点（自己），统计为 0
3层团队消费统计	maxLevel=3	正确汇总 L1/L2/L3 消费额
直推成员列表	level=L1	每行含 memberConsumption、myCfEarnedFromMember
折叠/展开交互	点击节点图标	子节点显示/隐藏，连接线正确

八、关联文档

docs/superpowers/api/API_REFERENCE.md - 接口参考（新增接口需同步记录）
cfc-backend/AGENTS.md - 后端规范
cfc-frontend/AGENTS.md - 前端规范

九、实施顺序建议

后端先行（1-2 天）：
- 新增 3 个接口 + 扩展 1 个接口
- 单元测试验证查询逻辑
- 更新 API_REFERENCE.md
前端并行（1-2 天）：
- 删除富页面推荐码
- 我的页面新增推荐人卡片 + 团队入口
- 新建 team-tree 页面（树形组件复用/新建）
- 接入 API
配置化（0.5 天）：
- 后台 CF 阶梯配置页扩展 maxLevel 字段
- 接口读取配置
联调验证（0.5 天）：
- 真实数据跑通
- 边界情况验证

十、风险与对策

风险	等级	对策
`referral_tree` 数据量大，树形查询慢	中	限制 `maxLevel`≤5，加索引 `idx_parent_level(parentId, level)`
消费额统计包含退款订单	高	严格筛选 `fulfillStatus = 'completed'`（仅统计已完成履约的订单，排除未结算/退货状态）
树形 UI 在小程序渲染卡顿	低	虚拟列表/分页加载，层级>3 懒加载
后台配置未生效（缓存）	低	配置读取走 Redis，更新后清理

文档结束

2026-09-09-team-hierarchy-design.md 13 KB History Raw

团队层级树与推荐关系可视化设计

一、概述

二、验收标准

2.1 富页面

2.2 我的页面

2.3 团队层级树页面（新建 /pages/profile/team-tree）

2.4 后端接口

2.5 配置化

三、技术方案

3.1 数据模型关系

3.2 后端接口设计

3.2.1 扩展 /api/commission/team/list

3.2.2 新增 /api/commission/team/consumption

3.2.3 新增 /api/commission/my-referrer

3.2.4 新增 /api/commission/team/tree

3.3 前端改动清单

3.4 后端实现要点

四、API 设计汇总

五、配置项

六、边界情况处理

七、测试用例

八、关联文档

九、实施顺序建议

十、风险与对策

2026-09-09-team-hierarchy-design.md 13 KB

History Raw

2.3 团队层级树页面（新建 `/pages/profile/team-tree`）

3.2.1 扩展 `/api/commission/team/list`

3.2.2 新增 `/api/commission/team/consumption`

3.2.3 新增 `/api/commission/my-referrer`

3.2.4 新增 `/api/commission/team/tree`