docs: add CRM plan management design spec (2026-05-05)

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/superpowers/specs/2026-05-05-crm-plan-management-design.md

@@ -0,0 +1,300 @@
+# CRM 计划管理模块 — 设计规格
+
+**版本：** 1.0  
+**日期：** 2026-05-05  
+**状态：** 待评审  
+**依据：** `plan/计划需求.md`、`plan/sx.sql`（库表对齐参考）、`plan/vehicle_management.sql`（车辆字段参考）
+
+---
+
+## 1. 背景与范围
+
+### 1.1 现状
+
+- 管理端前端：`crm/web`（Vue 3）
+- 生产后端：`crm/backend`（RuoYi-Vue-Plus / Spring Boot）
+- Python 重构后端：`crm/py-backend`（未纳入本规格交付范围）
+
+### 1.2 本规格覆盖
+
+在 CRM 内新增 **计划管理** 子系统，包含：
+
+- 计划管理（含与合同、调价函、证照门禁、运输与二维码、地磅与现场、核对与归档）
+- 自有车辆信息维护
+- 运输公司及车辆信息维护
+- 运输任务 / 运输信息
+- 库存相关能力与 **盘存统计分析**（口径见 §8）
+- **运输结算**（列表、多选生成结算单、审核、开票与汇款信息登记）
+
+### 1.3 边界声明（已确认）
+
+| 项目 | 结论 |
+|------|------|
+| **财务报销子系统（bx）** | **本阶段不对接。** 不向 bx 推送单据、不拉取报销状态、不共用 bx 审批实例。 |
+| **结算与票款** | 运输结算单、审核、通知开票、发票附件、汇款凭证均在 **CRM 库表与页面** 内完成记录与状态流转。 |
+| **用户与权限** | 复用 CRM **用户管理、角色管理**；计划相关权限使用独立权限标识（如 `crm:plan:*`，具体前缀以实现时 RuoYi 约定为准）。 |
+
+### 1.4 非目标（当前版本）
+
+- 与 bx 报销系统的接口、单点登录扩展、数据同步
+- 将计划模块完整迁移到 `crm/py-backend`（可作为远期选项，不阻塞 Java 交付）
+
+---
+
+## 2. 目标与成功标准
+
+### 2.1 业务目标
+
+1. 从 **合同** 发起计划，支持一单多产品；框架合同价格可通过 **调价函** 调整并保留 **版本历史**。
+2. 产品维度支持 **易制毒 / 易制爆**；命中时计划行必须先具备 **购买证、运输证** 才可进入运输安排。
+3. 运输支持 **自有车辆** 与 **承运商车辆**；生成可分享的 **二维码** 供司机 / 现场使用；待入库、待出库任务需 **通知现场**。
+4. 按规则识别 **待入库 / 待出库**，自动生成 **地磅单** 信息并在计划中可见；现场确认并上传地磅单与出入库附件。
+5. 司机扫码回传运输单据与数量等信息。
+6. **专员 B** 整单核对、**专员 C** 确认运费后 **归档**。
+7. 运输历史总览、多选生成 **运输结算单** 并经 **审核** 后完成开票通知、票据与汇款信息登记。
+8. **盘存统计分析** 可按约定口径输出报表或图表。
+
+### 2.2 成功标准（验收锚点）
+
+- 端到端流程在测试环境可演示：合同 → 计划 →（证照）→ 运输与二维码 → 地磅/现场 → 司机回传 → 核对 → 费用确认 → 归档。
+- 所有业务表名 **`plan_` 前缀**，与 `plan/sx.sql` 同库建模时可合并迁移脚本。
+- 权限仅使用 CRM 既有账号体系，无独立登录入口。
+
+---
+
+## 3. 角色与权限（对应需求中的 A / B / C）
+
+需求中的「计划专员 A / B / C」映射为 **可配置角色或数据权限 + 菜单权限**，建议：
+
+| 角色含义 | 典型职责 | 权限要点 |
+|----------|----------|----------|
+| 专员 A | 发起与安排运输、生成二维码、线下分发 | 计划编辑、运输安排、二维码生成、现场通知 |
+| 专员 B | 运输完成后的整单核对 | 核对通过/退回 |
+| 专员 C | 运输费用确认、归档 | 费用确认、归档 |
+| 现场人员 | 待入/待出相关地磅与附件 | 地磅确认、附件上传、仅可见指派任务 |
+
+具体 `Sa-Token` 权限码在实现阶段按 RuoYi 模块命名规范批量定义（如 `crm:plan:transport:arrange`）。
+
+---
+
+## 4. 核心业务过程（七步）与状态
+
+### 4.1 跟进状态（字典，与需求一致）
+
+`待采购`、`等客户通知`、`待安排`、`计划取消`、`待发货`、`已发货`、`待入库`、`已入库`、`待出库`、`已出库`。
+
+### 4.2 完成状态
+
+`是` / `否`（建议字典 `crm_plan_finished`：`1` / `0`）。
+
+### 4.3 单据类别
+
+`直销单`、`入库单`、`出库单`、`云栋单`。
+
+### 4.4 流程与状态关系（逻辑约束）
+
+- **步骤 1**：从合同生成计划头与多行；行上带入合同单价（可后改）；框架合同取当前生效 **调价版本** 对应价格。
+- **步骤 2**：若行关联产品为易制毒或易制爆，则必须存在有效 **购买证、运输证** 附件记录后，才允许进入步骤 3。
+- **步骤 3**：创建或关联运输记录，选择自有或承运商车辆，生成 **二维码**；若为 **待入库/待出库**，向现场人员发送 **系统内待办/任务**（初版默认站内消息 + 列表筛选；短信/企微为可选扩展，见 §10）。
+- **步骤 4**：满足 §5 规则时进入 **待入库** 或 **待出库**，自动生成 **地磅单** 主记录；现场上传地磅单及出入库附件后更新状态。
+- **步骤 5**：司机通过扫码入口提交回传数据（见 §7）。
+- **步骤 6**：专员 B 核对通过。
+- **步骤 7**：专员 C 确认运费，计划置 **归档**，完成状态为 **是**。
+
+状态迁移须在后端用 **显式校验**（禁止仅靠前端禁用按钮）。
+
+---
+
+## 5. 待入库 / 待出库 / 地磅规则
+
+**判定公司名称集合（可配置，禁止写死在代码）：**
+
+- `安庆市山峡化工有限公司`
+- `安徽云栋化工有限公司`
+
+**规则（与需求一致）：**
+
+- 若 **目的地** 为上述任一公司 → 业务类型为 **待入库**（并触发地磅与现场流程）。
+- 若 **供应商名称** 为上述任一公司 → 业务类型为 **待出库**（并触发地磅与现场流程）。
+
+**地磅单：** 满足上述条件时 **自动生成** 地磅单主数据；计划列表 / 详情需展示关联地磅摘要信息。
+
+---
+
+## 6. 合同侧改造：框架合同调价函
+
+### 6.1 要求
+
+- 框架合同下商品价格可多次调整。
+- 每次调整必须对应一份 **调价函**（附件 + 元数据）。
+- 保留 **全版本历史**（版本号、生效时间、操作人、关联附件）。
+
+### 6.2 数据归属
+
+- 调价函实体建议落在 CRM 合同域（表名可与现有 `crm_contract_*` 命名一致），计划模块通过 **合同 ID + 版本 ID** 解析行价格。
+- 若现有合同表无「框架合同」标志，需增加 **合同类型** 或布尔字段以区分框架合同。
+
+### 6.3 计划取价
+
+- 新建计划行时：**默认价** = 合同行当前生效版本单价；允许用户在计划内再次改价（与调价函历史分离，仅记录计划行上的成交价即可）。
+
+---
+
+## 7. 产品主数据扩展
+
+在 CRM **产品** 上增加：
+
+- `是否易制毒`（布尔或字典）
+- `是否易制爆`（布尔或字典）
+
+计划行通过产品 ID 继承属性并触发证照校验。
+
+---
+
+## 8. 库存与盘存统计
+
+需求仅描述「库存管理」「盘存统计分析」。本规格约定：
+
+- **库存管理（初版）：** 以 **计划行上的入库数 / 出库数 / 预估数** 及确认后的单据为准，是否落 **独立库存台账表** 由实现阶段根据现有 CRM 是否已有库存模块决定；若无，则 **`plan_inventory_ledger`（示例名）** 由确认后的出入库事件回写，避免双录。
+- **盘存统计分析：** 基于 `plan_*` 事实表 + 台账（若有）按物料、周期、仓库/公司维度汇总；具体报表字段在开发前列清单评审。
+
+---
+
+## 9. 运输与二维码
+
+### 9.1 运输编号
+
+格式：`SXYS` + 7 位数字序号（示例 `SXYS0000001`），序号 **全局递增**，并发下由服务端生成。
+
+### 9.2 运输信息字段（与需求对齐）
+
+运输编号、车牌号、运输公司、所属公司、运输介质、运输起点、运输终点、运输公里数、单位（吨/趟；需求原文「吨/躺」视为笔误）、运输费用、创建人、是否开票、备注。
+
+### 9.3 二维码
+
+- **载荷：** 建议为 **HTTPS 一次性令牌 URL**（token 绑定运输任务 ID、过期时间、可选 nonce），服务端校验后进入司机填报页（H5 或内置页面）。
+- **安全：** Token 有时效、可撤销；敏感操作需校验运输任务状态。
+
+---
+
+## 10. 现场通知（初版默认）
+
+- **默认：** CRM 内 **待办任务列表** + 计划/运输详情上的「现场任务」标记；权限限定现场角色。
+- **不阻塞交付的扩展：** 企业微信 / 短信 / 邮件，需单独接配置与模板，不写入本阶段必交付范围。
+
+---
+
+## 11. 运输结算（CRM 内闭环）
+
+### 11.1 功能
+
+- 运输情况 **历史总览**（列表 + 筛选）。
+- **多选** 运输记录生成 **运输结算单**。
+- 结算单 **提交审核**（推荐接入 RuoYi 已集成的 **Warm-Flow** 工作流，审批配置在系统内完成）。
+- 审核通过后：**通知对方开票**（系统内状态 + 可选备注）、上传 **发票**、登记 **汇款** 与 **汇款单据附件**。
+
+### 11.2 运费计算模式
+
+| 模式 | 规则 |
+|------|------|
+| 按重量 | 默认 `运输数量 × 运输单价`，结果 **允许人工调整** |
+| 按趟次 | **不自动计算**，以 **手填金额** 为准 |
+
+### 11.3 与报销系统
+
+**不向 bx 同步**；汇款与票据仅为 CRM 业务记录，后续若对接 bx，可通过 **新规格** 定义映射。
+
+---
+
+## 12. 通知信息模板
+
+按需求固定模板生成文本（字段来自计划头 / 行）：
+
+```
+计划号：{planNo}
+企业名称：{enterpriseName}
+提货单位：{pickupCompany}
+到货时间：{arrivalDate}
+药品名称：{productName}
+到货吨位：【{tonnage}吨】
+备注：{remark}
+```
+
+服务端提供「复制到剪贴板」所需纯文本或前端拼装。
+
+---
+
+## 13. 数据模型草案（表名均为 `plan_` 前缀）
+
+以下为逻辑实体，物理表名在实现时可微调但须保持前缀与职责清晰。
+
+| 逻辑实体 | 说明 |
+|----------|------|
+| `plan_order` | 计划头：计划日期、计划订单编号、单据类别、跟进状态、完成状态、供应商/目的地、销售合同 ID、跟进人、通知文本、审计字段等 |
+| `plan_order_line` | 计划行：物料、规格、包装、单位、入出库数量与价格、磅差、金额、与合同行/产品引用 |
+| `plan_line_cert` | 计划行证照：购买证/运输证附件及有效期（如需要） |
+| `plan_transport` | 运输任务：运输编号、车辆、承运商、路线、费用、单位、开票标志等 |
+| `plan_transport_token` | 二维码 token：关联运输任务、过期时间、是否已使用 |
+| `plan_driver_feedback` | 司机扫码回传：附件、数量、时间 |
+| `plan_weighbridge` | 地磅单：关联计划行或运输任务、磅值、状态 |
+| `plan_site_attachment` | 现场上传：地磅单/出入库附件 |
+| `plan_carrier` / `plan_carrier_vehicle` | 运输公司及车辆（字段参考 `vehicle_management.sql` 的 `vehicles`、车头车尾等） |
+| `plan_own_vehicle` | 自有车辆档案 |
+| `plan_settlement` / `plan_settlement_item` | 运输结算单头行 |
+| `plan_settlement_payment` | 发票与汇款登记（票据路径、金额、时间） |
+| `plan_sequence` | 计划订单号、运输号等序列（按业务类型分桶） |
+
+**编号生成：** `SXDDH` + `yyyyMMdd` + **6 位**日序号（与需求示例一致）；与运输编号分表维护序列，避免并发冲突。
+
+自有车辆与承运商车辆字段深度参考 **`plan/vehicle_management.sql`**（如车头 `vehicle_heads`、车尾 `vehicle_tails`、`vehicles` 组合关系、证件 `certificates` 等），映射到 `plan_*` 表时按 RuoYi 惯例改为雪花 ID、租户、逻辑删除等。
+
+---
+
+## 14. 技术栈与模块位置
+
+| 层级 | 路径约定 |
+|------|----------|
+| 后端 | `crm/backend` 下新建业务模块（如 `ruoyi-crm-plan` 或并入现有 `ruoyi-crm`，以前者为宜便于边界清晰） |
+| 前端 | `crm/web`：`api/crm/plan/*`、`views/crm/plan/*`（具体目录以实现时统一） |
+| 数据库 | 与现有 CRM 同一库；脚本纳入 `crm/sql` 或模块自带 `sql`，并与 **`plan/sx.sql`** 合并策略一致 |
+
+---
+
+## 15. 错误处理与审计
+
+- 状态非法迁移：返回明确业务码与中文说明。
+- 价格、数量、金额：`Decimal` 精度与数据库字段一致；金额由服务端重算防篡改。
+- 关键操作：`@Log` 记录；附件上传走统一 OSS/文件服务（与现有 CRM 一致）。
+
+---
+
+## 16. 测试要点
+
+- 编号生成：同日高并发下无重复单号。
+- 易制毒/易制爆：缺证时无法安排运输。
+- 待入/待出：配置公司与名称匹配规则（见 §5）。
+- 结算：按重量/按趟次两种模式金额正确；审核通过后状态封闭。
+- 二维码：过期、重复使用、错误 token 拒绝。
+
+---
+
+## 17. 未决项（本规格已给默认，上线前可再确认）
+
+| 项 | 默认假设 |
+|----|----------|
+| 司机端形态 | 独立 H5 页面（与 CRM 同域或子路径），免登录靠 token |
+| 工作流 | 使用已有 Warm-Flow |
+| 公司名称匹配 | 可配置表 + 去空格全等匹配；简称需求再增加别名表 |
+
+---
+
+## 18. 规格自检（2026-05-05）
+
+- [x] 无「TBD」占位；开放项集中在 §17 并带默认。
+- [x] 与「不对接报销」无矛盾；结算在 CRM 内闭环。
+- [x] 七步流程、字典、编号、地磅规则与需求文档一致。
+- [x] 范围可支撑单独 **implementation plan** 拆分（合同改造 / 主数据 / 计划核心 / 运输与扫码 / 结算与报表）。
+
+---
+
+**下一步：** 评审通过后，使用 `writing-plans` 技能生成 `docs/superpowers/plans/2026-05-05-crm-plan-management-implementation.md`（或按子模块拆分为多份计划）。