docs/superpowers/specs/2026-11-01-team-product-performance-design.md(已废弃,前提错误)referral_tree(推荐人下线)是两套独立模型,本次「我的团队」特指邀请制团队,推广返佣页(promotion/team.vue + CommissionController 的 referral 模型)是另一个「推广/分佣」概念,不在本设计范围内。| 体系 | 结算实现 | 是否「单一负责人整体结算、平台不拆分」 | 结论 |
|---|---|---|---|
| 供应商体系 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 拆分即「平台决定团队内部佣金分配」,违反「平台不负责团队内部分配」。distribution_relations(systemId,userId,parentId,depth)已是树:以任一成员为 root 的子树 = 该成员的团队,其 parentId=该成员 的直属下级即「他邀请加入的人」。ownerId/adminId 视角),不再按 70/30 沿 parent 链拆分。supply_hierarchy 直属下级为成员的子团队;无需新增表,查询层派生。| 团队类型 | 主表 | 成员加入方式 | 是否带"客户" | 服务指派 |
|---|---|---|---|---|
| 成长规划师团队 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 只归规划师个人。| # | 位置 | 现状 | 冲突 | 处置 |
|---|---|---|---|---|
| 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(客户维度、服务指派、活动团队)与负责人结算口径无冲突,均围绕供应商体系展开,保留。
以供应商体系为锚点(唯一已带客户),向上抽象出可复用的「团队」核心,规划师/活动团队复用同一套成员与服务指派机制。
| 概念 | 定义 | 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` |
SupplySystem。GuideTeam(后续对齐 Team 抽象)。activities 增加 teamId 关联,成员负责活动运营/服务(Phase 2)。AfterSalesRequest / ProductServicePerson。vendor/team-system.vue 统计项「客户归属」→「客户数量」(文案 + 字段语义)。product_orders 中 supplySystemId = 团队.systemId AND fulfillStatus='completed' 的下单用户(买家)去重计数。supply_customer_relation 的 referral 来源;订单自动归属(source='order',按 supplySystemId 归集)为主,manual 人工绑定保留。ProductOrderService 第 1150–1164 行已有的下单自动绑定逻辑(按 supplySystemId 归集到体系),把"客户"统一为「体系下完成订单的买家」。原 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 转元。member/add(管理员/归属人添加)或邀请码,已是「邀请制」,无需改加入机制member/add 只支持管理员直接添加,无邀请码/无受邀人记录(SupplySystemMember 无 inviteCode/invitedBy 字段),邀请是新增缺口(见 §3.5 / T38)。referral_tree 推广页(promotion/team.vue)无关。promotion/team.vue(referral 模型)保留为「推广/分佣」独立页,不并入本设计。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 增加「服务指派」入口/列表;新增服务任务页(成员侧)。SupplySystemController 只有 member/add(管理员直接加,参数仅 systemId/userId,不带 parentId、不联动 supply_hierarchy);SupplySystemMember 无邀请码/受邀人字段;前端 vendor/team-system.vue(780 行)无任何邀请入口。虚拟体系 DistributionService.generateInviteCode/registerByInviteCode 有邀请码实现可参照(但结算模型不同,仅复用"码生成/凭码注册"手法)。supply_system_member 扩列 invite_code(幂等 ensureColumn + 同步 schema.sql,唯一索引可后置)——每个成员一个个人专属邀请码(复用生成则不变,支持 re-generate 置旧码失效)。POST /supply-team/invite-code(入参 systemId,从 @RequestAttribute("userId") 取当前成员)→ 返回码 + 分享文案;已生成过则幂等复用(或按"刷新"重置)。POST /supply-team/invite/join(入参 inviteCode)→ 校验码有效 + 用户未加入过该体系 → ① addMember(systemId,userId)(role=member/status=active)② addRelation(systemId, inviterId, userId)(挂 supply_hierarchy,parentId=邀请人,level=父 level+1)→ 返回团队/邀请人信息。POST /supply-team/invite/info(入参 inviteCode)→ 团队名、邀请人昵称/头像、成员数(不泄露其他隐私)。vendor/team-system.vue 团队成员区加「邀请成员」按钮 → 弹窗:邀请码 + 复制按钮 + 二维码(teamId+inviteCode 生成小程序码,可后置);新增受邀确认页(展示邀请人/团队 → 点"加入")与"加入成功"态(跳转我的团队)。(systemId,userId) 只加入一次(addMember 已有 existing 检查);被移除(status=inactive)后可再申请;role=member 不可自助变更(沿用 change-role 管理员权限);邀请不与资金/佣金计算直接挂钩(结算走唯一负责人口径,§0.5)。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(服务指派)。| 接口 | 用途 |
|---|---|
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 |
凭邀请码加入团队(挂邀请人为上级) |
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:展示邀请人/团队 → 加入)或弹窗。| 任务 | 范围 | 优先级 |
|---|---|---|
| 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):在我的团队加邀请功能,邀请其他用户加入团队。
calculateCommission 返回单一结算对象 = DistributionSystem.ownerId(唯一负责人),金额 = 佣金总额,不再输出 level1Amount/level2Amount/platformAmount 三方拆分。profitRate(平台抽成)——团队拿 totalCommission 整体,平台不再从团队佣金里二次切分。ownerId 为空时降级:取该体系树 root 节点(parentId=null)的用户作为负责人,或按 profitRate 走「无团队结算」分支。level1Amount/level2Amount 旧字段若已有前端消费,改为 settleToUserId/settleAmount,旧字段置 null 或标记 @Deprecated 一期过渡,二期移除。SupplySettlementService 已符合口径(T37 不改 SupplySettlement*)。@PostMapping;@Resource 注入;@RequestAttribute("userId") 取用户;Result<T> 包装。docs/superpowers/api/API_REFERENCE.md 避免重复,并同步写入。BigDecimal 2 位 HALF_UP)。SupplyCustomerRelationService / ProductOrderService / SupplyTeamController。DatabaseInitializer.runMigrations() + ensureColumn;新增表须同步 schema.sql。AfterSalesRequest 可联动。DistributionService.calculateCommission 不再输出 70/30 L1/L2 拆分;结算对象=系统唯一负责人(ownerId);SupplySettlementService 保持「整体结算给 adminId」不变。supply_hierarchy.parentId=邀请人),同一用户不可重复加入同一体系;邀请人不改变(member/add 管理员添加仍可用)。mvn clean compile 通过;API_REFERENCE 同步;未破坏现有 4 套团队功能。