258 lines
6.4 KiB
Markdown
258 lines
6.4 KiB
Markdown
# 运输计划管理系统 - 技术设计
|
||
|
||
## 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: 框架合同调价函关联
|
||
|
||
**问题**：框架合同调价后，已发起计划的价格是否需要同步更新？
|
||
|
||
**建议**：保持计划创建时的价格不变（价格快照）；调价仅影响后续新建的计划
|