# 供应商销售体系 — 实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal**: 在管理后台建立供应商销售体系，支持多体系管理、成员、商品关联、结算

**Architecture**: 4 张新表 (`supply_system`, `supply_system_member`, `supply_settlement`, `supply_settlement_detail`) + 扩展现有 `product_orders` 表。后端 Spring Boot 2.7.18 新增 4 Entity + 4 Mapper + 2 Service + 2 Controller。前端 Vue 2 + Element UI 新增 3 页面 + 修改 3 个现有页面。

**Tech Stack**: Spring Boot 2.7.18 / MyBatis-Plus / Vue 2 / Element UI

---

## File Structure

### 后端新增

| 文件 | 职责 |
|------|------|
| `entity/SupplySystem.java` | 供应商体系实体 |
| `entity/SupplySystemMember.java` | 体系成员实体 |
| `entity/SupplySettlement.java` | 结算记录实体 |
| `entity/SupplySettlementDetail.java` | 结算明细实体 |
| `mapper/SupplySystemMapper.java` | 体系 Mapper |
| `mapper/SupplySystemMemberMapper.java` | 成员 Mapper |
| `mapper/SupplySettlementMapper.java` | 结算 Mapper |
| `mapper/SupplySettlementDetailMapper.java` | 结算明细 Mapper |
| `service/SupplySystemService.java` | 体系 + 成员业务逻辑 |
| `service/SupplySettlementService.java` | 结算业务逻辑 |
| `controller/admin/SupplySystemController.java` | 体系/成员 API |
| `controller/admin/SupplySettlementController.java` | 结算 API |

### 后端修改

| 文件 | 修改内容 |
|------|---------|
| `entity/ProductOrder.java` | 加 `supplySystemId`, `supplierUserId` 字段 |
| `entity/Product.java` | 已有 `distributionSystemId`, `profitRate` — 确认可用 |

### 前端新增

| 文件 | 职责 |
|------|------|
| `src/views/admin/supply-system/List.vue` | 体系列表 |
| `src/views/admin/supply-system/Form.vue` | 新建/编辑体系 |
| `src/views/admin/supply-system/Detail.vue` | 体系详情（4 Tab） |

### 前端修改

| 文件 | 修改内容 |
|------|---------|
| `src/api/admin.js` | 新增 supply-system CRUD API |
| `src/views/admin/ProductEdit.vue` | 增加「所属供应商体系」下拉框 |
| `src/views/admin/ProductEdit.vue` | 选择体系后自动填充 profit_rate |
| `src/views/Layout.vue` | 侧边栏新增「供应商体系」菜单 |
| `src/router/index.js` | 新增 supply-system 路由 |

---

## Tasks

### Task 1: 数据库迁移 SQL

**文件**: 在 `cfc-backend/src/main/resources/` 下创建 `supply_system_schema.sql`

- [ ] 编写 4 张 CREATE TABLE 语句（见设计文档第 2.1 节）
- [ ] 编写 ALTER TABLE `product_orders` 语句（加两个字段 + 索引）

---

### Task 2: 后端 Entity + Mapper（4 组）

**文件**:
- Create: `entity/SupplySystem.java`, `entity/SupplySystemMember.java`
- Create: `entity/SupplySettlement.java`, `entity/SupplySettlementDetail.java`
- Create: `mapper/SupplySystemMapper.java`, `mapper/SupplySystemMemberMapper.java`
- Create: `mapper/SupplySettlementMapper.java`, `mapper/SupplySettlementDetailMapper.java`

**Entity 模板** (以 SupplySystem 为例，使用 `@Data` + `@TableName` + `@TableId(type = IdType.AUTO)`，实现 Serializable)：

```java
@Data
@TableName("supply_system")
public class SupplySystem implements Serializable {
    @TableId(type = IdType.AUTO)
    private Long id;
    private String name;
    private Long adminId;
    private Integer settlementPeriodDays;
    private BigDecimal platformProfitRate;  // 百分比，如 5.00
    private String description;
    private String status;       // active/disabled
    private Date createdAt;
    private Date updatedAt;
}
```

- [ ] 创建 SupplySystem.java
- [ ] 创建 SupplySystemMember.java（字段: id/systemId/userId/role/status/joinedAt）
- [ ] 创建 SupplySettlement.java（字段见设计文档 2.1）
- [ ] 创建 SupplySettlementDetail.java（字段见设计文档 2.1）
- [ ] 创建 4 个 Mapper（每个 `extends BaseMapper<Entity>`，加 `@Mapper`）
- [ ] **编译**: `cd cfc-backend && mvn clean compile` → 通过

---

### Task 3: 扩展 ProductOrder Entity

- [ ] 在 `ProductOrder.java` 中新增：
```java
private Long supplySystemId;
private Long supplierUserId;
```
- [ ] 确认 `Product.java` 已有 `distributionSystemId` 和 `profitRate` 字段
- [ ] **编译通过**

---

### Task 4: SupplySystemService — 体系 + 成员业务逻辑

**文件**: Create `service/SupplySystemService.java`

**方法**:
- `list(params)` — 分页查询（支持 keyword 模糊搜索 name，status 过滤）
- `detail(id)` — 按 ID 查询
- `create(params)` — 创建体系，创建者自动成为 admin 成员
- `update(params)` — 更新体系
- `toggleStatus(id)` — 切换 active/disabled
- `listAll()` — 查询所有 active 体系（供前端下拉框）
- `memberList(systemId)` — 查询成员列表（联表 User 取 nickname/phone）
- `addMember(systemId, userId)` — 添加成员（role=member）
- `removeMember(memberId)` — 移除成员
- `changeRole(memberId, role)` — 变更角色

**DI**: `@Resource SupplySystemMapper`, `SupplySystemMemberMapper`, `UserMapper`

- [ ] 创建 Service，实现所有方法
- [ ] **编译通过**

---

### Task 5: SupplySettlementService — 结算业务逻辑

**文件**: Create `service/SupplySettlementService.java`

**方法**:
- `list(params)` — 分页查询（支持 systemId, status 过滤）
- `detail(id)` — 按 ID 查询
- `detailItems(settlementId)` — 查询结算明细列表
- `createSettlement(params)` — 创建结算单
- `confirm(id)` — 确认结算（pending → settled）

- [ ] 创建 Service
- [ ] **编译通过**

---

### Task 6: SupplySystemController — API 控制器

**文件**: Create `controller/admin/SupplySystemController.java`

路由 `/api/admin/supply-system`，提供端点：

| 端点 | 方法 |
|------|------|
| `/list` | list |
| `/create` | create |
| `/update` | update |
| `/detail` | detail |
| `/toggle-status` | toggleStatus |
| `/list-all` | listAll |
| `/member/list` | memberList |
| `/member/add` | addMember |
| `/member/remove` | removeMember |
| `/member/change-role` | changeRole |

- [ ] 创建 Controller
- [ ] **编译通过**

---

### Task 7: SupplySettlementController — 结算 API

**文件**: Create `controller/admin/SupplySettlementController.java`

路由 `/api/admin/supply-settlement`，提供端点：

| 端点 | 方法 |
|------|------|
| `/list` | list |
| `/detail` | detail |
| `/detail-items` | detailItems |
| `/create` | createSettlement |
| `/confirm` | confirm |

- [ ] 创建 Controller
- [ ] **编译通过**

---

### Task 8: 前端 API 层

**文件**: Modify `cfc-web/src/api/admin.js`

在 `商品管理 API` 之前添加 15 个 API 函数（对应后端所有端点）。

关键函数：
- `getSupplySystemList`, `createSupplySystem`, `updateSupplySystem`
- `getSupplySystemDetail`, `toggleSupplySystemStatus`
- `listAllSupplySystems` — 供 ProductEdit 下拉框使用
- `getSupplySystemMembers`, `addSupplySystemMember`, `removeSupplySystemMember`, `changeSupplySystemMemberRole`
- `getSupplySettlementList`, `getSupplySettlementDetail`, `getSupplySettlementDetailItems`
- `createSupplySettlement`, `confirmSupplySettlement`

- [ ] 在 admin.js 末尾添加 15 个 API 导出函数

---

### Task 9: 前端 — 供应商体系列表页 List.vue

**文件**: Create `src/views/admin/supply-system/List.vue`

- [ ] 搜索栏：按名称搜索
- [ ] el-table：名称/账期/平台留利/状态/操作（详情/编辑/启用禁用）
- [ ] 新建按钮 → /supply-system/create
- [ ] 分页
- [ ] 搜索防抖 + 加载状态

---

### Task 10: 前端 — 供应商体系表单页 Form.vue

**文件**: Create `src/views/admin/supply-system/Form.vue`

- [ ] 新建模式 (`/supply-system/create`) vs 编辑模式 (`/supply-system/:id/edit`)
- [ ] 表单字段：名称/管理员(远程搜索用户)/账期天数/平台留利%/描述
- [ ] 表单验证 (名称/管理员必填)
- [ ] 提交后跳转列表

---

### Task 11: 前端 — 体系详情页 Detail.vue

**文件**: Create `src/views/admin/supply-system/Detail.vue`

4 个 el-tab-pane：
- [ ] **商品** Tab：按 `distribution_system_id` 查询商品列表
- [ ] **成员** Tab：成员表格 + 添加/移除/改角色
- [ ] **订单** Tab：订单列表，每行可选收款方（下拉框绑定体系成员）
- [ ] **结算** Tab：结算记录 + 生成结算单 + 确认结算

---

### Task 12: 路由 + 菜单 + ProductEdit 修改

- [ ] **router/index.js**：新增 4 个路由（List/Create/Detail/Edit）
- [ ] **Layout.vue**：侧边栏新增 `{ path: '/supply-system', label: '供应商体系', icon: 'el-icon-s-management', perm: 'supply:system' }`
- [ ] **ProductEdit.vue**：增加「所属体系」下拉选择器，选择后自动填充 profit_rate（% × 10 = ‰）

---

### Task 13: 编译验证

- [ ] **后端**：`cd cfc-backend && mvn clean compile` — 0 error
- [ ] **前端**：`cd cfc-web && npm run build` — Build complete

---

## Self-review 核对

- [ ] 所有设计文档的 API 端点 → 有对应的 Controller 方法
- [ ] 所有 Controller 方法 → 有对应的 Service 方法
- [ ] 所有前端页面 → 有对应的后端 API
- [ ] 所有新建 Entity → 有对应的 CREATE TABLE SQL
- [ ] ProductOrder 扩展字段 → 有 ALTER TABLE SQL
- [ ] 路由配置包含所有 supply-system 路径
- [ ] Layout 菜单引用正确路径（/supply-system）
```