供应商团队客户归属功能实施总结

实施日期: 2026-10-05
功能名称: 供应商团队客户归属系统

一、业务需求回顾

供应商作为后台提供服务的加盟商（规划师、商品提供商等），需要：

查看下级带来的客户 — 上级服务商能看到下级供应商带来的客户列表
团队内部服务转介 — 团队成员之间可以进行服务转介
优先级排序 — 按推荐会员数排序，优先获得平台推荐

关键约束：平台只负责展示归属关系，不负责团队分佣。

二、已完成实现

2.1 数据库层

新建表 `supply_customer_relation`（迁移344）

文件位置:

cfc-backend/src/main/resources/schema.sql (末尾)
cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java (第11510-11530行)

表结构:

CREATE TABLE IF NOT EXISTS supply_customer_relation (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    system_id BIGINT NOT NULL COMMENT '供应商体系ID',
    parent_user_id BIGINT NOT NULL COMMENT '上级供应商用户ID',
    family_id BIGINT NOT NULL COMMENT '客户家庭ID',
    child_user_id BIGINT DEFAULT NULL COMMENT '下单用户ID',
    relation_type VARCHAR(32) NOT NULL DEFAULT 'family' COMMENT '归属类型: family/order',
    source VARCHAR(32) NOT NULL DEFAULT 'manual' COMMENT '来源: manual/order/referral',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_system_family (system_id, family_id),
    INDEX idx_parent_user (parent_user_id),
    INDEX idx_family_id (family_id),
    UNIQUE KEY uk_system_family (system_id, family_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

设计说明:

system_id + family_id 唯一键：防止重复记录
parent_user_id：上级供应商用户ID，支持查询"某上级下的所有客户"
source 字段区分来源：manual（人工绑定）/order（下单自动）/referral（推荐码）
relation_type：family（家庭归属）/order（订单关联）

2.2 后端实现

新建文件清单

文件	位置	说明
`SupplyCustomerRelation.java`	`entity/`	实体类
`SupplyCustomerRelationMapper.java`	`mapper/`	Mapper接口，含自定义查询方法
`SupplyCustomerRelationService.java`	`service/`	业务逻辑：绑定、查询、统计
`SupplyTeamController.java`	`controller/admin/`	RESTful API端点

关键业务逻辑

SupplyCustomerRelationService.java:

listCustomers(systemId, parentId, page, size): 分页查询上级供应商下的客户列表
bindCustomer(systemId, parentId, familyId, childUserId, source): 人工绑定客户归属
autoBindOnOrder(systemId, parentId, familyId, childUserId): 订单完成时自动绑定
listTeamMembers(systemId): 查询团队成员列表（含客户数量统计）
getRelationByFamily(systemId, familyId): 查询某个家庭的归属关系

修改文件

ProductOrderService.java (第778-782行):

// 原有逻辑
supplyHierarchyService.addRelation(order.getSupplySystemId(), buyer.getReferrerId(), order.getBuyerId());

// 新增逻辑
supplyCustomerRelationService.autoBindOnOrder(order.getSupplySystemId(), buyer.getReferrerId(), order.getFamilyId(), order.getBuyerId());

说明: 订单完成时，同时记录上下级关系和供应商团队客户归属关系。

新增 API 接口

接口	说明
`POST /api/admin/supply-team/customers`	查询上级供应商下的客户列表
`POST /api/admin/supply-team/bind-customer`	人工绑定客户归属
`POST /api/admin/supply-team/members`	查询团队成员列表（含客户数量统计）
`POST /api/admin/supply-team/relation`	查询某个家庭的归属关系

2.3 前端实现

新建页面

文件位置: cfc-frontend/pages/vendor/team-customers/team-customers.vue

页面功能:

展示上级供应商下的客户列表
支持按来源筛选（全部/推荐人/下单/人工）
支持下拉刷新和上拉加载更多
显示客户信息：昵称、头像、加入时间、订单数量、来源标签

页面注册: cfc-frontend/pages.json

{
  "path": "team-customers/team-customers",
  "style": { "navigationBarTitleText": "团队客户" }
}

API 封装

文件: cfc-frontend/utils/api.js

export const getTeamCustomers = (params) => {
  return request('/api/admin/supply-team/customers', 'POST', params)
}

三、业务流程

用户下单购买供应商商品
         ↓
ProductOrderService.orderComplete()
         ↓
  ┌──────┴──────┐
  ↓             ↓
supplyHierarchyService.addRelation()  ← 绑定上下级关系（已有）
  ↓
supplyCustomerRelationService.autoBindOnOrder()  ← 新增：记录客户归属
  ↓
写入 supply_customer_relation 表
  ↓
上级供应商通过 /api/admin/supply-team/customers 查询团队客户列表
  ↓
前端展示在「团队客户」页面

四、未实施内容（后续）

4.1 团队内部服务转介

需求: 团队成员之间可以进行服务转介

建议实现:

新建表 supply_referral_record:
- id, system_id, from_user_id, to_user_id, family_id, service_type, status, created_at
新增 API: POST /api/admin/supply-team/referral/apply
前端：在客户详情页添加「转介」按钮

4.2 推荐码体系关联

需求: 服务商通过推荐码绑定客户，自动关联供应商团队

建议实现:

在 CommissionService.bindReferrerByUserId() 中，检查推荐人是否属于某个供应商体系
如果是，同时写入 supply_customer_relation 表
需要新增 API: POST /api/admin/supply-team/bind-by-referral

4.3 前端页面入口

需求: 服务商可以从「服务商中心」跳转到「团队客户」页面

建议实现:

修改 pages/vendor/center/center.vue
在现有菜单项中添加「团队客户」入口

五、验证建议

5.1 数据库迁移验证

# 启动后端，查看日志确认迁移执行
mvn spring-boot:run

# 检查日志输出
# 应该看到: "迁移344: 已创建 supply_customer_relation 表"

5.2 后端 API 验证

# 测试绑定客户归属
curl -X POST http://localhost:9082/api/admin/supply-team/bind-customer \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{"systemId": 1, "parentId": 100, "familyId": 500, "childUserId": 200, "source": "manual"}'

# 测试查询客户列表
curl -X POST http://localhost:9082/api/admin/supply-team/customers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{"systemId": 1, "parentId": 100, "page": 1, "size": 20}'

5.3 前端验证

使用微信开发者工具导入项目
登录服务商账号（role=teacher 或 vendor_type=product_supplier）
从「服务商中心」跳转到「团队客户」页面
验证客户列表展示正确

六、技术要点

6.1 幂等性保证

supply_customer_relation 表使用 UNIQUE KEY uk_system_family (system_id, family_id)
Service 层 bindCustomer() 先检查是否已存在，存在则更新，不存在则插入
前端 loadCustomers() 支持分页加载，避免重复请求

6.2 权限控制

所有 API 在 JwtInterceptor 中验证 Token
Controller 中手动检查 @RequestAttribute("role")
建议后续增加：仅允许上级查看自己的下级客户，不允许越级查看

6.3 性能优化

索引设计：idx_system_family、idx_parent_user、idx_family_id
分页查询：page + size 参数，避免全表扫描
缓存建议：团队成员统计信息可使用 Redis 缓存（后续优化）

七、后续优化建议

增加前端页面入口: 在「服务商中心」添加「团队客户」快捷入口
实现团队内部服务转介: 新建 supply_referral_record 表及相关 API
关联推荐码体系: 在 CommissionService 中自动绑定供应商团队归属
增加数据可视化: 在团队客户页面添加图表展示客户增长趋势
性能优化: 为团队成员统计添加 Redis 缓存

八、文件变更清单

新增文件

cfc-backend/src/main/java/com/etotem/cfc/entity/SupplyCustomerRelation.java
cfc-backend/src/main/java/com/etotem/cfc/mapper/SupplyCustomerRelationMapper.java
cfc-backend/src/main/java/com/etotem/cfc/service/SupplyCustomerRelationService.java
cfc-backend/src/main/java/com/etotem/cfc/controller/admin/SupplyTeamController.java
cfc-frontend/pages/vendor/team-customers/team-customers.vue

修改文件

cfc-backend/src/main/resources/schema.sql (添加 supply_customer_relation 表定义)
cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java (添加迁移344)
cfc-backend/src/main/java/com/etotem/cfc/service/ProductOrderService.java (添加自动绑定逻辑)
cfc-frontend/utils/api.js (添加 getTeamCustomers API 封装)
cfc-frontend/pages.json (注册 team-customers 页面)

实施状态: ✅ 核心功能已完成
验证状态: ⏳ 待编译验证
前端联调: ⏳ 待后端 API 稳定后联调

IMPLEMENTATION-SUMMARY-2026-10-05.md 9.2 KB Istoric Crud

供应商团队客户归属功能实施总结

一、业务需求回顾

二、已完成实现

2.1 数据库层

新建表 supply_customer_relation（迁移344）

2.2 后端实现

新建文件清单

关键业务逻辑

修改文件

新增 API 接口

2.3 前端实现

新建页面

API 封装

三、业务流程

四、未实施内容（后续）

4.1 团队内部服务转介

4.2 推荐码体系关联

4.3 前端页面入口

五、验证建议

5.1 数据库迁移验证

5.2 后端 API 验证

5.3 前端验证

六、技术要点

6.1 幂等性保证

6.2 权限控制

6.3 性能优化

七、后续优化建议

八、文件变更清单

新增文件

修改文件

IMPLEMENTATION-SUMMARY-2026-10-05.md 9.2 KB

Istoric Crud

新建表 `supply_customer_relation`（迁移344）