tms-erp-api/运单导入校验-前后端对接完成总结.md

运单导入校验功能 - 前后端对接完成总结

完成时间

2026-09-08

改造方式

从前端校验改为后端校验，参考港口码头导入模块（/base/port-terminal）的实现方式。

---

一、后端实现完成

1. 修改的文件

1.1 控制器层

文件: /blade-service/blade-transport/src/main/java/org/springblade/transport/controller/WaybillController.java

修改内容:

• 修改 confirmImportBatch 方法签名
• 添加 HttpServletResponse response 参数
• 返回类型从 R 改为 void（响应通过 response 直接写入）

@PostMapping("/import-batch/confirm")
@ApiOperationSupport(order = 7)
@Operation(summary = "确认运单批量导入")
public void confirmImportBatch(@RequestBody WaybillImportBatchRequest request, HttpServletResponse response) {
    waybillImportBatchService.confirm(request, response);
}

1.2 服务接口层

文件: /blade-service/blade-transport/src/main/java/org/springblade/transport/service/IWaybillImportBatchService.java

修改内容:

• 添加 jakarta.servlet.http.HttpServletResponse 导入
• 修改 confirm 方法签名，添加 HttpServletResponse response 参数
• 返回类型从 WaybillImportBatch 改为 void

1.3 服务实现层

文件: /blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/WaybillImportBatchServiceImpl.java

修改内容:

1. 添加导入:

import jakarta.servlet.http.HttpServletResponse;
import org.springblade.common.excel.ImportFailureExcelUtil;
import org.springblade.core.tool.api.R;
import org.springblade.core.tool.utils.DateUtil;
import org.springblade.core.tool.utils.WebUtil;
import org.springblade.transport.excel.WaybillImportBatchExcel;

2. 重写 confirm 方法:

   • 在导入前执行校验
   • 校验失败时导出包含错误信息的 Excel 文件
   • 校验通过时执行导入并返回 JSON 成功响应

3. 修改 persist 方法:

   • 移除了内部的校验逻辑（校验已提前在 confirm 中处理）
   • 专注于数据持久化

4. 添加 mapToExcel 方法:

   • 将 Map<String, Object> 转换为 WaybillImportBatchExcel 对象
   • 用于生成错误明细 Excel

1.4 Excel 实体类

文件: /blade-service/blade-transport/src/main/java/org/springblade/transport/excel/WaybillImportBatchExcel.java

修改内容:

• 添加 errorMessage 字段（用于存储校验错误信息）

/** 导入失败原因（不导出到模板，仅用于失败明细） */
private String errorMessage;

2. 校验规则实现

后端已经实现了完整的校验规则（在 validateImportRows 方法中）：

2.1 格式校验

• ✅ 车牌号格式（公路运输）
• ✅ 手机号格式（11位数字）
• ✅ 运输方式枚举值
• ✅ 计量单位枚举值
• ✅ 正数校验（数量、里程）
• ✅ 日期时间格式

2.2 逻辑校验

• ✅ 运费合计 = 运费 + 其他费用合计
• ✅ 日期关系校验（发货时间不能晚于完成时间）
• ✅ 配载标识号一致性
• ✅ 同一运单标识号一致性

3. 错误明细 Excel 格式

• ✅ 在原始 Excel 最后一列追加"错误信息"列
• ✅ 错误信息以红色字体显示
• ✅ 校验通过的行显示空字符串
• ✅ 多个错误用 "; " 分隔
• ✅ 列宽自动调整

---

二、前端实现完成

1. 回滚的代码

1.1 删除的文件

• ❌ src/utils/waybill-import-validator.js（前端校验工具）
• ❌ src/utils/transport-plan-import-validator.js（运输计划校验工具）

1.2 修改的文件

文件: src/views/business/components/waybill-import-dialog.vue

回滚内容:

• 移除校验相关的导入
• 移除 validationResult、validationDetails、uploadedFile 等响应式变量
• 移除 performValidation 方法
• 移除 exportErrorReport 方法
• 简化 fileChange、fileRemove、confirmImport、resetCreateForm 方法

保留内容:

• 文件上传逻辑
• Excel 解析逻辑
• 表单提交逻辑

2. 前端处理流程

前端现在的处理逻辑非常简单：

1. 用户上传 Excel 文件
2. 前端解析文件并展示预览
3. 用户点击"确认导入"
4. 前端调用后端接口 POST /blade-transport/waybill-manage/import-batch/confirm
5. 后端响应：
   • JSON 响应 → 前端提示"导入成功"
   • Excel 文件流 → 浏览器自动下载错误明细表

关键点: 前端的 axios 会自动处理响应类型，当后端返回 Excel 文件流时，浏览器会自动触发下载。

---

三、接口对接说明

接口信息

• 路径: /blade-transport/waybill-manage/import-batch/confirm
• 方法: POST
• Content-Type: application/json

请求参数

{
  "id": null,
  "batchNo": "YDB202609080001",
  "projectId": 123,
  "contractId": 456,
  "carrierType": "承运商",
  "carrierId": 789,
  "carrierContractId": 101,
  "status": "completed",
  "importType": "waybill",
  "planId": null,
  "rows": [
    {
      "vehicleNo": "桂A12345",
      "transportType": "公路整车",
      "departureAddress": "广西南宁市...",
      "arrivalAddress": "广东广州市...",
      "cargoName": "钢材",
      "cargoType": "建筑材料",
      "quantity": "10",
      "quantityUnit": "吨",
      "actualStartDate": "2024-09-01",
      "actualEndDate": "2024-09-02",
      ...
    }
  ]
}

响应说明

成功响应（JSON）

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 200,
  "success": true,
  "data": null,
  "msg": "操作成功"
}

失败响应（Excel 文件流）

HTTP/1.1 200 OK
Content-Type: application/vnd.ms-excel
Content-Disposition: attachment; filename=运单导入失败明细20260908182530.xlsx

[Excel Binary Data]

错误明细 Excel 格式：

• 最后一列为"错误信息"列（红色字体）
• 每行显示该行的所有校验错误（用 "; " 分隔）
• 校验通过的行显示空字符串

---

四、测试验证

4.1 后端编译

✅ 成功 - mvn clean compile -DskipTests 通过

4.2 前端构建

✅ 成功 - pnpm run build 通过

4.3 待测试项

后端测试

• 上传完全正确的数据，验证导入成功
• 上传车牌号格式错误的数据，验证下载错误明细
• 上传必填项缺失的数据，验证下载错误明细
• 上传手机号格式错误的数据，验证下载错误明细
• 上传运费合计不匹配的数据，验证下载错误明细
• 上传日期逻辑错误的数据，验证下载错误明细
• 上传配载标识号车牌不一致的数据，验证下载错误明细
• 上传混合数据（部分正确部分错误），验证错误明细格式

前端测试

• 验证文件上传和预览功能
• 验证导入成功时的提示
• 验证校验失败时自动下载错误明细
• 验证错误明细 Excel 的格式和内容

联调测试

• 启动后端服务
• 启动前端服务
• 完整流程测试

---

五、文档输出

已创建的文档

1. 导入校验规则-后端实现文档.md - 详细的校验规则说明（供后端开发参考）
2. 导入校验改造总结.md - 改造过程总结
3. 本文档 - 前后端对接完成总结

---

六、运输计划导入

运输计划导入（/business/transport-plan/import）当前已经支持错误明细下载（代码行 519-547），只需要后端按照类似的方式实现校验逻辑即可。

待完成:

• 参考运单导入的实现方式
• 在运输计划导入接口中实现校验逻辑
• 校验失败时返回 Excel 文件流

---

七、注意事项

7.1 响应类型判断

前端的 axios 或 fetch 会根据响应头 Content-Type 自动处理：

• application/json → 解析为 JSON 对象
• application/vnd.ms-excel → 作为文件下载

重要: 后端必须正确设置响应头，否则前端无法正确处理。

7.2 事务处理

• 校验失败导出 Excel 时，不会执行数据库操作
• 校验通过后才会开始事务并持久化数据
• 如果持久化失败，事务会回滚

7.3 性能考虑

• 大文件导入建议设置超时时间（当前默认 60 秒）
• 校验使用了 TreeMap 确保错误信息按行号排序
• 使用 Map 数据结构优化跨行校验性能

7.4 扩展性

• 校验规则集中在 validateImportRows 方法中，便于维护
• 枚举值从配置中加载，便于扩展
• Excel 导出使用工具类，便于复用

---

八、后续工作

短期

1. 测试验证 - 完成上述测试用例
2. Bug 修复 - 根据测试结果修复问题
3. 运输计划导入 - 实现类似的校验逻辑

长期

1. 校验规则配置化 - 将部分规则抽取为配置
2. 地址库集成 - 实现真实的地址匹配校验
3. 性能优化 - 针对大文件导入进行优化
4. 国际化 - 支持多语言错误信息

---

九、参考资料

参考实现

• 港口码头导入: /blade-system/port-terminal/import-port-terminal
• 导入失败工具类: org.springblade.common.excel.ImportFailureExcelUtil
• 前端导入工具: /src/utils/import-excel.js

相关文档

• 《导入校验规则-后端实现文档.md》
• 《导入校验改造总结.md》

---

完成状态: ✅ 前后端代码已完成，编译通过，等待测试验证

编写人: Claude Code
版本: 1.0