📝 认证记录相关文件去掉外部文档引用,注释改为自解释
前一次提交的注释大量引用本仓库之外、同事看不到的东西: docs/adr/0001、docs/adr/0002、GLOSSARY.md、.scratch/ 下的 spec 与 ticket 编号、 以及 ADR-0002 / D10 / 不变式 I1~I3 这类代号。这些都在另一个 git 仓库 (weicw/tms-erp)里,单独 checkout 本仓库的人根本找不到,只会困惑。 改为把结论直接写在注释里: - 生效快照指针为何「一经设置永不回退」(原来只写「见 ADR-0002」); - 为何 redis 状态字段不能用 0 兜底; - 为何生成列要排除 is_deleted、为何 tenant_id 必须 NOT NULL; - changeStatus 为何被禁用(原来写「破坏 I3 的留痕」)。 顺带对齐本仓库的既有排版习惯: - 横幅破折号由 77 个改为 30 个(与 blade_annual_inspection_record.sql 等一致); - 去掉 SQL 注释里的 markdown 粗体(本目录无其他脚本这么写)。 仅注释变更:SQL 的 diff 已逐行核对,非注释行改动为 0,DDL 一字未动; 迁移重跑仍 exit 0,audit-migrations 通过,mvn clean compile 成功。
This commit is contained in:
+4
-3
@@ -255,11 +255,12 @@ public class Driver extends TenantEntity {
|
||||
* 生效快照指针:指向 blade_transport_cert_record.id
|
||||
* <p>
|
||||
* 「该司机是否已认证」的<b>唯一</b>判据。为 null 表示从未认证通过;
|
||||
* 一经设置<b>永不回退</b>——提交、驳回、作废都不得修改它(见 ADR-0002)。
|
||||
* 一经设置<b>永不回退</b>——提交、驳回、作废都不得修改它,
|
||||
* 因此重新提交认证不会让一个已认证的司机失去接单资格。
|
||||
* <p>
|
||||
* ⚠️ {@code READ_ONLY}:本字段<b>只能由审核链路</b>(03)写入。
|
||||
* ⚠️ {@code READ_ONLY}:本字段<b>只能由审核通过时</b>写入。
|
||||
* 司机档案的 {@code /submit} 直接以本实体接收请求体,若允许反序列化,
|
||||
* 调用方就能自行填一个记录 ID 把自己「认证」掉,绕过审核与 D10 的可用性门槛。
|
||||
* 调用方就能自行填一个记录 ID 把自己「认证」掉,绕过审核。
|
||||
*/
|
||||
@JsonProperty(access = JsonProperty.Access.READ_ONLY)
|
||||
@JsonSerialize(using = ToStringSerializer.class)
|
||||
|
||||
+5
-8
@@ -46,16 +46,13 @@ import java.time.LocalDateTime;
|
||||
* 标记为「已作废」,而<b>不是</b>删除。判定某个对象「是否已认证」只看它持有的生效快照指针,
|
||||
* 与记录表里的任何一条记录的状态都无关。
|
||||
* <p>
|
||||
* 设计依据:{@code docs/adr/0001-certification-record-immutable-snapshot.md},
|
||||
* 术语见根工作区 {@code GLOSSARY.md}。
|
||||
* <p>
|
||||
* ⚠️ <b>{@code status} 承载的是「审核状态」,不是 BladeX 的「启用 / 停用」。</b>
|
||||
* 该字段继承自 {@link TenantEntity},带来两条必须堵住的框架通道:
|
||||
* 一是 {@code BaseServiceImpl#resolveEntity} 在插入时会把 {@code null} 的 {@code status}
|
||||
* <b>静默填成 {@code 1}</b>(恰好是 {@link #STATUS_APPROVED});
|
||||
* 二是继承来的 {@code changeStatus(ids, 1)} 会直接写 {@code status},等于批量通过审核。
|
||||
* 二者都已在 {@code TransportCertRecordServiceImpl} 中封堵(前者校验抛错、后者覆写抛错),
|
||||
* 审核一律走 03 的审核接口。
|
||||
* 二者都已在 {@code TransportCertRecordServiceImpl} 中封堵(前者校验抛错、后者覆写抛错)。
|
||||
* 审核必须逐条、带审核人与审核时间落库,不得借道 {@code changeStatus} 批量改状态。
|
||||
*
|
||||
* @author Chill
|
||||
*/
|
||||
@@ -97,7 +94,7 @@ public class TransportCertRecord extends TenantEntity {
|
||||
/**
|
||||
* 认证对象类型:driver-司机,vehicle-车辆
|
||||
* <p>
|
||||
* {@code NEVER}:记录一经创建,认证对象的身份不可改(详见类注释的不变式 I3)。
|
||||
* {@code NEVER}:记录一经创建,认证对象的身份不可改。
|
||||
*/
|
||||
@TableField(updateStrategy = FieldStrategy.NEVER)
|
||||
@Schema(description = "认证对象类型:driver-司机,vehicle-车辆")
|
||||
@@ -117,8 +114,8 @@ public class TransportCertRecord extends TenantEntity {
|
||||
/**
|
||||
* 该次提交的全量认证内容(JSON),一经创建不可修改
|
||||
* <p>
|
||||
* {@code NEVER}:这是不变式 <b>I3</b> 的结构性保证——本字段<b>永不进入 UPDATE 语句</b>,
|
||||
* 因此不存在「某条链路忘了保护快照」的可能。改内容只能靠<b>新提交一条记录</b>。
|
||||
* {@code NEVER}:本字段<b>永不进入 UPDATE 语句</b>,因此不存在「某条链路
|
||||
* 忘了保护快照」的可能。改内容只能靠<b>新提交一条记录</b>。
|
||||
*/
|
||||
@TableField(updateStrategy = FieldStrategy.NEVER)
|
||||
@Schema(description = "该次提交的全量认证内容JSON")
|
||||
|
||||
+4
-4
@@ -231,13 +231,13 @@ public class TransportVehicle extends TenantEntity {
|
||||
* 生效快照指针:指向 blade_transport_cert_record.id
|
||||
* <p>
|
||||
* 「该车辆是否已认证」的<b>唯一</b>判据。为 null 表示从未认证通过;
|
||||
* 一经设置<b>永不回退</b>——重新提交、待审、被驳回都不得修改它(见 ADR-0002)。
|
||||
* 一经设置<b>永不回退</b>——重新提交、待审、被驳回都不得修改它,
|
||||
* 因此重新提交认证不会让一辆已认证的车掉出可用池。
|
||||
* 改造后 {@link #certificationStatus} 降级为「最新提交状态」的展示缓存。
|
||||
* <p>
|
||||
* ⚠️ {@code READ_ONLY}:本字段<b>只能由审核链路</b>(03)写入。
|
||||
* ⚠️ {@code READ_ONLY}:本字段<b>只能由审核通过时</b>写入。
|
||||
* {@code POST /transport-vehicle/submit} 直接以本实体接收请求体,
|
||||
* 若允许反序列化,调用方就能自行填一个记录 ID 把自己「认证」掉,
|
||||
* 从而完全绕过审核与 D10 的可用性门槛。
|
||||
* 若允许反序列化,调用方就能自行填一个记录 ID 把自己「认证」掉,绕过审核。
|
||||
*/
|
||||
@JsonProperty(access = JsonProperty.Access.READ_ONLY)
|
||||
@JsonSerialize(using = ToStringSerializer.class)
|
||||
|
||||
Reference in New Issue
Block a user