dingdanquanliucheng/确定版需求说明书.md

# 订单管理系统需求说明书（确定版）

## 1. 文档信息

- 项目名称：订单管理系统
- 文档名称：确定版需求说明书
- 文档版本：V1.0
- 编写日期：2026-05-05
- 适用端：WEB 业务员端、小程序管理层端、小程序司机端、WEB 管理后台

---

## 2. 项目背景

本系统用于管理销售订单、客户、产品、工厂、物流任务、回扣、欠款提醒和业绩统计等业务流程，覆盖业务员、管理层、秘书、司机和后台管理员等多个角色。

系统目标是实现订单从录入、审核、下发、履约到统计的完整闭环，同时支持权限隔离、信息可见性控制、提醒机制和 AI 辅助识别能力。

---

## 3. 建设目标

### 3.1 业务目标

1. 业务员可快速录入销售订单并提交审核。
2. 管理层可查看订单利润并进行最终审批。
3. 订单审批通过后可生成下发工厂的复制文本。
4. 司机可通过小程序完成接单、揽货、送达。
5. 系统可自动对物流超时、欠款超期、长期未下单客户进行提醒。
6. 后台可统一维护客户、产品、工厂、用户、角色和系统配置。

### 3.2 产品目标

- 建立订单从录入到完成的闭环管理。
- 建立不同角色的信息隔离与权限控制。
- 引入 AI 辅助识别与信息整理，提高录入和匹配效率。
- 通过配置化规则支持提醒和统计能力。

---

## 4. 角色定义

### 4.1 业务员

负责客户维护、订单录入、提交审核、查看个人订单、跟踪订单状态、处理系统提醒、发起取消申请等。

### 4.2 管理层 / 何总

负责审核销售单、查看完整订单信息、判断订单是否盈利、审批取消、查看全局经营数据。

### 4.3 何总秘书

负责物流图片录入、AI 识别辅助、订单信息整理等操作。

### 4.4 司机

负责接收运输任务、确认揽货、确认送达、上传照片、查看任务详情。

### 4.5 后台管理员

负责用户、角色、菜单、配置、客户、产品、工厂等基础数据管理，以及统计报表维护。

---

## 5. 端与模块划分

### 5.1 WEB 业务员端

用于业务员录单、查单、查看提醒、查看订单状态。

### 5.2 小程序管理层端

用于何总等管理人员审批订单、查看利润、处理取消审批、查看下发信息。

### 5.3 小程序司机端

用于司机查看任务、接单、揽货、送达、上传照片。

### 5.4 WEB 管理后台

用于客户、产品、工厂、员工、角色、菜单、配置、报表等基础管理。

---

## 6. 确认后的业务规则

### 6.1 订单状态定义

订单状态定义如下：

- 草稿
- 待审核
- 已通过
- 已退回
- 待下发工厂
- 待司机接单
- 已接单
- 已揽货
- 已送达
- 已取消
- 生产中
- 已发货
- 已完成
- 已结算

### 6.2 订单取消规则

- 草稿、待审核状态的订单可直接取消。
- 已通过后的订单取消需何总确认。
- 已进入履约阶段的订单，允许取消，但必须经过特殊审批规则。

### 6.3 新客户判定规则

- 新客户识别标准为：**手机号 + 姓名同时匹配**。
- 批量导入客户时，同样按姓名 + 手机号进行去重校验。

### 6.4 利润计算规则

利润公式统一如下：

- **利润 = 销售价 - 成本价 - 回扣 - 运费 - 税费 - 其他费用**
- **利润率 = 利润 ÷ 销售价 × 100%**

### 6.5 提醒规则

#### 6.5.1 物流超时提醒
- 第一个物流节点定义为：首次出现揽件/物流流转信息的节点。
- 当第一个物流节点超过 2 天无流转信息时，仅提醒一次。

#### 6.5.2 欠款提醒
- 月结客户信息维护在客户资料中。
- 欠款超期提醒起算节点支持配置：订单日期、对账日期、发货日期。
- 提醒对象为业务员。

#### 6.5.3 长时间未下单提醒
- 可配置客户长期未下单的周期。
- 可配置金额阈值。
- 低于金额阈值的小客户不纳入提醒范围。

### 6.6 AI 规则

- AI 仅用于辅助识别和整理。
- 最终结果由人工确认。
- 对识别不清晰或相似度高的订单，业务员或秘书需人工判断。
- AI 的原始识别结果与人工修正结果均需保留。
- AI 不作为自动审批的唯一依据。

### 6.7 工厂协同规则

- 当前工厂仅作为基础字典数据维护。
- 系统不建设工厂独立登录端。
- 审批通过后，系统生成可复制文本供人工发送给工厂。
- 不同工厂可生成不同模板内容，但本期均以文本复制为主。

### 6.8 司机端可见范围

司机端仅可查看以下信息：

- 取货地址
- 取件内容
- 数量
- 关联工厂
- 任务状态
- 部分所属业务员信息

司机端不可查看以下信息：

- 客户敏感信息
- 财务敏感信息
- 非任务相关内容

### 6.9 报表规则

- 业绩统计按月度、季度、年度维度展示。
- 报表统计内容包含订单数量、订单金额。
- 报表按工业品、日用品拆分统计。
- 电商平台订单通过订单来源标签进行识别并剔除。
- 报表支持导出。
- 提成核对相关统计纳入报表范围。

### 6.10 订单通知规则

- 订单状态变化时，相关角色可收到通知。
- 业务员仅能看到自己相关订单的有限信息。
- 管理层可查看订单全量信息，包括数量、成本、回扣、利润、报价等。

---

## 7. 核心业务流程

### 7.1 销售订单主流程

1. 业务员录入销售订单。
2. 系统识别客户是否存在。
3. 若客户不存在，则按手机号 + 姓名规则自动同步到客户库。
4. 业务员提交审核。
5. 管理层查看订单利润与相关信息后进行审批。
6. 审批通过后，系统生成下发工厂的复制文本。
7. 订单进入履约流程，由司机或相关人员继续处理物流任务。
8. 司机完成接单、揽货、送达。
9. 系统记录订单状态变更并支持追踪查询。

### 7.2 取消流程

- 草稿或待审核订单可直接取消。
- 已通过订单取消需何总确认。
- 已进入履约阶段的订单取消需走特殊审批规则。
- 取消操作需留痕。

### 7.3 物流提醒流程

- 系统监控订单的首个物流节点。
- 若首个物流节点超过 2 天未流转，自动提醒对应业务员。
- 提醒默认仅发送一次。

### 7.4 欠款提醒流程

- 系统根据客户月结信息和订单账期计算欠款。
- 对超过配置天数未结算的订单自动提醒业务员。
- 业务员负责后续催收跟进。

### 7.5 长时间未下单提醒流程

- 系统根据客户历史下单频率及最近下单时间判断是否长期未下单。
- 可配置金额阈值，低于阈值的客户可不纳入追踪。
- 提醒结果发送给业务员。

---

## 8. 功能需求说明

## 8.1 销售订单管理

### 8.1.1 销售单录入并提交审核

**功能描述：** 业务员录入销售订单，包括客户信息、物流信息、订单信息、回扣信息等，并提交审核。

**业务规则：**
- 如客户不存在，则根据手机号 + 姓名自动同步到客户库。
- 提交后订单进入待审核状态。
- 订单提交信息需记录提交人、提交时间。

### 8.1.2 查看个人历史销售订单

**功能描述：** 业务员查看自己历史提交的销售订单。

**权限规则：**
- 仅能查看与本人关联的订单。
- 显示字段按权限脱敏。

### 8.1.3 销售订单状态查询与追踪

**功能描述：** 查看订单状态与物流信息。

**业务规则：**
- 物流信息对接快递 100 接口。
- 支持订单及物流节点查询。

### 8.1.4 销售订单取消

**功能描述：** 业务员取消订单，或发起取消申请。

**业务规则：**
- 草稿、待审核状态可直接取消。
- 已通过订单取消需何总确认。
- 已进入履约阶段的订单取消需走特殊审批规则。
- 操作需记录取消原因与操作日志。

### 8.1.5 物流消息提醒

**功能描述：** 首个物流节点超时提醒业务员。

**业务规则：**
- 首个节点定义为首次揽件/首次物流流转。
- 超过 2 天无流转仅提醒一次。

### 8.1.6 订单进度信息通知

**功能描述：** 订单状态变化后向相关角色推送通知。

**权限规则：**
- 业务员只看自己相关订单的有限信息。
- 何总查看订单全部信息，包括数量、成本、回扣、利润、报价等。

### 8.1.7 物流图片录入与 AI 识别

**功能描述：** 何总秘书在泰兴工厂等场景下录入物流图片，并借助 AI 辅助识别订单信息。

**业务规则：**
- 支持自动识别与人工修正。
- 识别失败时可人工输入。
- 相似订单需人工判断是否重复。

### 8.1.8 长时间未下单提醒

**功能描述：** 对长时间未下单客户自动提醒业务员。

**业务规则：**
- 支持配置沉默周期。
- 支持配置金额阈值。
- 低于阈值客户可不提醒。

---

## 8.2 销售单审批管理

### 8.2.1 销售单最终审批

**功能描述：** 管理层根据订单信息进行最终审批。

**业务规则：**
- 系统自动匹配产品表，计算成本、利润和利润率。
- 审核页需展示计算过程与结果。
- 可一键通过或退回。
- 退回后业务员需收到通知。

### 8.2.2 审批通过后下发工厂

**功能描述：** 审批通过后生成可复制文本，供业务人员下发给工厂。

**业务规则：**
- 当前不要求工厂端系统对接。
- 不同工厂生成内容可不同，但本期以文本复制为主。

### 8.2.3 审批取消订单

**功能描述：** 对已审批订单进行取消审批。

**业务规则：**
- 与业务员端取消逻辑统一。
- 取消过程留痕。

### 8.2.4 回扣设置

**功能描述：** 录单时标记订单是否存在回扣，并录入金额。

**业务规则：**
- 回扣金额计入利润计算。
- 回扣信息可作为审核依据。

---

## 8.3 司机任务管理

### 8.3.1 查看任务详情

**功能描述：** 司机查看自己可执行的任务。

**可见信息：**
- 取货地址
- 取件内容
- 数量
- 关联工厂
- 所属业务员部分信息

**不可见信息：**
- 客户敏感信息
- 财务敏感信息
- 非任务相关内容

### 8.3.2 接单

**功能描述：** 司机确认接收任务。

### 8.3.3 确认揽货

**功能描述：** 司机拍照上传收货记录，并同步给业务员。

**业务规则：**
- 提交前可撤回。
- 提交后不可撤回。
- 图片存储至 COS。
- 通过微信订阅消息通知相关人员。

### 8.3.4 确认送达

**功能描述：** 司机确认送达仓库并更新任务状态。

---

## 8.4 产品管理

### 8.4.1 产品录入

**功能描述：** 录入产品基础信息，用于后续订单报价和成本核算。

**字段定义：**
- 产品名称
- 规格
- 单位
- 分类
- 成本价
- 售价
- 状态
- 备注

### 8.4.2 产品查询

**功能描述：** 支持按名称、规格、分类等条件查询产品。

---

## 8.5 工厂/供应商管理

### 8.5.1 维护合作工厂信息

**功能描述：** 维护合作工厂及供应商基础信息。

**业务规则：**
- 当前作为字典数据使用。
- 不要求工厂独立登录系统。

---

## 8.6 客户管理

### 8.6.1 客户信息录入与查询

**功能描述：** 录入和查询直接客户信息，支持批量导入。

**业务规则：**
- 姓名 + 电话作为重复校验标准。
- 支持导入模板。
- 重复数据支持去重或提示。

### 8.6.2 欠款及超期提醒

**功能描述：** 系统自动统计月结客户欠款总额，并推送超期提醒。

**业务规则：**
- 月结信息维护在客户资料中。
- 起算节点可配置为订单日期、对账日期、发货日期。
- 提醒对象为业务员。

---

## 8.7 员工管理

### 8.7.1 员工信息维护

**功能描述：** 管理后台维护员工基础信息。

**说明：** 当前原始需求未展开详细字段，后续可补充。

---

## 8.8 业绩统计报表

### 8.8.1 月度 / 季度 / 年度业绩统计

**功能描述：** 系统统计销售数据并生成可导出报表。

**统计维度：**
- 订单数量
- 订单金额
- 工业品 / 日用品分类
- 排除电商平台订单

**业务规则：**
- 产品分类需在产品表中维护。
- 电商平台订单需在订单数据中有来源标签。
- 支持导出。
- 提成核对相关统计纳入报表范围。

---

## 8.9 后台系统管理

### 8.9.1 后台用户管理

管理系统登录用户。

### 8.9.2 角色管理

管理业务员、管理层、司机、秘书、管理员等角色权限。

### 8.9.3 菜单管理

管理不同角色可访问的菜单。

### 8.9.4 配置管理

支持维护提醒周期、金额阈值、物流超时规则、欠款起算规则等配置项。

---

## 9. 权限与可见性规则

### 9.1 业务员

可查看自己订单、自己的客户、自己的任务及系统提醒。

### 9.2 管理层

可查看全量订单信息、成本、利润、回扣、报价、审批记录等。

### 9.3 司机

可查看任务信息、取货地址、取件内容、数量等，不可查看敏感财务信息。

### 9.4 管理员

可管理系统全部基础配置、用户、角色、菜单、字典及统计信息。

---

## 10. 配置项

后台支持以下配置项：

- 物流首节点超时时间
- 长时间未下单周期
- 欠款提醒超时时间
- 欠款提醒起算节点
- 金额阈值
- 提醒方式
- 订单利润判断阈值
- 是否允许某些状态取消

---

## 11. 验收标准

### 11.1 订单录入

- 可完成订单新增、客户自动识别、提交审核。
- 新客户按姓名 + 手机号规则写入客户库。

### 11.2 审核流程

- 审核时可看到计算结果和计算过程。
- 可通过、退回并触发消息通知。

### 11.3 取消流程

- 草稿、待审核订单可直接取消。
- 已通过订单需何总确认取消。
- 已进入履约阶段的订单取消需走特殊审批规则。

### 11.4 司机任务

- 司机可接单、揽货、送达。
- 揽货可上传照片并同步通知。

### 11.5 提醒流程

- 物流超时提醒可触发一次。
- 欠款提醒和长时间未下单提醒可按配置生效。

### 11.6 报表

- 可查看月度、季度、年度业绩统计并导出。

---

## 12. 接口级需求

本章节定义系统各模块需要提供的接口能力、请求/响应约定、关键入参、关键返回值以及接口级业务规则。具体接口命名在后续技术设计阶段可再细化，但本章作为需求基准需保持稳定。

### 12.1 通用接口约定

#### 12.1.1 接口风格
- 接口采用 HTTP/HTTPS 方式提供服务。
- 接口能力覆盖查询、新增、修改、删除、提交、审批、撤回、导出、通知等场景。
- 所有业务接口均需进行登录态校验和权限校验。
- 涉及敏感数据的接口需根据角色进行字段脱敏或隐藏。

#### 12.1.2 通用请求约定
- 所有登录后接口需携带用户身份信息。
- 列表类接口支持分页。
- 查询类接口支持按条件筛选。
- 涉及修改类接口需记录操作人、操作时间、操作前后变化。

#### 12.1.3 通用响应约定
- 接口响应需包含成功/失败状态。
- 失败时需返回可读的错误提示。
- 分页接口需返回总数、当前页、每页条数、数据列表。

### 12.2 登录与权限接口

#### 12.2.1 登录接口
**功能：** 用户登录系统。

**输入：** 账号、密码、角色类型。

**输出：** 用户信息、权限信息、可访问菜单、登录态凭证。

#### 12.2.2 当前用户信息接口
**功能：** 获取当前登录用户信息。

**输出：** 用户基本信息、所属角色、可见范围、菜单权限。

#### 12.2.3 退出登录接口
**功能：** 注销当前登录态。

### 12.3 订单接口

#### 12.3.1 订单新增接口
**功能：** 创建销售订单。

**输入：** 客户信息、订单明细、物流信息、回扣信息、备注等。

**业务规则：**
- 新客户按姓名 + 手机号规则自动识别并同步到客户库。
- 创建后默认进入草稿状态。

#### 12.3.2 订单提交审核接口
**功能：** 将草稿订单提交至待审核状态。

**输入：** 订单 ID。

**输出：** 提交结果、状态变更结果。

#### 12.3.3 订单详情接口
**功能：** 查询订单详情。

**输出：** 订单基础信息、订单明细、状态信息、物流信息、审批信息、回扣信息、权限内可见字段。

#### 12.3.4 订单列表接口
**功能：** 查询订单列表。

**输入：** 订单状态、客户名称、手机号、时间范围、业务员、工厂、订单来源、分页参数等。

**输出：** 订单列表、总数、分页信息。

#### 12.3.5 订单取消接口
**功能：** 取消订单或发起取消申请。

**业务规则：**
- 草稿、待审核订单可直接取消。
- 已通过订单需何总确认。
- 已进入履约阶段的订单需特殊审批。

#### 12.3.6 订单状态流转接口
**功能：** 更新订单状态。

**适用场景：** 审核通过、退回、取消、履约推进、完成等。

#### 12.3.7 订单通知接口
**功能：** 当订单状态变化时，推送消息给相关角色。

### 12.4 审批接口

#### 12.4.1 销售单最终审批接口
**功能：** 管理层审批订单。

**输入：** 订单 ID、审批结果、审批意见。

**输出：** 审批结果、状态变更结果、通知结果。

**业务规则：**
- 审核时需返回利润、利润率及计算过程。
- 审批结果包括通过和退回。

#### 12.4.2 取消审批接口
**功能：** 对已审批或履约中的订单进行取消确认。

**输入：** 订单 ID、审批结果、审批意见。

### 12.5 客户接口

#### 12.5.1 客户新增接口
**功能：** 新增客户信息。

**输入：** 姓名、手机号、地址、结算方式、月结天数、账期起算口径、客户类型、归属业务员、备注等。

#### 12.5.2 客户列表接口
**功能：** 查询客户列表。

**输入：** 姓名、手机号、客户类型、结算方式、业务员、分页参数等。

#### 12.5.3 客户详情接口
**功能：** 查询客户详情。

#### 12.5.4 客户导入接口
**功能：** 批量导入客户。

**业务规则：**
- 以姓名 + 手机号去重。
- 重复数据按规则提示或合并。

### 12.6 产品接口

#### 12.6.1 产品新增接口
**功能：** 新增产品基础信息。

**输入：** 产品名称、规格、单位、分类、成本价、售价、状态、备注。

#### 12.6.2 产品列表接口
**功能：** 查询产品列表。

#### 12.6.3 产品详情接口
**功能：** 查询产品详情。

### 12.7 工厂/供应商接口

#### 12.7.1 工厂新增接口
**功能：** 新增工厂或供应商基础信息。

#### 12.7.2 工厂列表接口
**功能：** 查询工厂或供应商信息。

#### 12.7.3 工厂下发文本生成接口
**功能：** 根据订单和工厂类型生成可复制文本。

**业务规则：**
- 当前不对接工厂端系统。
- 输出内容支持按不同工厂模板生成。

### 12.8 司机任务接口

#### 12.8.1 任务列表接口
**功能：** 查询司机可接任务列表。

#### 12.8.2 任务详情接口
**功能：** 查询司机任务详情。

#### 12.8.3 接单接口
**功能：** 司机确认接单。

#### 12.8.4 确认揽货接口
**功能：** 司机上传揽货照片并确认揽货。

**业务规则：**
- 提交前允许撤回。
- 提交后不可撤回。
- 图片上传后存储到 COS。

#### 12.8.5 确认送达接口
**功能：** 司机确认任务送达。

### 12.9 物流与 AI 接口

#### 12.9.1 物流查询接口
**功能：** 查询订单物流轨迹。

**业务规则：**
- 对接快递 100 接口。
- 返回物流节点信息。

#### 12.9.2 物流超时提醒接口
**功能：** 系统定时检查物流首节点超时情况。

#### 12.9.3 图片识别接口
**功能：** 对物流图片进行 AI 识别。

**输出：** 识别结果、识别置信度、原始结果、建议修正内容。

#### 12.9.4 图片修正接口
**功能：** 人工修正 AI 识别结果并保存。

### 12.10 提醒接口

#### 12.10.1 欠款提醒接口
**功能：** 识别并推送欠款超期提醒。

#### 12.10.2 长时间未下单提醒接口
**功能：** 识别并推送长期未下单提醒。

### 12.11 报表接口

#### 12.11.1 业绩统计接口
**功能：** 查询月度、季度、年度业绩统计结果。

#### 12.11.2 报表导出接口
**功能：** 导出统计报表。

**业务规则：**
- 统计结果需支持按工业品、日用品拆分。
- 电商平台订单需按来源标签剔除。
- 提成核对相关数据纳入统计。

### 12.12 配置接口

#### 12.12.1 配置查询接口
**功能：** 查询系统配置项。

#### 12.12.2 配置更新接口
**功能：** 修改提醒周期、金额阈值、起算口径等配置项。

### 12.13 审计接口要求

- 所有新增、修改、删除、提交、审批、取消、接单、揽货、送达等操作都需写入操作日志。
- 关键业务操作需记录操作人、时间、结果、备注。
- 涉及审批的操作需记录审批前后状态。

## 13. 数据库表设计草案

以下为满足当前需求的核心数据库表设计草案，字段为需求级建议，后续技术实现可在不改变业务语义的前提下细化类型、索引与约束。

### 13.1 用户表 `sys_user`

**用途：** 存储系统登录用户。

**核心字段：**
- `id`：主键
- `username`：登录账号
- `password_hash`：密码哈希
- `real_name`：姓名
- `mobile`：手机号
- `role_id`：角色 ID
- `status`：启用/停用
- `created_at`：创建时间
- `updated_at`：更新时间

### 13.2 角色表 `sys_role`

**用途：** 存储角色信息。

**核心字段：**
- `id`：主键
- `role_name`：角色名称
- `role_code`：角色编码
- `status`：状态
- `created_at`：创建时间
- `updated_at`：更新时间

### 13.3 菜单表 `sys_menu`

**用途：** 存储系统菜单。

**核心字段：**
- `id`：主键
- `parent_id`：父级菜单 ID
- `menu_name`：菜单名称
- `menu_path`：路由路径
- `menu_type`：菜单类型
- `permission_code`：权限标识
- `status`：状态
- `sort_no`：排序号

### 13.4 客户表 `crm_customer`

**用途：** 存储客户资料。

**核心字段：**
- `id`：主键
- `customer_name`：客户姓名
- `mobile`：手机号
- `address`：地址
- `settlement_type`：结算方式
- `settlement_days`：月结天数
- `settlement_start_type`：账期起算口径
- `customer_type`：客户类型
- `salesman_id`：归属业务员 ID
- `credit_limit`：信用额度
- `arrears_amount`：欠款金额
- `status`：状态
- `remark`：备注
- `created_at`：创建时间
- `updated_at`：更新时间

### 13.5 产品表 `product`

**用途：** 存储产品基础信息。

**核心字段：**
- `id`：主键
- `product_name`：产品名称
- `specification`：规格
- `unit`：单位
- `category`：分类
- `cost_price`：成本价
- `sale_price`：售价
- `status`：状态
- `remark`：备注
- `created_at`：创建时间
- `updated_at`：更新时间

### 13.6 工厂/供应商表 `base_supplier`

**用途：** 存储工厂和供应商信息。

**核心字段：**
- `id`：主键
- `supplier_name`：名称
- `supplier_type`：类型（工厂/供应商）
- `contact_name`：联系人
- `contact_mobile`：联系电话
- `address`：地址
- `template_type`：下发文本模板类型
- `status`：状态
- `remark`：备注

### 13.7 销售订单主表 `sales_order`

**用途：** 存储订单主信息。

**核心字段：**
- `id`：主键
- `order_no`：订单编号
- `customer_id`：客户 ID
- `customer_name_snapshot`：客户名称快照
- `customer_mobile_snapshot`：手机号快照
- `salesman_id`：业务员 ID
- `order_source`：订单来源标签
- `order_status`：订单状态
- `sale_price_total`：销售价总额
- `cost_price_total`：成本价总额
- `rebate_total`：回扣总额
- `freight_total`：运费总额
- `tax_total`：税费总额
- `other_fee_total`：其他费用总额
- `profit_total`：利润
- `profit_rate`：利润率
- `factory_id`：工厂 ID
- `delivery_type`：发货类型
- `created_by`：创建人
- `submitted_at`：提交时间
- `approved_by`：审批人
- `approved_at`：审批时间
- `canceled_at`：取消时间
- `completed_at`：完成时间
- `remark`：备注
- `created_at`：创建时间
- `updated_at`：更新时间

### 13.8 销售订单明细表 `sales_order_item`

**用途：** 存储订单明细行。

**核心字段：**
- `id`：主键
- `order_id`：订单 ID
- `product_id`：产品 ID
- `product_name_snapshot`：产品名称快照
- `specification_snapshot`：规格快照
- `unit_snapshot`：单位快照
- `quantity`：数量
- `sale_price`：销售单价
- `cost_price`：成本单价
- `rebate_amount`：回扣金额
- `freight_amount`：运费分摊
- `tax_amount`：税费分摊
- `other_fee_amount`：其他费用分摊
- `line_profit`：行利润
- `remark`：备注

### 13.9 审批记录表 `sales_order_approve_log`

**用途：** 存储订单审批记录。

**核心字段：**
- `id`：主键
- `order_id`：订单 ID
- `approve_type`：审批类型（提交审核/最终审批/取消审批）
- `approve_result`：结果（通过/退回/拒绝）
- `approve_opinion`：审批意见
- `approver_id`：审批人 ID
- `approver_name`：审批人名称快照
- `created_at`：审批时间

### 13.10 物流任务表 `logistics_task`

**用途：** 存储司机运输任务。

**核心字段：**
- `id`：主键
- `order_id`：订单 ID
- `task_no`：任务编号
- `driver_id`：司机用户 ID
- `status`：任务状态
- `pickup_address`：取货地址
- `delivery_address`：送达地址
- `pickup_content`：取件内容
- `quantity`：数量
- `factory_id`：工厂 ID
- `accepted_at`：接单时间
- `pickup_confirmed_at`：揽货时间
- `delivered_at`：送达时间
- `remark`：备注
- `created_at`：创建时间
- `updated_at`：更新时间

### 13.11 物流节点表 `logistics_trace`

**用途：** 存储物流轨迹节点。

**核心字段：**
- `id`：主键
- `order_id`：订单 ID
- `task_id`：任务 ID
- `node_time`：节点时间
- `node_desc`：节点描述
- `node_type`：节点类型
- `source_platform`：来源平台
- `created_at`：创建时间

### 13.12 客户欠款记录表 `customer_arrears`

**用途：** 存储欠款统计与提醒记录。

**核心字段：**
- `id`：主键
- `customer_id`：客户 ID
- `order_id`：订单 ID
- `arrears_amount`：欠款金额
- `settlement_start_date`：起算日期
- `due_date`：到期日期
- `status`：状态（pending/overdue/paid/closed）
- `reminded_at`：提醒时间
- `created_at`：创建时间

### 13.13 提醒记录表 `system_reminder`

**用途：** 存储系统提醒记录。

**核心字段：**
- `id`：主键
- `reminder_type`：提醒类型
- `biz_type`：业务类型
- `biz_id`：业务主键
- `receiver_user_id`：接收人 ID
- `reminder_title`：提醒标题
- `reminder_content`：提醒内容
- `status`：状态（pending/sent/read/canceled）
- `sent_at`：发送时间
- `created_at`：创建时间

### 13.14 系统配置表 `system_config`

**用途：** 存储可配置业务规则。

**核心字段：**
- `id`：主键
- `config_key`：配置键
- `config_value`：配置值
- `config_name`：配置名称
- `remark`：备注
- `status`：状态
- `updated_at`：更新时间

### 13.15 文件附件表 `file_attachment`

**用途：** 存储图片、附件等文件元数据。

**核心字段：**
- `id`：主键
- `biz_type`：业务类型
- `biz_id`：业务主键
- `file_name`：文件名
- `file_url`：文件地址
- `file_type`：文件类型
- `file_size`：文件大小
- `created_by`：上传人
- `created_at`：创建时间

### 13.16 AI 识别结果表 `ai_recognition_log`

**用途：** 存储图片识别的原始结果与修正结果。

**核心字段：**
- `id`：主键
- `biz_type`：业务类型
- `biz_id`：业务主键
- `image_url`：图片地址
- `raw_result`：原始识别结果
- `confidence`：置信度
- `corrected_result`：人工修正结果
- `created_by`：操作人
- `created_at`：创建时间

### 13.17 业绩统计缓存表 `performance_stat_cache`

**用途：** 存储业绩统计结果缓存。

**核心字段：**
- `id`：主键
- `stat_type`：统计类型（月/季/年）
- `stat_period`：统计周期
- `industry_amount`：工业品金额
- `daily_amount`：日用品金额
- `order_count`：订单数量
- `order_amount`：订单金额
- `commission_amount`：提成核对金额
- `created_at`：创建时间

---

## 14. 接口字段级定义

以下对前述接口补充字段级定义。字段为需求级定义，后续技术实现时可根据具体框架补充数据类型、校验规则与错误码。

### 14.1 登录与权限接口字段定义

#### 14.1.1 登录接口

**请求字段：**
- `username`：登录账号
- `password`：登录密码
- `role_type`：角色类型

**响应字段：**
- `user_id`：用户 ID
- `real_name`：姓名
- `role_id`：角色 ID
- `role_name`：角色名称
- `token`：登录凭证
- `menus`：可访问菜单列表
- `permissions`：权限标识列表

#### 14.1.2 当前用户信息接口

**响应字段：**
- `user_id`：用户 ID
- `username`：账号
- `real_name`：姓名
- `mobile`：手机号
- `role_id`：角色 ID
- `role_name`：角色名称
- `menus`：菜单列表
- `permissions`：权限列表

#### 14.1.3 退出登录接口

**请求字段：**
- 无必填字段

**响应字段：**
- `success`：是否成功

### 14.2 订单接口字段定义

#### 14.2.1 订单新增接口

**请求字段：**
- `customer_name`：客户姓名
- `customer_mobile`：客户手机号
- `customer_address`：客户地址
- `order_source`：订单来源标签
- `delivery_type`：发货类型
- `factory_id`：工厂 ID
- `remark`：备注
- `items`：订单明细列表
- `rebate_total`：回扣总额
- `freight_total`：运费总额
- `tax_total`：税费总额
- `other_fee_total`：其他费用总额

**订单明细字段：**
- `product_id`：产品 ID
- `product_name`：产品名称
- `specification`：规格
- `unit`：单位
- `quantity`：数量
- `sale_price`：销售单价
- `cost_price`：成本单价
- `rebate_amount`：回扣金额
- `freight_amount`：运费分摊
- `tax_amount`：税费分摊
- `other_fee_amount`：其他费用分摊
- `remark`：备注

**响应字段：**
- `order_id`：订单 ID
- `order_no`：订单编号
- `order_status`：订单状态
- `profit_total`：利润
- `profit_rate`：利润率

#### 14.2.2 订单提交审核接口

**请求字段：**
- `order_id`：订单 ID

**响应字段：**
- `order_id`：订单 ID
- `order_status`：变更后的状态
- `submitted_at`：提交时间

#### 14.2.3 订单详情接口

**响应字段：**
- `order_id`：订单 ID
- `order_no`：订单编号
- `customer_id`：客户 ID
- `customer_name`：客户姓名
- `customer_mobile`：客户手机号
- `salesman_id`：业务员 ID
- `order_source`：订单来源标签
- `order_status`：订单状态
- `delivery_type`：发货类型
- `factory_id`：工厂 ID
- `sale_price_total`：销售价总额
- `cost_price_total`：成本价总额
- `rebate_total`：回扣总额
- `freight_total`：运费总额
- `tax_total`：税费总额
- `other_fee_total`：其他费用总额
- `profit_total`：利润
- `profit_rate`：利润率
- `items`：订单明细列表
- `approve_logs`：审批记录列表
- `logistics_info`：物流信息
- `remark`：备注

#### 14.2.4 订单列表接口

**请求字段：**
- `order_status`：订单状态
- `customer_name`：客户姓名
- `customer_mobile`：客户手机号
- `salesman_id`：业务员 ID
- `factory_id`：工厂 ID
- `order_source`：订单来源标签
- `start_time`：开始时间
- `end_time`：结束时间
- `page_no`：页码
- `page_size`：每页条数

**响应字段：**
- `total`：总数
- `page_no`：页码
- `page_size`：每页条数
- `list`：订单列表

#### 14.2.5 订单取消接口

**请求字段：**
- `order_id`：订单 ID
- `cancel_reason`：取消原因
- `cancel_opinion`：取消意见

**响应字段：**
- `order_id`：订单 ID
- `order_status`：变更后的状态
- `canceled_at`：取消时间

#### 14.2.6 订单状态流转接口

**请求字段：**
- `order_id`：订单 ID
- `target_status`：目标状态
- `remark`：备注

**响应字段：**
- `order_id`：订单 ID
- `order_status`：变更后的状态

#### 14.2.7 订单通知接口

**请求字段：**
- `biz_id`：业务主键
- `biz_type`：业务类型
- `receiver_user_id`：接收人 ID
- `title`：通知标题
- `content`：通知内容

**响应字段：**
- `success`：是否成功

### 14.3 审批接口字段定义

#### 14.3.1 销售单最终审批接口

**请求字段：**
- `order_id`：订单 ID
- `approve_result`：审批结果
- `approve_opinion`：审批意见

**响应字段：**
- `order_id`：订单 ID
- `order_status`：审批后状态
- `profit_total`：利润
- `profit_rate`：利润率
- `approve_time`：审批时间

#### 14.3.2 取消审批接口

**请求字段：**
- `order_id`：订单 ID
- `approve_result`：审批结果
- `approve_opinion`：审批意见

**响应字段：**
- `order_id`：订单 ID
- `order_status`：审批后状态

### 14.4 客户接口字段定义

#### 14.4.1 客户新增接口

**请求字段：**
- `customer_name`：客户姓名
- `mobile`：手机号
- `address`：地址
- `settlement_type`：结算方式
- `settlement_days`：月结天数
- `settlement_start_type`：账期起算口径
- `customer_type`：客户类型
- `salesman_id`：归属业务员 ID
- `credit_limit`：信用额度
- `remark`：备注

**响应字段：**
- `customer_id`：客户 ID
- `customer_name`：客户姓名
- `mobile`：手机号

#### 14.4.2 客户列表接口

**请求字段：**
- `customer_name`：客户姓名
- `mobile`：手机号
- `customer_type`：客户类型
- `settlement_type`：结算方式
- `salesman_id`：归属业务员 ID
- `page_no`：页码
- `page_size`：每页条数

**响应字段：**
- `total`：总数
- `page_no`：页码
- `page_size`：每页条数
- `list`：客户列表

#### 14.4.3 客户详情接口

**响应字段：**
- `customer_id`：客户 ID
- `customer_name`：客户姓名
- `mobile`：手机号
- `address`：地址
- `settlement_type`：结算方式
- `settlement_days`：月结天数
- `settlement_start_type`：账期起算口径
- `customer_type`：客户类型
- `salesman_id`：归属业务员 ID
- `credit_limit`：信用额度
- `arrears_amount`：欠款金额
- `status`：状态
- `remark`：备注

#### 14.4.4 客户导入接口

**请求字段：**
- `file_url`：导入文件地址
- `import_mode`：导入模式

**响应字段：**
- `total_count`：总条数
- `success_count`：成功条数
- `duplicate_count`：重复条数
- `fail_count`：失败条数
- `fail_list`：失败明细

### 14.5 产品接口字段定义

#### 14.5.1 产品新增接口

**请求字段：**
- `product_name`：产品名称
- `specification`：规格
- `unit`：单位
- `category`：分类
- `cost_price`：成本价
- `sale_price`：售价
- `status`：状态
- `remark`：备注

**响应字段：**
- `product_id`：产品 ID
- `product_name`：产品名称

#### 14.5.2 产品列表接口

**请求字段：**
- `product_name`：产品名称
- `specification`：规格
- `category`：分类
- `status`：状态
- `page_no`：页码
- `page_size`：每页条数

**响应字段：**
- `total`：总数
- `page_no`：页码
- `page_size`：每页条数
- `list`：产品列表

#### 14.5.3 产品详情接口

**响应字段：**
- `product_id`：产品 ID
- `product_name`：产品名称
- `specification`：规格
- `unit`：单位
- `category`：分类
- `cost_price`：成本价
- `sale_price`：售价
- `status`：状态
- `remark`：备注

### 14.6 工厂/供应商接口字段定义

#### 14.6.1 工厂新增接口

**请求字段：**
- `supplier_name`：名称
- `supplier_type`：类型
- `contact_name`：联系人
- `contact_mobile`：联系电话
- `address`：地址
- `template_type`：模板类型
- `status`：状态
- `remark`：备注

**响应字段：**
- `supplier_id`：工厂/供应商 ID
- `supplier_name`：名称

#### 14.6.2 工厂列表接口

**请求字段：**
- `supplier_name`：名称
- `supplier_type`：类型
- `status`：状态
- `page_no`：页码
- `page_size`：每页条数

**响应字段：**
- `total`：总数
- `page_no`：页码
- `page_size`：每页条数
- `list`：工厂/供应商列表

#### 14.6.3 工厂下发文本生成接口

**请求字段：**
- `order_id`：订单 ID
- `supplier_id`：工厂/供应商 ID

**响应字段：**
- `text_content`：可复制文本内容
- `template_type`：模板类型

### 14.7 司机任务接口字段定义

#### 14.7.1 任务列表接口

**请求字段：**
- `status`：任务状态
- `page_no`：页码
- `page_size`：每页条数

**响应字段：**
- `total`：总数
- `page_no`：页码
- `page_size`：每页条数
- `list`：任务列表

#### 14.7.2 任务详情接口

**响应字段：**
- `task_id`：任务 ID
- `order_id`：订单 ID
- `task_no`：任务编号
- `status`：任务状态
- `pickup_address`：取货地址
- `delivery_address`：送达地址
- `pickup_content`：取件内容
- `quantity`：数量
- `factory_id`：工厂 ID
- `salesman_name`：业务员姓名（按可见范围返回）

#### 14.7.3 接单接口

**请求字段：**
- `task_id`：任务 ID

**响应字段：**
- `task_id`：任务 ID
- `status`：任务状态
- `accepted_at`：接单时间

#### 14.7.4 确认揽货接口

**请求字段：**
- `task_id`：任务 ID
- `photo_files`：照片文件列表
- `remark`：备注

**响应字段：**
- `task_id`：任务 ID
- `status`：任务状态
- `pickup_confirmed_at`：揽货时间
- `attachment_ids`：附件 ID 列表

#### 14.7.5 确认送达接口

**请求字段：**
- `task_id`：任务 ID
- `remark`：备注

**响应字段：**
- `task_id`：任务 ID
- `status`：任务状态
- `delivered_at`：送达时间

### 14.8 物流与 AI 接口字段定义

#### 14.8.1 物流查询接口

**请求字段：**
- `order_id`：订单 ID

**响应字段：**
- `order_id`：订单 ID
- `logistics_company`：物流公司
- `tracking_no`：运单号
- `trace_list`：物流节点列表

**物流节点字段：**
- `node_time`：节点时间
- `node_desc`：节点描述
- `node_type`：节点类型
- `source_platform`：来源平台

#### 14.8.2 物流超时提醒接口

**请求字段：**
- `order_id`：订单 ID
- `node_type`：节点类型
- `timeout_hours`：超时时长

**响应字段：**
- `reminder_result`：提醒结果

#### 14.8.3 图片识别接口

**请求字段：**
- `image_url`：图片地址
- `biz_type`：业务类型
- `biz_id`：业务 ID

**响应字段：**
- `raw_result`：原始识别结果
- `confidence`：置信度
- `suggested_result`：建议修正结果

#### 14.8.4 图片修正接口

**请求字段：**
- `log_id`：识别记录 ID
- `corrected_result`：人工修正结果

**响应字段：**
- `log_id`：识别记录 ID
- `saved`：是否保存成功

### 14.9 提醒接口字段定义

#### 14.9.1 欠款提醒接口

**请求字段：**
- `customer_id`：客户 ID
- `order_id`：订单 ID
- `arrears_amount`：欠款金额
- `settlement_start_date`：起算日期
- `due_date`：到期日期

**响应字段：**
- `reminder_id`：提醒 ID
- `status`：提醒状态

#### 14.9.2 长时间未下单提醒接口

**请求字段：**
- `customer_id`：客户 ID
- `last_order_time`：最近订单时间
- `threshold_days`：提醒周期
- `threshold_amount`：金额阈值

**响应字段：**
- `reminder_id`：提醒 ID
- `status`：提醒状态

### 14.10 报表接口字段定义

#### 14.10.1 业绩统计接口

**请求字段：**
- `stat_type`：统计类型（月/季/年）
- `start_date`：开始日期
- `end_date`：结束日期
- `category_type`：分类维度

**响应字段：**
- `stat_period`：统计周期
- `order_count`：订单数量
- `order_amount`：订单金额
- `industry_amount`：工业品金额
- `daily_amount`：日用品金额
- `commission_amount`：提成核对金额

#### 14.10.2 报表导出接口

**请求字段：**
- `stat_type`：统计类型
- `start_date`：开始日期
- `end_date`：结束日期

**响应字段：**
- `file_url`：导出文件地址

### 14.11 配置接口字段定义

#### 14.11.1 配置查询接口

**请求字段：**
- `config_key`：配置键

**响应字段：**
- `config_key`：配置键
- `config_value`：配置值
- `config_name`：配置名称
- `remark`：备注

#### 14.11.2 配置更新接口

**请求字段：**
- `config_key`：配置键
- `config_value`：配置值
- `remark`：备注

**响应字段：**
- `config_key`：配置键
- `updated`：是否更新成功

### 14.12 审计接口要求

- 所有新增、修改、删除、提交、审批、取消、接单、揽货、送达等操作都需写入操作日志。
- 日志至少包含：操作人、操作时间、操作类型、业务主键、操作前值、操作后值、结果、备注。

---

## 15. 字段映射检查表

为了统一《确定版需求说明书》《数据库.sql》《系统标准API文档》的字段口径，新增《字段映射检查表.md》作为三份文档之间的字段对照依据。

字段映射检查表定义了：

- 核心业务对象的统一字段名
- 数据库字段命名
- API 字段命名
- 状态字段统一口径
- 三份文档的对齐说明

后续开发、数据库设计和接口设计均以三份文档及《字段映射检查表.md》为准。