2026-11-01-team-system-design.md 22 KB

团队体系设计(邀请制成员 + 客户=产品购买者 + 服务指派)

  • 日期:2026-11-01
  • 状态:设计定稿(待拆任务入派发池)
  • 需求方:廖总
  • 关联:原 T32(已修订并入本设计)、docs/superpowers/specs/2026-11-01-team-product-performance-design.md(已废弃,前提错误)

0. 需求与口径澄清(来自廖总 2026-11-01)

  1. 团队成员 = 邀请加入,不是推荐人下级。
    • 由当前用户通过「邀请码 / 管理员添加」纳入团队;与 referral_tree(推荐人下线)是两套独立模型,本次「我的团队」特指邀请制团队,推广返佣页(promotion/team.vue + CommissionController 的 referral 模型)是另一个「推广/分佣」概念,不在本设计范围内。
  2. 客户数量(原「客户归属」改名)= 所有购买过「团队产品」的用户。
    • 在客户列表中可查看这些用户的列表,及其购买情况(关联订单、关联金额等)。
  3. 团队管理的作用 = 服务指派:对服务性内容,指派团队成员去服务客户。
    • 例:用户对某商品有售后问题 → 指派团队成员跟进;规划师团队做咨询;活动管理团队做活动支持。
  4. 团队类型:供应商团队(带货+售后)、规划师团队(咨询)、活动管理团队(活动支持)等。
  5. 团队 = 通过浠艾福平台销售产品/服务的一批人(负责人结算口径,2026-11-01 末次澄清,最高优先):
    • 平台从客户处收到费用后,向团队结算,结算对象 = 团队负责人(唯一)。
    • 结算费用团队内部怎么分配,平台不负责——平台不做成员间佣金拆分。
    • 每个团队成员都有自己的团队 = 他邀请加入的人(即每个成员都是其自身子团队的负责人)。

0.5 负责人结算模型(本次澄清的落点)

0.5.1 结论:供应商体系已是正确模型,虚拟/销售体系(DistributionSystem)冲突

体系 结算实现 是否「单一负责人整体结算、平台不拆分」 结论
供应商体系 SupplySystem SupplySettlementService.createSettlement:platform_profit = total_sales × platform_profit_rate/100;supplier_payout = total_sales − platform_profit;结算单挂 systemId,归属校验 system.getAdminId()(唯一负责人) ✅ 完全符合——平台抽成一次,剩余整体结算给 adminId,成员间分配平台不管 保留,无需改
虚拟/销售体系 DistributionSystem DistributionService.calculateCommission:totalCommission=orderAmount×profitRate/1000;level1Amount=total×70%;level2Amount=total×30%;platformAmount=total−L1−L2 ❌ 直接冲突——平台按 70/30 拆分给 L1/L2 上级,平台留剩余 需修正(见 §1.5 / T37)

关键事实:

  • SupplySystem.adminId(唯一负责人)+ platformProfitRate(平台抽成率)→ SupplySettlement.supplierPayout 为一次性整体结算,isOwnSettlement 用 system.getAdminId() 判定归属 → 平台只结算给唯一负责人。✓ 与澄清完全一致。
  • DistributionSystem.ownerId 字段存在但从未被结算逻辑使用;DistributionService.calculateCommission 的 70/30 拆分即「平台决定团队内部佣金分配」,违反「平台不负责团队内部分配」。

0.5.2 「每个成员都有自己的团队」如何表达

  • 结构上 distribution_relations(systemId,userId,parentId,depth)已是树:以任一成员为 root 的子树 = 该成员的团队,其 parentId=该成员 的直属下级即「他邀请加入的人」。
  • 结算语义上:每个成员作为自己子团队的负责人,平台按其子树整体结算给他(ownerId/adminId 视角),不再按 70/30 沿 parent 链拆分。
  • 供应商体系同理:成员加入即形成以该成员为负责人、以 supply_hierarchy 直属下级为成员的子团队;无需新增表,查询层派生。

1. 现状盘点(4 套独立团队模型)

团队类型 主表 成员加入方式 是否带"客户" 服务指派
成长规划师团队 GuideTeam guide_invite_codes + guide_hierarchy 邀请码 join-by-invite 否(仅 guide_orders 销售额) 无
虚拟/销售体系 VirtualTeam=DistributionSystem distribution_systems + distribution_relations 邀请码 否 无
供应商体系 SupplyTeam/SupplySystem supply_system + supply_system_member + supply_hierarchy + supply_customer_relation 管理员 member/add + 层级 是(唯一) 无(售后 AfterSalesRequest.handledBy 不挂团队)
推广返佣 Promotion「我的团队」 无表,派生自 referral_tree + product_orders 推荐人下线 派生(消费聚合) 无

关键事实(已代码实证):

  • 「客户归属」标签实际出现在供应商体系小程序页 cfc-frontend/pages/vendor/team-system/team-system.vue(统计项 teamStats.customerCount)与后端 SupplyCustomerRelationService / SupplyTeamController,不是 promotion/team.vue。本次「我的团队」即指供应商体系的团队页。
  • 供应商体系已有客户列表页 cfc-frontend/pages/vendor/team-customers/team-customers.vue → getVendorTeamCustomers → POST /api/admin/supply-team/customers(SupplyTeamController.listCustomers),来源 Tab:推荐码/下单/人工。
  • 客户模型目前仅 supply_customer_relation(= 被归属到某上游成员的家庭),无购买明细视图;客户目前仅供应商体系专有,未泛化。
  • 服务指派完全不存在于团队概念中:AfterSalesRequest.handledBy、ProductServicePerson(商品维度服务人)均不挂团队。
  • 活动团队不存在:activities 无 teamId;guide_activities 只归规划师个人。

1.5 与「负责人结算」理念的冲突清单(2026-11-01 末次澄清后核查)

# 位置 现状 冲突 处置
C1 DistributionService.calculateCommission(396 行) totalCommission=orderAmount×profitRate/1000;level1Amount=total×70%;level2Amount=total×30%;platformAmount=total−L1−L2 平台决定团队内部佣金分配(70/30 给 L1/L2 上级)→ 违反「结算费用团队怎么分配平台不负责」 T37:改为整体结算给系统唯一负责人
C2 DistributionSystem.ownerId 字段存在但结算逻辑从未使用 「唯一负责人」语义未落地为结算对象 随 T37 一并接入
C3 distribution_relations(树) systemId,userId,parentId,depth,inviteCode,整体系一棵大树,getParentChain 最多 10 层、calculateCommission 取 2 层 「每个成员都有自己的团队」未按负责人结算建模(成员子树 = 其团队语义存在但未用于结算) 随 T37 明确:成员子树整体结算给该成员,不沿链拆分
C4 SupplySystem + SupplySettlementService adminId + platformProfitRate → supplier_payout=total_sales−platform_profit,挂 systemId,isOwnSettlement 按 adminId 无冲突——已是「唯一负责人整体结算、平台不拆分」 保留不动
C5 supply_customer_relation family 口径 客户按 familyId 归集家庭,未挂「成员的团队」 轻微:客户归属应以「团队(负责人)」为结算单元而非家庭语义混淆 在客户维度设计(T32/T33 已 done)中已按 supplySystemId 归集,保留;备注明确 family 仅做展示归组
C6 设计文档 §2.1 Team 未写明「唯一负责人 + 平台整体结算、不内部分配」 设计口径缺失 本文档已补 §0.5,Team 定义按 §0.5 口径

结论:核心冲突集中在虚拟/销售体系 DistributionSystem 的 70/30 拆分(C1–C3),供应商体系结算(C4)已符合澄清,无需改动。 T32/T33/T34/T35(客户维度、服务指派、活动团队)与负责人结算口径无冲突,均围绕供应商体系展开,保留。

2. 统一团队模型(目标态)

以供应商体系为锚点(唯一已带客户),向上抽象出可复用的「团队」核心,规划师/活动团队复用同一套成员与服务指派机制。

2.1 核心抽象(Phase 2 统一,Phase 1 先对齐语义)

概念 定义 Phase 1 落点
Team(团队) 一个服务/销售单元,含类型与归属人;结算单元 = 团队负责人(唯一),平台只向负责人整体结算,团队内部分配平台不负责 复用 supply_system(类型=SUPPLIER,负责人=adminId);GuideTeam 暂并行,术语对齐
TeamMember(成员) 被邀请加入的成员 `teamId,userId,role[LEAD MEMBER],invitedBy,status,joinedAt`;每个成员同时是自己邀请子团队的负责人
TeamCustomer(客户) 购买过团队产品的用户 teamId,userId/familyId,source,firstOrderAt 复用 supply_customer_relation(扩 source 口径)
TeamServiceAssignment(服务指派) 指派某成员服务某客户 `teamId,customerId,assigneeMemberId,serviceType[AFTER_SALE CONSULT],refOrderId/refRequestId,status,assignedBy,assignedAt`

2.2 团队类型

  • 供应商团队 SUPPLIER:带货 + 售后。锚点 = SupplySystem。
  • 规划师团队 GUIDE:咨询。锚点 = GuideTeam(后续对齐 Team 抽象)。
  • 活动管理团队 ACTIVITY:活动支持。活动 activities 增加 teamId 关联,成员负责活动运营/服务(Phase 2)。
  • 服务团队 SERVICE(可选):纯服务交付单元,成员=服务人,对接 AfterSalesRequest / ProductServicePerson。

3. 本次要做的关键修正(Phase 1 落地)

3.1 客户数量:改名 + 重定义

  • UI:供应商团队页 vendor/team-system.vue 统计项「客户归属」→「客户数量」(文案 + 字段语义)。
  • 口径:去重用户数 = 在 product_orders 中 supplySystemId = 团队.systemId AND fulfillStatus='completed' 的下单用户(买家)去重计数。
  • 不再局限于 supply_customer_relation 的 referral 来源;订单自动归属(source='order',按 supplySystemId 归集)为主,manual 人工绑定保留。
  • 复用 ProductOrderService 第 1150–1164 行已有的下单自动绑定逻辑(按 supplySystemId 归集到体系),把"客户"统一为「体系下完成订单的买家」。

3.2 客户列表 + 购买情况(关联订单 / 关联金额)

原 T32 的「关联订单/关联金额」放错维度——应是客户维度的购买明细,而非团队-SKU 聚合。

  • 扩展 SupplyTeamController.listCustomers(/api/admin/supply-team/customers):每条客户除现有 familyName/memberType/source/createdAt/buyerNickname 外,增加:
    • orderCount(该客户在体系下的已完成订单数,去重 orderNo)
    • totalAmountYuan(关联金额·元 = sum(totalAmount)/100)
    • recentOrders(最近 1–3 笔:orderNo, productName, amountYuan, paidAt)
  • 前端 vendor/team-customers.vue 客户卡片增加「关联订单 N / 关联金额 ¥X」展示,可下钻查看购买明细。
  • 数据来源:product_orders WHERE supplySystemId=? AND buyerId=? AND fulfillStatus='completed'(或按 familyId 归集),金额 ÷100 转元。

3.3 团队成员 = 邀请(与推荐人解耦)

  • 供应商体系成员本就是 member/add(管理员/归属人添加)或邀请码,已是「邀请制」,无需改加入机制 —— 此结论已于 2026-11-02 修正:廖总明确要求"在我的团队加一个邀请功能,邀请其他用户加入团队",且供应商体系现有 member/add 只支持管理员直接添加,无邀请码/无受邀人记录(SupplySystemMember 无 inviteCode/invitedBy 字段),邀请是新增缺口(见 §3.5 / T38)。
  • 口径不变:本「我的团队」=邀请制,与 referral_tree 推广页(promotion/team.vue)无关。
  • promotion/team.vue(referral 模型)保留为「推广/分佣」独立页,不并入本设计。

3.4 服务指派(团队管理核心能力,新增)

  • 新增表 team_service_assignment(Phase 1 可在 supply_* 命名空间下,如 supply_service_assignment): id, systemId(teamId), customerRelationId, assigneeUserId, serviceType[AFTER_SALE|CONSULT|ACTIVITY_SUPPORT], refOrderId, refRequestId, status[PENDING|PROCESSING|DONE], assignedBy, assignedAt, doneAt, note
  • 接口(统一 @PostMapping,/api/admin/supply-team/* 或新建 /api/team/*):
    • POST /team/service-assign:把某客户(售后/咨询)指派给某成员(触发:售后请求、咨询请求)
    • POST /team/service-tasks:成员查看「派给我的服务任务」
    • POST /team/customer/{id}/services:某客户的全部服务记录
  • 对接:AfterSalesRequest 建单时可自动生成一条待指派服务任务;ProductServicePerson 的商品服务人可作为指派候选。
  • 前端:vendor/team-system.vue 增加「服务指派」入口/列表;新增服务任务页(成员侧)。

3.5 邀请功能(T38,2026-11-02 廖总需求)

  • 需求原话:「在我的团队加一个邀请功能,邀请其他用户加入团队。」
  • 现状确认(勿重复核查):后端 SupplySystemController 只有 member/add(管理员直接加,参数仅 systemId/userId,不带 parentId、不联动 supply_hierarchy);SupplySystemMember 无邀请码/受邀人字段;前端 vendor/team-system.vue(780 行)无任何邀请入口。虚拟体系 DistributionService.generateInviteCode/registerByInviteCode 有邀请码实现可参照(但结算模型不同,仅复用"码生成/凭码注册"手法)。
  • 方案(邀请码 + 邀请即挂上级):
    1. supply_system_member 扩列 invite_code(幂等 ensureColumn + 同步 schema.sql,唯一索引可后置)——每个成员一个个人专属邀请码(复用生成则不变,支持 re-generate 置旧码失效)。
    2. 生成:POST /supply-team/invite-code(入参 systemId,从 @RequestAttribute("userId") 取当前成员)→ 返回码 + 分享文案;已生成过则幂等复用(或按"刷新"重置)。
    3. 加入:POST /supply-team/invite/join(入参 inviteCode)→ 校验码有效 + 用户未加入过该体系 → ① addMember(systemId,userId)(role=member/status=active)② addRelation(systemId, inviterId, userId)(挂 supply_hierarchy,parentId=邀请人,level=父 level+1)→ 返回团队/邀请人信息。
    4. 查询(确认页用):POST /supply-team/invite/info(入参 inviteCode)→ 团队名、邀请人昵称/头像、成员数(不泄露其他隐私)。
    5. 语义:邀请加入的人是团队成员(非客户);邀请人=其上级 → 自然形成「每个成员都有自己的团队 = 他邀请的人」(与 §0.5 结算口径一致:成员子树整体结算给该成员)。
  • 前端:vendor/team-system.vue 团队成员区加「邀请成员」按钮 → 弹窗:邀请码 + 复制按钮 + 二维码(teamId+inviteCode 生成小程序码,可后置);新增受邀确认页(展示邀请人/团队 → 点"加入")与"加入成功"态(跳转我的团队)。
  • 边界:同一 (systemId,userId) 只加入一次(addMember 已有 existing 检查);被移除(status=inactive)后可再申请;role=member 不可自助变更(沿用 change-role 管理员权限);邀请不与资金/佣金计算直接挂钩(结算走唯一负责人口径,§0.5)。
  • 待确认项(不阻塞,默认按此实施):① 自助加入即生效 or 需团队负责人确认(默认即生效,负责人可移除);② 邀请码有效期/限量(默认永久有效+唯一,可后续加过期时间列)。

4. 数据模型与接口清单(Phase 1)

4.1 实体/表

  • 复用:supply_system、supply_system_member、supply_hierarchy、supply_customer_relation、product_orders(已有 supplySystemId,servicePersonId,buyerId,familyId,activityId,fulfillStatus,totalAmount,orderNo,productId,skuId)。
  • 扩展:supply_customer_relation(确认 source 含 order 且按 supplySystemId 归集;必要时加 firstOrderAt)。
  • 新增:supply_service_assignment(服务指派)。

4.2 后端接口(cfc-backend,@PostMapping,@Resource,Result)
接口 用途
POST /api/admin/supply-team/stats 客户数量(重定义后口径)
POST /api/admin/supply-team/customers 客户列表(扩展 orderCount/totalAmountYuan/recentOrders)
POST /api/admin/supply-team/service-assign 服务指派
POST /api/admin/supply-team/service-tasks 成员侧:我的服务任务
POST /api/admin/supply-team/customer/{id}/services 客户的服务记录
POST /api/admin/supply-team/invite-code 生成/获取我的邀请码(幂等)
POST /api/admin/supply-team/invite/info 邀请码信息(确认页展示:团队名/邀请人)
POST /api/admin/supply-team/invite/join 凭邀请码加入团队(挂邀请人为上级)

4.3 前端(cfc-frontend)

  • pages/vendor/team-system/team-system.vue:「客户归属」→「客户数量」文案;成员区加「邀请成员」入口。
  • pages/vendor/team-customers/team-customers.vue:卡片加「关联订单 N / 关联金额 ¥X」+ 购买明细下钻。
  • 新增 pages/vendor/team-service/index.vue(服务任务/指派)或并入 team-system。
  • 新增受邀确认页(invite/join.vue:展示邀请人/团队 → 加入)或弹窗。

5. 派发任务拆解(入池)

任务 范围 优先级
T32(修订) 团队客户列表「关联订单/关联金额(元)」购买情况接口(客户维度,非 SKU 聚合)+ 前端卡片展示 P1
T33 客户数量改名+重定义(supply_customer_relation 扩 source/统计口径 + UI 文案) P1
T34 团队服务指派能力(supply_service_assignment 表 + 指派/我的任务/客户记录接口 + 前端入口) P1
T35 活动管理团队(activities 加 teamId + 活动团队创建/成员/服务,Phase 2) P2
T37(新) 消除 70/30 内部分配冲突:DistributionService.calculateCommission 改为「整体结算给系统唯一负责人 ownerId」,平台不参与成员间分配;ownerId 接入结算;明确成员子树=其团队 P1
T38(新) 团队邀请功能:supply_system_member 扩 invite_code + 邀请码生成/信息/凭码加入接口(加入=addMember+addRelation 挂邀请人为上级)+ 前端「邀请成员」入口与受邀确认页 P1

T32 原 prompt(团队-SKU 聚合)前提错误,已按本设计修订为客户维度购买明细。 T37 源于 2026-11-01 末次澄清(§0.5/§1.5):平台只向唯一负责人结算,团队内部分配平台不负责。 T38 源于 2026-11-02 廖总需求(§3.5):在我的团队加邀请功能,邀请其他用户加入团队。

5.1 T37 修正要求(负责人结算)

  • 目标:calculateCommission 返回单一结算对象 = DistributionSystem.ownerId(唯一负责人),金额 = 佣金总额,不再输出 level1Amount/level2Amount/platformAmount 三方拆分。
  • 平台与团队的分成本就是 profitRate(平台抽成)——团队拿 totalCommission 整体,平台不再从团队佣金里二次切分。
  • ownerId 为空时降级:取该体系树 root 节点(parentId=null)的用户作为负责人,或按 profitRate 走「无团队结算」分支。
  • 保留「每个成员都有自己的团队」表达:成员子树整体结算给该成员(作为其子团队负责人),成员间分配不再由平台计算。
  • 兼容:level1Amount/level2Amount 旧字段若已有前端消费,改为 settleToUserId/settleAmount,旧字段置 null 或标记 @Deprecated 一期过渡,二期移除。
  • 不动供应商体系:SupplySettlementService 已符合口径(T37 不改 SupplySettlement*)。

6. 技术约束(AGENTS.md 铁律)

  • 后端统一 @PostMapping;@Resource 注入;@RequestAttribute("userId") 取用户;Result<T> 包装。
  • 新增/修改接口前查 docs/superpowers/api/API_REFERENCE.md 避免重复,并同步写入。
  • 金额单位「分」→ 接口返回「元」须 ÷100(BigDecimal 2 位 HALF_UP)。
  • 不引入全新框架;复用现有 SupplyCustomerRelationService / ProductOrderService / SupplyTeamController。
  • 迁移唯一入口 DatabaseInitializer.runMigrations() + ensureColumn;新增表须同步 schema.sql。

7. 验收

  • 团队页「客户归属」不再出现,改为「客户数量」,数值=体系下完成订单的去重买家数。
  • 客户列表每个客户展示关联订单数 + 关联金额(元) + 可下钻购买明细;金额换算正确。
  • 客户列表仅含「邀请制团队」成员关系下的购买用户,不含 referral 推广下线混淆。
  • 可对某客户(售后/咨询)指派团队成员,被指派成员能在「服务任务」中看到并跟进;AfterSalesRequest 可联动。
  • DistributionService.calculateCommission 不再输出 70/30 L1/L2 拆分;结算对象=系统唯一负责人(ownerId);SupplySettlementService 保持「整体结算给 adminId」不变。
  • 团队成员可在「我的团队」生成/复制个人邀请码;他人凭码加入后成为其下级(supply_hierarchy.parentId=邀请人),同一用户不可重复加入同一体系;邀请人不改变(member/add 管理员添加仍可用)。
  • mvn clean compile 通过;API_REFERENCE 同步;未破坏现有 4 套团队功能。