cykj/shanxia2.0
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
299609706ced6b7d1b8c4ab0a0bfc56364fb1985
shanxia2.0/openspec/changes/transport-plan-management/design.md
T
zlwu 299609706c 提交
2026-06-21 09:19:07 +08:00

6.4 KiB
Raw Blame History

运输计划管理系统 - 技术设计

Context

项目背景

安庆山峡化工有限公司已建设 CRM 系统（线索/客户/商机/报价单/合同/产品管理）和地磅系统。现需建设统一的运输计划管理系统，将 CRM 合同与后续的运输、地磅、库存等环节串联，形成从合同→计划→运输→地磅→结算→归档的完整业务闭环。

技术栈

  • 后端：Python FastAPI + SQLAlchemy + MySQL
  • 前端：Vue 3 + Element Plus + TypeScript
  • 对象存储：MinIO（附件上传）
  • 数据库：MySQL 5.7+

约束条件

  1. 按需求文档要求，所有计划相关表统一使用 pl_ 前缀
  2. 遵循 shanxia2.0 工程规范（见 openspec/changes/zkxw-engineering-standards/）
  3. 遵循 UI 规范（Fresh Mint 风格）
  4. 数据暂不按归属公司隔离
  5. 地磅数据由现场人员手动填写，不对接硬件设备

利益相关者

  • 计划专员A：发起计划
  • 计划专员B：核对订单
  • 计划专员C：运费结算确认
  • 司机：扫码回传
  • 现场工作人员：地磅确认

Goals / Non-Goals

Goals:

  1. 实现完整的计划管理流程：从合同发起→运输安排→状态流转→归档
  2. 支持运输审批流程（会签审批）
  3. 实现运费结算功能
  4. 实现车辆和司机管理
  5. 实现盘存统计和库存预警
  6. 遵循工程规范和 UI 规范

Non-Goals:

  1. 不对接地磅硬件设备（手动填写数据）
  2. 不实现复杂的移动端功能（司机端仅扫码回传）
  3. 不实现电子签名
  4. 不实现多语言支持
  5. 不实现操作日志（暂不考虑）

Decisions

Decision 1: 数据库表命名规范

选择：统一使用 pl_ 前缀

理由：

  • 与现有 sys_*、biz_*、wf_* 命名体系保持一致
  • 便于识别和管理计划相关的表
  • 需求文档明确要求

备选方案：

  • plan_* - 与业务语义更贴近，但不符合统一前缀规范
  • transport_* - 过于局限，无法覆盖库存等其他功能

Decision 2: 审批流程实现方式

选择：自定义审批流程（不使用工作流引擎）

理由：

  • 需求简单：仅支持会签审批（1-2级）
  • 不走复杂的工作流引擎
  • 审批规则灵活（用户选择审批人）
  • 减少系统复杂度

备选方案：

  • 使用 Warm-Flow 工作流引擎 - 过于复杂，不适合简单审批场景
  • 使用独立审批服务 - 增加系统复杂度，当前阶段不必要

Decision 3: 计划与运输的关系设计

选择：采用中间关联表实现 N:N 关系

理由：

  • 需求明确支持：1:1、1:N、N:1 三种场景
  • 中间表 pl_plan_transport 清晰表达关联关系
  • 便于后续扩展和维护

表结构：

pl_plan_transport
├── plan_id (FK)
├── transport_id (FK)
├── create_time
└── del_flag

Decision 4: 库存金额计算方式

选择：每批入库单独计算，不使用加权平均

理由：

  • 需求明确要求：使用入库时的实际价格，每批单独计算
  • 财务合规性：每批货物成本清晰可追溯
  • 简化计算逻辑

Decision 5: 二维码实现方式

选择：URL Scheme + 参数编码

理由：

  • 简单可靠：二维码包含运输单ID和基本信息
  • 无需复杂加密：运输单ID已足够定位
  • 便于调试：可通过URL直接访问

二维码内容：

{base_url}/transport/scan/{transport_id}?code={verify_code}

Decision 6: 证件过期提醒实现

选择：定时任务每日检查

理由：

  • 需求明确：过期前30天提醒
  • 定时任务简单可靠
  • 避免实时检查性能开销

Risks / Trade-offs

Risk 1: 多系统数据同步

风险：CRM 合同变更可能导致已发起计划的数据不一致

缓解措施：

  • 计划发起时冗余存储合同关键信息
  • 明确告知用户：合同变更后需手动同步
  • 在计划详情页显示合同信息快照

Risk 2: 并发状态流转冲突

风险：多人同时操作同一计划可能导致状态不一致

缓解措施：

  • 使用乐观锁（version_no 字段）
  • 状态变更前检查当前状态
  • 前端操作后及时刷新状态

Risk 3: 大量数据统计性能

风险：盘存统计涉及大量数据汇总，可能影响性能

缓解措施：

  • 归档后的数据不会频繁变更，考虑使用物化视图或定时统计表
  • 限制查询时间范围
  • 大数据量场景考虑分库分表（未来扩展）

Migration Plan

Phase 1: 数据库变更

  1. 创建新表（按依赖顺序）：

    • pl_vehicle、pl_driver、pl_carrier（基础数据）
    • pl_plan、pl_plan_product（计划主表）
    • pl_transport、pl_transport_approval（运输相关）
    • pl_freight_settlement（运费结算）
    • pl_inventory、pl_inventory_warning（库存相关）

  2. 初始化基础数据（车辆类型、承运商等）

Phase 2: 后端 API 开发

  1. 基础 CRUD API（车辆、司机、承运商）
  2. 计划管理 API
  3. 运输管理 API
  4. 审批流程 API
  5. 运费结算 API
  6. 盘存统计 API

Phase 3: 前端页面开发

  1. 车辆管理页面
  2. 司机管理页面
  3. 计划管理页面
  4. 运输管理页面
  5. 运费结算页面
  6. 盘存统计页面
  7. 工作台（待办、预警）

Phase 4: 定时任务

  1. 证件过期提醒任务
  2. 库存统计定时更新（如采用统计表方案）

Rollback Strategy

  • Phase 1：回滚数据库变更（DROP TABLE）
  • Phase 2：删除新增的 API 路由
  • Phase 3：删除新增的前端页面和组件
  • Phase 4：禁用定时任务

Open Questions

Q1: 审批人权限控制

问题：审批人选择时是否需要过滤有审批权限的用户？

建议：暂不限制，所有用户都可被选择；后续按需细化权限

Q2: 通知发送方式

问题：系统消息之外是否需要邮件/短信通知？

建议：暂仅使用系统消息；后续按需扩展

Q3: 统计报表导出

问题：盘存统计报表是否需要导出功能？

建议：暂不实现；后续按需补充（见需求文档）

Q4: 框架合同调价函关联

问题：框架合同调价后，已发起计划的价格是否需要同步更新？

建议：保持计划创建时的价格不变（价格快照）；调价仅影响后续新建的计划

Reference in new issue View Git Blame Copy Permalink