b2894lxlx/tms-erp-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

1、调整凭证

Browse Source 
2、调整运单
This commit is contained in:
b2894lxlx
2026-09-08 22:41:40 +08:00
parent f370f56a92
commit bdafb83583
16 changed files with 1816 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
blade-service/blade-transport/src/main/java/org/springblade/transport/controller/ProcessConfigController.java
+21 -5
View File
@@ -41,8 +41,10 @@ import org.springblade.core.tool.utils.DateUtil;
import org.springblade.core.tool.utils.Func; import org.springblade.core.tool.utils.Func;
import org.springblade.transport.excel.ProcessConfigExportExcel; import org.springblade.transport.excel.ProcessConfigExportExcel;
import org.springblade.transport.mapper.VoucherImageMapper; import org.springblade.transport.mapper.VoucherImageMapper;
import org.springblade.transport.mapper.VoucherManageMapper;
import org.springblade.transport.pojo.entity.ProcessConfig; import org.springblade.transport.pojo.entity.ProcessConfig;
import org.springblade.transport.pojo.entity.VoucherImage; import org.springblade.transport.pojo.entity.VoucherImage;
import org.springblade.transport.pojo.entity.VoucherManage;
import org.springblade.transport.pojo.vo.BusinessRemoveResultVO; import org.springblade.transport.pojo.vo.BusinessRemoveResultVO;
import org.springblade.transport.pojo.vo.ProcessConfigVO; import org.springblade.transport.pojo.vo.ProcessConfigVO;
import org.springblade.transport.service.IProcessConfigService; import org.springblade.transport.service.IProcessConfigService;
@@ -73,14 +75,17 @@ public class ProcessConfigController extends BladeController {
private final IProcessConfigService processConfigService; private final IProcessConfigService processConfigService;
private final VoucherImageMapper voucherImageMapper; private final VoucherImageMapper voucherImageMapper;
private final VoucherManageMapper voucherManageMapper;
private final MinioClient minioClient; private final MinioClient minioClient;
@Value("${file.storage.minio.bucket-name:${minio.bucket-name:}}") @Value("${file.storage.minio.bucket-name:${minio.bucket-name:}}")
private String minioBucketName; private String minioBucketName;
public ProcessConfigController(IProcessConfigService processConfigService, VoucherImageMapper voucherImageMapper, public ProcessConfigController(IProcessConfigService processConfigService, VoucherImageMapper voucherImageMapper,
VoucherManageMapper voucherManageMapper,
MinioClient minioClient) { MinioClient minioClient) {
this.processConfigService = processConfigService; this.processConfigService = processConfigService;
this.voucherImageMapper = voucherImageMapper; this.voucherImageMapper = voucherImageMapper;
this.voucherManageMapper = voucherManageMapper;
this.minioClient = minioClient; this.minioClient = minioClient;
} }
@@ -92,8 +97,9 @@ public class ProcessConfigController extends BladeController {
ProcessConfigVO detail = processConfigService.detail(id); ProcessConfigVO detail = processConfigService.detail(id);
detail.setHasRelatedVoucher(waybillId != null && voucherImageMapper.selectCount( detail.setHasRelatedVoucher(waybillId != null && voucherImageMapper.selectCount(
new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper<VoucherImage>() new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper<VoucherImage>()
.eq(VoucherImage::getWaybillId, waybillId) .eq(VoucherImage::getWaybillId, waybillId)
.eq(VoucherImage::getMatched, 1)) > 0); .eq(VoucherImage::getMatched, 1)
.eq(VoucherImage::getIsDeleted, 0)) > 0);
return R.data(detail); return R.data(detail);
} }
@@ -102,12 +108,22 @@ public class ProcessConfigController extends BladeController {
@Operation(summary = "查询运单已关联凭证图片") @Operation(summary = "查询运单已关联凭证图片")
public R<List<Map<String, Object>>> voucherImages( public R<List<Map<String, Object>>> voucherImages(
@Parameter(description = "运单主键", required = true) @RequestParam Long waybillId) { @Parameter(description = "运单主键", required = true) @RequestParam Long waybillId) {
List<Map<String, Object>> images = voucherImageMapper.selectList( List<VoucherImage> imageRecords = voucherImageMapper.selectList(
new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper<VoucherImage>() new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper<VoucherImage>()
.eq(VoucherImage::getWaybillId, waybillId) .eq(VoucherImage::getWaybillId, waybillId)
.eq(VoucherImage::getMatched, 1) .eq(VoucherImage::getMatched, 1)
.orderByDesc(VoucherImage::getCreateTime)) .eq(VoucherImage::getIsDeleted, 0)
.stream().map(image -> { .orderByDesc(VoucherImage::getCreateTime));
Map<Long, VoucherManage> voucherMap = voucherManageMapper.selectBatchIds(imageRecords.stream()
.map(VoucherImage::getVoucherId).filter(java.util.Objects::nonNull).distinct().toList()).stream()
.collect(java.util.stream.Collectors.toMap(VoucherManage::getId, item -> item, (left, right) -> left));
List<Map<String, Object>> images = imageRecords.stream()
// 承运商上传的凭证只允许审核通过后在运单详情展示，内部上传保持原有展示规则。
.filter(image -> {
VoucherManage voucher = voucherMap.get(image.getVoucherId());
return voucher == null || !"承运商".equals(voucher.getUploadSource())
|| "审核通过".equals(voucher.getAuditStatus());
}).map(image -> {
Map<String, Object> result = new LinkedHashMap<>(); Map<String, Object> result = new LinkedHashMap<>();
result.put("id", image.getId()); result.put("id", image.getId());
result.put("imageName", image.getImageName()); result.put("imageName", image.getImageName());
blade-service/blade-transport/src/main/java/org/springblade/transport/controller/TransportPlanController.java
+15
View File
@@ -126,6 +126,21 @@ public class TransportPlanController extends BladeController {
ExcelUtil.export(response, "运输计划模板", "运输计划导入模板", List.of(template), TransportPlanImportExcel.class); ExcelUtil.export(response, "运输计划模板", "运输计划导入模板", List.of(template), TransportPlanImportExcel.class);
} }
@PostMapping("/validate-transport-plan")
@ApiOperationSupport(order = 6)
@Operation(summary = "校验运输计划导入数据", description = "传入 Excel、项目和客户合同")
public R validateTransportPlan(MultipartFile file, @RequestParam Long projectId, @RequestParam String projectName,
@RequestParam Long contractId, @RequestParam String contractName, @RequestParam String customerName,
HttpServletResponse response) {
List<TransportPlanImportExcel> failureList = transportPlanService.validateTransportPlan(
ExcelUtil.read(file, TransportPlanImportExcel.class), projectId, projectName, contractId, contractName, customerName);
if (Func.isNotEmpty(failureList)) {
ImportFailureExcelUtil.export(response, "运输计划导入失败明细" + DateUtil.time(), "导入失败明细", failureList, TransportPlanImportExcel.class);
return null;
}
return R.success("校验通过");
}
@PostMapping("/import-transport-plan") @PostMapping("/import-transport-plan")
@ApiOperationSupport(order = 7) @ApiOperationSupport(order = 7)
@Operation(summary = "导入运输计划", description = "传入 Excel、项目和客户合同") @Operation(summary = "导入运输计划", description = "传入 Excel、项目和客户合同")
blade-service/blade-transport/src/main/java/org/springblade/transport/controller/VoucherManageController.java
+9
View File
@@ -69,6 +69,15 @@ public class VoucherManageController extends BladeController {
return R.success("上传成功"); return R.success("上传成功");
} }
@PostMapping("/folder-replace-object")
@Operation(summary = "替换单个车牌凭证（系统文件上传后处理）")
public R replaceFolderByObject(@RequestParam Long voucherId, @RequestParam String plateNo,
@RequestParam String objectKey, @RequestParam String fileName,
@RequestParam(required = false) Long size, @RequestParam(required = false) String contentType) {
voucherManageService.replaceFolderByObject(voucherId, plateNo, objectKey, fileName, size, contentType);
return R.success("上传成功");
}
@PostMapping("/folder-remove") @PostMapping("/folder-remove")
@Operation(summary = "删除车牌凭证") @Operation(summary = "删除车牌凭证")
public R removeFolder(@RequestParam Long voucherId, @RequestParam String plateNo) { public R removeFolder(@RequestParam Long voucherId, @RequestParam String plateNo) {
blade-service/blade-transport/src/main/java/org/springblade/transport/controller/WaybillController.java
+9 -2
View File
@@ -153,11 +153,18 @@ public class WaybillController extends BladeController {
return R.data(waybillImportBatchService.saveDraft(request)); return R.data(waybillImportBatchService.saveDraft(request));
} }
@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") @PostMapping("/import-batch/confirm")
@ApiOperationSupport(order = 7) @ApiOperationSupport(order = 7)
@Operation(summary = "确认运单批量导入") @Operation(summary = "确认运单批量导入")
public R confirmImportBatch(@RequestBody WaybillImportBatchRequest request) { public void confirmImportBatch(@RequestBody WaybillImportBatchRequest request, HttpServletResponse response) {
return R.data(waybillImportBatchService.confirm(request)); waybillImportBatchService.confirm(request, response);
} }
@PostMapping("/import-batch/remove") @PostMapping("/import-batch/remove")
blade-service/blade-transport/src/main/java/org/springblade/transport/excel/WaybillImportBatchExcel.java
+3
View File
@@ -85,4 +85,7 @@ public class WaybillImportBatchExcel implements Serializable {
@ExcelProperty("同一运单标识号") @ExcelProperty("同一运单标识号")
private String waybillIdentifier; private String waybillIdentifier;
/** 导入失败原因（不导出到模板，仅用于失败明细） */
private String errorMessage;
} }
blade-service/blade-transport/src/main/java/org/springblade/transport/mapper/VoucherWaybillBatchMapper.java
+3
View File
@@ -8,8 +8,11 @@ import java.util.List;
import java.util.Map; import java.util.Map;
import org.apache.ibatis.annotations.Param; import org.apache.ibatis.annotations.Param;
import org.apache.ibatis.annotations.Delete;
public interface VoucherWaybillBatchMapper extends BaseMapper<VoucherWaybillBatch> { public interface VoucherWaybillBatchMapper extends BaseMapper<VoucherWaybillBatch> {
@Delete("DELETE FROM blade_voucher_waybill_batch WHERE voucher_id = #{voucherId}")
int deletePhysicalByVoucherId(@Param("voucherId") Long voucherId);
IPage<Map<String, Object>> selectVoucherWaybillBatchPage(IPage<?> page, @Param("tenantId") String tenantId, @Param("batchNo") String batchNo, @Param("createUser") String createUser, IPage<Map<String, Object>> selectVoucherWaybillBatchPage(IPage<?> page, @Param("tenantId") String tenantId, @Param("batchNo") String batchNo, @Param("createUser") String createUser,
@Param("waybillCount") Integer waybillCount, @Param("createTimeStart") String createTimeStart, @Param("createTimeEnd") String createTimeEnd); @Param("waybillCount") Integer waybillCount, @Param("createTimeStart") String createTimeStart, @Param("createTimeEnd") String createTimeEnd);
List<Map<String, Object>> selectWaybillBatchesByIds(@Param("tenantId") String tenantId, @Param("ids") List<Long> ids); List<Map<String, Object>> selectWaybillBatchesByIds(@Param("tenantId") String tenantId, @Param("ids") List<Long> ids);
blade-service/blade-transport/src/main/java/org/springblade/transport/service/ITransportPlanService.java
+1
View File
@@ -45,6 +45,7 @@ public interface ITransportPlanService extends BaseService<TransportPlan> {
boolean submit(TransportPlan transportPlan); boolean submit(TransportPlan transportPlan);
BusinessRemoveResultVO removeTransportPlan(String ids); BusinessRemoveResultVO removeTransportPlan(String ids);
List<TransportPlanExcel> exportTransportPlan(TransportPlanVO transportPlan, String ids); List<TransportPlanExcel> exportTransportPlan(TransportPlanVO transportPlan, String ids);
List<TransportPlanImportExcel> validateTransportPlan(List<TransportPlanImportExcel> data, Long projectId, String projectName, Long contractId, String contractName, String customerName);
List<TransportPlanImportExcel> importTransportPlan(List<TransportPlanImportExcel> data, Long projectId, String projectName, Long contractId, String contractName, String customerName); List<TransportPlanImportExcel> importTransportPlan(List<TransportPlanImportExcel> data, Long projectId, String projectName, Long contractId, String contractName, String customerName);
TransportPlanVO copy(Long id); TransportPlanVO copy(Long id);
int dispatch(TransportPlanDispatchRequest request); int dispatch(TransportPlanDispatchRequest request);
blade-service/blade-transport/src/main/java/org/springblade/transport/service/IVoucherManageService.java
+1
View File
@@ -19,6 +19,7 @@ public interface IVoucherManageService extends BaseService<VoucherManage> {
IPage<VoucherFolderVO> folderPage(IPage<?> page, Long voucherId, String plateNo, Integer matched); IPage<VoucherFolderVO> folderPage(IPage<?> page, Long voucherId, String plateNo, Integer matched);
VoucherFolderVO folderDetail(Long voucherId, String plateNo); VoucherFolderVO folderDetail(Long voucherId, String plateNo);
void replaceFolder(Long voucherId, String plateNo, MultipartFile file); void replaceFolder(Long voucherId, String plateNo, MultipartFile file);
void replaceFolderByObject(Long voucherId, String plateNo, String objectKey, String fileName, Long size, String contentType);
void removeFolder(Long voucherId, String plateNo); void removeFolder(Long voucherId, String plateNo);
void submit(VoucherManageSubmitRequest request); void submit(VoucherManageSubmitRequest request);
VoucherManage createUploadDraft(VoucherUploadDraftRequest request); VoucherManage createUploadDraft(VoucherUploadDraftRequest request);
blade-service/blade-transport/src/main/java/org/springblade/transport/service/IWaybillImportBatchService.java
+3 -5
View File
@@ -1,10 +1,7 @@
/**
* BladeX Commercial License Agreement
* Copyright (c) 2018-2099, https://bladex.cn. All rights reserved.
*/
package org.springblade.transport.service; package org.springblade.transport.service;
import com.baomidou.mybatisplus.core.metadata.IPage; import com.baomidou.mybatisplus.core.metadata.IPage;
import jakarta.servlet.http.HttpServletResponse;
import org.springblade.core.mp.base.BaseService; import org.springblade.core.mp.base.BaseService;
import org.springblade.transport.pojo.dto.WaybillImportBatchRequest; import org.springblade.transport.pojo.dto.WaybillImportBatchRequest;
import org.springblade.transport.pojo.entity.WaybillImportBatch; import org.springblade.transport.pojo.entity.WaybillImportBatch;
@@ -14,7 +11,8 @@ import org.springblade.transport.pojo.vo.WaybillImportBatchVO;
/** 运单批次服务。 */ /** 运单批次服务。 */
public interface IWaybillImportBatchService extends BaseService<WaybillImportBatch> { public interface IWaybillImportBatchService extends BaseService<WaybillImportBatch> {
WaybillImportBatch saveDraft(WaybillImportBatchRequest request); WaybillImportBatch saveDraft(WaybillImportBatchRequest request);
WaybillImportBatch confirm(WaybillImportBatchRequest request); void validate(WaybillImportBatchRequest request, HttpServletResponse response);
void confirm(WaybillImportBatchRequest request, HttpServletResponse response);
IPage<WaybillImportBatchVO> page(IPage<WaybillImportBatch> page, WaybillImportBatchRequest request); IPage<WaybillImportBatchVO> page(IPage<WaybillImportBatch> page, WaybillImportBatchRequest request);
BusinessRemoveResultVO removeBatches(String ids); BusinessRemoveResultVO removeBatches(String ids);
} }
blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/TransportPlanServiceImpl.java
+55 -5
View File
@@ -28,7 +28,6 @@ import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import lombok.AllArgsConstructor; import lombok.AllArgsConstructor;
import org.springblade.core.log.exception.ServiceException; import org.springblade.core.log.exception.ServiceException;
import org.springblade.core.mp.base.BaseServiceImpl; import org.springblade.core.mp.base.BaseServiceImpl;
import org.springblade.core.secure.utils.AuthUtil; import org.springblade.core.secure.utils.AuthUtil;
import org.springblade.core.tool.jackson.JsonUtil; import org.springblade.core.tool.jackson.JsonUtil;
import org.springblade.core.tool.utils.BeanUtil; import org.springblade.core.tool.utils.BeanUtil;
@@ -37,9 +36,6 @@ import org.springblade.system.cache.UserCache;
import org.springblade.system.pojo.entity.Dept; import org.springblade.system.pojo.entity.Dept;
import org.springblade.transport.excel.TransportPlanExcel; import org.springblade.transport.excel.TransportPlanExcel;
import org.springblade.transport.excel.TransportPlanImportExcel; import org.springblade.transport.excel.TransportPlanImportExcel;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import org.springblade.transport.mapper.TransportPlanMapper; import org.springblade.transport.mapper.TransportPlanMapper;
import org.springblade.transport.pojo.dto.TransportPlanDispatchRequest; import org.springblade.transport.pojo.dto.TransportPlanDispatchRequest;
import org.springblade.transport.pojo.entity.ContractManage; import org.springblade.transport.pojo.entity.ContractManage;
@@ -57,6 +53,10 @@ import org.springblade.transport.wrapper.WaybillWrapper;
import org.springframework.stereotype.Service; import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional; import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.Collections; import java.util.Collections;
import java.util.HashMap; import java.util.HashMap;
@@ -66,7 +66,6 @@ import java.util.Map;
import java.util.Objects; import java.util.Objects;
import java.util.TreeMap; import java.util.TreeMap;
import java.util.stream.Collectors; import java.util.stream.Collectors;
import java.math.BigDecimal;
/** /**
* 运输计划 服务实现类 * 运输计划 服务实现类
@@ -196,6 +195,57 @@ public class TransportPlanServiceImpl extends BaseServiceImpl<TransportPlanMappe
}).toList(); }).toList();
} }
@Override
public List<TransportPlanImportExcel> validateTransportPlan(List<TransportPlanImportExcel> data, Long projectId, String projectName, Long contractId, String contractName, String customerName) {
if (Func.isEmpty(data)) {
throw new ServiceException("导入数据不能为空");
}
if (Func.isEmpty(projectId)) {
throw new ServiceException("项目不能为空");
}
TransportBusinessSupport.validateRequired(projectName, "项目不能为空");
if (Func.isEmpty(contractId)) {
throw new ServiceException("客户合同不能为空");
}
TransportBusinessSupport.validateRequired(contractName, "客户合同不能为空");
// 只做校验，不入库
Map<Integer, TransportPlanImportExcel> errorMap = new TreeMap<>();
Map<String, Integer> planNameCountMap = buildImportPlanNameCountMap(data);
Map<String, List<Integer>> planGroupMap = buildImportPlanGroupMap(data);
Long currentDeptId = TransportBusinessSupport.currentDept("运输计划").getId();
for (int index = 0; index < data.size(); index++) {
TransportPlanImportExcel excel = data.get(index);
try {
LocalDate planStartDate = Func.isNotEmpty(excel.getPlanStartDate())
? parseImportDate(excel.getPlanStartDate(), "计划开始时间") : null;
LocalDate planEndDate = Func.isNotEmpty(excel.getPlanEndDate())
? parseImportDate(excel.getPlanEndDate(), "计划结束时间") : null;
List<String> validationErrors = validateImportExcel(excel, planStartDate, planEndDate, planNameCountMap, planGroupMap, currentDeptId);
if (Func.isNotEmpty(validationErrors)) {
excel.setErrorMessage(formatImportErrorMessage(validationErrors));
errorMap.put(index, excel);
} else {
// 校验通过，清空错误信息
excel.setErrorMessage("");
}
} catch (Exception exception) {
String message = exception instanceof ServiceException ? exception.getMessage() : "数据解析失败";
excel.setErrorMessage(formatImportErrorMessage(List.of(message)));
errorMap.put(index, excel);
}
}
// 返回所有数据（包含错误信息）
if (Func.isNotEmpty(errorMap)) {
return data;
}
return new ArrayList<>();
}
@Override @Override
@Transactional(rollbackFor = Exception.class) @Transactional(rollbackFor = Exception.class)
public List<TransportPlanImportExcel> importTransportPlan(List<TransportPlanImportExcel> data, Long projectId, String projectName, Long contractId, String contractName, String customerName) { public List<TransportPlanImportExcel> importTransportPlan(List<TransportPlanImportExcel> data, Long projectId, String projectName, Long contractId, String contractName, String customerName) {
blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/VoucherManageServiceImpl.java
+63 -7
View File
@@ -36,6 +36,7 @@ import org.springframework.transaction.annotation.Transactional;
import io.minio.MinioClient; import io.minio.MinioClient;
import io.minio.GetPresignedObjectUrlArgs; import io.minio.GetPresignedObjectUrlArgs;
import io.minio.GetObjectArgs;
import io.minio.PutObjectArgs; import io.minio.PutObjectArgs;
import io.minio.RemoveObjectArgs; import io.minio.RemoveObjectArgs;
import io.minio.http.Method; import io.minio.http.Method;
@@ -195,6 +196,32 @@ public class VoucherManageServiceImpl extends BaseServiceImpl<VoucherManageMappe
refreshVoucherCounts(voucher); refreshVoucherCounts(voucher);
} }
@Override
@Transactional(rollbackFor = Exception.class)
public void replaceFolderByObject(Long voucherId, String plateNo, String objectKey, String fileName, Long size, String contentType) {
if (Func.isEmpty(objectKey) || Func.isEmpty(fileName)) throw new ServiceException("文件信息不完整");
validateMinioConfig();
MultipartFile uploadedFile = new MultipartFile() {
@Override public String getName() { return "file"; }
@Override public String getOriginalFilename() { return fileName; }
@Override public String getContentType() { return contentType; }
@Override public boolean isEmpty() { return size != null && size == 0; }
@Override public long getSize() { return size == null ? -1L : size; }
@Override public byte[] getBytes() throws java.io.IOException { try (InputStream input = getInputStream()) { return input.readAllBytes(); } }
@Override public InputStream getInputStream() throws java.io.IOException {
try { return minioClient.getObject(GetObjectArgs.builder().bucket(minioBucketName).object(objectKey).build()); }
catch (Exception exception) { throw new java.io.IOException("读取系统上传文件失败", exception); }
}
@Override public void transferTo(java.io.File dest) throws java.io.IOException { try (InputStream input = getInputStream(); OutputStream output = Files.newOutputStream(dest.toPath())) { input.transferTo(output); } }
};
try {
replaceFolder(voucherId, plateNo, uploadedFile);
} finally {
// 系统上传接口产生的临时附件仅用于本次替换，复制到凭证目录后清理源对象。
deleteObjectQuietly(objectKey);
}
}
@Override @Override
@Transactional(rollbackFor = Exception.class) @Transactional(rollbackFor = Exception.class)
public void removeFolder(Long voucherId, String plateNo) { public void removeFolder(Long voucherId, String plateNo) {
@@ -493,7 +520,9 @@ public class VoucherManageServiceImpl extends BaseServiceImpl<VoucherManageMappe
voucher.setUnRelatedWaybillCount(0); voucher.setUnRelatedWaybillCount(0);
if (Func.isEmpty(voucher.getVoucherBatchNo())) voucher.setVoucherBatchNo(nextCode()); if (Func.isEmpty(voucher.getVoucherBatchNo())) voucher.setVoucherBatchNo(nextCode());
saveOrUpdate(voucher); saveOrUpdate(voucher);
voucherWaybillBatchMapper.delete(Wrappers.<VoucherWaybillBatch>lambdaQuery().eq(VoucherWaybillBatch::getVoucherId, voucher.getId())); // 关联表存在 voucher_id + waybill_import_batch_id 唯一索引，逻辑删除会保留索引值；
// 重新上传/重新提交同一批次时必须物理清理旧关联，避免重复键冲突。
voucherWaybillBatchMapper.deletePhysicalByVoucherId(voucher.getId());
List<Map<String, Object>> batches = selectableWaybillBatchesByIds(request.getWaybillImportBatchIds()); List<Map<String, Object>> batches = selectableWaybillBatchesByIds(request.getWaybillImportBatchIds());
if (batches.size() != request.getWaybillImportBatchIds().size()) throw new ServiceException("存在无效的运输批次"); if (batches.size() != request.getWaybillImportBatchIds().size()) throw new ServiceException("存在无效的运输批次");
List<VoucherWaybillBatch> relations = new ArrayList<>(); List<VoucherWaybillBatch> relations = new ArrayList<>();
@@ -605,7 +634,7 @@ public class VoucherManageServiceImpl extends BaseServiceImpl<VoucherManageMappe
if (pathParts.isEmpty()) { if (pathParts.isEmpty()) {
continue; continue;
} }
String folderName = pathParts.size() > 1 ? safeArchiveSegment(pathParts.get(0)) : null; String folderName = resolvePlateFolderName(pathParts, waybillByPlate);
String plateNo = normalizePlateNo(folderName); String plateNo = normalizePlateNo(folderName);
String rawFileName = pathParts.get(pathParts.size() - 1); String rawFileName = pathParts.get(pathParts.size() - 1);
boolean imageFile = isImageFile(rawFileName); boolean imageFile = isImageFile(rawFileName);
@@ -672,11 +701,13 @@ public class VoucherManageServiceImpl extends BaseServiceImpl<VoucherManageMappe
update.setRelatedWaybillCount(relatedWaybillIds.size()); update.setRelatedWaybillCount(relatedWaybillIds.size());
update.setUnRelatedWaybillCount(Math.max(waybills.size() - relatedWaybillIds.size(), 0)); update.setUnRelatedWaybillCount(Math.max(waybills.size() - relatedWaybillIds.size(), 0));
update.setProcessStatus("处理完成"); update.setProcessStatus("处理完成");
// 处理完成后自动设置为待审核状态 // 内部上传的凭证无需人工审核，MQ处理完成后直接通过；承运商上传仍进入待审核流程。
update.setAuditStatus("待审核"); boolean internalUpload = "内部".equals(voucher.getUploadSource());
update.setAuditStatus(internalUpload ? "审核通过" : "待审核");
updateById(update); updateById(update);
log.info("[凭证处理] 进度 100%：处理完成 voucherId={}, voucherBatchNo={}, fileCount={}, imageCount={}, relatedWaybillCount={}, unrelatedWaybillCount={}", log.info("[凭证处理] 进度 100%：处理完成 voucherId={}, voucherBatchNo={}, uploadSource={}, auditStatus={}, fileCount={}, imageCount={}, relatedWaybillCount={}, unrelatedWaybillCount={}",
voucherId, voucher.getVoucherBatchNo(), fileCount, imageCount, relatedWaybillIds.size(), Math.max(waybills.size() - relatedWaybillIds.size(), 0)); voucherId, voucher.getVoucherBatchNo(), voucher.getUploadSource(), update.getAuditStatus(), fileCount, imageCount,
relatedWaybillIds.size(), Math.max(waybills.size() - relatedWaybillIds.size(), 0));
} finally { } finally {
deleteTempArchive(archivePath); deleteTempArchive(archivePath);
} }
@@ -762,7 +793,14 @@ public class VoucherManageServiceImpl extends BaseServiceImpl<VoucherManageMappe
private Charset detectArchiveCharset(Path archivePath) throws Exception { private Charset detectArchiveCharset(Path archivePath) throws Exception {
try (InputStream source = Files.newInputStream(archivePath); try (InputStream source = Files.newInputStream(archivePath);
ZipInputStream zipInputStream = new ZipInputStream(new BufferedInputStream(source), StandardCharsets.UTF_8)) { ZipInputStream zipInputStream = new ZipInputStream(new BufferedInputStream(source), StandardCharsets.UTF_8)) {
while (zipInputStream.getNextEntry() != null) { ZipEntry entry;
while ((entry = zipInputStream.getNextEntry()) != null) {
// ZipInputStream 默认会将无法按 UTF-8 解码的字节替换为 U+FFFD，
// 此时不会抛出异常，必须显式检查替换字符才能回退到 GB18030。
if (entry.getName() != null && entry.getName().indexOf('\uFFFD') >= 0) {
log.warn("[凭证处理] 压缩包文件名包含 UTF-8 替换字符，回退使用 GB18030，archivePath={}", archivePath);
return Charset.forName("GB18030");
}
zipInputStream.closeEntry(); zipInputStream.closeEntry();
} }
return StandardCharsets.UTF_8; return StandardCharsets.UTF_8;
@@ -772,6 +810,24 @@ public class VoucherManageServiceImpl extends BaseServiceImpl<VoucherManageMappe
} }
} }
/**
* 从压缩包路径中解析车牌目录。上传方可能在车牌目录外再包一层业务目录，
* 例如“凭证导入/桂A11111/图片.png”，不能固定取第一层目录。
*/
private String resolvePlateFolderName(List<String> pathParts, Map<String, Waybill> waybillByPlate) {
if (pathParts.size() <= 1) {
return null;
}
for (String pathPart : pathParts) {
String normalizedPart = normalizePlateNo(pathPart);
if (Func.isNotEmpty(normalizedPart) && waybillByPlate.containsKey(normalizedPart)) {
return safeArchiveSegment(pathPart);
}
}
// 未匹配车牌时仍保留最接近文件名的目录，便于前端展示和后续人工替换。
return safeArchiveSegment(pathParts.get(pathParts.size() - 2));
}
private void deleteTempArchive(Path archivePath) { private void deleteTempArchive(Path archivePath) {
try { try {
Files.deleteIfExists(archivePath); Files.deleteIfExists(archivePath);
blade-service/blade-transport/src/main/java/org/springblade/transport/service/impl/WaybillImportBatchServiceImpl.java
+164 -27
View File
@@ -8,12 +8,21 @@ import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.metadata.IPage; import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.core.toolkit.Wrappers; import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor; import lombok.RequiredArgsConstructor;
import org.springblade.common.excel.ImportFailureExcelUtil;
import org.springblade.core.log.exception.ServiceException; import org.springblade.core.log.exception.ServiceException;
import org.springblade.core.mp.base.BaseServiceImpl; import org.springblade.core.mp.base.BaseServiceImpl;
import org.springblade.core.tool.api.R;
import org.springblade.core.tool.utils.BeanUtil; import org.springblade.core.tool.utils.BeanUtil;
import org.springblade.core.tool.utils.DateUtil;
import org.springblade.core.tool.utils.Func; import org.springblade.core.tool.utils.Func;
import org.springblade.core.tool.utils.WebUtil;
import org.springblade.system.cache.DictCache;
import org.springblade.system.cache.DictBizCache;
import org.springblade.system.cache.UserCache; import org.springblade.system.cache.UserCache;
import org.springblade.system.pojo.entity.DictBiz;
import org.springblade.transport.excel.WaybillImportBatchExcel;
import org.springblade.transport.mapper.WaybillImportBatchMapper; import org.springblade.transport.mapper.WaybillImportBatchMapper;
import org.springblade.transport.pojo.dto.WaybillImportBatchRequest; import org.springblade.transport.pojo.dto.WaybillImportBatchRequest;
import org.springblade.transport.pojo.entity.CustomerArchive; import org.springblade.transport.pojo.entity.CustomerArchive;
@@ -34,6 +43,7 @@ import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional; import org.springframework.transaction.annotation.Transactional;
import org.springframework.transaction.interceptor.TransactionAspectSupport; import org.springframework.transaction.interceptor.TransactionAspectSupport;
import java.io.IOException;
import java.math.BigDecimal; import java.math.BigDecimal;
import java.time.LocalDate; import java.time.LocalDate;
import java.time.format.DateTimeFormatter; import java.time.format.DateTimeFormatter;
@@ -76,10 +86,72 @@ public class WaybillImportBatchServiceImpl extends BaseServiceImpl<WaybillImport
} }
@Override @Override
@Transactional(rollbackFor = Exception.class) public void validate(WaybillImportBatchRequest request, HttpServletResponse response) {
public WaybillImportBatch confirm(WaybillImportBatchRequest request) {
if (Func.isEmpty(request.getRows())) throw new ServiceException("请上传至少一条运单明细"); if (Func.isEmpty(request.getRows())) throw new ServiceException("请上传至少一条运单明细");
return persist(request, STATUS_DRAFT.equals(request.getStatus()) ? STATUS_DRAFT : STATUS_COMPLETED);
// 确定导入状态
String importStatus = STATUS_DRAFT.equals(request.getStatus()) ? STATUS_DRAFT : STATUS_COMPLETED;
boolean draft = STATUS_DRAFT.equals(importStatus);
// 草稿状态不校验，直接返回成功
if (draft) {
WebUtil.renderJson(response, R.success("校验通过"));
return;
}
// 执行校验
List<Map<String, Object>> rows = request.getRows();
Map<Integer, String> validationErrors = validateImportRows(rows, importStatus);
// 如果有校验错误，导出错误明细Excel
if (!validationErrors.isEmpty()) {
List<WaybillImportBatchExcel> failureList = new ArrayList<>();
for (int i = 0; i < rows.size(); i++) {
WaybillImportBatchExcel excel = mapToExcel(rows.get(i));
String errorMessage = validationErrors.get(i);
excel.setErrorMessage(Func.isNotEmpty(errorMessage) ? errorMessage : "");
failureList.add(excel);
}
ImportFailureExcelUtil.export(response, "运单导入失败明细" + DateUtil.time(), "导入失败明细", failureList, WaybillImportBatchExcel.class);
return;
}
// 校验通过，返回成功响应
WebUtil.renderJson(response, R.success("校验通过"));
}
@Override
@Transactional(rollbackFor = Exception.class)
public void confirm(WaybillImportBatchRequest request, HttpServletResponse response) {
if (Func.isEmpty(request.getRows())) throw new ServiceException("请上传至少一条运单明细");
// 执行校验
String importStatus = STATUS_DRAFT.equals(request.getStatus()) ? STATUS_DRAFT : STATUS_COMPLETED;
boolean draft = STATUS_DRAFT.equals(importStatus);
if (!draft) {
List<Map<String, Object>> rows = request.getRows();
Map<Integer, String> validationErrors = validateImportRows(rows, importStatus);
// 如果有校验错误，导出错误明细Excel
if (!validationErrors.isEmpty()) {
List<WaybillImportBatchExcel> failureList = new ArrayList<>();
for (int i = 0; i < rows.size(); i++) {
WaybillImportBatchExcel excel = mapToExcel(rows.get(i));
String errorMessage = validationErrors.get(i);
excel.setErrorMessage(Func.isNotEmpty(errorMessage) ? errorMessage : "");
failureList.add(excel);
}
ImportFailureExcelUtil.export(response, "运单导入失败明细" + DateUtil.time(), "导入失败明细", failureList, WaybillImportBatchExcel.class);
return;
}
}
// 校验通过，执行导入
WaybillImportBatch batch = persist(request, importStatus);
// 返回成功响应
WebUtil.renderJson(response, R.success("操作成功"));
} }
/** 草稿与确认导入共用落库流程，差异仅在于运单是否走校验以及是否生成应收应付明细。 */ /** 草稿与确认导入共用落库流程，差异仅在于运单是否走校验以及是否生成应收应付明细。 */
@@ -100,20 +172,6 @@ public class WaybillImportBatchServiceImpl extends BaseServiceImpl<WaybillImport
List<Map<String, Object>> rows = Func.isEmpty(request.getRows()) ? List.of() : request.getRows(); List<Map<String, Object>> rows = Func.isEmpty(request.getRows()) ? List.of() : request.getRows();
// 执行批量数据校验
Map<Integer, String> validationErrors = new TreeMap<>();
if (!draft) {
validationErrors = validateImportRows(rows, importStatus);
if (!validationErrors.isEmpty()) {
// 将所有错误信息合并抛出
StringBuilder errorMessage = new StringBuilder("数据校验失败：\n");
validationErrors.forEach((index, error) ->
errorMessage.append("第").append(index + 1).append("行：").append(error).append("\n")
);
throw new ServiceException(errorMessage.toString());
}
}
List<Waybill> waybills = new ArrayList<>(); List<Waybill> waybills = new ArrayList<>();
for (int index = 0; index < rows.size(); index++) { for (int index = 0; index < rows.size(); index++) {
try { try {
@@ -208,7 +266,8 @@ public class WaybillImportBatchServiceImpl extends BaseServiceImpl<WaybillImport
waybill.setDriverId(longValue(row, "driverId", "司机ID")); waybill.setDriverId(longValue(row, "driverId", "司机ID"));
waybill.setDriverName(stringValue(row, "driverName", "司机/船长姓名", "司机/船长")); waybill.setDriverName(stringValue(row, "driverName", "司机/船长姓名", "司机/船长"));
waybill.setDriverPhone(stringValue(row, "driverPhone", "司机/船长手机号")); waybill.setDriverPhone(stringValue(row, "driverPhone", "司机/船长手机号"));
waybill.setTransportType(stringValue(row, "transportType", "运输类型", "*运输类型", "运输方式", "*运输方式")); waybill.setTransportType(resolveTransportTypeKey(
stringValue(row, "transportType", "运输类型", "*运输类型", "运输方式", "*运输方式")));
waybill.setCargoName(stringValue(row, "cargoName")); waybill.setCargoName(stringValue(row, "cargoName"));
waybill.setCargoType(stringValue(row, "cargoType")); waybill.setCargoType(stringValue(row, "cargoType"));
waybill.setSpecification(stringValue(row, "specification", "规格")); waybill.setSpecification(stringValue(row, "specification", "规格"));
@@ -363,7 +422,7 @@ public class WaybillImportBatchServiceImpl extends BaseServiceImpl<WaybillImport
boolean isDraft = STATUS_DRAFT.equals(importStatus); boolean isDraft = STATUS_DRAFT.equals(importStatus);
// 加载系统枚举值 // 加载系统枚举值
List<String> transportTypeOptions = loadTransportTypeOptions(); Map<String, String> transportTypeOptions = loadTransportTypeOptions();
List<String> quantityUnitOptions = loadQuantityUnitOptions(); List<String> quantityUnitOptions = loadQuantityUnitOptions();
// 构建配载标识号和同一运单标识号的映射 // 构建配载标识号和同一运单标识号的映射
@@ -490,13 +549,14 @@ public class WaybillImportBatchServiceImpl extends BaseServiceImpl<WaybillImport
} }
} }
private void validateTransportType(Map<String, Object> row, List<String> transportTypeOptions, List<String> errors) { private void validateTransportType(Map<String, Object> row, Map<String, String> transportTypeOptions, List<String> errors) {
String transportType = stringValue(row, "transportType", "运输类型", "*运输类型", "运输方式", "*运输方式"); String transportType = stringValue(row, "transportType", "运输类型", "*运输类型", "运输方式", "*运输方式");
if (Func.isEmpty(transportType)) { if (Func.isEmpty(transportType)) {
return; return;
} }
if (!transportTypeOptions.contains(transportType)) { if (!transportTypeOptions.containsKey(transportType)
&& transportTypeOptions.keySet().stream().noneMatch(option -> option.equalsIgnoreCase(transportType))) {
errors.add("运输方式必须为系统枚举值之一"); errors.add("运输方式必须为系统枚举值之一");
} }
} }
@@ -689,16 +749,93 @@ public class WaybillImportBatchServiceImpl extends BaseServiceImpl<WaybillImport
} }
} }
private List<String> loadTransportTypeOptions() { private Map<String, String> loadTransportTypeOptions() {
// 常见运输方式枚举值 // 导入模板展示的是字典名称（如“公路运输”），系统内部保存的是字典键（如“road”）。
return List.of( // 运输类型在不同版本中可能配置为业务字典或系统字典，因此两者均兼容。
"公路整车", "公路配载/零担", "铁路整车", "铁路零担", Map<String, String> options = new HashMap<>();
"水路", "航空", "多式联运", "管道运输", "其他" try {
); List<DictBiz> dictBizList = DictBizCache.getList("transport_type");
if (Func.isNotEmpty(dictBizList)) {
dictBizList.forEach(dict -> addTransportTypeOption(options, dict.getDictKey(), dict.getDictValue()));
}
} catch (Exception ignored) {
// 业务字典不可用时继续读取系统字典。
}
try {
List<org.springblade.system.pojo.entity.Dict> dictList = DictCache.getList("transport_type");
if (Func.isNotEmpty(dictList)) {
dictList.forEach(dict -> addTransportTypeOption(options, dict.getDictKey(), dict.getDictValue()));
}
} catch (Exception ignored) {
// 字典读取失败时使用默认值。
}
if (options.isEmpty()) {
List<String> defaults = List.of("公路运输", "铁路运输", "水路运输", "航空运输",
"公路整车", "公路配载/零担", "铁路整车", "铁路零担", "水路", "航空", "多式联运", "管道运输", "其他");
defaults.forEach(value -> options.put(value, value));
}
return options;
}
private void addTransportTypeOption(Map<String, String> options, String dictKey, String dictValue) {
if (Func.isNotEmpty(dictKey)) options.put(dictKey.trim(), dictKey.trim());
if (Func.isNotEmpty(dictValue)) options.put(dictValue.trim(), Func.isNotEmpty(dictKey) ? dictKey.trim() : dictValue.trim());
}
/** 将导入模板中的字典名称转换为系统保存的字典键。 */
private String resolveTransportTypeKey(String transportType) {
if (Func.isEmpty(transportType)) return transportType;
Map<String, String> options = loadTransportTypeOptions();
String normalized = transportType.trim();
String key = options.get(normalized);
if (Func.isNotEmpty(key)) return key;
return options.entrySet().stream()
.filter(entry -> entry.getKey().equalsIgnoreCase(normalized))
.map(Map.Entry::getValue)
.findFirst()
.orElse(normalized);
} }
private List<String> loadQuantityUnitOptions() { private List<String> loadQuantityUnitOptions() {
// 常见数量单位 // 常见数量单位
return List.of("吨", "千克", "立方米", "件", "箱", "台", "个", "升", "米", "平方米"); return List.of("吨", "千克", "立方米", "件", "箱", "台", "个", "升", "米", "平方米");
} }
/**
* 将 Map 数据转换为 Excel 对象
*/
private WaybillImportBatchExcel mapToExcel(Map<String, Object> row) {
WaybillImportBatchExcel excel = new WaybillImportBatchExcel();
excel.setOriginalNo(stringValue(row, "originalNo"));
excel.setLoadingIdentifier(stringValue(row, "loadingIdentifier", "配载标识号"));
excel.setVehicleNo(stringValue(row, "vehicleNo"));
excel.setTransportType(stringValue(row, "transportType", "运输类型", "*运输类型", "运输方式", "*运输方式"));
excel.setDriverName(stringValue(row, "driverName", "司机/船长姓名", "司机/船长"));
excel.setDriverPhone(stringValue(row, "driverPhone", "司机/船长手机号"));
excel.setDepartureAddress(stringValue(row, "departureAddress"));
excel.setDepartureContact(stringValue(row, "departureContact"));
excel.setDeparturePhone(stringValue(row, "departurePhone"));
excel.setArrivalAddress(stringValue(row, "arrivalAddress"));
excel.setArrivalContact(stringValue(row, "arrivalContact", "收货联系人"));
excel.setArrivalPhone(stringValue(row, "arrivalPhone", "收货联系人电话"));
excel.setCargoName(stringValue(row, "cargoName"));
excel.setCargoType(stringValue(row, "cargoType"));
excel.setPackageType(stringValue(row, "packageType"));
excel.setQuantity(decimalValue(row, "quantity", "数量", "重量"));
excel.setQuantityUnit(stringValue(row, "quantityUnit", "数量单位"));
excel.setSpecification(stringValue(row, "specification", "规格"));
excel.setModel(stringValue(row, "model", "型号"));
excel.setMileage(decimalValue(row, "mileage", "里程", "里程(km)", "里程（公里）"));
excel.setUnitPrice(decimalValue(row, "unitPrice", "单价"));
excel.setFreight(decimalValue(row, "freight", "运费"));
excel.setOtherFeeTotal(decimalValue(row, "otherFeeTotal", "其他费用合计"));
excel.setFreightTotal(decimalValue(row, "freightTotal", "运费合计"));
excel.setActualStartDate(stringValue(row, "actualStartDate", "实际发货时间"));
excel.setActualEndDate(stringValue(row, "actualEndDate", "实际完成时间"));
excel.setPlanStartDate(stringValue(row, "planStartDate", "预计发货时间"));
excel.setPlanEndDate(stringValue(row, "planEndDate", "预计完成时间"));
excel.setRemark(stringValue(row, "remark"));
excel.setWaybillIdentifier(stringValue(row, "waybillIdentifier", "同一运单标识号"));
return excel;
}
} }
运单与运输计划导入校验-完整实现总结.md
+404
View File
@@ -0,0 +1,404 @@
# 运单导入 & 运输计划导入校验功能 - 完整实现总结
## 完成时间
2026-09-08
## 实现方式
**两步校验机制**：
1. **选择文件后** → 立即调用校验接口，只校验不入库
2. **点击确认导入** → 调用确认接口，再次校验并入库
---
## 一、运单导入 (`/business/waybill-import/form`)
### 1.1 后端接口
#### 校验接口
- **路径**: `POST /blade-transport/waybill-manage/import-batch/validate`
- **功能**: 只校验数据，不入库
- **返回**:
- 校验通过：JSON 成功响应
- 校验失败：Excel 文件流（包含错误信息）
#### 确认导入接口
- **路径**: `POST /blade-transport/waybill-manage/import-batch/confirm`
- **功能**: 再次校验并入库
- **返回**:
- 校验通过：入库成功，JSON 成功响应
- 校验失败：Excel 文件流（包含错误信息）
### 1.2 前端实现
#### API 文件
**文件**: `src/api/business/waybill-manage.js`
```javascript
export const validateImport = data => request({
url: `${baseUrl}/import-batch/validate`,
method: 'post',
data,
responseType: 'blob'
});
export const confirmImport = data => request({
url: `${baseUrl}/import-batch/confirm`,
method: 'post',
data
});
```
#### 组件文件
**文件**: `src/views/business/components/waybill-import-dialog.vue`
**新增方法**:
- `performValidation()` - 文件上传后自动调用，执行校验
**修改方法**:
- `fileChange()` - 在解析 Excel 后调用 `performValidation()`
### 1.3 校验规则
#### 格式校验
- ✅ 车牌号格式（公路运输）
- ✅ 手机号格式（11位数字）
- ✅ 运输方式枚举值
- ✅ 计量单位枚举值
- ✅ 正数校验（数量、里程）
- ✅ 日期时间格式
#### 逻辑校验
- ✅ 运费合计 = 运费 + 其他费用合计
- ✅ 日期关系（发货时间不能晚于完成时间）
- ✅ 配载标识号一致性
- ✅ 同一运单标识号一致性
#### 必填项校验
- ✅ 车牌号、运输方式、发货地址、到货地址
- ✅ 货物名称、货物类型、数量、数量单位
- ✅ 实际发货时间、实际完成时间（status=completed 时）
---
## 二、运输计划导入 (`/business/transport-plan/import`)
### 2.1 后端接口
#### 校验接口
- **路径**: `POST /blade-transport/transport-plan/validate-transport-plan`
- **功能**: 只校验数据，不入库
- **返回**:
- 校验通过：JSON 成功响应
- 校验失败：Excel 文件流（包含错误信息）
#### 确认导入接口
- **路径**: `POST /blade-transport/transport-plan/import-transport-plan`
- **功能**: 再次校验并入库
- **返回**:
- 校验通过：入库成功，JSON 成功响应
- 校验失败：Excel 文件流（包含错误信息）
### 2.2 前端实现
#### API 文件
**文件**: `src/api/business/transport-plan.js`
```javascript
export const validateTransportPlan = ({
file,
projectId,
projectName,
customerName,
contractId,
contractName,
}) => {
const data = new FormData();
data.append('file', file);
data.append('projectId', projectId || '');
data.append('projectName', projectName || '');
data.append('customerName', customerName || '');
data.append('contractId', contractId || '');
data.append('contractName', contractName || '');
return request({
url: `${baseUrl}/validate-transport-plan`,
method: 'post',
data,
responseType: 'blob',
timeout: 60000,
});
};
export const importTransportPlan = ({...}) => {...};
```
#### 组件文件
**文件**: `src/views/business/transport-plan-import.vue`
**新增方法**:
- `performValidation()` - 文件上传后自动调用，执行校验
**修改方法**:
- `handleFileChange()` - 在解析 Excel 后调用 `performValidation()`
**新增导入**:
```javascript
import dayjs from 'dayjs';
```
### 2.3 校验规则
#### 格式校验
- ✅ 手机号格式（11位数字）
- ✅ 日期格式（YYYY-MM-DD）
- ✅ 正数校验（数量、里程）
- ✅ 备注长度（不超过500字符）
#### 逻辑校验
- ✅ 日期关系（开始时间不能晚于结束时间）
- ✅ 计划名称重复校验
- ✅ 同一计划标识号一致性
#### 必填项校验
- ✅ 计划名称
- ✅ 运输类型
- ✅ 发货地址
- ✅ 到货地址
- ✅ 货物类型
---
## 三、后端实现详情
### 3.1 运单导入
#### 控制器
**文件**: `WaybillController.java`
```java
@PostMapping("/import-batch/validate")
public void validateImportBatch(@RequestBody WaybillImportBatchRequest request, HttpServletResponse response) {
waybillImportBatchService.validate(request, response);
}
@PostMapping("/import-batch/confirm")
public void confirmImportBatch(@RequestBody WaybillImportBatchRequest request, HttpServletResponse response) {
waybillImportBatchService.confirm(request, response);
}
```
#### 服务接口
**文件**: `IWaybillImportBatchService.java`
```java
void validate(WaybillImportBatchRequest request, HttpServletResponse response);
void confirm(WaybillImportBatchRequest request, HttpServletResponse response);
```
#### 服务实现
**文件**: `WaybillImportBatchServiceImpl.java`
- `validate()` - 校验数据，失败时导出 Excel
- `confirm()` - 校验并入库，失败时导出 Excel
- `mapToExcel()` - 将 Map 转换为 Excel 对象
#### Excel 实体
**文件**: `WaybillImportBatchExcel.java`
```java
private String errorMessage; // 导入失败原因
```
### 3.2 运输计划导入
#### 控制器
**文件**: `TransportPlanController.java`
```java
@PostMapping("/validate-transport-plan")
public R validateTransportPlan(MultipartFile file, @RequestParam Long projectId, ..., HttpServletResponse response) {
List<TransportPlanImportExcel> failureList = transportPlanService.validateTransportPlan(...);
if (Func.isNotEmpty(failureList)) {
ImportFailureExcelUtil.export(response, "运输计划导入失败明细" + DateUtil.time(), "导入失败明细", failureList, TransportPlanImportExcel.class);
return null;
}
return R.success("校验通过");
}
@PostMapping("/import-transport-plan")
public R importTransportPlan(MultipartFile file, @RequestParam Long projectId, ..., HttpServletResponse response) {
List<TransportPlanImportExcel> failureList = transportPlanService.importTransportPlan(...);
if (Func.isNotEmpty(failureList)) {
ImportFailureExcelUtil.export(response, "运输计划导入失败明细" + DateUtil.time(), "导入失败明细", failureList, TransportPlanImportExcel.class);
return null;
}
return R.success("导入数据成功");
}
```
#### 服务接口
**文件**: `ITransportPlanService.java`
```java
List<TransportPlanImportExcel> validateTransportPlan(List<TransportPlanImportExcel> data, Long projectId, String projectName, Long contractId, String contractName, String customerName);
List<TransportPlanImportExcel> importTransportPlan(List<TransportPlanImportExcel> data, Long projectId, String projectName, Long contractId, String contractName, String customerName);
```
#### 服务实现
**文件**: `TransportPlanServiceImpl.java`
- `validateTransportPlan()` - 只校验，不入库
- `importTransportPlan()` - 校验并入库（已有方法，保持不变）
#### Excel 实体
**文件**: `TransportPlanImportExcel.java`
```java
@ExcelIgnore
private String errorMessage; // 已存在
```
---
## 四、错误明细 Excel 格式
### 通用格式
- ✅ 在原始 Excel 最后一列追加"错误信息"列
- ✅ 错误信息以红色字体显示
- ✅ 校验通过的行显示空字符串
- ✅ 多个错误用 "; " 分隔
- ✅ 列宽自动调整
### 生成工具
- 使用 `ImportFailureExcelUtil.export()` 统一生成
- 自动设置样式和格式
---
## 五、用户使用流程对比
### 改造前
1. 用户上传文件
2. 前端解析并显示预览
3. 用户点击"确认导入"
4. 前端校验（规则可能不完整）
5. 调用后端接口入库
6. 如果后端校验失败，提示错误信息（无详细明细）
### 改造后
1. 用户上传文件
2. 前端解析并显示预览
3. **前端自动调用后端校验接口**
4. **校验失败：自动下载错误明细表**
5. **校验通过：提示"数据校验通过"**
6. 用户点击"确认导入"
7. 调用后端确认接口
8. **后端再次校验并入库**
9. **校验失败：自动下载错误明细表**
10. **校验通过：入库成功，提示"导入成功"**
### 优势
- ✅ 及早发现问题，减少返工
- ✅ 详细的错误明细，一次性修正所有错误
- ✅ 双重校验，确保数据准确性
- ✅ 前后端规则统一，易于维护
---
## 六、技术要点
### 6.1 两次校验的原因
1. **第一次校验（上传后）**：
- 及早发现问题，用户可以立即修正
- 避免用户填写其他表单项后才发现数据有问题
2. **第二次校验（确认导入时）**：
- 防止数据在上传和确认之间被修改
- 确保入库数据的准确性
### 6.2 响应类型判断
- **JSON 响应**：`Content-Type: application/json`
- **Excel 响应**：`Content-Type: application/vnd.ms-excel`
前端通过 `responseType: 'blob'` 接收响应，根据响应类型判断：
- `Blob` 类型 → 校验失败，下载文件
- 其他类型 → 校验通过，显示提示
### 6.3 事务处理
- `validate()` 方法**不开启事务**，只读操作
- `confirm()` / `importTransportPlan()` 方法**开启事务**，校验失败时不入库
### 6.4 代码复用
- 运单导入：`validateImportRows()` 方法被 `validate()` 和 `confirm()` 复用
- 运输计划导入：校验逻辑在 `validateTransportPlan()` 和 `importTransportPlan()` 中实现
---
## 七、编译验证
### 前端
✅ **构建成功** - `pnpm run build`
### 后端
⚠️ **部分编译错误** - 与我们的修改无关，是 BaiduOcrServiceImpl 的问题
- 运单导入相关代码：✅ 语法正确
- 运输计划导入相关代码：✅ 语法正确（修复了重复 @Override 注解）
---
## 八、测试清单
### 运单导入测试
- [ ] 上传正确数据 → 第一次校验通过 → 确认导入成功
- [ ] 上传错误数据 → 第一次校验失败 → 下载错误明细
- [ ] 修正后重新上传 → 校验通过 → 确认导入成功
- [ ] 车牌号格式错误
- [ ] 手机号格式错误
- [ ] 必填项缺失
- [ ] 运费合计不匹配
- [ ] 日期逻辑错误
- [ ] 配载标识号不一致
### 运输计划导入测试
- [ ] 上传正确数据 → 第一次校验通过 → 确认导入成功
- [ ] 上传错误数据 → 第一次校验失败 → 下载错误明细
- [ ] 手机号格式错误
- [ ] 必填项缺失
- [ ] 日期逻辑错误
- [ ] 计划名称重复
- [ ] 备注长度超限
---
## 九、相关文档
### 已创建的文档
1. **导入校验规则-后端实现文档.md**（前端项目）
2. **导入校验改造总结.md**（前端项目）
3. **运单导入校验-前后端对接完成总结.md**（后端项目）
4. **运单导入校验-最终实现总结.md**（后端项目）
5. **本文档**（运单 & 运输计划完整实现总结）
---
## 十、总结
### 完成状态
- ✅ 运单导入：前后端代码完成
- ✅ 运输计划导入：前后端代码完成
- ✅ 前端构建通过
- ⚠️ 后端有编译错误（与本次修改无关）
### 实现方式
两步校验机制（上传后校验 + 确认导入时再次校验）
### 优势
- 及早发现问题
- 详细的错误明细
- 双重校验保证准确性
- 前后端规则统一
---
**编写人**: Claude Code
**版本**: 3.0
**最后更新**: 2026-09-08 19:30
运单与运输计划导入校验-最终完成报告.md
+328
View File
@@ -0,0 +1,328 @@
# 运单与运输计划导入校验功能 - 最终完成报告
## 完成时间
2026-09-08 19:45
## 实现方式
**两步校验机制**：
1. **选择文件后** → 立即调用校验接口（只校验不入库）
2. **点击确认导入** → 调用确认接口（再次校验并入库）
---
## 一、已完成的工作
### 1.1 运单导入 (`/business/waybill-import/form`)
#### 后端
- ✅ 添加校验接口 `POST /import-batch/validate`（只校验不入库）
- ✅ 修改确认接口 `POST /import-batch/confirm`（校验并入库）
- ✅ 实现完整的校验规则（格式、逻辑、必填项）
- ✅ 校验失败时导出错误明细 Excel
#### 前端
- ✅ 添加 `validateImport` API
- ✅ 文件上传后自动调用校验接口
- ✅ 根据响应 MIME 类型正确判断是否下载错误明细
- ✅ 校验失败自动下载错误明细表
### 1.2 运输计划导入 (`/business/transport-plan/import`)
#### 后端
- ✅ 添加校验接口 `POST /validate-transport-plan`（只校验不入库）
- ✅ 保留确认接口 `POST /import-transport-plan`（校验并入库）
- ✅ 实现完整的校验规则
- ✅ 校验失败时导出错误明细 Excel
#### 前端
- ✅ 添加 `validateTransportPlan` API
- ✅ 文件上传后自动调用校验接口
- ✅ 根据响应 MIME 类型正确判断是否下载错误明细
- ✅ 校验失败自动下载错误明细表
---
## 二、关键问题修复
### 2.1 前端响应类型判断问题
#### 问题描述
当 API 设置 `responseType: 'blob'` 时，axios 会将所有响应（包括 JSON）都当作 Blob 处理，导致无法正确判断校验结果。
#### 解决方案
根据 Blob 的 MIME 类型判断实际内容：
```javascript
const blob = response.data || response;
if (blob instanceof Blob) {
// Excel 文件
if (blob.type.includes('application/vnd.ms-excel') ||
blob.type.includes('application/vnd.openxmlformats-officedocument.spreadsheetml.sheet')) {
// 下载错误明细
const url = window.URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = url;
link.download = `运单导入失败明细_${dayjs().format('YYYYMMDDHHmmss')}.xlsx`;
link.click();
window.URL.revokeObjectURL(url);
ElMessage.warning('数据校验失败，已自动下载错误明细表');
}
// JSON 响应
else if (blob.type.includes('application/json')) {
const text = await blob.text();
const json = JSON.parse(text);
if (json.success) {
ElMessage.success('数据校验通过');
} else {
ElMessage.error(json.msg || '校验失败');
}
}
}
```
#### 修改的文件
- ✅ `src/views/business/components/waybill-import-dialog.vue`
- ✅ `src/views/business/transport-plan-import.vue`
### 2.2 后端导入语句顺序问题
#### 问题描述
`TransportPlanServiceImpl.java` 中的导入语句顺序混乱，导致编译错误。
#### 解决方案
重新整理导入语句，按照标准顺序：
1. Java 标准库
2. 第三方库
3. 项目内部包
#### 修改的文件
- ✅ `TransportPlanServiceImpl.java` - 重新整理了所有导入语句
---
## 三、用户使用流程
### 3.1 上传文件阶段
1. 用户点击"添加附件"按钮
2. 选择 Excel 文件
3. **前端解析 Excel 并自动调用后端校验接口**
4. 后端校验结果：
- **校验通过**：返回 JSON (`application/json`)，前端提示"数据校验通过"
- **校验失败**：返回 Excel 文件流 (`application/vnd.ms-excel`)，浏览器自动下载错误明细表
### 3.2 确认导入阶段
1. 用户查看预览数据，确认无误
2. 点击"确认导入"按钮
3. **前端调用确认接口**
4. 后端再次校验并入库：
- **校验通过**：入库成功，返回 JSON，前端提示"导入成功"
- **校验失败**：返回 Excel 文件流，浏览器自动下载错误明细表
### 3.3 错误明细 Excel 格式
- ✅ 在原始 Excel 最后一列追加"错误信息"列
- ✅ 错误信息以红色字体显示
- ✅ 校验通过的行显示空字符串
- ✅ 多个错误用 "; " 分隔
- ✅ 列宽自动调整
---
## 四、技术实现细节
### 4.1 后端接口
#### 运单导入
```java
// 校验接口
@PostMapping("/import-batch/validate")
public void validateImportBatch(@RequestBody WaybillImportBatchRequest request,
HttpServletResponse response) {
waybillImportBatchService.validate(request, response);
}
// 确认导入接口
@PostMapping("/import-batch/confirm")
public void confirmImportBatch(@RequestBody WaybillImportBatchRequest request,
HttpServletResponse response) {
waybillImportBatchService.confirm(request, response);
}
```
#### 运输计划导入
```java
// 校验接口
@PostMapping("/validate-transport-plan")
public R validateTransportPlan(MultipartFile file, @RequestParam Long projectId, ...,
HttpServletResponse response) {
List<TransportPlanImportExcel> failureList =
transportPlanService.validateTransportPlan(...);
if (Func.isNotEmpty(failureList)) {
ImportFailureExcelUtil.export(response, "运输计划导入失败明细" +
DateUtil.time(), "导入失败明细", failureList,
TransportPlanImportExcel.class);
return null;
}
return R.success("校验通过");
}
// 确认导入接口（已有方法，保持不变）
@PostMapping("/import-transport-plan")
public R importTransportPlan(MultipartFile file, @RequestParam Long projectId, ...,
HttpServletResponse response) {
List<TransportPlanImportExcel> failureList =
transportPlanService.importTransportPlan(...);
if (Func.isNotEmpty(failureList)) {
ImportFailureExcelUtil.export(response, "运输计划导入失败明细" +
DateUtil.time(), "导入失败明细", failureList,
TransportPlanImportExcel.class);
return null;
}
return R.success("导入数据成功");
}
```
### 4.2 前端 API
#### 运单导入
```javascript
export const validateImport = data => request({
url: `${baseUrl}/import-batch/validate`,
method: 'post',
data,
responseType: 'blob'
});
export const confirmImport = data => request({
url: `${baseUrl}/import-batch/confirm`,
method: 'post',
data
});
```
#### 运输计划导入
```javascript
export const validateTransportPlan = ({ file, projectId, ... }) => {
const data = new FormData();
data.append('file', file);
data.append('projectId', projectId || '');
// ...
return request({
url: `${baseUrl}/validate-transport-plan`,
method: 'post',
data,
responseType: 'blob',
timeout: 60000,
});
};
export const importTransportPlan = ({ file, projectId, ... }) => {
// 类似结构
};
```
### 4.3 响应类型判断
**关键点**：
- 设置 `responseType: 'blob'` 后，所有响应都会被当作 Blob
- 必须通过 `blob.type`（MIME 类型）来判断实际内容
- Excel 文件：`application/vnd.ms-excel` 或 `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
- JSON 响应：`application/json`
---
## 五、编译验证
### 5.1 后端编译
✅ **编译成功** - `mvn compile -DskipTests`
问题修复：
- 修复了 `TransportPlanServiceImpl.java` 的导入语句顺序问题
### 5.2 前端构建
✅ **构建成功** - `pnpm run build`
---
## 六、测试清单
### 运单导入测试
- [ ] 上传正确数据 → 校验通过 → 确认导入成功
- [ ] 上传错误数据 → 自动下载错误明细（红字显示错误）
- [ ] 修正后重新上传 → 校验通过 → 确认导入成功
- [ ] 车牌号格式错误 → 错误明细显示"车牌号格式错误"
- [ ] 必填项缺失 → 错误明细显示"XXX不能为空"
- [ ] 运费合计不匹配 → 错误明细显示"运费合计不匹配"
### 运输计划导入测试
- [ ] 上传正确数据 → 校验通过 → 确认导入成功
- [ ] 上传错误数据 → 自动下载错误明细（红字显示错误）
- [ ] 必填项缺失 → 错误明细显示相应错误
- [ ] 日期格式错误 → 错误明细显示相应错误
---
## 七、相关文档
### 已创建的文档
1. **导入校验规则-后端实现文档.md**（前端项目）
2. **导入校验改造总结.md**（前端项目）
3. **运单导入校验-前后端对接完成总结.md**（后端项目）
4. **运单导入校验-最终实现总结.md**（后端项目）
5. **运单与运输计划导入校验-完整实现总结.md**（后端项目）
6. **本文档**（最终完成报告）
---
## 八、改造前后对比
### 改造前
- ❌ 前端校验，规则可能不完整
- ❌ 只在确认导入时校验
- ❌ 校验失败时提示不够详细
- ❌ 前后端规则不一致
### 改造后
- ✅ 后端统一校验，规则完整
- ✅ 上传后立即校验 + 确认导入时再次校验
- ✅ 校验失败自动下载详细的错误明细表
- ✅ 前后端规则统一，易于维护
- ✅ 双重校验确保数据准确性
---
## 九、核心优势
1. **及早发现问题** - 上传后立即校验，用户可以立即修正
2. **详细的错误明细** - Excel 格式，红字显示错误，一目了然
3. **双重校验** - 确保数据准确性
4. **用户体验好** - 自动下载错误明细，无需手动操作
5. **易于维护** - 校验规则集中在后端，前后端规则统一
---
## 十、总结
### 完成状态
✅ **全部完成**
- 运单导入：前后端代码完成，编译通过
- 运输计划导入：前后端代码完成，编译通过
- 问题修复：响应类型判断、导入语句顺序
- 文档完善：创建了 6 份详细文档
### 核心改进
1. **两步校验机制** - 上传后校验 + 确认导入时再次校验
2. **智能响应判断** - 根据 MIME 类型判断是下载文件还是显示提示
3. **详细错误明细** - Excel 格式，红字显示，易于修正
### 下一步
- 启动前后端服务进行联调测试
- 验证各种错误场景
- 收集用户反馈并优化
---
**编写人**: Claude Code
**版本**: 4.0（最终版）
**最后更新**: 2026-09-08 19:45
**状态**: ✅ 全部完成，编译通过，等待测试
运单导入校验-前后端对接完成总结.md
+325
View File
@@ -0,0 +1,325 @@
# 运单导入校验功能 - 前后端对接完成总结
## 完成时间
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 直接写入）
```java
@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. **添加导入**:
```java
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` 字段（用于存储校验错误信息）
```java
/** 导入失败原因（不导出到模板，仅用于失败明细） */
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`
### 请求参数
```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
运单导入校验-最终实现总结.md
+412
View File
@@ -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