dingdanquanliucheng/开发任务清单与验收标准.md

# 订单管理系统开发任务清单与验收标准

## 1. 文档说明

### 1.1 依据文档

- 《确定版需求说明书.md》
- 《数据库.sql》
- 《系统标准API文档.md》
- 《字段映射检查表.md》（如字段口径发生冲突，以该文档与 API 文档共同校验）

### 1.2 范围说明

本清单覆盖订单管理系统完整前后端开发任务，包括：

- WEB 业务员端
- 小程序管理层端
- 小程序司机端
- WEB 管理后台
- 后端 API、数据库、权限、定时任务、第三方接口、审计与报表

### 1.3 技术选型

| 层级 | 技术 | 说明 |
| --- | --- | --- |
| 后端语言 | Python | 后端统一使用 Python 开发 |
| 后端框架 | FastAPI | 用于构建标准 HTTP/JSON API，支持自动接口文档、类型校验和异步扩展 |
| 数据库 | MySQL 8.0+ | 业务数据持久化，使用 `utf8mb4` 字符集 |
| ORM/迁移 | SQLAlchemy + Alembic | 数据模型映射与数据库版本迁移 |
| 参数校验 | Pydantic | 请求、响应、配置项和业务 DTO 校验 |
| 鉴权 | JWT Token | 登录后通过 `Authorization: Bearer <token>` 访问接口 |
| 文件存储 | 阿里云 OSS | 图片、视频、导入文件、导出文件统一存储 |
| AI/OCR | 阿里云模型/OCR | 一期真实接入，封装为可替换适配层 |
| WEB 前端 | Vue 3 + Vite | WEB 业务员端和 WEB 管理后台统一使用 Vue 开发 |
| WEB UI 组件 | Element Plus | 适合后台、表格、表单、弹窗、分页等管理类页面 |
| 状态管理 | Pinia | 登录态、用户信息、权限菜单、页面状态管理 |
| 路由 | Vue Router | WEB 端页面路由和权限拦截 |
| 小程序 | 微信原生小程序 | 使用微信开发者工具开发管理层端和司机端 |

### 1.4 总体验收原则

- 所有接口返回结构符合统一响应体：`code`、`message`、`data`。
- 除登录接口外，所有接口必须校验 `Authorization: Bearer <token>`。
- 所有列表接口支持分页，并返回 `total`、`page_no`、`page_size`、`list`。
- 所有新增、修改、删除、提交、审批、取消、接单、揽货、送达等关键操作写入 `audit_log`。
- 所有状态流转必须校验当前状态，非法流转返回 `40005`。
- 所有角色的数据范围和字段可见性必须在后端控制，不能只依赖前端隐藏。
- 金额、利润、利润率、欠款、统计数据必须以后端计算结果为准。
- 与数据库字段、API 字段、需求字段不一致的地方，开发前必须明确映射并记录。

## 2. 开发里程碑

| 阶段 | 目标 | 主要交付物 | 验收标准 |
| --- | --- | --- | --- |
| M1 基础工程 | 完成前后端工程骨架、数据库初始化、认证权限基础能力 | 工程结构、数据库迁移、登录鉴权、角色菜单 | 可登录、可获取当前用户、接口统一响应与错误码可用 |
| M2 基础资料 | 完成客户、产品、工厂/供应商、配置管理 | CRUD、列表、详情、导入、配置接口和页面 | 基础资料可维护，去重、分页、权限、审计可验证 |
| M3 订单主流程 | 完成订单创建、提交、审批、下发文本、状态追踪 | 订单 API、审批 API、业务员端、管理层端 | 从录单到审批通过可完整闭环，利润计算正确 |
| M4 履约与司机端 | 完成物流任务、司机接单、揽货、送达、附件上传 | 司机任务 API、小程序司机端、附件记录 | 司机只能看本人任务，任务状态与订单状态联动正确 |
| M5 提醒与 AI | 完成物流超时、欠款、沉默客户提醒，AI 识别与修正 | 定时任务、提醒 API、AI 记录、修正页面 | 提醒只生成一次或按规则生成，AI 原始与修正结果均留存 |
| M6 报表与审计 | 完成业绩统计、导出、审计日志查询 | 报表 API、导出文件、审计后台 | 月/季/年统计正确，导出可下载，日志可追溯 |
| M7 联调验收 | 完成端到端测试、权限测试、异常测试、数据核对 | 测试记录、缺陷清单、验收清单 | 核心流程无阻断缺陷，验收用例全部通过 |

## 3. 后端开发任务清单

### 3.1 基础工程与数据库

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-001 | 后端工程初始化 | 使用 Python + FastAPI 建立 API 服务、环境配置、日志、统一异常处理 | 服务可启动；健康检查可访问；异常返回统一 JSON |
| BE-002 | 数据库初始化 | 基于 `数据库.sql` 建表，建立初始化脚本或迁移流程 | 所有表创建成功；字符集为 `utf8mb4`；索引与唯一约束存在 |
| BE-003 | 数据访问层 | 使用 SQLAlchemy 建立核心表模型、仓储或 Mapper | 表字段映射完整；逻辑删除字段默认生效 |
| BE-004 | ID 与编号生成 | 支持主键 ID、订单编号、任务编号生成 | 并发创建不重复；订单号和任务号唯一 |
| BE-005 | 统一响应与错误码 | 实现 `code/message/data`、分页响应、错误码映射 | 参数错、未登录、无权限、资源不存在、重复、状态非法均返回文档约定错误码 |
| BE-006 | 审计日志基础能力 | 封装审计日志写入 | 关键操作能记录操作人、时间、类型、业务主键、前后值、结果 |
| BE-007 | 文件存储服务 | 图片、视频、导入文件、导出文件统一接入阿里云 OSS 对象存储 | 上传成功返回文件 URL、文件名、类型、大小；文件元数据写入 `file_attachment`；凭证通过安全配置管理 |

### 3.2 认证、角色、权限

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-101 | 登录接口 | `POST /api/auth/login`，校验账号、密码、角色类型 | 成功返回 token、用户、角色、菜单、权限；失败返回明确错误 |
| BE-102 | 当前用户接口 | `GET /api/auth/me` | token 有效时返回当前用户信息；token 无效返回 `40002` |
| BE-103 | 退出登录接口 | `POST /api/auth/logout` | 退出后 token 不可继续访问受保护接口 |
| BE-104 | 角色权限模型 | 基于 `sys_user`、`sys_role`、`sys_menu` 实现权限判断 | 不同角色访问未授权接口返回 `40003` |
| BE-105 | 数据范围控制 | 业务员、司机、管理层、管理员分别限制数据范围 | 业务员只能访问本人订单/客户/提醒；司机只能访问本人任务；管理层可访问全量订单和财务字段 |
| BE-106 | 字段级脱敏 | 财务与客户敏感字段按角色屏蔽 | 司机端不返回客户敏感与财务字段；业务员不可越权查看利润等字段 |

### 3.3 客户管理

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-201 | 新增客户 | `POST /api/customers` | 姓名 + 手机号重复返回 `40006`；成功写入 `crm_customer` |
| BE-202 | 客户列表 | `GET /api/customers` | 支持姓名、手机号、类型、结算方式、业务员、分页筛选 |
| BE-203 | 客户详情 | `GET /api/customers/{customer_id}` | 返回结算、账期、欠款、归属业务员等字段 |
| BE-204 | 客户导入 | `POST /api/customers/import` | 按姓名 + 手机号去重；返回总数、成功数、重复数、失败数、失败明细 |
| BE-205 | 客户自动同步 | 订单创建时新客户自动写入客户库 | 不存在客户时自动创建；存在时复用客户 ID |
| BE-206 | 欠款字段维护 | 支持订单结算与欠款记录联动 | 客户欠款金额与 `customer_arrears` 可核对 |

### 3.4 产品管理

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-301 | 新增产品 | `POST /api/products` | 必填字段校验；成功写入 `product` |
| BE-302 | 产品列表 | `GET /api/products` | 支持名称、规格、分类、状态、分页筛选 |
| BE-303 | 产品详情 | `GET /api/products/{product_id}` | 返回成本价、售价、规格、单位、分类、状态 |
| BE-304 | 产品状态控制 | 禁用产品不可被新订单误选或需明确提示 | 禁用产品创建订单时被拦截或提示 |
| BE-305 | 产品快照 | 订单明细保存产品名称、规格、单位快照 | 产品后续修改不影响历史订单快照 |
| BE-306 | 产品分类管理 | 管理员维护产品分类，不将分类固定写死为工业品/日用品 | 可新增、编辑、停用分类；产品创建时从分类字典中选择；报表按配置分类汇总 |

### 3.5 工厂/供应商管理

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-401 | 新增工厂/供应商 | `POST /api/suppliers` | 成功写入 `base_supplier`，支持类型、模板类型、联系人 |
| BE-402 | 工厂/供应商列表 | `GET /api/suppliers` | 支持名称、类型、状态、分页筛选 |
| BE-403 | 下发文本生成 | `POST /api/orders/{order_id}/supplier-text` | `approved` 订单可生成可复制文本；不同模板类型返回对应内容 |
| BE-404 | 工厂字典约束 | 工厂仅作为基础字典，不建设工厂独立登录端 | 无工厂登录入口；仅后台维护数据 |
| BE-405 | 确认下发工厂 | 生成/确认下发工厂文本后推动订单状态流转 | 点击确认下发后，订单由 `approved` 变为 `pending_factory`，并写入审计日志 |

### 3.6 订单管理

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-501 | 创建订单 | `POST /api/orders`，写入 `sales_order`、`sales_order_item` | 默认状态 `draft`；明细至少一条；金额字段计算正确 |
| BE-502 | 利润计算 | 利润 = 销售价 - 成本价 - 回扣 - 运费 - 税费 - 其他费用 | 订单总利润、行利润、利润率与测试数据手工计算一致 |
| BE-503 | 提交审核 | `POST /api/orders/{order_id}/submit` | `draft` 可提交为 `pending_approve`；记录提交时间；重复提交返回 `40005` 或 `40006` |
| BE-504 | 订单详情 | `GET /api/orders/{order_id}` | 返回主信息、明细、审批记录、物流信息、备注；按角色控制字段 |
| BE-505 | 订单列表 | `GET /api/orders` | 支持状态、客户、业务员、工厂、来源、时间、分页筛选 |
| BE-506 | 订单取消 | `POST /api/orders/{order_id}/cancel` | 草稿/待审核可直接取消；已通过或履约中进入 `cancel_pending` 等待审批；记录原因和时间 |
| BE-507 | 状态变更 | `POST /api/orders/{order_id}/status` | 只允许定义内状态流转；非法状态返回 `40005` |
| BE-508 | 订单通知 | 状态变化后生成相关提醒或通知 | 相关角色可收到通知；无关角色不可见 |
| BE-509 | 订单快照 | 保存客户、产品、审批人等历史快照 | 基础资料修改后历史订单显示仍保持原快照 |
| BE-510 | 电商订单标记 | 使用订单来源标签识别电商平台订单 | 报表统计可按规则剔除电商订单 |
| BE-511 | 订单固定提成 | 每个订单维护固定提成金额，暂不按公式自动计算 | 创建或编辑订单时可保存订单提成金额；报表提成核对金额按订单固定提成汇总 |

### 3.7 审批管理

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-601 | 最终审批 | `POST /api/orders/{order_id}/approve` | 管理层可审批；通过后状态变更为 `approved`；退回为 `rejected` |
| BE-602 | 审批记录 | 写入 `sales_order_approve_log` | 记录审批类型、结果、意见、审批人、时间 |
| BE-603 | 审批利润展示数据 | 审批接口或详情提供利润计算过程 | 管理层可看到销售、成本、回扣、运费、税费、其他费用、利润率 |
| BE-604 | 取消审批 | `POST /api/orders/{order_id}/cancel-approve` | `cancel_pending` 订单取消需审批；审批通过后订单进入 `canceled`，审批拒绝后回到取消前状态 |
| BE-605 | 退回通知 | 审批退回通知业务员 | 业务员能在提醒或通知中看到退回原因 |

### 3.8 司机任务与履约

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-700 | 创建/分配司机任务 | 管理后台或管理层手动创建并分配司机任务 | 可选择订单、司机、取货地址、送达地址、取件内容、数量、工厂；不会在审批通过后自动创建 |
| BE-701 | 司机任务列表 | `GET /api/driver/tasks` | 司机只能查看本人任务；支持状态和分页 |
| BE-702 | 司机任务详情 | `GET /api/driver/tasks/{task_id}` | 仅返回取货地址、送达地址、取件内容、数量、工厂、任务状态、有限业务员信息 |
| BE-703 | 接单 | `POST /api/driver/tasks/{task_id}/accept` | `pending` 变为 `accepted`；记录接单时间 |
| BE-704 | 确认揽货 | `POST /api/driver/tasks/{task_id}/pickup` | `accepted` 变为 `picked_up`；支持照片附件；记录揽货时间 |
| BE-705 | 确认送达 | `POST /api/driver/tasks/{task_id}/deliver` | `picked_up` 变为 `delivered`；记录送达时间 |
| BE-706 | 订单状态联动 | 司机任务状态变化同步订单状态 | 接单、揽货、送达后订单状态按规则更新 |
| BE-707 | 附件记录 | 上传图片、视频等文件到阿里云 OSS，并写入 `file_attachment` | 附件与任务或订单关联；可追溯上传人、文件 URL、文件类型、文件大小和时间 |

### 3.9 物流与 AI

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-800 | 手动物流节点维护 | 一期支持人工录入、编辑物流节点 | 可按订单维护物流节点；节点写入 `logistics_trace`；订单详情可查看 |
| BE-801 | 物流轨迹查询 | `GET /api/logistics/{order_id}/trace` | 一期优先返回手动维护的物流节点；保留快递 100 对接结构，第三方失败返回 `40009` |
| BE-802 | 物流轨迹存储 | 保存或缓存轨迹到 `logistics_trace` | 节点时间、描述、类型、来源可查询 |
| BE-803 | 物流超时提醒 | 首个物流节点超过 2 天无流转提醒一次 | 相同订单同一规则不重复提醒 |
| BE-804 | AI 图片识别 | `POST /api/ai/recognize` | 一期真实接入阿里云模型能力，包含图片 OCR 识别；识别服务做成可替换适配层；保存 `raw_result`、`confidence`、`image_url` 到 `ai_recognition_log` |
| BE-805 | AI 结果修正 | `POST /api/ai/recognize/{log_id}/correct` | 保存人工修正结果；原始结果不被覆盖 |
| BE-806 | AI 人工确认规则 | AI 仅辅助，不自动审批 | 识别结果必须经人工确认后才进入业务流程 |

### 3.10 提醒管理

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-901 | 欠款提醒检查 | `POST /api/reminders/arrears/check` 或定时任务 | 按客户结算方式、账期起算口径、到期日生成提醒 |
| BE-902 | 沉默客户提醒检查 | `POST /api/reminders/inactive-customers/check` 或定时任务 | 超过配置周期且金额达到阈值的客户生成提醒 |
| BE-903 | 提醒记录 | 写入 `system_reminder` | 包含提醒类型、业务类型、业务 ID、接收人、标题、内容、状态 |
| BE-904 | 提醒状态 | 支持 pending/sent/read/canceled | 状态可流转；已取消提醒不再展示为待处理 |
| BE-905 | 提醒配置 | 阈值、周期、账期起算口径从配置读取 | 修改配置后新生成提醒按新配置执行 |
| BE-906 | 欠款生成模式配置 | 管理员配置欠款生成模式，提供 `shipped` 发货后记账、`delivered` 送达后记账两个选项，默认 `delivered` | 新订单按当前配置节点生成欠款记录；订单结算后关闭欠款记录 |

### 3.11 报表统计

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-1001 | 业绩统计 | `GET /api/reports/performance` | 支持月、季、年；返回订单数量、订单金额、按产品分类汇总金额、订单固定提成汇总 |
| BE-1002 | 分类统计 | 按管理员维护的产品分类配置汇总，不硬编码工业品/日用品 | 新增分类后，报表可按新分类准确汇总 |
| BE-1003 | 电商订单剔除 | 按订单来源标签剔除电商平台订单 | 同一时间范围内含/不含电商订单统计结果可核对 |
| BE-1004 | 统计缓存 | 可使用 `performance_stat_cache` 缓存统计结果 | 缓存生成、查询、刷新规则明确且结果一致 |
| BE-1005 | 报表导出 | `GET /api/reports/performance/export` | 返回可下载 `file_url`；导出内容与页面统计一致 |

### 3.12 配置与审计

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| BE-1101 | 配置查询 | `GET /api/configs/{config_key}` | 返回配置键、值、名称、备注 |
| BE-1102 | 配置更新 | `PUT /api/configs/{config_key}` | 更新成功返回 `updated=true`；写审计日志 |
| BE-1103 | 审计日志列表 | `GET /api/audit-logs` | 支持业务类型、业务 ID、操作人、时间、分页筛选 |
| BE-1104 | 敏感操作审计 | 覆盖新增、修改、删除、提交、审批、取消、接单、揽货、送达 | 任一关键操作均可在审计日志查到 |

## 4. 前端开发任务清单

### 4.1 通用前端能力

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| FE-001 | 前端工程初始化 | 建立 Vue 3 + Vite WEB 工程，以及微信原生小程序工程 | WEB 端可本地启动和构建；小程序可在微信开发者工具中运行；环境变量可区分开发/生产 |
| FE-002 | 登录态管理 | 保存 token、请求自动带 Authorization | 登录后可访问受保护页面；过期后跳转登录 |
| FE-003 | 路由与权限菜单 | 按 `menus`、`permissions` 渲染导航和按钮 | 未授权菜单和按钮不可见；直接访问路由被拦截 |
| FE-004 | API 请求封装 | 统一处理响应体、错误码、分页、loading | 接口错误能展示明确提示；分页组件与后端参数一致 |
| FE-005 | 表单与校验组件 | 必填、手机号、金额、数量、日期等校验 | 无效输入不能提交；错误提示清晰 |
| FE-006 | 文件/图片/视频上传组件 | 支持司机揽货照片、AI 识别图片、视频、导入文件，文件存储到阿里云 OSS | 上传成功返回文件地址或附件 ID；失败有提示 |
| FE-007 | 字段脱敏展示 | 根据后端返回和角色控制页面字段 | 司机、业务员等角色看不到越权字段 |

### 4.2 WEB 业务员端

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| FE-101 | 业务员登录页 | 支持账号、密码、角色类型登录 | 登录成功进入业务员首页；失败显示错误信息 |
| FE-102 | 订单录入页 | 录入客户、物流、订单明细、回扣、运费、税费、其他费用 | 必填校验完整；可新增/删除明细；金额自动汇总 |
| FE-103 | 产品选择与快照 | 支持选择产品并带出规格、单位、成本、售价 | 手动修改后按提交值保存；历史订单不受产品修改影响 |
| FE-104 | 新客户自动提示 | 按姓名 + 手机号判断是否新客户 | 新客户提交后可在客户列表看到 |
| FE-105 | 订单提交审核 | 草稿订单可提交审核 | 提交后状态变为待审核；按钮状态同步变化 |
| FE-106 | 我的订单列表 | 查看本人订单，按状态、客户、时间筛选 | 仅显示本人订单；分页、筛选正常 |
| FE-107 | 订单详情页 | 展示订单、状态、物流、审批意见 | 业务员不可见无权限财务字段 |
| FE-108 | 订单取消 | 支持输入取消原因并提交 | 草稿/待审核可取消；已审批或履约中提交后显示 `cancel_pending` 等待审批 |
| FE-109 | 提醒中心 | 查看物流超时、欠款、沉默客户、退回通知 | 可区分未读/已读；只显示本人相关提醒 |
| FE-110 | 状态追踪 | 展示订单状态流转与物流节点 | 状态与后端一致；物流节点按时间排序 |

### 4.3 小程序管理层端

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| FE-201 | 管理层登录 | 支持管理层角色登录 | 登录后进入审批首页 |
| FE-202 | 待审批列表 | 展示待审核订单 | 支持分页、搜索；只展示可审批数据 |
| FE-203 | 审批详情页 | 展示完整订单、明细、客户、利润计算过程 | 可看到销售额、成本、回扣、运费、税费、其他费用、利润、利润率 |
| FE-204 | 审批操作 | 支持通过、退回、填写意见 | 操作后状态更新；业务员收到通知 |
| FE-205 | 取消审批 | 处理 `cancel_pending` 订单取消申请 | 审批结果写入记录；通过后进入已取消，拒绝后回到取消前状态 |
| FE-206 | 下发文本查看与确认 | 查看、复制并确认工厂下发文本 | 文本内容与订单和工厂模板一致；确认下发后订单由 `approved` 进入 `pending_factory` |
| FE-207 | 经营数据概览 | 查看核心订单与业绩指标 | 数据与报表接口一致 |
| FE-208 | 司机任务创建/分配 | 管理层手动为订单创建并分配司机任务 | 可选择司机、取货地址、送达地址、取件内容、数量、工厂；保存后司机端可见 |

### 4.4 小程序司机端

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| FE-301 | 司机登录 | 支持司机角色登录 | 登录后进入任务列表 |
| FE-302 | 任务列表 | 按待接单、已接单、已揽货、已送达查看任务 | 司机只能看到本人任务；分页和状态筛选正常 |
| FE-303 | 任务详情 | 展示取货地址、送达地址、取件内容、数量、工厂、有限业务员信息 | 不展示客户敏感信息、报价、成本、利润、回扣 |
| FE-304 | 接单 | 司机确认接单 | 任务状态变为已接单，记录接单时间 |
| FE-305 | 确认揽货 | 上传照片并确认揽货 | 必须按规则上传照片；状态变为已揽货 |
| FE-306 | 确认送达 | 确认送达并填写备注 | 状态变为已送达；订单状态联动 |
| FE-307 | 异常提示 | 状态非法、无权限、上传失败等提示 | 错误提示清晰，不出现空白页或无反馈 |

### 4.5 WEB 管理后台

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| FE-401 | 后台首页与菜单 | 管理员进入系统后台 | 菜单按权限渲染；刷新后登录态保持 |
| FE-402 | 用户管理 | 维护用户、角色归属、状态 | 用户可新增/编辑/停用；停用用户无法登录 |
| FE-403 | 角色与菜单管理 | 维护角色、菜单、按钮权限 | 权限调整后重新登录生效 |
| FE-404 | 客户管理 | 客户新增、列表、详情、导入 | 去重、导入结果、分页、筛选正常 |
| FE-405 | 产品管理 | 产品新增、列表、详情、状态维护 | 禁用产品状态可见；筛选正常 |
| FE-405A | 产品分类管理 | 管理员维护可扩展产品分类 | 可新增、编辑、停用分类；报表分类配置可引用 |
| FE-406 | 工厂/供应商管理 | 维护工厂、供应商、模板类型 | 可新增、查询、停用；订单下发可选择 |
| FE-407 | 订单管理后台 | 管理员查看全量订单 | 可按状态、客户、业务员、工厂、时间筛选 |
| FE-407A | 司机任务管理 | 管理员手动创建、分配、查看司机任务 | 任务保存后司机端可见；任务状态可追踪 |
| FE-408 | 物流与 AI 管理 | 手动维护物流节点、上传物流图片、发起 AI 识别、人工修正 | 物流节点可在订单详情显示；原始结果与修正结果均可查看 |
| FE-409 | 提醒管理 | 查看系统提醒记录 | 可按类型、状态、接收人筛选 |
| FE-410 | 报表统计 | 月/季/年业绩报表、分类统计 | 页面数据与导出数据一致 |
| FE-411 | 报表导出 | 发起导出并下载文件 | 下载文件可打开，内容准确 |
| FE-412 | 系统配置 | 维护提醒周期、金额阈值、账期口径、欠款生成模式、报表分类映射等配置 | 配置保存成功后新规则生效 |
| FE-413 | 审计日志 | 查询操作日志 | 支持筛选；关键操作可追溯 |

## 5. 联调任务清单

| 编号 | 任务 | 说明 | 验收标准 |
| --- | --- | --- | --- |
| INT-001 | 接口契约联调 | 按 API 文档逐个校验请求、响应、错误码 | 前后端字段一致；无临时字段依赖 |
| INT-002 | 登录权限联调 | 校验业务员、管理层、司机、管理员权限 | 未授权接口和页面均不可访问 |
| INT-003 | 订单主流程联调 | 录单、提交、审批、下发、履约、完成 | 全流程状态正确，审计日志完整 |
| INT-004 | 取消流程联调 | 草稿取消、待审核取消、已通过取消、履约中取消 | 不同状态按规则处理，审批记录完整 |
| INT-005 | 司机端联调 | 任务列表、详情、接单、揽货、送达 | 任务和订单状态联动，附件保存成功 |
| INT-006 | 提醒联调 | 物流超时、欠款、沉默客户提醒 | 触发条件准确，不重复生成不该重复的提醒 |
| INT-007 | AI 联调 | 图片上传、识别、修正、留痕 | AI 失败有兜底提示；修正结果保存成功 |
| INT-008 | 报表联调 | 页面统计与数据库核对、导出核对 | 统计口径一致，导出内容一致 |
| INT-009 | 异常联调 | 参数错、无权限、资源不存在、状态非法、第三方失败 | 错误码与提示符合 API 文档 |
| INT-010 | 数据安全联调 | 越权访问、字段泄露、司机端敏感字段检查 | 后端不返回越权数据 |

## 6. 核心业务验收用例

### 6.1 订单主流程验收

| 步骤 | 操作 | 预期结果 |
| --- | --- | --- |
| 1 | 业务员创建新客户订单 | 自动创建客户；订单状态为 `draft`；利润计算完成 |
| 2 | 业务员提交审核 | 状态变为 `pending_approve`；记录提交时间 |
| 3 | 管理层查看审批详情 | 可看到完整订单、成本、回扣、利润、利润率 |
| 4 | 管理层审批通过 | 状态变为 `approved`；写入审批记录 |
| 5 | 生成并确认工厂下发文本 | 返回可复制文本，内容包含订单核心信息；确认后状态变为 `pending_factory` |
| 6 | 管理层或管理员手动创建/分配司机任务 | 司机端可看到任务 |
| 7 | 司机接单、揽货、送达 | 任务状态依次变更，订单状态联动 |
| 8 | 送达后生成欠款记录 | 按后台欠款生成模式配置生成欠款；默认订单送达后生成，结算后关闭 |
| 9 | 查看审计日志 | 录单、提交、审批、接单、揽货、送达均有日志 |

### 6.2 利润计算验收

| 场景 | 输入 | 预期结果 |
| --- | --- | --- |
| 单明细订单 | 销售价 100，成本 60，回扣 5，运费 10，税费 3，其他 2 | 利润 20，利润率 20% |
| 多明细订单 | 多行分别计算行利润 | 订单总利润等于所有行利润与总费用口径汇总结果 |
| 销售价为 0 | 销售价为 0 或非法金额 | 返回参数错误或业务规则错误，不产生错误利润率 |
| 修改产品成本 | 历史订单已保存快照 | 历史订单利润不受产品新成本影响 |
| 固定提成 | 订单录入固定提成金额 50 | 报表提成核对金额按 50 汇总，不按公式二次计算 |

### 6.3 权限验收

| 角色 | 可访问 | 不可访问 |
| --- | --- | --- |
| 业务员 | 本人订单、本人客户、本人提醒、订单录入 | 他人订单、全局利润、后台配置 |
| 管理层 | 全量订单、审批、利润、报表 | 系统底层配置修改（除明确授权外） |
| 司机 | 本人任务、任务相关有限信息 | 客户敏感信息、报价、成本、利润、回扣 |
| 管理员 | 基础资料、用户角色、配置、审计、报表 | 不应绕过业务状态规则直接破坏数据 |

### 6.4 提醒验收

| 类型 | 触发条件 | 预期结果 |
| --- | --- | --- |
| 物流超时 | 首个物流节点后超过 2 天无流转 | 生成一次业务员提醒 |
| 欠款超期 | 超过客户账期配置未结算 | 生成欠款提醒，关联客户和订单 |
| 长期未下单 | 超过配置周期且金额达到阈值 | 生成沉默客户提醒 |
| 不满足阈值 | 金额低于配置阈值 | 不生成沉默客户提醒 |
| 欠款生成模式 | 后台配置为 `shipped` 发货后记账或 `delivered` 送达后记账 | 新订单按配置节点生成欠款记录，结算后关闭 |

### 6.5 AI 验收

| 场景 | 操作 | 预期结果 |
| --- | --- | --- |
| 识别成功 | 上传图片发起识别 | 保存原始结果、置信度、建议结果 |
| 识别失败 | 第三方接口失败 | 返回统一错误；记录异常；允许人工录入 |
| 人工修正 | 提交修正结果 | 保存修正结果，不覆盖原始结果 |
| 相似订单 | AI 识别到疑似重复 | 页面提示人工确认，不自动合并或审批 |

## 7. 数据库验收标准

| 表 | 验收点 |
| --- | --- |
| `sys_user`、`sys_role`、`sys_menu` | 支持用户、角色、菜单权限；用户名唯一；角色编码唯一 |
| `crm_customer` | 姓名 + 手机号唯一；支持归属业务员、结算方式、账期、欠款 |
| `product` | 支持产品名称、规格、单位、分类、成本价、售价、状态 |
| 产品分类配置 | 支持管理员维护产品分类，并配置报表分类映射 |
| `base_supplier` | 支持工厂/供应商类型、联系人、模板类型 |
| `sales_order` | 保存订单主信息、金额汇总、利润、状态、时间节点、快照 |
| `sales_order_item` | 保存订单明细、产品快照、数量、单价、费用、行利润 |
| `sales_order_approve_log` | 保存提交审核、最终审批、取消审批记录 |
| `logistics_task` | 保存司机任务、状态、接单/揽货/送达时间 |
| `logistics_trace` | 保存物流轨迹节点 |
| `customer_arrears` | 保存客户欠款、账期起算、到期日、状态 |
| `system_reminder` | 保存提醒类型、业务关联、接收人、标题、内容、状态 |
| `system_config` | 保存提醒、阈值、账期等配置 |
| `file_attachment` | 保存阿里云 OSS 中的图片、视频、导入文件、导出文件等附件元数据 |
| `ai_recognition_log` | 保存 AI 原始结果、置信度、人工修正 |
| `performance_stat_cache` | 保存统计缓存数据 |
| `audit_log` | 保存关键操作审计记录 |

## 8. 非功能验收标准

| 类别 | 标准 |
| --- | --- |
| 安全 | 接口必须鉴权；越权返回 `40003`；敏感字段由后端控制不返回 |
| 一致性 | 订单、任务、提醒、欠款、报表数据可从数据库追溯核对 |
| 幂等性 | 重复提交、重复审批、重复接单等操作不能造成重复数据或非法状态 |
| 可维护性 | 状态值、错误码、配置键应集中定义，避免散落硬编码 |
| 可观测性 | 关键异常、第三方接口失败、定时任务执行结果应记录日志 |
| 性能 | 常用列表按索引字段查询；分页接口不能一次返回全量数据 |
| 兼容性 | Vue WEB 端主流浏览器可用；小程序端按微信原生小程序开发，并在微信开发者工具和目标微信版本可用 |
| 数据安全 | 历史快照不随基础资料修改而被破坏；删除采用逻辑删除 |

## 9. 交付物清单

| 类型 | 交付物 | 验收标准 |
| --- | --- | --- |
| 后端 | Python/FastAPI API 服务代码、MySQL 数据库迁移、定时任务、第三方接口适配 | 接口测试通过，核心流程可跑通 |
| WEB 业务员端 | Vue 登录、录单、订单、提醒、状态追踪页面 | 业务员主流程可独立完成 |
| 小程序管理层端 | 审批、取消审批、下发文本、经营数据页面 | 管理层审批流程可完成 |
| 小程序司机端 | 任务列表、详情、接单、揽货、送达页面 | 司机履约流程可完成 |
| WEB 管理后台 | Vue 基础资料、用户角色、配置、报表、审计页面 | 管理员可完成系统维护 |
| 测试 | 接口测试、权限测试、端到端测试、验收记录 | 核心用例全部通过，阻断缺陷清零 |
| 文档 | 部署说明、接口联调说明、配置说明、操作手册 | 新环境可按文档部署并完成基础操作 |

## 10. 已确认实施口径

- 订单审批通过后先进入 `approved`，点击“生成/确认下发工厂文本”后再进入 `pending_factory`。
- 新增订单状态 `cancel_pending`，用于已审批或履约中订单的取消申请待审批场景。
- 司机任务由管理后台或管理层手动创建/分配，不在订单审批通过后自动创建。
- 一期物流保留接口和数据结构，支持手动录入物流节点；快递 100 真实对接暂不作为一期验收前置条件。
- 一期 AI 做“图片上传 + 阿里云模型/OCR 识别接口真实开发 + 人工修正留痕”，AI 模型服务以可替换适配层实现。
- 产品分类由管理员维护，不硬编码为工业品和日用品；报表按产品 `category` 和系统配置的分类映射统计。
- 每个订单维护固定提成金额，暂不设计自动计算公式。
- 欠款默认在订单送达后生成，结算后关闭；后台增加欠款生成模式配置，提供 `shipped` 发货后记账、`delivered` 送达后记账两个选项，默认 `delivered`。
- 小程序端按微信原生小程序开发。

## 11. 开发联调前准备事项

- 阿里云模型/OCR 调用凭证、开通地域、费用预算、识别字段范围需要在 AI 联调前准备；凭证不写入代码，使用环境变量或安全配置管理。
- 图片、视频和业务附件统一使用阿里云 OSS 对象存储；开发联调前需要准备 OSS Bucket、访问凭证、访问域名、上传大小限制和生命周期策略。
- 微信小程序发布所需 AppID、服务器域名备案、上传域名白名单和体验成员名单由甲方在开发联调前准备。