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

## 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: 框架合同调价函关联

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

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