1、调整凭证

2、调整运单
2026-09-08 17:50:34 +08:00
parent a7315b4491
commit cba2ad3b3b
43 changed files with 5730 additions and 1119 deletions
@@ -0,0 +1,286 @@
+# 运输计划导入增强功能 - 快速部署指南
+
+## 一、修改文件清单
+
+### 前端文件（tms-erp-web）
+1. ✅ `src/views/business/transport-plan-import.vue` - 导入页面（已更新字段）
+
+### 后端文件（tms-erp-api）
+1. ✅ `blade-service-api/blade-transport-api/src/main/java/org/springblade/transport/pojo/entity/TransportPlan.java` - 实体类（新增字段）
+2. ✅ `blade-service/blade-transport/src/main/java/org/springblade/transport/excel/TransportPlanImportExcel.java` - 导入Excel实体
+3. ✅ `blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/TransportPlanServiceImpl.java` - 服务实现（核心逻辑）
+
+### 数据库脚本
+1. ✅ `doc/sql/transport/blade_transport_plan_add_fields_20260908.sql` - 字段迁移脚本
+
+## 二、部署步骤
+
+### 步骤1：数据库升级（必须最先执行）
+
+```bash
+cd /Users/liangxin/Project/JAVA/tms-erp-api
+mysql -u用户名 -p密码 数据库名 < doc/sql/transport/blade_transport_plan_add_fields_20260908.sql
+```
+
+**验证：**
+```sql
+DESC blade_transport_plan;
+-- 应该能看到 mileage 和 plan_group_id 两个新字段
+```
+
+### 步骤2：后端编译打包
+
+```bash
+cd /Users/liangxin/Project/JAVA/tms-erp-api
+mvn clean package -DskipTests
+```
+
+**验证编译结果：**
+- 检查 `blade-service/blade-transport/target/` 目录是否有 jar 包生成
+
+### 步骤3：前端构建
+
+```bash
+cd /Users/liangxin/Project/Html/web/tms-erp-web
+pnpm run build
+```
+
+### 步骤4：部署后端服务
+
+停止运输服务 → 替换 jar 包 → 启动服务
+
+### 步骤5：部署前端
+
+将 `dist` 目录部署到Web服务器
+
+## 三、功能测试清单
+
+### 测试1：模板下载
+- [ ] 访问 `/business/transport-plan/import` 页面
+- [ ] 点击"下载模板"按钮
+- [ ] 验证Excel模板字段顺序和标题正确
+
+**预期字段顺序：**
+```
+序号 | *计划名称 | *运输类型 | *发货地址 | 发货联系人 | 发货联系人电话 | 
+*到货地址 | 收货联系人 | 收货联系人电话 | 货物名称 | *货物类型 | 
+数量 | 计量单位 | 包装 | 规格 | 型号 | 里程(km) | 
+计划开始时间 | 计划结束时间 | 备注 | 同一计划标识号
+```
+
+### 测试2：必填字段校验
+**测试数据：** 计划名称为空
+- [ ] 上传Excel
+- [ ] 系统提示导入失败
+- [ ] 下载错误Excel
+- [ ] 验证错误信息：`1. 计划名称不能为空`
+
+### 测试3：运输类型枚举校验
+**测试数据：** 运输类型 = "陆运"（非枚举值）
+- [ ] 上传Excel
+- [ ] 系统提示导入失败
+- [ ] 验证错误信息包含枚举值列表
+
+### 测试4：电话格式校验
+**测试数据：** 发货联系人电话 = "12345"
+- [ ] 上传Excel
+- [ ] 系统提示导入失败
+- [ ] 验证错误信息：`发货联系人电话格式不正确（需11位数字）`
+
+### 测试5：计划名称唯一性
+**测试数据：** 两条记录使用相同的计划名称
+- [ ] 上传Excel
+- [ ] 系统提示导入失败
+- [ ] 验证错误信息：`计划名称在导入数据中重复`
+
+### 测试6：日期逻辑校验
+**测试数据：** 计划结束时间 < 计划开始时间
+- [ ] 上传Excel
+- [ ] 系统提示导入失败
+- [ ] 验证错误信息：`计划结束时间不得早于计划开始时间`
+
+### 测试7：多个错误显示
+**测试数据：** 一条记录缺少多个必填字段
+- [ ] 上传Excel
+- [ ] 验证错误信息以编号列表形式展示
+```
+1. 计划名称不能为空
+2. 运输类型不能为空
+3. 发货地址不能为空
+```
+
+### 测试8：部分数据有错不导入全部
+**测试数据：** 10条记录，第5条有错误
+- [ ] 上传Excel
+- [ ] 验证：数据库中没有任何记录被导入
+- [ ] 验证：错误Excel中仅第5条有错误信息
+
+### 测试9：新增字段功能
+**测试数据：** 填写里程和同一计划标识号
+- [ ] 上传Excel（所有数据正确）
+- [ ] 验证导入成功
+- [ ] 查看计划详情，验证里程和同一计划标识号已保存
+
+### 测试10：同一计划标识号关联
+**测试数据：** 3条记录使用相同的同一计划标识号
+- [ ] 上传Excel（所有数据正确）
+- [ ] 验证导入成功
+- [ ] 查询时可通过同一计划标识号筛选出这3条记录
+
+### 测试11：正常导入
+**测试数据：** 完整正确的数据
+```
+计划名称：测试计划001
+运输类型：公路整车
+发货地址：广西壮族自治区柳州市柳北区鹧鸪江路15号桂中海迅物流园
+发货联系人：周经理
+发货联系人电话：13800000001
+到货地址：浙江省宁波市北仑区集翔路8号舟山港
+收货联系人：王经理
+收货联系人电话：13900000001
+货物名称：石灰石
+货物类型：石灰石
+数量：100
+计量单位：吨
+里程(km)：850
+```
+- [ ] 上传Excel
+- [ ] 验证导入成功提示
+- [ ] 进入运输计划列表验证数据已创建
+
+## 四、常见问题排查
+
+### 问题1：编译失败
+**症状：** Maven 编译报错
+**排查：**
+```bash
+# 检查 Java 版本
+java -version
+
+# 清理并重新编译
+mvn clean compile
+```
+
+### 问题2：导入时报错 "字段不存在"
+**原因：** 数据库脚本未执行
+**解决：**
+```sql
+-- 检查字段是否存在
+SHOW COLUMNS FROM blade_transport_plan LIKE 'mileage';
+SHOW COLUMNS FROM blade_transport_plan LIKE 'plan_group_id';
+
+-- 如果不存在，执行迁移脚本
+SOURCE doc/sql/transport/blade_transport_plan_add_fields_20260908.sql;
+```
+
+### 问题3：错误Excel未下载
+**原因：** 浏览器拦截下载
+**解决：** 检查浏览器下载设置，允许自动下载
+
+### 问题4：导入后数据丢失
+**原因：** 部分数据有错导致全部回滚（这是预期行为）
+**解决：** 修正所有错误数据后重新导入
+
+### 问题5：计划名称重复错误
+**原因：** 当前组织下已存在同名计划
+**解决：** 
+1. 修改计划名称
+2. 或删除/修改已有的同名计划
+
+## 五、回滚方案
+
+如果新功能有问题，需要回滚：
+
+### 回滚步骤1：恢复后端代码
+```bash
+cd /Users/liangxin/Project/JAVA/tms-erp-api
+git checkout HEAD -- blade-service/blade-transport/
+git checkout HEAD -- blade-service-api/blade-transport-api/
+```
+
+### 回滚步骤2：恢复前端代码
+```bash
+cd /Users/liangxin/Project/Html/web/tms-erp-web
+git checkout HEAD -- src/views/business/transport-plan-import.vue
+```
+
+### 回滚步骤3：数据库字段（可选）
+```sql
+-- 新字段不影响旧功能，可以不删除
+-- 如需删除：
+ALTER TABLE blade_transport_plan DROP COLUMN mileage;
+ALTER TABLE blade_transport_plan DROP COLUMN plan_group_id;
+```
+
+### 回滚步骤4：重新编译部署
+按照正常流程重新编译和部署
+
+## 六、监控指标
+
+部署后需要关注：
+
+1. **导入成功率**
+   - 观察用户导入的成功/失败比例
+   - 预期：初期可能失败率较高（用户适应新校验规则）
+
+2. **常见错误类型**
+   - 统计最常见的校验错误
+   - 针对性优化用户指导文档
+
+3. **性能监控**
+   - 大批量导入（1000+条）的响应时间
+   - 数据库查询性能
+
+4. **用户反馈**
+   - 收集用户对新校验规则的反馈
+   - 调整过严或过松的规则
+
+## 七、用户培训要点
+
+向用户说明：
+
+1. ✅ **新的校验逻辑**
+   - 所有数据必须全部正确才能导入
+   - 有任何错误都不会导入
+
+2. ✅ **错误Excel使用**
+   - 下载错误Excel查看具体错误
+   - 修正后重新上传
+
+3. ✅ **运输类型枚举值**
+   - 必须使用：公路整车、公路配载/零担、铁路运输、水路运输、跨境海运、航空运输
+
+4. ✅ **电话格式要求**
+   - 必须是11位数字
+   - 不要包含空格、横线等符号
+
+5. ✅ **计划名称唯一性**
+   - 当前组织下不能重复
+   - 建议使用日期+序号命名
+
+6. ✅ **同一计划标识号**
+   - 用于关联同一计划的多条货物记录
+   - 同一标识号下应保持地址等信息一致
+
+## 八、技术支持
+
+如遇到问题：
+
+1. 查看服务日志
+2. 检查数据库字段是否正确
+3. 验证导入Excel格式
+4. 联系开发团队
+
+---
+
+**部署完成检查项：**
+- [ ] 数据库字段已添加
+- [ ] 后端服务已重启
+- [ ] 前端已更新
+- [ ] 模板下载正常
+- [ ] 基础导入测试通过
+- [ ] 错误校验测试通过
+- [ ] 用户已培训
+
+**预计部署时间：** 30分钟（不含用户培训）
+**建议部署时间：** 非业务高峰期