CRM 计划管理模块 — 设计规格

版本： 1.1
日期： 2026-05-05（v1.1 补充交付路径：以 crm/py-backend 为准）
状态： 待评审
依据： plan/计划需求.md、plan/sx.sql（库表对齐参考）、plan/vehicle_management.sql（车辆字段参考）

1. 背景与范围

1.1 现状与交付路径

管理端前端：crm/web（Vue 3）
当前阶段目标后端： crm/py-backend（Python / FastAPI 等，以仓库内实际栈为准）。本规格中的业务接口、领域逻辑、审批与审计，优先在 py-backend 实现并完善。
历史 / 对照后端： crm/backend（RuoYi-Vue-Plus / Spring Boot）。上线切换完成后 不再作为 CRM 生产运行时；切换前可作接口与表结构对照，新功能不默认要求在 Java 侧重复交付。

1.2 本规格覆盖

在 CRM 内新增 计划管理 子系统，包含：

计划管理（含与合同、调价函、证照门禁、运输与二维码、地磅与现场、核对与归档）
自有车辆信息维护
运输公司及车辆信息维护
运输任务 / 运输信息
库存相关能力与 盘存统计分析（口径见 §8）
运输结算（列表、多选生成结算单、审核、开票与汇款信息登记）

1.3 边界声明（已确认）

项目	结论
财务报销子系统（bx）	本阶段不对接。不向 bx 推送单据、不拉取报销状态、不共用 bx 审批实例。
结算与票款	运输结算单、审核、通知开票、发票附件、汇款凭证均在 CRM 库表与页面内完成记录与状态流转。
用户与权限	复用 CRM 用户管理、角色管理（数据与约定仍来自现网 CRM）；py-backend 侧需实现与之对齐的认证与鉴权（如 JWT、权限码校验规则与 `crm/web` 约定一致）。权限标识可沿用 `crm:plan:*` 或 py 侧统一前缀，以实现时前后端对齐为准。
运行时策略	先完善 py-backend；正式上线后 CRM 仅使用 py-backend，停用 Java CRM 后端。

1.4 非目标（当前版本）

与 bx 报销系统的接口、单点登录扩展、数据同步
在 crm/backend 中完整重复实现 本规格全部能力（除非切换窗口期需要临时补丁，须在计划中单独列出）

1.5 Java → Python 切换注意点（实现约束）

数据库： 与现网一致时使用 plan/sx.sql 同一库；plan_* 表由 py-backend 迁移脚本或 DDL 创建与演进，避免 Java 与 Python 两套迁移长期分叉；若切换期双栈并行，须约定 唯一写入口（默认仅 py-backend 写计划域表）。
前端： crm/web 的 API 基地址在切换后指向 py-backend；接口路径、鉴权头、错误体格式需在联调阶段与 Java 行为对齐或显式改版并文档化。
合同 / 产品 / 调价函： 若切换前数据仍由 Java 维护，py-backend 通过 只读同一库表 或 同步只读视图 读取；切换完成后写操作逐步收口到 py（规格不强制一次改完合同 Java 代码，但 计划域以 py 为真源）。

2. 目标与成功标准

2.1 业务目标

从合同发起计划，支持一单多产品；框架合同价格可通过 调价函 调整并保留 版本历史。
产品维度支持 易制毒 / 易制爆；命中时计划行必须先具备 购买证、运输证 才可进入运输安排。
运输支持 自有车辆 与 承运商车辆；生成可分享的 二维码 供司机 / 现场使用；待入库、待出库任务需 通知现场。
按规则识别 待入库 / 待出库，自动生成 地磅单 信息并在计划中可见；现场确认并上传地磅单与出入库附件。
司机扫码回传运输单据与数量等信息。
专员 B 整单核对、专员 C 确认运费后归档。
运输历史总览、多选生成 运输结算单 并经审核后完成开票通知、票据与汇款信息登记。
盘存统计分析 可按约定口径输出报表或图表。

2.2 成功标准（验收锚点）

端到端流程在测试环境可演示：合同 → 计划 →（证照）→ 运输与二维码 → 地磅/现场 → 司机回传 → 核对 → 费用确认 → 归档；主链路由 py-backend 提供 API。
所有业务表名 plan_ 前缀，与 plan/sx.sql 同库建模时可合并迁移脚本。
权限与账号体系与现网 CRM 一致；鉴权在 py-backend 实现。

3. 角色与权限（对应需求中的 A / B / C）

需求中的「计划专员 A / B / C」映射为 可配置角色或数据权限 + 菜单权限，建议：

角色含义	典型职责	权限要点
专员 A	发起与安排运输、生成二维码、线下分发	计划编辑、运输安排、二维码生成、现场通知
专员 B	运输完成后的整单核对	核对通过/退回
专员 C	运输费用确认、归档	费用确认、归档
现场人员	待入/待出相关地磅与附件	地磅确认、附件上传、仅可见指派任务

权限码字符串在实现阶段批量定义，建议与现网 RuoYi 菜单权限格式对齐（如 crm:plan:transport:arrange），便于 crm/web 继续复用 v-hasPermi 等；校验逻辑在 py-backend 实现（与 Java Sa-Token 解耦，可对齐同一权限表或 JWT 内嵌权限列表）。

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 功能

运输情况 历史总览（列表 + 筛选）。
多选运输记录生成 运输结算单。
结算单 提交审核：以 py-backend 内实现为准。可选路径：（a）表驱动审批状态 + 审批记录表（与 Java Warm-Flow 解耦，便于独立上线）；（b）后续若统一工作流引擎再在 py 侧集成。初版推荐 （a），避免切换期依赖 Java 内嵌流程。
审核通过后：通知对方开票（系统内状态 + 可选备注）、上传发票、登记汇款与 汇款单据附件。（审批流实现见 §11.1，以 py-backend 为准。）

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_* 表时与 plan/sx.sql 现网表习惯 对齐（主键策略、租户、逻辑删除、审计字段等以库中已有 CRM 表为准；若全新表且仅 py 写入，可采用 UUID/雪花等与团队约定一致的方案）。

14. 技术栈与模块位置

层级	路径约定
后端（主交付）	`crm/py-backend`：计划域 REST API、业务规则、编号序列、二维码 token、审批状态机等。目录与分层以该仓库现有结构为准（如 `app/routers`、`app/services`、`app/models`）。
后端（对照 / 切换期）	`crm/backend`：仅在不与「py 为唯一写入口」冲突的前提下作兼容或只读；不作为本规格默认实现落点。
前端	`crm/web`：调用 py-backend 暴露的 API（`api/crm/plan/` 或统一 `/api` 前缀，以实现时为准）、`views/crm/plan/`
数据库	与现有 CRM 同一库；DDL / Alembic（或项目采用的迁移方式）放在 py-backend 侧维护，并与 `plan/sx.sql` 合并策略一致

15. 错误处理与审计

状态非法迁移：返回明确业务码与中文说明。
价格、数量、金额：Decimal 精度与数据库字段一致；金额由服务端重算防篡改。
关键操作：在 py-backend 中 落审计（操作人、时间、对象 ID、前后摘要）；实现方式可为审计表 + 中间件，或与项目已有日志规范一致；不依赖 Java @Log。附件上传走与现网一致的 OSS/文件服务配置。

16. 测试要点

编号生成：同日高并发下无重复单号。
易制毒/易制爆：缺证时无法安排运输。
待入/待出：配置公司与名称匹配规则（见 §5）。
结算：按重量/按趟次两种模式金额正确；审核通过后状态封闭。
二维码：过期、重复使用、错误 token 拒绝。

17. 未决项（本规格已给默认，上线前可再确认）

项	默认假设
司机端形态	独立 H5 页面（与 CRM 同域或子路径），免登录靠 token；由 py-backend 提供页面数据接口或 SSR 视项目而定
工作流	py-backend 内表驱动审批（见 §11.1）；不依赖 Java Warm-Flow
公司名称匹配	可配置表 + 去空格全等匹配；简称需求再增加别名表

18. 规格自检（2026-05-05）

无「TBD」占位；开放项集中在 §17 并带默认。
与「不对接报销」无矛盾；结算在 CRM 内闭环。
七步流程、字典、编号、地磅规则与需求文档一致。
主交付后端为 crm/py-backend；上线后停用 Java CRM 后端 已在 §1、§14、§15、§17 一致体现。
范围可支撑单独 implementation plan 拆分（合同数据读取或迁移 / 主数据 / 计划核心 / 运输与扫码 / 结算与报表 / py 鉴权与联调）。

下一步： 评审通过后，使用 writing-plans 技能生成 crm/py-backend 优先 的 docs/superpowers/plans/2026-05-05-crm-plan-management-implementation.md（或按子模块拆分为多份计划）。

2026-05-05-crm-plan-management-design.md 17 KB История Исходник