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

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

---

## 一、业务需求回顾

供应商作为后台提供服务的加盟商（规划师、商品提供商等），需要：
1. **查看下级带来的客户** — 上级服务商能看到下级供应商带来的客户列表
2. **团队内部服务转介** — 团队成员之间可以进行服务转介
3. **优先级排序** — 按推荐会员数排序，优先获得平台推荐

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

---

## 二、已完成实现

### 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行)

**表结构**:
```sql
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行):
```java
// 原有逻辑
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`
```json
{
  "path": "team-customers/team-customers",
  "style": { "navigationBarTitleText": "团队客户" }
}
```

#### API 封装

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

```javascript
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 团队内部服务转介

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

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

### 4.2 推荐码体系关联

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

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

### 4.3 前端页面入口

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

**建议实现**:
1. 修改 `pages/vendor/center/center.vue`
2. 在现有菜单项中添加「团队客户」入口

---

## 五、验证建议

### 5.1 数据库迁移验证

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

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

### 5.2 后端 API 验证

```bash
# 测试绑定客户归属
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 前端验证

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

---

## 六、技术要点

### 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 缓存（后续优化）

---

## 七、后续优化建议

1. **增加前端页面入口**: 在「服务商中心」添加「团队客户」快捷入口
2. **实现团队内部服务转介**: 新建 `supply_referral_record` 表及相关 API
3. **关联推荐码体系**: 在 `CommissionService` 中自动绑定供应商团队归属
4. **增加数据可视化**: 在团队客户页面添加图表展示客户增长趋势
5. **性能优化**: 为团队成员统计添加 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 稳定后联调