287 lines
8.2 KiB
Markdown
287 lines
8.2 KiB
Markdown
# 运输计划导入增强功能 - 快速部署指南
|
||
|
||
## 一、修改文件清单
|
||
|
||
### 前端文件（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分钟（不含用户培训）
|
||
**建议部署时间：** 非业务高峰期
|