docs(spec): CRM plan module targets py-backend; Java CRM retired at go-live

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

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

@@ -1,7 +1,7 @@
 # CRM 计划管理模块 — 设计规格
 
-**版本：** 1.0  
-**日期：** 2026-05-05  
+**版本：** 1.1  
+**日期：** 2026-05-05（v1.1 补充交付路径：以 `crm/py-backend` 为准）  
 **状态：** 待评审  
 **依据：** `plan/计划需求.md`、`plan/sx.sql`（库表对齐参考）、`plan/vehicle_management.sql`（车辆字段参考）
 
@@ -9,11 +9,11 @@
 
 ## 1. 背景与范围
 
-### 1.1 现状
+### 1.1 现状与交付路径
 
 - 管理端前端：`crm/web`（Vue 3）
-- 生产后端：`crm/backend`（RuoYi-Vue-Plus / Spring Boot）
-- Python 重构后端：`crm/py-backend`（未纳入本规格交付范围）
+- **当前阶段目标后端：** `crm/py-backend`（Python / FastAPI 等，以仓库内实际栈为准）。**本规格中的业务接口、领域逻辑、审批与审计，优先在 py-backend 实现并完善。**
+- **历史 / 对照后端：** `crm/backend`（RuoYi-Vue-Plus / Spring Boot）。上线切换完成后 **不再作为 CRM 生产运行时**；切换前可作接口与表结构对照，**新功能不默认要求在 Java 侧重复交付**。
 
 ### 1.2 本规格覆盖
 
@@ -32,12 +32,19 @@
 |------|------|
 | **财务报销子系统（bx）** | **本阶段不对接。** 不向 bx 推送单据、不拉取报销状态、不共用 bx 审批实例。 |
 | **结算与票款** | 运输结算单、审核、通知开票、发票附件、汇款凭证均在 **CRM 库表与页面** 内完成记录与状态流转。 |
-| **用户与权限** | 复用 CRM **用户管理、角色管理**；计划相关权限使用独立权限标识（如 `crm:plan:*`，具体前缀以实现时 RuoYi 约定为准）。 |
+| **用户与权限** | 复用 CRM **用户管理、角色管理**（数据与约定仍来自现网 CRM）；py-backend 侧需实现 **与之对齐的认证与鉴权**（如 JWT、权限码校验规则与 `crm/web` 约定一致）。权限标识可沿用 `crm:plan:*` 或 py 侧统一前缀，以实现时前后端对齐为准。 |
+| **运行时策略** | **先完善 py-backend；正式上线后 CRM 仅使用 py-backend，停用 Java CRM 后端。** |
 
 ### 1.4 非目标（当前版本）
 
 - 与 bx 报销系统的接口、单点登录扩展、数据同步
-- 将计划模块完整迁移到 `crm/py-backend`（可作为远期选项，不阻塞 Java 交付）
+- **在 `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 为真源**）。
 
 ---
 
@@ -56,9 +63,9 @@
 
 ### 2.2 成功标准（验收锚点）
 
-- 端到端流程在测试环境可演示：合同 → 计划 →（证照）→ 运输与二维码 → 地磅/现场 → 司机回传 → 核对 → 费用确认 → 归档。
+- 端到端流程在测试环境可演示：合同 → 计划 →（证照）→ 运输与二维码 → 地磅/现场 → 司机回传 → 核对 → 费用确认 → 归档；**主链路由 py-backend 提供 API。**
 - 所有业务表名 **`plan_` 前缀**，与 `plan/sx.sql` 同库建模时可合并迁移脚本。
-- 权限仅使用 CRM 既有账号体系，无独立登录入口。
+- 权限与账号体系与现网 CRM 一致；**鉴权在 py-backend 实现**。
 
 ---
 
@@ -73,7 +80,7 @@
 | 专员 C | 运输费用确认、归档 | 费用确认、归档 |
 | 现场人员 | 待入/待出相关地磅与附件 | 地磅确认、附件上传、仅可见指派任务 |
 
-具体 `Sa-Token` 权限码在实现阶段按 RuoYi 模块命名规范批量定义（如 `crm:plan:transport:arrange`）。
+权限码字符串在实现阶段批量定义，**建议与现网 RuoYi 菜单权限格式对齐**（如 `crm:plan:transport:arrange`），便于 `crm/web` 继续复用 `v-hasPermi` 等；**校验逻辑在 py-backend 实现**（与 Java `Sa-Token` 解耦，可对齐同一权限表或 JWT 内嵌权限列表）。
 
 ---
 
@@ -190,8 +197,8 @@
 
 - 运输情况 **历史总览**（列表 + 筛选）。
 - **多选** 运输记录生成 **运输结算单**。
-- 结算单 **提交审核**（推荐接入 RuoYi 已集成的 **Warm-Flow** 工作流，审批配置在系统内完成）。
-- 审核通过后：**通知对方开票**（系统内状态 + 可选备注）、上传 **发票**、登记 **汇款** 与 **汇款单据附件**。
+- 结算单 **提交审核**：**以 py-backend 内实现为准**。可选路径：（a）**表驱动审批状态 + 审批记录表**（与 Java Warm-Flow 解耦，便于独立上线）；（b）后续若统一工作流引擎再在 py 侧集成。初版推荐 **（a）**，避免切换期依赖 Java 内嵌流程。
+- 审核通过后：**通知对方开票**（系统内状态 + 可选备注）、上传 **发票**、登记 **汇款** 与 **汇款单据附件**。（审批流实现见 §11.1，以 py-backend 为准。）
 
 ### 11.2 运费计算模式
 
@@ -246,7 +253,7 @@
 
 **编号生成：** `SXDDH` + `yyyyMMdd` + **6 位**日序号（与需求示例一致）；与运输编号分表维护序列，避免并发冲突。
 
-自有车辆与承运商车辆字段深度参考 **`plan/vehicle_management.sql`**（如车头 `vehicle_heads`、车尾 `vehicle_tails`、`vehicles` 组合关系、证件 `certificates` 等），映射到 `plan_*` 表时按 RuoYi 惯例改为雪花 ID、租户、逻辑删除等。
+自有车辆与承运商车辆字段深度参考 **`plan/vehicle_management.sql`**（如车头 `vehicle_heads`、车尾 `vehicle_tails`、`vehicles` 组合关系、证件 `certificates` 等），映射到 `plan_*` 表时与 **`plan/sx.sql` 现网表习惯** 对齐（主键策略、租户、逻辑删除、审计字段等以库中已有 CRM 表为准；若全新表且仅 py 写入，可采用 UUID/雪花等与团队约定一致的方案）。
 
 ---
 
@@ -254,9 +261,10 @@
 
 | 层级 | 路径约定 |
 |------|----------|
-| 后端 | `crm/backend` 下新建业务模块（如 `ruoyi-crm-plan` 或并入现有 `ruoyi-crm`，以前者为宜便于边界清晰） |
-| 前端 | `crm/web`：`api/crm/plan/*`、`views/crm/plan/*`（具体目录以实现时统一） |
-| 数据库 | 与现有 CRM 同一库；脚本纳入 `crm/sql` 或模块自带 `sql`，并与 **`plan/sx.sql`** 合并策略一致 |
+| **后端（主交付）** | **`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`** 合并策略一致 |
 
 ---
 
@@ -264,7 +272,7 @@
 
 - 状态非法迁移：返回明确业务码与中文说明。
 - 价格、数量、金额：`Decimal` 精度与数据库字段一致；金额由服务端重算防篡改。
-- 关键操作：`@Log` 记录；附件上传走统一 OSS/文件服务（与现有 CRM 一致）。
+- 关键操作：**在 py-backend 中** 落审计（操作人、时间、对象 ID、前后摘要）；实现方式可为审计表 + 中间件，或与项目已有日志规范一致；**不依赖 Java `@Log`**。附件上传走与现网一致的 OSS/文件服务配置。
 
 ---
 
@@ -282,8 +290,8 @@
 
 | 项 | 默认假设 |
 |----|----------|
-| 司机端形态 | 独立 H5 页面（与 CRM 同域或子路径），免登录靠 token |
-| 工作流 | 使用已有 Warm-Flow |
+| 司机端形态 | 独立 H5 页面（与 CRM 同域或子路径），免登录靠 token；**由 py-backend 提供页面数据接口或 SSR 视项目而定** |
+| 工作流 | **py-backend 内表驱动审批**（见 §11.1）；不依赖 Java Warm-Flow |
 | 公司名称匹配 | 可配置表 + 去空格全等匹配；简称需求再增加别名表 |
 
 ---
@@ -293,8 +301,9 @@
 - [x] 无「TBD」占位；开放项集中在 §17 并带默认。
 - [x] 与「不对接报销」无矛盾；结算在 CRM 内闭环。
 - [x] 七步流程、字典、编号、地磅规则与需求文档一致。
-- [x] 范围可支撑单独 **implementation plan** 拆分（合同改造 / 主数据 / 计划核心 / 运输与扫码 / 结算与报表）。
+- [x] **主交付后端为 `crm/py-backend`；上线后停用 Java CRM 后端** 已在 §1、§14、§15、§17 一致体现。
+- [x] 范围可支撑单独 **implementation plan** 拆分（合同数据读取或迁移 / 主数据 / 计划核心 / 运输与扫码 / 结算与报表 / **py 鉴权与联调**）。
 
 ---
 
-**下一步：** 评审通过后，使用 `writing-plans` 技能生成 `docs/superpowers/plans/2026-05-05-crm-plan-management-implementation.md`（或按子模块拆分为多份计划）。
+**下一步：** 评审通过后，使用 `writing-plans` 技能生成 **`crm/py-backend` 优先** 的 `docs/superpowers/plans/2026-05-05-crm-plan-management-implementation.md`（或按子模块拆分为多份计划）。