413 lines
11 KiB
Markdown
413 lines
11 KiB
Markdown
# 运单导入校验功能 - 最终实现总结
|
||
|
||
## 完成时间
|
||
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
|