docs(acm2-75): 清理空转待决项并对齐全仓旧编号引用

- 删 Q2/Q15/Q19/Q20:时钟偏斜不进判据、实现自定已是结论、原文留存已定、
  运营日冲突处置已由 DEAD(PROTOCOL) 定
- Q6 的 abdg 定案本版不提供;Q22 改为 13 类报文到 admin-api 实体表组的映射
  (REF_MASTER 单表口径退位);Q23 收窄为 SODT+FLID 幂等重试
- C-1 自清口径四方同步(requirements 非目标、US-03 AC2、architecture §6)
- INV-2 吸收回填只写空值;§7 恢复 G-RESP-GUARD
- architecture/implementation/README/V1/oracle/Kotlin/seed 中 40+ 处旧编号
  按映射重指,check-docs 全绿
This commit is contained in:
windyboy
2026-09-20 07:13:20 +08:00
parent 21168d728a
commit 2bd650a551
21 changed files with 121 additions and 123 deletions
@@ -68,7 +68,7 @@ data class ProcState(
val receivedAt: Instant? = null,
/**
* 本地入队时间(本系统写入,非空)。超期补写期限 `R` **只比较它**:与判据用的本地
* `NOW` 同源,不受库方时钟偏斜影响`PRE-4`
* `NOW` 同源,不受库方时钟偏斜影响。
*/
val enqueuedAt: Instant? = null,
/** 非空表示已确认信箱行带上了处理标记。 */
@@ -119,7 +119,7 @@ interface ProcStateRepository {
*
* [overdueBefore] 是兜底:入队时间早于它的(已经等了超过 `R`)无视退避直接补写。
* 没有这条兜底,退避一直失败的话这些行就永远打不上标记,库方也没法清理信箱。
* 判据比较的是**本地** `ENQUEUED_AT`,不是库方时钟的 `RECEIVED_AT``PRE-4`
* 判据比较的是**本地** `ENQUEUED_AT`,不是库方时钟的 `RECEIVED_AT`。
*/
fun findBackfillDue(now: Instant, overdueBefore: Instant, limit: Int): List<BackfillDue>
@@ -244,7 +244,7 @@ interface FlightStateRepository {
* 物理删除主行与明细,按 `(FLID, STATE_VERSION)` 守卫:只删归档确认过的那个版本,
* 期间被主泵写过的行影响 0 行。
*
* **只能在历史存储确认归档成功、且在 `PIPELINE_LOCK` 事务内按同一判据复查之后调用**(`INV-18`);
* **只能在历史存储确认归档成功、且在 `PIPELINE_LOCK` 事务内按同一判据复查之后调用**(`US-14` AC4);
* 历史存储没接通时,调用方必须传空列表,也就是一条都不删。
*/
fun purgeArchived(candidates: List<HistoryCandidate>): Int
@@ -37,10 +37,10 @@ class JdbcCminmsgInboxRepository(
}
} catch (e: IllegalStateException) {
// 只调整适配代码、不碰共享 Schema:把"取不到 generated key"变成可诊断错误,
// 指出这是共享信箱 ID 生成方式的前提(C-14、Q8)。
// 指出这是共享信箱编号生成方式的前提(Q7、Q8)。
throw IllegalStateException(
"shared mailbox insert returned no generated CMINMSGS_ID; " +
"the CMINMSGS_ID column must be DB-generated (C-14, Q8)",
"the CMINMSGS_ID column must be DB-generated (Q7, Q8)",
e,
)
}
@@ -86,7 +86,7 @@ class JdbcProcStateRepository(
{ ps ->
ps.setLong(1, msgId)
ps.setTimestamp(2, receivedAt?.toSqlTimestamp())
// 入队时间必须由本系统时钟给出:它同时是超期判据 R 的比较对象PRE-4
// 入队时间必须由本系统时钟给出:它同时是超期判据 R 的比较对象。
ps.setTimestamp(3, (enqueuedAt ?: now).toSqlTimestamp())
ps.setTimestamp(4, now.toSqlTimestamp())
},
@@ -252,7 +252,7 @@ class JdbcProcStateRepository(
*/
/**
* 超期判据用 `enqueued_at`(本地时钟、非空),不用 `received_at`
* 后者来自库方时钟,前偏会让 `NOW − R` 提前成立`PRE-4`
* 后者来自库方时钟,前偏会让 `NOW − R` 提前成立。
*/
override fun findBackfillDue(now: Instant, overdueBefore: Instant, limit: Int): List<BackfillDue> =
ds.query(
@@ -72,7 +72,7 @@ class InboxPoller(
val enqueued = txManager.inTransaction {
var n = 0
rows.takeWhile { it.msgId <= committedTo }.forEach { row ->
// 入队时间用本轮注入的本地时钟,与超期判据 R 同源PRE-4
// 入队时间用本轮注入的本地时钟,与超期判据 R 同源。
if (procState.insertIfAbsent(row.msgId, row.receivedAt, enqueuedAt = now)) n++
}
cursor.save(InboxCursorRepository.Cursor(committedTo, holeSince))
@@ -46,10 +46,10 @@ class InboxService(
}
val receivedAt = mailboxReceivedAt ?: now
try {
// 入队时间单独传本地时钟:它是超期判据 R 的比较对象,不能借用库方时间PRE-4
// 入队时间单独传本地时钟:它是超期判据 R 的比较对象,不能借用库方时间。
procState.insertIfAbsent(id, receivedAt, enqueuedAt = now)
} catch (e: Exception) {
// PG 入队失败不回退接收结果:原文已在信箱,轮询会按 ID 补建,且只建一条(INV-2b、US-01)。
// PG 入队失败不回退接收结果:原文已在信箱,轮询会按 ID 补建,且只建一条(INV-1、US-01)。
pgEnqueueFailures.incrementAndGet()
log.error("compat accepted but PG enqueue failed msgId={}; poller will re-create", id, e)
}
@@ -68,7 +68,7 @@ class HistorySweepJob(
val toPurge = candidates.filter { it.flid in archivedFlids }
// 归档与删除之间主泵可能已写入同一 FLID:进锁事务后按 (FLID, STATE_VERSION) 复查,
// 仍合格才登记 tombstone 并删除;事件与删除同事务提交或回滚(INV-17、INV-18)。
// 仍合格才登记 tombstone 并删除;事件与删除同事务提交或回滚(D1、US-14 AC4)。
var purged = 0
txManager.inTransaction {
lock.lock()