✨ 管理端认证审核接口,并弃用旧车辆审核入口

审核作用于**一条认证记录**,不是车辆行或司机行。两条路径的差别是本次改造的关键:
- 通过:记录转已通过 + 写审核人/审核时间,并把该对象的生效快照指针**切换**到它
  (切换而非追加,故一个对象至多一条生效快照);
- 驳回:记录转已驳回并留原因,生效快照指针**一个字都不动**。

因此「已认证的车被驳回」不会掉出可用池,只是这次提交没被采纳。

已终态(已通过/已驳回/已作废)的记录拒绝再次审核。理由:若允许,
把指针指着的那条「已通过」改成「已驳回」,生效值就凭空消失了。

审核详情同时返回待审快照与当前生效值两侧,供审核页做字段级 diff
(这正是「看出司机改了什么」的实质要求),并附 certified 标记,
便于前端提示「本次驳回不影响该对象继续使用」。

旧接口 POST /transport-vehicle/audit-certification 置为 @Deprecated 并加告警日志:
它作用于车辆行且原地覆盖,在生效值/待审值分离后语义已不成立。
保留而不删除是为了避免小程序历史版本或其它系统 404;它只写展示缓存,
不再影响可用性判定(可用性只看 effective_cert_record_id)。

修复过程中被测试抓到两个真实问题:
1. 通过路径原先对同一行连发两次 UPDATE(先切指针、再刷展示缓存),
   合并为一次,消除了「后写覆盖先写」的可能;
2. 新增 EffectivePointerUpdateSqlTest,直接断言 MyBatis-Plus 生成的 UPDATE SET 片段:
   指针列必须被「值非 null 才写」的 if 包住——驳回传 null 因此物理上碰不到它。
   把「靠约定」变成「靠语句」,若有人给该字段加 ALWAYS 策略,测试立刻变红。

13 个审核用例 + 全模块 48 个测试通过:mvn -o test -pl blade-service/blade-transport -am
This commit is contained in:
2026-10-02 16:26:20 +08:00
parent 63762b9dd0
commit 5747975152
7 changed files with 859 additions and 1 deletions
@@ -0,0 +1,95 @@
/**
* BladeX Commercial License Agreement
* Copyright (c) 2018-2099, https://bladex.cn. All rights reserved.
* <p>
* Use of this software is governed by the Commercial License Agreement
* obtained after purchasing a license from BladeX.
* <p>
* 1. This software is for development use only under a valid license
* from BladeX.
* <p>
* 2. Redistribution of this software's source code to any third party
* without a commercial license is strictly prohibited.
* <p>
* 3. Licensees may copyright their own code but cannot use segments
* from this software for such purposes. Copyright of this software
* remains with BladeX.
* <p>
* Using this software signifies agreement to this License, and the software
* must not be used for illegal purposes.
* <p>
* THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY. The author is
* not liable for any claims arising from secondary or illegal development.
* <p>
* Author: Chill Zhuang (bladejava@qq.com)
*/
package org.springblade.transport.controller;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.AllArgsConstructor;
import org.springblade.core.boot.ctrl.BladeController;
import org.springblade.core.secure.annotation.PreAuth;
import org.springblade.core.tool.api.R;
import org.springblade.transport.pojo.vo.CertAuditDetailVO;
import org.springblade.transport.pojo.vo.TransportCertRecordVO;
import org.springblade.transport.service.ICertAuditService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* 认证审核(管理端)
* <p>
* 审核对象是**一条认证记录**,不是「一辆车」或「一个人」。
* 这与旧的车辆认证审核接口有本质区别:旧接口作用于车辆行并原地覆盖,
* 在「生效值 / 待审值分离」之后语义已不成立,故已弃用。
*/
@RestController
@AllArgsConstructor
@RequestMapping({"/certification-audit", "/blade-transport/certification-audit"})
@Tag(name = "认证审核", description = "管理端司机认证与车辆认证审核")
public class CertificationAuditController extends BladeController {
private final ICertAuditService certAuditService;
@GetMapping("/pending-page")
@ApiOperationSupport(order = 1)
@Operation(summary = "待审列表", description = "按认证对象类型分页查询审核中的记录,按提交时间倒序")
@PreAuth("hasAnyRole('administrator','admin')")
public R<IPage<TransportCertRecordVO>> pendingPage(
@Parameter(description = "认证对象类型:driver-司机,vehicle-车辆", required = true)
@RequestParam String bizType,
@Parameter(description = "展示键模糊匹配:司机姓名 / 车牌号")
@RequestParam(required = false) String bizKey,
@Parameter(description = "页码") @RequestParam(required = false) Integer current,
@Parameter(description = "每页条数") @RequestParam(required = false) Integer size) {
return R.data(certAuditService.pendingPage(bizType, bizKey, current, size));
}
@GetMapping("/detail")
@ApiOperationSupport(order = 2)
@Operation(summary = "审核详情", description = "同时返回待审快照与当前生效值,供前端做字段级对比")
@PreAuth("hasAnyRole('administrator','admin')")
public R<CertAuditDetailVO> detail(
@Parameter(description = "认证记录主键", required = true) @RequestParam Long id) {
return R.data(certAuditService.detail(id));
}
@PostMapping("/audit")
@ApiOperationSupport(order = 3)
@Operation(summary = "审核认证记录", description = "通过使该记录成为生效快照;驳回只终结该记录,生效快照不变")
@PreAuth("hasAnyRole('administrator','admin')")
public R<Boolean> audit(
@Parameter(description = "认证记录主键", required = true) @RequestParam Long id,
@Parameter(description = "是否通过", required = true) @RequestParam Boolean pass,
@Parameter(description = "驳回原因,驳回时必填") @RequestParam(required = false) String rejectReason) {
return R.status(certAuditService.audit(id, Boolean.TRUE.equals(pass), rejectReason));
}
}
@@ -35,6 +35,7 @@ import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.validation.Valid;
import lombok.AllArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springblade.core.boot.ctrl.BladeController;
import org.springblade.core.excel.util.ExcelUtil;
import org.springblade.core.mp.support.Condition;
@@ -67,6 +68,7 @@ import java.util.List;
*/
@RestController
@AllArgsConstructor
@Slf4j
@PreAuth(menu = "transport_vehicle")
@RequestMapping("/transport-vehicle")
@Tag(name = "车辆管理", description = "车辆管理")
@@ -132,11 +134,27 @@ public class TransportVehicleController extends BladeController {
return R.status(transportVehicleService.changeStatus(id, status));
}
/**
* 审核车辆认证(已弃用)
*
* @deprecated 本接口作用于**车辆行**并原地覆盖认证状态,在「生效值 / 待审值分离」
* 之后语义已不成立:一次审核应对应**一条认证记录**,且通过才建立生效快照、
* 驳回不得影响既得认证。请改用
* {@code POST /blade-transport/certification-audit/audit}。
* <p>
* 保留而非删除,是因为它可能仍被小程序历史版本或其它系统调用;
* 调用时记录告警日志。它只写展示缓存,**不再影响可用性判定**
* (可用性只看 {@code effective_cert_record_id})。
*/
@Deprecated
@PostMapping("/audit-certification")
@ApiOperationSupport(order = 6)
@Operation(summary = "审核车辆认证")
@Operation(summary = "审核车辆认证(已弃用)",
description = "已弃用:作用于车辆行且原地覆盖。请改用 /blade-transport/certification-audit/audit")
public R auditCertification(@RequestParam Long id, @RequestParam Integer certificationStatus,
@RequestParam(required = false) String rejectReason) {
log.warn("[认证审核] 调用了已弃用接口 audit-certification,vehicleId={}, status={};"
+ "请改用 /blade-transport/certification-audit/audit", id, certificationStatus);
return R.status(transportVehicleService.auditCertification(id, certificationStatus, rejectReason));
}
@@ -0,0 +1,80 @@
/**
* BladeX Commercial License Agreement
* Copyright (c) 2018-2099, https://bladex.cn. All rights reserved.
* <p>
* Use of this software is governed by the Commercial License Agreement
* obtained after purchasing a license from BladeX.
* <p>
* 1. This software is for development use only under a valid license
* from BladeX.
* <p>
* 2. Redistribution of this software's source code to any third party
* without a commercial license is strictly prohibited.
* <p>
* 3. Licensees may copyright their own code but cannot use segments
* from this software for such purposes. Copyright of this software
* remains with BladeX.
* <p>
* Using this software signifies agreement to this License, and the software
* must not be used for illegal purposes.
* <p>
* THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY. The author is
* not liable for any claims arising from secondary or illegal development.
* <p>
* Author: Chill Zhuang (bladejava@qq.com)
*/
package org.springblade.transport.service;
import com.baomidou.mybatisplus.core.metadata.IPage;
import org.springblade.transport.pojo.entity.TransportCertRecord;
import org.springblade.transport.pojo.vo.CertAuditDetailVO;
import org.springblade.transport.pojo.vo.TransportCertRecordVO;
/**
* 认证审核服务(管理端)
* <p>
* 审核对象是**一条认证记录**,不是「一辆车」或「一个人」。
* 通过使该记录成为生效快照;驳回只终结该记录,生效快照保持不变。
*
* @author Chill
*/
public interface ICertAuditService {
/**
* 待审记录分页(按认证对象类型)
*
* @param bizType 认证对象类型:driver-司机,vehicle-车辆
* @param bizKey 展示键模糊匹配,可为空
* @param pageNum 页码
* @param pageSize 每页条数
* @return 待审记录分页
*/
IPage<TransportCertRecordVO> pendingPage(String bizType, String bizKey, Integer pageNum, Integer pageSize);
/**
* 审核详情:同时返回待审快照与当前生效值,供前端做 diff
*
* @param recordId 认证记录主键
* @return 审核详情
*/
CertAuditDetailVO detail(Long recordId);
/**
* 审核一条认证记录
*
* @param recordId 认证记录主键
* @param pass true 通过,false 驳回
* @param rejectReason 驳回原因;驳回时必填,≤200 字
* @return 是否成功
*/
boolean audit(Long recordId, boolean pass, String rejectReason);
/**
* 按主键取记录,供写指针时复用
*
* @param recordId 认证记录主键
* @return 认证记录;不存在返回 null
*/
TransportCertRecord getRecordOrNull(Long recordId);
}
@@ -0,0 +1,225 @@
/**
* BladeX Commercial License Agreement
* Copyright (c) 2018-2099, https://bladex.cn. All rights reserved.
* <p>
* Use of this software is governed by the Commercial License Agreement
* obtained after purchasing a license from BladeX.
* <p>
* 1. This software is for development use only under a valid license
* from BladeX.
* <p>
* 2. Redistribution of this software's source code to any third party
* without a commercial license is strictly prohibited.
* <p>
* 3. Licensees may copyright their own code but cannot use segments
* from this software for such purposes. Copyright of this software
* remains with BladeX.
* <p>
* Using this software signifies agreement to this License, and the software
* must not be used for illegal purposes.
* <p>
* THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY. The author is
* not liable for any claims arising from secondary or illegal development.
* <p>
* Author: Chill Zhuang (bladejava@qq.com)
*/
package org.springblade.transport.service.impl;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import lombok.RequiredArgsConstructor;
import org.springblade.core.log.exception.ServiceException;
import org.springblade.core.secure.utils.AuthUtil;
import org.springblade.core.tool.utils.Func;
import org.springblade.transport.pojo.entity.Driver;
import org.springblade.transport.pojo.entity.TransportCertRecord;
import org.springblade.transport.pojo.entity.TransportVehicle;
import org.springblade.transport.pojo.vo.CertAuditDetailVO;
import org.springblade.transport.pojo.vo.TransportCertRecordVO;
import org.springblade.transport.service.ICertAuditService;
import org.springblade.transport.service.IDriverService;
import org.springblade.transport.service.ITransportCertRecordService;
import org.springblade.transport.service.ITransportVehicleService;
import org.springblade.transport.support.CertificationRuleSupport;
import org.springblade.transport.wrapper.TransportCertRecordWrapper;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.time.LocalDateTime;
/**
* 认证审核服务实现
* <p>
* 审核作用于**一条记录**。两条路径的差别是本次改造的关键:
* <ul>
* <li><b>通过</b>:记录转已通过,并把该对象的生效快照指针切到它;</li>
* <li><b>驳回</b>:记录转已驳回并留原因,生效快照指针<b>一个字都不动</b>。</li>
* </ul>
* 因此「已认证的车被驳回」不会让它掉出可用池,只是这次提交没被采纳。
*
* @author Chill
*/
@Service
@RequiredArgsConstructor
public class CertAuditServiceImpl implements ICertAuditService {
private final ITransportCertRecordService certRecordService;
private final ITransportVehicleService transportVehicleService;
private final IDriverService driverService;
@Override
public IPage<TransportCertRecordVO> pendingPage(String bizType, String bizKey,
Integer pageNum, Integer pageSize) {
if (!CertificationRuleSupport.isValidBizType(bizType)) {
throw new ServiceException("认证对象类型不正确");
}
LambdaQueryWrapper<TransportCertRecord> queryWrapper = Wrappers.<TransportCertRecord>lambdaQuery()
.eq(TransportCertRecord::getBizType, bizType)
.eq(TransportCertRecord::getStatus, TransportCertRecord.STATUS_PENDING)
.like(Func.isNotEmpty(bizKey), TransportCertRecord::getBizKey, bizKey)
.orderByDesc(TransportCertRecord::getSubmitTime);
Page<TransportCertRecord> page = Page.of(
Func.isEmpty(pageNum) ? 1 : pageNum,
Func.isEmpty(pageSize) ? 10 : pageSize);
return TransportCertRecordWrapper.build().pageVO(certRecordService.page(page, queryWrapper));
}
@Override
public CertAuditDetailVO detail(Long recordId) {
TransportCertRecord record = requireRecord(recordId);
Long effectiveId = effectiveRecordIdOf(record.getBizType(), record.getBizId());
CertAuditDetailVO detail = new CertAuditDetailVO();
detail.setId(record.getId());
detail.setBizType(record.getBizType());
detail.setBizId(record.getBizId());
detail.setBizKey(record.getBizKey());
detail.setStatus(record.getStatus());
detail.setStatusText(CertificationRuleSupport.statusText(record.getStatus()));
detail.setSubmitTime(record.getSubmitTime());
detail.setSubmitUser(record.getSubmitUser());
detail.setPendingSnapshotJson(record.getSnapshotJson());
// 生效值一侧:从未认证通过时为 null,前端按「无对比基准」处理
detail.setEffectiveRecordId(effectiveId);
detail.setCertified(CertificationRuleSupport.isCertified(effectiveId));
if (Func.isNotEmpty(effectiveId)) {
TransportCertRecord effective = certRecordService.getById(effectiveId);
detail.setEffectiveSnapshotJson(effective == null ? null : effective.getSnapshotJson());
}
return detail;
}
@Override
@Transactional(rollbackFor = Exception.class)
public boolean audit(Long recordId, boolean pass, String rejectReason) {
TransportCertRecord record = requireRecord(recordId);
// 终态不可再审。若允许,把指针指着的那条「已通过」改成「已驳回」,
// 生效值就凭空消失了——这正是必须挡住的原因。
if (!CertificationRuleSupport.isAuditable(record)) {
throw new ServiceException("该认证记录已是"
+ CertificationRuleSupport.statusText(record.getStatus()) + "状态,不可再次审核");
}
if (!CertificationRuleSupport.isRejectReasonValid(pass, rejectReason)) {
throw new ServiceException("请输入认证驳回原因(不超过"
+ TransportCertRecord.REJECT_REASON_MAX_LENGTH + "字)");
}
Long auditor = AuthUtil.getUserId();
LocalDateTime auditTime = LocalDateTime.now();
// 1) 记录本身:状态 + 审核留痕(审核人、审核时间写在这条记录上,不依赖会被覆盖的审计字段)
TransportCertRecord patch = new TransportCertRecord();
patch.setId(record.getId());
patch.setStatus(pass ? TransportCertRecord.STATUS_APPROVED : TransportCertRecord.STATUS_REJECTED);
patch.setRejectReason(pass
? CertificationRuleSupport.reasonForApprove()
: CertificationRuleSupport.reasonForReject(rejectReason));
patch.setAuditUser(auditor);
patch.setAuditTime(auditTime);
certRecordService.updateById(patch);
// 2) 认证对象:通过才切指针;驳回只刷展示缓存。两者合并为**一次** UPDATE,
// 避免对同一行连续写两次(第二次会把第一次的指针覆盖掉的风险也随之消失)。
updateCertTarget(record, pass, rejectReason);
return true;
}
@Override
public TransportCertRecord getRecordOrNull(Long recordId) {
return Func.isEmpty(recordId) ? null : certRecordService.getById(recordId);
}
/**
* 更新认证对象的展示缓存,并在通过时把生效快照指针切到这条记录
* <p>
* 只发**一次** UPDATE:
* <ul>
* <li>通过 —— 状态=已通过、清空驳回原因、指针指向本条(切换而非追加,故仍至多一条生效快照);</li>
* <li>驳回 —— 状态=已驳回、写入原因,**不带指针字段**,生效快照一个字都不动。</li>
* </ul>
* 分两次写同一行除了多一次往返,还会让「先切指针、后被展示缓存更新覆盖」成为可能。
*
* @param record 被审核的记录
* @param pass 是否通过
* @param rejectReason 驳回原因
*/
private void updateCertTarget(TransportCertRecord record, boolean pass, String rejectReason) {
boolean vehicleTarget = TransportCertRecord.BIZ_TYPE_VEHICLE.equals(record.getBizType());
Integer status = pass ? TransportCertRecord.STATUS_APPROVED : TransportCertRecord.STATUS_REJECTED;
String reason = pass ? null : CertificationRuleSupport.reasonForReject(rejectReason);
// 只有通过才切指针;驳回时保持 null,框架的 not_null 更新策略会跳过该列
Long newEffectiveId = pass ? record.getId() : null;
if (vehicleTarget) {
TransportVehicle vehicle = new TransportVehicle();
vehicle.setId(record.getBizId());
vehicle.setCertificationStatus(status);
vehicle.setCertificationRejectReason(reason);
if (pass) {
vehicle.setEffectiveCertRecordId(newEffectiveId);
}
transportVehicleService.updateById(vehicle);
return;
}
Driver driver = new Driver();
driver.setId(record.getBizId());
driver.setCertificationStatus(status);
driver.setCertificationRejectReason(reason);
if (pass) {
driver.setEffectiveCertRecordId(newEffectiveId);
}
driverService.updateById(driver);
}
/**
* 取该对象当前的生效快照指针
*
* @param bizType 认证对象类型
* @param bizId 认证对象主键
* @return 指针值;对象不存在或从未认证通过时返回 null
*/
private Long effectiveRecordIdOf(String bizType, Long bizId) {
if (TransportCertRecord.BIZ_TYPE_VEHICLE.equals(bizType)) {
TransportVehicle vehicle = transportVehicleService.getById(bizId);
return vehicle == null ? null : vehicle.getEffectiveCertRecordId();
}
Driver driver = driverService.getById(bizId);
return driver == null ? null : driver.getEffectiveCertRecordId();
}
private TransportCertRecord requireRecord(Long recordId) {
if (Func.isEmpty(recordId)) {
throw new ServiceException("认证记录主键不能为空");
}
TransportCertRecord record = certRecordService.getById(recordId);
if (record == null) {
throw new ServiceException("认证记录不存在");
}
return record;
}
}