📝 删除认证分支注释里的叙事性措辞

把「本改造的核心」「这正是要避免的事」「本次改造要保住的东西」这类写作时的叙事从注释中去掉，只留读者需要的事实（反直觉的约束、坑、兼容性）。测试的 @DisplayName 同步去掉「改造前/改造期间」等时间状语。注释与文案调整，无逻辑改动；CertificationGateTest 等 35 个测试通过。
2026-10-04 23:55:22 +08:00
parent 5061df8c78
commit e3d860668b
6 changed files with 18 additions and 27 deletions
@@ -243,7 +243,7 @@ public class TransportVehicle extends TenantEntity {
 	 * 「该车辆是否已认证」的<b>唯一</b>判据。为 null 表示从未认证通过；
 	 * 一经设置<b>永不回退</b>——重新提交、待审、被驳回都不得修改它，
 	 * 因此重新提交认证不会让一辆已认证的车掉出可用池。
-	 * 改造后 {@link #certificationStatus} 降级为「最新提交状态」的展示缓存。
+	 * {@link #certificationStatus} 是「最新提交状态」的展示缓存，不代表是否已认证。
 	 * <p>
 	 * ⚠️ {@code READ_ONLY}：本字段<b>只能由审核通过时</b>写入。
 	 * {@code POST /transport-vehicle/submit} 直接以本实体接收请求体，
@@ -55,10 +55,10 @@ import java.util.List;
 /**
 * 认证审核服务实现
 * <p>
- * 审核作用于**一条记录**。两条路径的差别是本次改造的关键：
+ * 审核作用于一条记录，两条路径的差别在于是否切换生效快照：
 * <ul>
 *   <li><b>通过</b>：记录转已通过，并把该对象的生效快照指针切到它；</li>
- *   <li><b>驳回</b>：记录转已驳回并留原因，生效快照指针<b>一个字都不动</b>。</li>
+ *   <li><b>驳回</b>：记录转已驳回并留原因，生效快照指针一个字都不动。</li>
 * </ul>
 * 因此「已认证的车被驳回」不会让它掉出可用池，只是这次提交没被采纳。
 *
@@ -354,10 +354,10 @@ public class CertAuditServiceImpl implements ICertAuditService {
 		} catch (Exception exception) {
 			throw new ServiceException("该认证记录的提交内容无法解析，未写入车辆档案");
 		}
-		// 字段名对不上时 JSON 会解析成「全是 null」而不报错（改造前的历史快照就是这种情况），
+		// 字段名对不上时 JSON 会解析成「全是 null」而不报错（早期格式的历史快照就是这种情况），
 		// 那样写回等于什么也没写。故用证件内容里的关键字段判定「这份快照是否是当前格式」。
 		if (Func.isEmpty(snapshot.getDrivingLicenseNo()) && Func.isEmpty(snapshot.getApprovedLoadKg())) {
-			throw new ServiceException("该认证记录的提交内容与当前字段定义不匹配（可能是改造前的历史快照），"
+			throw new ServiceException("该认证记录的提交内容与当前字段定义不匹配（可能是早期格式的历史快照），"
 				+ "未写入车辆档案；请重新提交一次认证");
 		}
 		vehicle.setOwnerName(snapshot.getOwnerName());
@@ -33,18 +33,13 @@ import org.springframework.stereotype.Component;
 /**
 * 认证可用性门槛
 * <p>
- * 在原有的运营状态（启用 / 停用）之上**叠加**一层「是否已认证」：
- * <ul>
- *   <li>车辆：运营状态为启用，且存在生效快照；</li>
- *   <li>司机：存在生效快照。</li>
- * </ul>
+ * 在运营状态（启用 / 停用）之上叠加一层「是否已认证」：
+ * 车辆需运营状态为启用且存在生效快照；司机需存在生效快照。
 * <p>
- * ⚠️ 判据是**生效快照指针**，不是「最新提交状态」展示缓存。
- * 这一区别是本改造的核心：司机重新提交认证会把展示缓存变成「审核中」，
- * 若照它判定，司机一提交认证就立刻接不了单——正是要避免的事。
- * 生效快照只在审核通过时才切换，故「曾认证通过即持续可用」。
+ * 判据是生效快照指针，不是「最新提交状态」展示缓存——重新提交认证会把展示缓存
+ * 变成「审核中」，照它判定会让司机一提交就接不了单。生效快照只在审核通过时切换。
 * <p>
- * 两个开关默认开启，可通过配置关闭以便线上快速回退到改造前的行为：
+ * 两个开关默认开启，可关掉以回退到不校验认证的行为：
 * <pre>
 * transport:
 *   certification:
@@ -97,7 +97,7 @@ class CertAuditServiceImplTest {
 	}

 	@Test
-	@DisplayName("通过车辆认证：快照是改造前的旧格式时明确失败，不能「通过但什么也没写」")
+	@DisplayName("通过车辆认证：快照是旧格式时明确失败，不能「通过但什么也没写」")
 	void approveRejectsLegacySnapshot() {
 		// 旧快照的键名与当前字段定义不同，会解析成「全是 null」而不报错——最危险的一种情况
 		TransportCertRecord record = vehicleRecord(TransportCertRecord.STATUS_PENDING,
@@ -322,11 +322,11 @@ class PersonCertRoundTripTest {
 	@Test
 	@DisplayName("历史快照：读不懂就跳过写回，审核本身照常通过")
 	void legacySnapshotSkipsWriteBackWithoutFailingAudit() {
-		// 改造前的快照没有 idCardNo / driverFileNo，解析出来字段全是 null；
+		// 早期格式的快照没有 idCardNo / driverFileNo，解析出来字段全是 null；
 		// 此时既不能把 null 当成「司机没填」写进档案，也不能让这次审核直接失败
 		Long recordId = driverCertService.submitPersonCert(personCert("张三", "110101199001011234"));
 		TransportCertRecord record = recordStore.get(recordId);
-		record.setSnapshotJson("{\"legacyField\":\"改造前的旧内容\"}");
+		record.setSnapshotJson("{\"legacyField\":\"早期格式的旧内容\"}");

 		certAuditService.audit(recordId, true, null);

@@ -10,10 +10,8 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
 /**
 * 认证可用性门槛测试。
 * <p>
- * 这是整个认证改造的**核心验收点**：一辆已认证的车被重新提交认证后，必须**仍可接单**。
- * 改造前的判定只看车辆的启用/停用状态；本门槛叠加一层「是否已认证」。
- * 之所以必须叠加在生效快照上而不是「最新提交状态」，正是因为重新提交会把
- * 「最新提交状态」变成「审核中」——若照它判定，司机一提交认证就立刻接不了单。
+ * 关键场景：已认证的车被重新提交认证后仍可接单——判定必须走生效快照，
+ * 而重新提交会把「最新提交状态」变成「审核中」。
 */
 class CertificationGateTest {

@@ -34,7 +32,7 @@ class CertificationGateTest {
 	}

 	@Test
-	@DisplayName("关闭后行为回到改造前：不因未认证而拦截（便于快速回退）")
+	@DisplayName("关闭后不因未认证而拦截（便于快速回退）")
 	void disabledLetsEveryoneThrough() {
 		gate.setVehicleGateEnabled(false);
 		gate.setDriverGateEnabled(false);
@@ -54,9 +52,7 @@ class CertificationGateTest {
 	@Test
 	@DisplayName("车辆：重新提交后【状态变成审核中】但仍有生效快照 → 仍可用")
 	void resubmittedVehicleStaysAvailable() {
-		// 关键场景：司机提交了新资料，展示缓存变成「审核中」，
-		// 但 effective_cert_record_id 仍指着上一次通过的记录。
-		// 门槛只看指针，故这辆车照跑不误——这就是本次改造要保住的东西。
+		// 展示缓存变成「审核中」，但 effective_cert_record_id 仍指着上一次通过的记录。
 		assertTrue(gate.isVehicleAvailable(Boolean.TRUE, 7001L),
 			"已认证的车重新提交后必须仍可接单，否则司机一提交就停工");
 	}
@@ -90,7 +86,7 @@ class CertificationGateTest {
 	}

 	@Test
-	@DisplayName("司机门槛可单独关闭（改造期间用于渐进放开）")
+	@DisplayName("司机门槛可单独关闭")
 	void driverGateCanBeDisabledIndependently() {
 		gate.setDriverGateEnabled(false);
 		assertTrue(gate.isDriverAvailable(null), "司机门槛关闭时不应拦截");