# 供应商管理 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 供应商管理（交易市场平台） |
| 目标 | 在业务后台维护交易市场**供应商主数据**（主体信息、联系方式、车辆及收费规则），支撑供应商检索、台账维护及后续交易、结算等业务引用 |
| 关联系统 | 业务后台；本模块为供应商**主档维护**，不替代交易开单、对账、支付等下游流程（若需与订单/结算联动，另出集成需求） |
| 修订依据 | 同目录 `供应商管理-草稿.md`、界面原型（`供应商管理.png`） |

本文档仅描述**功能需求与业务规则**，不涉及库表结构、接口路径、请求体字段命名、HTTP 报文及技术栈选型。

---

## 2. 术语与枚举

### 2.1 供应商（一条记录）

- 表示交易市场内的一个**供货/服务主体**（个体户或企业）。  
- 由运营人员在后台**登记与维护**；保存成功后可在列表检索，并供后续业务按编号或名称引用。  
- 单条记录包含：编号、名称、类型、身份识别号、联系方式、经营地点、车辆号牌集合、收费方式及与之关联的费率/标准字段。

### 2.2 供应商类型（单选，必填）

| 类型 | 含义 | 身份识别字段（界面标签） |
| --- | --- | --- |
| **个体户** | 自然人经营主体 | **身份证号** |
| **企业** | 法人或非法人组织主体 | **主体识别号**（统一社会信用代码等，见 **§2.5**） |

切换类型时，身份识别字段的**标签、校验规则**随之切换；已填写的识别号在切换类型后须**重新校验**，不符合新类型规则时拒绝保存并提示。

### 2.3 收费方式（单选，必填）

| 收费方式 | 含义概要 | 关联必填字段 |
| --- | --- | --- |
| **按户计费** | 按「户」为单位计费，不依赖头数与交易额比例 | **无**额外费率/标准字段 |
| **按头计费** | 按牲畜（或等价「头」）数量计费 | **收费标准**（元/头） |
| **按额计费** | 按交易金额比例计费 | **交易费率**、**管理费率**（均为百分比） |

**联动原则（保存时）：**

- 选择 **按户计费**：不校验、不保存「收费标准」「交易费率」「管理费率」的有效值；界面宜**隐藏或清空**上述三项，避免误填残留。  
- 选择 **按头计费**：**收费标准**必填且 > 0；**交易费率、管理费率**不适用，宜隐藏或清空。  
- 选择 **按额计费**：**交易费率、管理费率**均必填，取值范围 **0～100**（单位 **%**，含 0 与 100 是否允许由产品确认，**默认允许 0、不允许超过 100**）；**收费标准**不适用，宜隐藏或清空。

> **说明：** 原型辅助说明中曾出现「‰」表述，与表单「%」展示不一致；**以百分比（%）为准**，全文统一。

### 2.4 供应商编号

- **系统自动生成**，用户**不可手工录入或修改**（新增弹窗中只读展示，修改时只读）。  
- 格式：**2 位数字**字符串，建议左侧补零（如 `01`、`02` … `99`）。  
- **全局唯一**：同一系统内不得重复；编号用尽（如已达 `99`）时拒绝继续新增并提示「供应商编号已达上限，请联系管理员」。  
- 生成时机：用户点击新增保存且校验通过时分配；未保存前可展示「保存后自动生成」类占位。

### 2.5 身份识别号校验（摘要）

| 供应商类型 | 规则摘要 |
| --- | --- |
| 个体户 · 身份证号 | **必填**；18 位居民身份证格式及校验位规则（末位可为 `X`/`x`），与项目全局身份证校验一致 |
| 企业 · 主体识别号 | **必填**；统一社会信用代码 **18 位**（字符集、校验位与项目全局规则一致）；若业务仅采集营业执照注册号，须在评审时单独约定并替换本节 |

### 2.6 车辆号码

- 一条供应商可登记 **0～N 个**号牌（**N 建议上限 10**，评审可调）。  
- 通过「新增一行 / +」增加号牌，每行一个；支持删除单行。  
- 列表与详情中多个号牌以**顿号、逗号或换行**等方式展示，风格与项目列表长文本一致。  
- 单条号牌格式校验与项目全局车牌规则一致（若暂无全局规则：允许中文省份简称 + 字母数字组合，长度宜 **7～8** 位，非法格式拒绝保存）。

### 2.7 平台账号分配

- 列表提供「**分配账号**」操作：为当前供应商创建若依平台登录用户，供其登录业务后台或关联端使用。  
- **默认登录名**：供应商名称的**汉字拼音首字母**（小写，连续拼接）+ 该条记录的**数据库主键 id**（如名称「扎西供应商」、id=12 → `zxgys12`）。  
- **默认角色**：绑定平台角色编号 **103**（供应商端角色，以 `sys_role.role_id` 为准）。  
- **仅可成功分配一次**：`account_assigned=已分配` 后不可再次分配；登录名冲突等失败时**不**标记为已分配，允许在满足前置条件下重试。  
- **删除联动**：逻辑删除供应商时，若已分配账号，**同时删除**关联的 `sys_user`（与畜牧医疗资源管理一致）。

### 2.8 删除与可见性

- 删除采用与项目其他业务台账一致的**逻辑删除**：删除后默认不在列表与常规查询中展示，数据保留供审计。  
- **本期不提供**回收站界面；物理清除须单独审批。  
- 若供应商存在**未结算**的结算单（`settlement_status=待结算`），**禁止删除**并提示「存在未结算的结算单，无法删除」；仅**已完成**结算单不阻止删除。

### 2.9 列表筛选项与记录字段的关系

| 筛选项 | 与记录字段关系 |
| --- | --- |
| 供应商编号 | 与记录中「供应商编号」**完全一致**（精确匹配）；空则不过滤 |
| 供应商名称 | 与记录中「供应商名称」**完全一致**（精确匹配）；空则不过滤 |

---

## 3. 功能范围

**本期实现：**

| 能力 | 说明 |
| --- | --- |
| 供应商列表 | 编号、名称精确筛选；分页；见 **§5.2** |
| 新增供应商 | 录入业务字段；编号自动生成；见 **§5.1** |
| 修改供应商 | 除编号外字段均可改；收费方式联动校验；见 **§5.3** |
| 查看详情 | 只读展示全部业务字段；见 **§5.4** |
| 删除供应商 | 单条删除；见 **§5.5** |
| 分配账号 | 为供应商创建平台用户；每条仅成功一次；见 **§5.6** |
| 工具栏 | 搜索、重置、新增 |

**本期不实现（除非后续单独立项）：**

- 供应商准入审批流、黑名单、资质证照附件上传与到期提醒  
- 供应商批量导入/导出、编号手工指定或跳号规则配置界面  
- 与交易订单、结算单、对账单的自动联动（仅维护主档）  
- 供应商评分、合同管理、银行账户子模块  
- 按区域、收费方式的列表筛选（原型未要求则不做）  

---

## 4. 业务流程概览

```mermaid
flowchart TD
    A[进入供应商管理] --> B{用户操作}
    B -->|登记| C[新增供应商]
    C --> D[选择类型与收费方式]
    D --> E[填写并联动校验]
    E -->|通过| F[系统分配编号并保存]
    E -->|未通过| C
    F --> G[返回列表]
    B -->|检索| H[输入编号/名称]
    H --> I[搜索列表]
    I --> J{行操作}
    J -->|查看| K[只读详情]
    J -->|编辑| L[修改供应商]
    L --> E
    J -->|分配账号| Q[创建平台用户]
    Q --> G
    J -->|删除| M[二次确认]
    M -->|允许| N[逻辑删除]
    M -->|有关联| O[提示不可删]
    N --> G
    K --> I
    B -->|重置| P[清空筛选]
    P --> I
```

**典型使用顺序：**

1. 运营人员**新增**供应商，选择个体户/企业与收费方式，填写身份号、联系方式及按收费方式要求的费率/标准。  
2. 系统**自动分配**两位编号并落库。  
3. 日常按**编号**或**名称**精确查询台账。  
4. 需要供应商登录平台时，对未分配行执行**分配账号**。  
5. 信息变更时**修改**（编号不变）；无效或重复登记**删除**（无关联时）。  
6. 需要核对完整收费规则时**查看**详情。

---

## 5. 详细功能需求

### 5.1 新增供应商

#### 5.1.1 业务字段

| 字段 | 必填 | 规则摘要 |
| --- | --- | --- |
| 供应商编号 | — | **只读**；保存成功后展示系统生成的 2 位数字编号 |
| 供应商名称 | 是 | **1～20** 个字符（与草稿「限制 20 字」一致）；去除首尾空白后非空 |
| 供应商类型 | 是 | **个体户** / **企业**，单选 |
| 身份证号 / 主体识别号 | 是 | 标签随类型切换；校验见 **§2.5** |
| 联系方式 | 是 | **中国大陆手机号**格式校验（11 位、号段与项目全局一致） |
| 经营地点 | 否 | 文本；长度宜 **0～50** 字（有内容时按 1～50 校验） |
| 车辆号码 | 否 | 0～N 个；见 **§2.6** |
| 收费方式 | 是 | **按户计费** / **按头计费** / **按额计费**，单选 |
| 收费标准 | 条件 | **按头计费**时必填；数值 **> 0**；单位展示 **元/头** |
| 交易费率 | 条件 | **按额计费**时必填；**0～100**，单位 **%** |
| 管理费率 | 条件 | **按额计费**时必填；**0～100**，单位 **%** |

#### 5.1.2 界面联动（与原型一致）

| 用户操作 | 界面行为 |
| --- | --- |
| 选择「个体户」 | 身份字段标签为「身份证号」 |
| 选择「企业」 | 身份字段标签为「主体识别号」 |
| 选择「按户计费」 | 隐藏或禁用「收费标准」「交易费率」「管理费率」 |
| 选择「按头计费」 | 显示「收费标准（元/头）」；隐藏或禁用两项费率 |
| 选择「按额计费」 | 显示「交易费率（%）」「管理费率（%）」；隐藏或禁用「收费标准」 |

#### 5.1.3 保存与取消

| 操作 | 行为 |
| --- | --- |
| **确定** | 全量校验通过后保存；分配供应商编号；关闭弹窗并刷新列表 |
| **取消** | 关闭弹窗，不保存 |

#### 5.1.4 校验摘要

| 规则 | 说明 |
| --- | --- |
| 收费方式联动 | 未选收费方式或条件字段缺失/非法时拒绝保存 |
| 必填 | 任一必填为空或仅空白时拒绝保存 |
| 名称唯一 | 若业务要求**供应商名称不可重复**，须在评审时确认；**默认建议名称唯一**，重复时提示「供应商名称已存在」 |
| 身份号唯一 | 若业务要求同一身份识别号不可重复登记，须在评审时确认；**默认建议唯一** |

---

### 5.2 查询供应商列表

#### 5.2.1 筛选

| 条件 | 规则 |
| --- | --- |
| 供应商编号 | 选填；**精确**匹配；空则不过滤 |
| 供应商名称 | 选填；**精确**匹配；空则不过滤 |

支持**编号 + 名称**组合筛选（同时满足）。

#### 5.2.2 列表规则

- 默认每页 **20** 条。  
- 默认排序：**供应商编号升序**（或 **创建时间倒序**，产品择一后全文一致；**默认建议编号升序**便于人工查找）。  
- 工具栏：**搜索**、**重置**、**新增**。

#### 5.2.3 展示列（与原型一致）

供应商编号、供应商名称、供应商类型、身份证号/主体识别号、联系方式、经营地点、车辆号码、收费方式、**账号分配**、操作。

| 列 | 展示说明 |
| --- | --- |
| 供应商类型 | 中文：个体户 / 企业 |
| 身份证号/主体识别号 | 列表统一列展示对应类型的识别号；无则「—」 |
| 经营地点 | 过长时省略，详情可看全 |
| 车辆号码 | 多个号牌合并展示；无则「—」 |
| 收费方式 | 中文：按户计费 / 按头计费 / 按额计费 |
| 账号分配 | 未分配显示「否」；已分配显示「是」及登录名（若有） |
| 操作 | 查看、编辑、删除；**未分配**时显示「分配账号」（权限见 **§6**） |

> **说明：** 列表可不单独展示「收费标准」「交易费率」「管理费率」列，以免过宽；完整数值在**详情**中展示（见 **§5.4**）。若产品要求在列表增加摘要列（如「10元/头」或「交易2%/管理1%」），可评审后补充。

---

### 5.3 修改供应商

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「编辑」；详情页可提供「编辑」快捷入口（与列表等价） |
| 不可改字段 | **供应商编号**（只读） |
| 可改范围 | **§5.1.1** 中其余全部字段 |
| 类型/收费方式变更 | 切换后按 **§5.1.2** 联动显示与 **§2.3** 重新校验；不适用字段须清空，避免脏数据 |
| 校验 | 与新增 **§5.1.4** 一致 |
| 保存 | **确定** 保存并刷新列表；**取消** 放弃修改 |

---

### 5.4 查看供应商详情

| 项 | 要求 |
| --- | --- |
| 展示内容 | **§5.1.1** 全部字段；按收费方式展示适用的收费标准或费率；车辆号码全文展示；**是否已分配账号**、**已分配登录名**（若有） |
| 只读 | 全部字段不可编辑 |
| 操作 | 可提供 **编辑**、**删除**（权限与列表一致）；**未分配**时可提供 **分配账号**；**关闭** 返回列表 |
| 收费规则展示示例 | 按头：`收费标准：XX 元/头`；按额：`交易费率：XX%`；`管理费率：XX%`；按户：仅展示收费方式，不展示费率行 |

宜含**创建人、创建时间、修改人、修改时间**等审计信息（与项目其他台账一致）。

---

### 5.5 删除供应商

| 项 | 要求 |
| --- | --- |
| 入口 | 列表「删除」；详情可提供「删除」 |
| 确认 | 删除前**二次确认**（宜展示编号、名称） |
| 删除方式 | **逻辑删除**（**§2.7**） |
| 关联约束 | 存在**未结算**结算单时**拒绝删除**，提示「存在未结算的结算单，无法删除」 |
| 批量删除 | **本期不提供** |

---

## 6. 操作与权限矩阵（汇总）

在**已授权**前提下：

| 操作 | 列表/详情 | 说明 |
| --- | --- | --- |
| 查询列表、筛选 | ✓ | 需列表查询权限 |
| 新增 | 工具栏「新增」 | 需新增权限 |
| 查看 | 行内/详情 | 需查看权限 |
| 修改 | 行内/详情 | 需修改权限；编号不可改 |
| 删除 | 行内/详情 | 需删除权限；受关联约束 |
| 分配账号 | 行内/详情 | 需分配账号权限；**仅未分配**行可用 |

无权限的按钮**不展示或禁用**（与若依按钮权限惯例一致）。

---

## 7. 收费方式与字段适用对照（自查）

| 收费方式 | 收费标准 | 交易费率 | 管理费率 |
| --- | --- | --- | --- |
| 按户计费 | 不适用 | 不适用 | 不适用 |
| 按头计费 | **必填**（元/头，>0） | 不适用 | 不适用 |
| 按额计费 | 不适用 | **必填**（%，0～100） | **必填**（%，0～100） |

---

## 8. 异常与提示（业务侧）

面向使用方的提示须**可读、可区分**，例如：

| 场景 | 提示方向（示例） |
| --- | --- |
| 手机号格式错误 | 请输入正确的手机号码 |
| 身份证/主体识别号错误 | 请输入正确的身份证号 / 主体识别号 |
| 收费方式未选 | 请选择收费方式 |
| 按头未填收费标准 | 请填写收费标准（元/头） |
| 按额未填费率 | 请填写交易费率 / 管理费率 |
| 费率超范围 | 费率须在 0～100% 之间 |
| 名称/身份号重复 | 供应商名称已存在 / 该身份识别号已登记 |
| 编号用尽 | 供应商编号已达上限，请联系管理员 |
| 删除受阻 | 存在未结算的结算单，无法删除 |
| 车牌格式错误 | 请输入正确的车辆号码 |
| 重复分配账号 | 该供应商已分配账号，不可重复分配 |
| 账号创建失败 | 账号创建失败：登录名已存在 / 用户保存失败 |

**本期不涉及**统一 HTTP 响应结构、错误码表等技术约定。

---

## 9. 非功能需求（摘要）

| 项 | 要求 |
| --- | --- |
| 易用性 | 类型、收费方式切换时联动及时，避免用户填写无效字段 |
| 一致性 | 校验规则、逻辑删除、分页默认值与项目其他台账模块保持一致 |
| 安全 | 联系方式、身份识别号在列表是否脱敏由项目统一规范（**默认列表不脱敏、按角色可扩展脱敏**） |

---

## 10. 修订记录

| 版本 | 说明 |
| --- | --- |
| 1.0 | 初稿：依据草稿与原型整理；明确收费方式联动、编号自动生成、类型与身份字段切换；剔除接口与技术栈描述 |
| 1.1 | 新增 §2.7、§5.6 分配账号：拼音首字母+id 登录名、角色 103、仅一次；删除联动删平台用户 |
| 1.3 | §2.8、§5.5：存在未结算结算单时禁止删除 |