shanxia2.0/openspec/changes/dibang-migration/design.md

Context

原地磅系统源码位于 simple-dibang-xiaoshou（FastAPI + SQLModel async + art-design-pro），DDL 快照为 docs/sql/dibang.sql。shanxia2.0 已具备 CRM 产品/客户主数据、统一用户权限、报销 bx 子域移植先例。用户确认采用方案 A（主数据仅存名称文本）及五模块移植范围。

原系统核心表关系：db_weighing_slip → db_purchase_plan → db_inbound_outbound，保存地磅单时在同一事务内更新计划执行量并生成出入库单。

Goals / Non-Goals

Goals:

• 4 张 db_* 表符合 database-conventions（UUID、tenant_no、del_flag、create_time 等）
• 完整移植五模块业务功能及地磅→计划→出入库联动
• 计划按月自动生成定时任务
• web-admin Fresh Mint UI + 菜单权限
• 历史数据可迁移脚本

Non-Goals:

• 不移植 cargos/companies/users 表及对应 CRUD 页
• 不引入 product_id/customer_id 外键（方案 A）
• 不做小程序端地磅页面（本期仅 web-admin）
• 不改造 CRM 产品/客户模块本身
• 不保留原地磅独立登录与 JWT 体系

Decisions

D1: 表前缀 db_* 与子域 app/api/db/

选择: 业务表 db_purchase_plan 等，代码子域 db（非 dibang 缩写混用）
理由: 与 bx_*、crm_* 命名一致；路由 /api/.../db/ 简短
替代: 表名保留 purchase_plans → 违反门户命名规范，弃用

D2: 主数据方案 A — 文本冗余

选择: 业务表继续存 product/cargo_name/customer_name 等 varchar；表单从 CRM 下拉选中后写入名称
理由: 与原系统行为一致；避免 CRM 与地磅历史名称不一致导致迁移失败
替代: 加 FK 字段 → 改动大、历史数据对齐成本高，用户已拒绝

D3: 后端参照 bx 子域而非照搬 SQLModel async

选择: SQLAlchemy 同步 Session + DbCrudService 基类 + 门户 { code, data, message } 响应
理由: 与 shanxia2.0 主栈一致；bx 已验证该模式
替代: 保留 async SQLModel → 与门户 middleware/CRUD 模式割裂

D4: 地磅作废保留 is_voided 字段

选择: 除 del_flag 外保留 is_voided
理由: 作废是业务操作（可回滚计划量），与软删除语义不同；原系统已有此区分
替代: 合并为 status 枚举 → 需大范围改前端逻辑，本期不采用

D5: 前端按 P02 复杂列表 + order 模板页

选择: 计划/出入库/地磅单参照 views/system/order/index.vue；车辆参照 unit/index.vue
理由: ui-conventions 模板页要求；原 art-design-pro 样式不可直接复用
替代: 复制 art-design-pro 页面 → 违反 Fresh Mint 规范

D6: 定时任务迁入 APScheduler

选择: app/tasks/db_auto_plan.py，在 init_scheduled_tasks 注册
理由: 门户已有 APScheduler；原独立 cron 脚本可退役
替代: 保留 shell cron → 运维分散，弃用

Risks / Trade-offs

• [名称不一致] CRM 下拉与历史文本可能不匹配 → 允许手工输入；迁移不强制关联 CRM id
• [联动回归] weighing 保存逻辑复杂 → 移植时逐函数对照原 weighing.py；验收用原库样例数据
• [ID 迁移] int→UUID 关联易错 → 迁移脚本输出映射 CSV 并做 count 校验
• [单位混用] t vs kg → 文档与代码注释明确；禁止「优化」换算逻辑
• [ecosystem 文档] 归档前需更新 landscape spec → 本 change 含 delta

Migration Plan

1. 执行 DDL 创建 db_* 表（空库可开发联调）
2. 部署后端 db 子域 + 前端页面（菜单权限 SQL）
3. 运行历史数据迁移脚本导入生产数据
4. 并行运行：原系统只读对照验收 1–2 周
5. 切换 DNS/入口至门户；退役原 backend 与 art-design-pro
6. 回滚: 保留原库快照；门户侧 feature flag 关闭地磅菜单

Open Questions

• （已关闭）主数据 FK vs 文本 → 方案 A 已确认
• 生产切换窗口与是否双写：实施阶段与业务方确认