1、调整凭证

2、调整运单
2026-09-08 22:41:40 +08:00
parent f370f56a92
commit bdafb83583
16 changed files with 1816 additions and 51 deletions
@@ -0,0 +1,412 @@
+# 运单导入校验功能 - 最终实现总结
+
+## 完成时间
+2026-09-08
+
+## 实现方式
+**两步校验机制**：
+1. **选择文件后** → 立即调用校验接口（`/import-batch/validate`），只校验不入库
+2. **点击确认导入** → 调用确认接口（`/import-batch/confirm`），再次校验并入库
+
+---
+
+## 一、用户使用流程
+
+### 1. 上传文件阶段
+1. 用户点击"添加附件"按钮
+2. 选择 Excel 文件
+3. **前端自动调用校验接口** `POST /blade-transport/waybill-manage/import-batch/validate`
+4. 后端返回结果：
+   - **校验通过**：返回 JSON，前端提示"数据校验通过"
+   - **校验失败**：返回 Excel 文件流，浏览器自动下载错误明细表，前端提示"数据校验失败，已自动下载错误明细表，请修正后重新上传"
+
+### 2. 确认导入阶段
+1. 用户查看预览数据，确认无误
+2. 点击"确认导入"按钮
+3. **前端调用确认接口** `POST /blade-transport/waybill-manage/import-batch/confirm`
+4. 后端再次校验并入库：
+   - **校验通过**：入库成功，返回 JSON，前端提示"导入成功"
+   - **校验失败**：返回 Excel 文件流，浏览器自动下载错误明细表（防止数据在上传和确认之间被修改）
+
+---
+
+## 二、后端实现
+
+### 1. 新增接口
+
+#### 1.1 校验接口
+**路径**: `POST /blade-transport/waybill-manage/import-batch/validate`
+
+**功能**: 只校验数据，不入库
+
+**返回**:
+- 校验通过：JSON 成功响应
+- 校验失败：Excel 文件流（包含错误信息）
+
+**实现位置**:
+- 控制器：`WaybillController.validateImportBatch()`
+- 服务接口：`IWaybillImportBatchService.validate()`
+- 服务实现：`WaybillImportBatchServiceImpl.validate()`
+
+#### 1.2 确认导入接口（修改）
+**路径**: `POST /blade-transport/waybill-manage/import-batch/confirm`
+
+**功能**: 再次校验并入库
+
+**返回**:
+- 校验通过：入库成功，JSON 成功响应
+- 校验失败：Excel 文件流（包含错误信息）
+
+**实现位置**:
+- 控制器：`WaybillController.confirmImportBatch()`
+- 服务接口：`IWaybillImportBatchService.confirm()`
+- 服务实现：`WaybillImportBatchServiceImpl.confirm()`
+
+### 2. 修改的文件
+
+#### 2.1 控制器
+**文件**: `/blade-service/blade-transport/src/main/java/org/springblade/transport/controller/WaybillController.java`
+
+```java
+@PostMapping("/import-batch/validate")
+@ApiOperationSupport(order = 6)
+@Operation(summary = "校验运单批量导入数据")
+public void validateImportBatch(@RequestBody WaybillImportBatchRequest request, HttpServletResponse response) {
+    waybillImportBatchService.validate(request, response);
+}
+
+@PostMapping("/import-batch/confirm")
+@ApiOperationSupport(order = 7)
+@Operation(summary = "确认运单批量导入")
+public void confirmImportBatch(@RequestBody WaybillImportBatchRequest request, HttpServletResponse response) {
+    waybillImportBatchService.confirm(request, response);
+}
+```
+
+#### 2.2 服务接口
+**文件**: `/blade-service/blade-transport/src/main/java/org/springblade/transport/service/IWaybillImportBatchService.java`
+
+```java
+public interface IWaybillImportBatchService extends BaseService<WaybillImportBatch> {
+    WaybillImportBatch saveDraft(WaybillImportBatchRequest request);
+    void validate(WaybillImportBatchRequest request, HttpServletResponse response);
+    void confirm(WaybillImportBatchRequest request, HttpServletResponse response);
+    IPage<WaybillImportBatchVO> page(IPage<WaybillImportBatch> page, WaybillImportBatchRequest request);
+    BusinessRemoveResultVO removeBatches(String ids);
+}
+```
+
+#### 2.3 服务实现
+**文件**: `/blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/WaybillImportBatchServiceImpl.java`
+
+**新增方法**:
+- `validate()` - 校验数据，不入库
+- `mapToExcel()` - 将 Map 转换为 Excel 对象
+
+**修改方法**:
+- `confirm()` - 校验并入库
+- `persist()` - 移除内部校验逻辑
+
+#### 2.4 Excel 实体
+**文件**: `/blade-service/blade-transport/src/main/java/org/springblade/transport/excel/WaybillImportBatchExcel.java`
+
+**新增字段**:
+```java
+/** 导入失败原因（不导出到模板，仅用于失败明细） */
+private String errorMessage;
+```
+
+---
+
+## 三、前端实现
+
+### 1. 修改的文件
+
+#### 1.1 API 文件
+**文件**: `src/api/business/waybill-manage.js`
+
+**新增接口**:
+```javascript
+export const validateImport = data => request({ 
+  url: `${baseUrl}/import-batch/validate`, 
+  method: 'post', 
+  data, 
+  responseType: 'blob' 
+});
+```
+
+#### 1.2 组件文件
+**文件**: `src/views/business/components/waybill-import-dialog.vue`
+
+**新增方法**:
+```javascript
+const performValidation = async () => {
+  if (!rows.value.length) return;
+
+  try {
+    const response = await api.validateImport(buildImportPayload());
+
+    if (response instanceof Blob) {
+      // 校验失败，下载错误明细
+      const url = window.URL.createObjectURL(response);
+      const link = document.createElement('a');
+      link.href = url;
+      link.download = `运单导入失败明细_${dayjs().format('YYYYMMDDHHmmss')}.xlsx`;
+      link.click();
+      window.URL.revokeObjectURL(url);
+      ElMessage.warning('数据校验失败，已自动下载错误明细表，请修正后重新上传');
+    } else {
+      // 校验通过
+      ElMessage.success('数据校验通过');
+    }
+  } catch (error) {
+    console.error('校验失败:', error);
+    ElMessage.error('校验接口调用失败');
+  }
+};
+```
+
+**修改方法**:
+- `fileChange()` - 文件上传后调用 `performValidation()`
+
+---
+
+## 四、校验规则
+
+### 已实现的校验规则
+
+#### 4.1 格式校验
+- ✅ 车牌号格式（公路运输：首位汉字 + 次位大写字母 + 7-8 位长度）
+- ✅ 手机号格式（11 位数字）
+- ✅ 运输方式枚举值
+- ✅ 计量单位枚举值
+- ✅ 正数校验（数量、里程）
+- ✅ 日期时间格式（YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss）
+
+#### 4.2 逻辑校验
+- ✅ 运费合计 = 运费 + 其他费用合计
+- ✅ 日期关系（发货时间不能晚于完成时间）
+- ✅ 配载标识号一致性（同一配载标识号的车牌号必须一致）
+- ✅ 同一运单标识号一致性（同一运单标识号的车牌号必须一致）
+
+#### 4.3 必填项校验
+- ✅ 车牌号/航班号/船号/班列号
+- ✅ 运输方式
+- ✅ 发货地址
+- ✅ 到货地址
+- ✅ 货物名称
+- ✅ 货物类型
+- ✅ 数量
+- ✅ 数量单位
+- ✅ 实际发货时间（status=completed 时）
+- ✅ 实际完成时间（status=completed 时）
+
+### 错误明细 Excel 格式
+
+- ✅ 在原始 Excel 最后一列追加"错误信息"列
+- ✅ 错误信息以红色字体显示
+- ✅ 校验通过的行显示空字符串
+- ✅ 多个错误用 "; " 分隔
+- ✅ 列宽自动调整
+
+---
+
+## 五、技术要点
+
+### 5.1 两次校验的原因
+1. **第一次校验（上传后）**：
+   - 及早发现问题，用户可以立即修正
+   - 避免用户填写其他表单项后才发现数据有问题
+
+2. **第二次校验（确认导入时）**：
+   - 防止数据在上传和确认之间被修改
+   - 确保入库数据的准确性
+
+### 5.2 响应类型判断
+- **JSON 响应**：`Content-Type: application/json`
+- **Excel 响应**：`Content-Type: application/vnd.ms-excel`
+
+前端通过 `responseType: 'blob'` 接收响应，根据响应类型判断：
+- `Blob` 类型 → 校验失败，下载文件
+- 其他类型 → 校验通过，显示提示
+
+### 5.3 事务处理
+- `validate()` 方法**不开启事务**，只读操作
+- `confirm()` 方法**开启事务**，校验失败时不入库，校验通过后才入库
+
+### 5.4 性能优化
+- 校验逻辑复用（`validateImportRows()` 方法）
+- 使用 `TreeMap` 确保错误信息按行号排序
+- 使用 `Map` 数据结构优化跨行校验性能
+
+---
+
+## 六、测试验证
+
+### 6.1 编译验证
+✅ **后端编译成功** - `mvn clean compile -DskipTests`
+✅ **前端构建成功** - `pnpm run build`
+
+### 6.2 待测试项
+
+#### 功能测试
+- [ ] 上传完全正确的数据
+  - 第一次校验提示"数据校验通过"
+  - 点击确认导入，提示"导入成功"
+  
+- [ ] 上传错误数据（如车牌号格式错误）
+  - 第一次校验自动下载错误明细
+  - 修正后重新上传，校验通过
+  - 点击确认导入，提示"导入成功"
+  
+- [ ] 上传混合数据（部分正确部分错误）
+  - 下载的错误明细最后一列显示错误信息（红色）
+  - 正确的行显示空字符串
+
+#### 边界测试
+- [ ] 上传空文件
+- [ ] 上传非 Excel 文件
+- [ ] 上传超大文件（>5000 行）
+- [ ] 同一配载标识号车牌不一致
+- [ ] 运费合计不匹配
+
+#### 性能测试
+- [ ] 上传 1000 行数据，校验响应时间
+- [ ] 上传 5000 行数据，校验响应时间
+- [ ] 并发上传测试
+
+---
+
+## 七、对比改造前后
+
+### 改造前
+- ❌ 前端校验，规则分散
+- ❌ 前端生成错误 Excel
+- ❌ 前后端规则不一致
+- ❌ 只在确认导入时校验
+
+### 改造后
+- ✅ 后端校验，规则集中
+- ✅ 后端生成错误 Excel
+- ✅ 统一的校验规则
+- ✅ 上传后立即校验 + 确认导入时再次校验
+- ✅ 使用成熟的工具类（`ImportFailureExcelUtil`）
+
+---
+
+## 八、后续工作
+
+### 短期
+1. **联调测试** - 启动前后端服务，完整流程测试
+2. **Bug 修复** - 根据测试结果修复问题
+3. **运输计划导入** - 实现类似的两步校验机制
+
+### 长期
+1. **校验规则配置化** - 将规则抽取为配置，便于维护
+2. **地址库集成** - 实现真实的地址匹配校验
+3. **性能优化** - 针对大文件导入进行优化
+4. **国际化** - 支持多语言错误信息
+
+---
+
+## 九、相关文档
+
+### 已创建的文档
+1. **导入校验规则-后端实现文档.md**（前端项目）
+2. **导入校验改造总结.md**（前端项目）
+3. **运单导入校验-前后端对接完成总结.md**（后端项目）
+4. **本文档**（最终实现总结）
+
+### 参考实现
+- **港口码头导入**: `/blade-system/port-terminal/import-port-terminal`
+- **导入失败工具类**: `org.springblade.common.excel.ImportFailureExcelUtil`
+
+---
+
+## 十、API 接口文档
+
+### 10.1 校验接口
+
+#### 请求
+```
+POST /blade-transport/waybill-manage/import-batch/validate
+Content-Type: application/json
+
+{
+  "projectId": 123,
+  "contractId": 456,
+  "status": "completed",
+  "rows": [...]
+}
+```
+
+#### 响应
+
+**成功（校验通过）**:
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "code": 200,
+  "success": true,
+  "msg": "校验通过"
+}
+```
+
+**失败（校验不通过）**:
+```
+HTTP/1.1 200 OK
+Content-Type: application/vnd.ms-excel
+Content-Disposition: attachment; filename=运单导入失败明细20260908190730.xlsx
+
+[Excel Binary Data]
+```
+
+### 10.2 确认导入接口
+
+#### 请求
+```
+POST /blade-transport/waybill-manage/import-batch/confirm
+Content-Type: application/json
+
+{
+  "projectId": 123,
+  "contractId": 456,
+  "status": "completed",
+  "rows": [...]
+}
+```
+
+#### 响应
+
+**成功（导入成功）**:
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "code": 200,
+  "success": true,
+  "msg": "操作成功"
+}
+```
+
+**失败（校验不通过）**:
+```
+HTTP/1.1 200 OK
+Content-Type: application/vnd.ms-excel
+Content-Disposition: attachment; filename=运单导入失败明细20260908190730.xlsx
+
+[Excel Binary Data]
+```
+
+---
+
+**完成状态**: ✅ 前后端代码已完成，编译通过，等待联调测试
+
+**实现方式**: 两步校验机制（上传后校验 + 确认导入时再次校验）
+
+**编写人**: Claude Code  
+**版本**: 2.0  
+**最后更新**: 2026-09-08 19:10