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

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

1. 概述

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

1.1 角色定义

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

1.2 业务规则

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

2. 数据模型

2.1 新建表

`supply_system` — 供应商体系

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` — 体系成员

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` — 结算记录

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` — 结算明细

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 中添加「所属供应商体系」下拉框：

选择体系 → distribution_system_id 写入 Product
自动填充 profit_rate = 体系 platform_profit_rate × 10（转为千分比）
后续编辑时 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 指定货款收款方

流程：

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

5.2 结算流程

管理员或平台运营点击「生成结算单」
系统汇总指定周期内该体系下所有已完成的订单
计算：总销售额 → 平台留利 → 供应商实付
生成 supply_settlement + 对应的 supply_settlement_detail 记录
平台运营审核确认 → 状态改为 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 迁移

-- 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`);

2026-07-05-supply-distribution-system-design.md 12 KB Постійне посилання Історія Запис