# 供应商销售体系 — 设计规格

> **日期**: 2026-07-05
> **状态**: 草稿
> **范围**: 管理端后台（cfc-web） + 后端（cfc-backend）

---

## 1. 概述

在管理后台建立供应商销售体系。每个供应商可创建或加入多个**供应商体系**（虚拟部门），每个体系独立配置账期和平台留利比例，体系内所有商品给平台的留利空间一致。体系管理员负责商品供应、定价、折扣和发货管理，并可指定货款打给哪个具体供应商。

### 1.1 角色定义

| 角色 | 说明 |
|------|------|
| **体系管理员** | 创建和管理供应商体系，管理商品/定价/折扣，指定货款收款方 |
| **体系成员** | 加入体系的供应商，可被指定为收款方 |
| **平台运营** | 查看所有体系数据，进行结算管理 |

### 1.2 业务规则

- 一个用户可加入**多个**供应商体系，在每个体系中角色独立（管理员或成员）
- 同一体系内所有商品的**平台留利比例一致**，取自体系配置
- **账期**按体系配置（如 30/60/90 天），到期生成结算单
- 管理员可为每笔订单**指定货款收款方**（体系内的某个供应商成员）
- 订单走现有商城流程（小程序 C 端下单），后台做供应商维度的管理

---

## 2. 数据模型

### 2.1 新建表

#### `supply_system` — 供应商体系

```sql
CREATE TABLE `supply_system` (
  `id`          bigint       NOT NULL AUTO_INCREMENT,
  `name`        varchar(100) NOT NULL COMMENT '体系名称',
  `admin_id`    bigint       NOT NULL COMMENT '管理员用户ID',
  `settlement_period_days` int NOT NULL DEFAULT 30 COMMENT '账期（天）',
  `platform_profit_rate` decimal(5,2) NOT NULL DEFAULT 0 COMMENT '平台留利比例(%)',
  `description` varchar(500) DEFAULT NULL COMMENT '描述',
  `status`      varchar(20) NOT NULL DEFAULT 'active' COMMENT '状态: active/disabled',
  `created_at`  datetime     NOT NULL,
  `updated_at`  datetime     NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='供应商体系';
```

#### `supply_system_member` — 体系成员

```sql
CREATE TABLE `supply_system_member` (
  `id`         bigint       NOT NULL AUTO_INCREMENT,
  `system_id`  bigint       NOT NULL COMMENT '体系ID',
  `user_id`    bigint       NOT NULL COMMENT '用户ID',
  `role`       varchar(20)  NOT NULL DEFAULT 'member' COMMENT '角色: admin/member',
  `status`     varchar(20)  NOT NULL DEFAULT 'active' COMMENT '状态: active/inactive',
  `joined_at`  datetime     NOT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_system_user` (`system_id`, `user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='体系成员';
```

#### `supply_settlement` — 结算记录

```sql
CREATE TABLE `supply_settlement` (
  `id`              bigint       NOT NULL AUTO_INCREMENT,
  `system_id`       bigint       NOT NULL COMMENT '体系ID',
  `period_start`    date         NOT NULL COMMENT '结算周期开始',
  `period_end`      date         NOT NULL COMMENT '结算周期结束',
  `total_sales`     int          NOT NULL DEFAULT 0 COMMENT '销售总额(分)',
  `platform_profit` int          NOT NULL DEFAULT 0 COMMENT '平台留利金额(分)',
  `supplier_payout` int          NOT NULL DEFAULT 0 COMMENT '供应商实付(分)',
  `status`          varchar(20)  NOT NULL DEFAULT 'pending' COMMENT '状态: pending/settled',
  `settled_at`      datetime     DEFAULT NULL COMMENT '结算时间',
  `remark`          varchar(500) DEFAULT NULL COMMENT '备注',
  `created_at`      datetime     NOT NULL,
  PRIMARY KEY (`id`),
  KEY `idx_system_id` (`system_id`),
  KEY `idx_period` (`period_start`, `period_end`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='结算记录';
```

#### `supply_settlement_detail` — 结算明细

```sql
CREATE TABLE `supply_settlement_detail` (
  `id`            bigint       NOT NULL AUTO_INCREMENT,
  `settlement_id` bigint       NOT NULL COMMENT '结算ID',
  `order_id`      bigint       NOT NULL COMMENT '订单ID',
  `order_no`      varchar(64)  NOT NULL COMMENT '订单号',
  `product_name`  varchar(200) NOT NULL COMMENT '商品名称',
  `amount`        int          NOT NULL COMMENT '订单金额(分)',
  `platform_fee`  int          NOT NULL COMMENT '平台留利(分)',
  `supplier_id`   bigint       DEFAULT NULL COMMENT '收款供应商用户ID',
  `supplier_name` varchar(100) DEFAULT NULL COMMENT '收款供应商名称',
  `payout`        int          NOT NULL COMMENT '供应商实付(分)',
  `created_at`    datetime     NOT NULL,
  PRIMARY KEY (`id`),
  KEY `idx_settlement_id` (`settlement_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='结算明细';
```

### 2.2 扩展现有表

#### `products` 表（已存在）

现有字段可直接使用：

| 字段 | 类型 | 说明 | 状态 |
|------|------|------|------|
| `distribution_system_id` | bigint | 所属供应商体系ID | ✅ 已有 |
| `profit_rate` | int | 平台利润率(千分比) | ✅ 已有 |
| `vendor_id` | bigint | 供应商用户ID | ✅ 已有 |
| `vendor_name` | varchar | 供应商名称 | ✅ 已有 |

**说明**：创建/编辑商品时，选择所属供应商体系后，`profit_rate` 自动填充为该体系的 `platform_profit_rate`（转换为千分比）。

#### `product_orders` 表 — 新增字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `supply_system_id` | bigint | 所属供应商体系ID（冗余，方便查询） |
| `supplier_user_id` | bigint | 该笔订单指定的收款供应商用户ID |

---

## 3. 后端设计

### 3.1 新增文件

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

### 3.2 API 端点

**体系管理** (`SupplySystemController`, 路由前缀 `/api/admin/supply-system`)

| 端点 | 方法 | 说明 |
|------|------|------|
| `/list` | POST | 体系列表（分页+搜索） |
| `/create` | POST | 创建体系 |
| `/update` | POST | 编辑体系 |
| `/detail` | POST | 体系详情 |
| `/toggle-status` | POST | 启用/禁用体系 |

**成员管理**（同上 Controller）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/member/list` | POST | 体系成员列表 |
| `/member/add` | POST | 添加成员 |
| `/member/remove` | POST | 移除成员 |
| `/member/change-role` | POST | 变更角色 |

**结算管理** (`SupplySettlementController`, 路由前缀 `/api/admin/supply-settlement`)

| 端点 | 方法 | 说明 |
|------|------|------|
| `/list` | POST | 结算记录列表 |
| `/detail` | POST | 结算明细 |
| `/create` | POST | 手动生成结算单 |
| `/confirm` | POST | 确认结算 |

**商品关联**（在现有 ProductEdit 流程中）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/admin/product/list-by-system` | POST | 查询某体系的商品列表 |

### 3.3 商品关联逻辑

在现有 `ProductEdit.vue` 中添加「所属供应商体系」下拉框：

1. 选择体系 → `distribution_system_id` 写入 Product
2. 自动填充 `profit_rate` = 体系 `platform_profit_rate × 10`（转为千分比）
3. 后续编辑时 `profit_rate` 跟随体系配置，不可单独修改（规则约束）

---

## 4. 前端设计

### 4.1 新增页面（cfc-web）

```
src/views/admin/supply-system/
├── List.vue          — 供应商体系列表
├── Detail.vue        — 体系详情（Tab: 商品/成员/订单/结算）
└── Form.vue          — 新建/编辑体系
```

#### List.vue — 体系列表

- 表格列：体系名称、管理员、账期、平台留利、商品数、成员数、状态、操作
- 搜索：按名称搜索
- 操作：新建、编辑、启用/禁用

#### Detail.vue — 体系详情

使用 el-tabs 分 Tab：

| Tab | 内容 |
|-----|------|
| **商品** | 关联的商品列表，可跳转商品编辑 |
| **成员** | 成员表格（用户名/角色/加入时间），可添加/移除/改角色 |
| **订单** | 该体系下的订单列表，支持指定收款供应商 |
| **结算** | 结算记录列表，可生成/查看结算单 |

#### Form.vue — 体系表单

| 字段 | 组件 | 说明 |
|------|------|------|
| 体系名称 | el-input | 必填 |
| 管理员 | el-select (搜索用户) | 必填 |
| 账期(天) | el-input-number | 30/60/90 |
| 平台留利(%) | el-input-number | 0-100，小数点后2位 |
| 描述 | el-textarea | 选填 |
| 状态 | el-switch | active/disabled |

### 4.2 修改现有页面

#### ProductEdit.vue — 新增字段

在基本信息区域增加「所属供应商体系」选择器：

- 下拉选项：所有 active 的 supply_system
- 选择后自动填充 `profit_rate`（只读显示）
- 不选择则商品不属于任何销售体系

#### Layout.vue — 侧边栏菜单

```
供应商管理
├── 供应商体系（新增，路径 /supply-system）
└── ... 现有菜单
```

---

## 5. 订单与结算流程

### 5.1 指定货款收款方

流程：
1. 管理员在后台「订单详情」中看到属于自己体系的订单
2. 点击「指定收款方」→ 弹出该体系的成员列表
3. 选择成员 → `product_orders.supplier_user_id` 更新
4. 可随时修改，以结算时的指定为准

### 5.2 结算流程

1. 管理员或平台运营点击「生成结算单」
2. 系统汇总指定周期内该体系下所有已完成的订单
3. 计算：`总销售额 → 平台留利 → 供应商实付`
4. 生成 `supply_settlement` + 对应的 `supply_settlement_detail` 记录
5. 平台运营审核确认 → 状态改为 `settled`

计算公式：
```
platform_profit = total_sales × platform_profit_rate / 100
supplier_payout = total_sales - platform_profit
```

---

## 6. 与现有系统的集成

| 现有系统 | 集成方式 |
|---------|----------|
| **Product** | 加 system_id 关联，profit_rate 自动填充 |
| **ProductOrder** | 加 system_id + supplier_user_id |
| **User** | 直接使用，admin_id 和 member user_id 都引用 User |
| **商品管理** | ProductEdit.vue 增加「所属体系」字段 |
| **订单管理** | OrderManage.vue 增加「体系列」筛选和「指定收款方」操作 |
| **权限系统** | `supply:*` 权限码，admin 角色可见 |

---

## 7. 不在此次范围内的功能

- 小程序端供应商商品展示（C 端走现有商城，无需修改）
- 支付分账（平台先收全款，线下与供应商结算）
- 自动结算（仅支持手动生成）
- 供应商自主申请入驻（由管理端后台创建）

---

## 8. 数据库 SQL 迁移

```sql
-- 1. supply_system
CREATE TABLE IF NOT EXISTS `supply_system` (...);

-- 2. supply_system_member
CREATE TABLE IF NOT EXISTS `supply_system_member` (...);

-- 3. supply_settlement
CREATE TABLE IF NOT EXISTS `supply_settlement` (...);

-- 4. supply_settlement_detail
CREATE TABLE IF NOT EXISTS `supply_settlement_detail` (...);

-- 5. product_orders 新增字段
ALTER TABLE `product_orders`
  ADD COLUMN `supply_system_id` bigint DEFAULT NULL COMMENT '所属供应商体系ID' AFTER `coupon_id`,
  ADD COLUMN `supplier_user_id` bigint DEFAULT NULL COMMENT '收款供应商用户ID' AFTER `supply_system_id`,
  ADD KEY `idx_supply_system_id` (`supply_system_id`);
```