# 运输计划导入增强功能 - 快速部署指南

## 一、修改文件清单

### 前端文件（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分钟（不含用户培训）
**建议部署时间：** 非业务高峰期