refactor(flight-state): SCHD 日计划收敛为缺失保留合并语义并对齐现行设计文档

按现行 docs/flight-state.md(111 行版,§1-§7)全面对齐 domain 包及其消费方,
删除整套指向已退役长版文档(§5.x-§10)的引用与死代码:

- 语义:FlightStateEngine.snapshotState 由"完整快照整体替换"改为 §3.1 合并语义
  ——出现 Set/Replace、缺失保留、标量空串显式清空;DELETED 不被日计划恢复(§3.3)。
- 校验:validateMessage 移除从未接线的报文覆盖范围(scope)参数,只保留 §4 步骤 2
  的声明数量/航班标识/运营日推导校验;ScheduleBody 删除 scopeStart/scopeEnd。
- 删除死代码:domain/Decision.kt、FlightModel 的 SnapshotPatch/UpsertOutcome、
  ProcState.isTerminal/archivable、SnapshotFlag.SEQN_REGRESSION、
  ScheduleRecord.seqn(及 wire FlightRecordXml.SEQN);codec 移除未消费 FFID。
- 删除未接线且引用已退役列(fday/last_message_id)的 SqlDialect 方言脚手架,
  oracle11g README 改为按 V1 现列重建的口径。
- 注释/测试:domain、processing、infra 仓储与 jobs/delivery、配置类及对应测试的
  KDoc 章节引用全部对齐现行 flight-state.md/design.md;FlightStateEngineTest
  重写为合并语义(62/62 通过)。

V1__flight_state_baseline.sql 保留原样(内容注释仍带旧章节号,改动会破坏
已应用迁移的 Flyway checksum,待重建基线或 V2 净迁移时收敛)。
This commit is contained in:
windyboy
2026-09-09 22:17:04 +08:00
parent b75f566276
commit 99a0f5f738
35 changed files with 320 additions and 370 deletions
@@ -58,7 +58,7 @@ class PipelineSmokeTest {
}
companion object {
/** 合法 META,但 TYPE 未在支持范围 → FAILED(UNSUPPORTED)§9 */
/** 合法 META,但 TYPE 未在支持范围 → FAILED(UNSUPPORTED)design.md §2.3 */
val UNSUPPORTED_XML = """
<MSG>
<META><SNDR>AODB</SNDR><SEQN>1</SEQN><DTTM>20260908120000</DTTM><TYPE>XYZQ</TYPE><STYP>FOO</STYP></META>
@@ -3,6 +3,7 @@ package com.gzzn.omms.msgexchange.codec
import com.gzzn.omms.msgexchange.domain.MsgKind
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertInstanceOf
import org.junit.jupiter.api.Assertions.assertNull
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test
@@ -57,7 +58,8 @@ class JacksonXmlCodecTest {
val body = msg.body as FlopPayload
assertEquals("121112312", body.flid)
assertEquals("CA-CA101-A-12DEC261345-D", body.scalars["FFID"])
// FFID(友好航班号)是 wire 必填字段,但当前状态模型不消费它,映射层应忽略。
assertNull(body.scalars["FFID"])
assertEquals(3, body.collections["GTDT"]!!.size)
assertEquals("G28", body.collections["GTDT"]!![0]["GATE"])
assertEquals("1", body.collections["GTDT"]!![0]["GTNO"])
@@ -16,7 +16,7 @@ import org.junit.jupiter.api.Test
import java.time.Instant
/**
* 投递调度(docs/flight-state.md §7.3):
* 投递调度(docs/flight-state.md §5 + design.md §5.1/§5.2):
* KAFKA_MSG 逐条 FIFOKAFKA_SCHD 唯一出口 flushSchd——同 FLID 未发事件按最新
* STATE_VERSION 合并;TOMBSTONE 发 null 值消息;失败退避重试、达上限 DEAD。
*/
@@ -84,7 +84,7 @@ class DispatcherTickTest {
d.flushSchd()
assertEquals(1, port.tombstones.size)
assertEquals("F1", port.tombstones.single().key) // 整态键缺失表示删除旧值(§7.3
assertEquals("F1", port.tombstones.single().key) // §5整态键缺失表示删除旧值
assertNull(port.tombstones.single().payload)
}
@@ -8,7 +8,7 @@ import java.time.LocalDate
import java.time.ZoneId
/**
* 运营日计算(docs/flight-state.md §3.5):SODTddMMMyyHHmm+ 机场时区 + 业务切日边界。
* 运营日计算(docs/flight-state.md §2.1):SODTddMMMyyHHmm+ 机场时区 + 业务切日边界。
*/
class OperationDayTest {
@@ -10,9 +10,10 @@ import java.time.LocalDate
import java.time.ZoneId
/**
* 航班状态引擎(docs/flight-state.md §3.3/§5.2/§5.4/§6.1)不变量:
* 快照整体替换(缺失=清除)、DELETED 不被 SCHD 恢复、FLOP 增量保留缺失字段、
* §5.2 五项校验整包拒绝语义。
* 航班状态引擎(docs/flight-state.md §2–§4)不变量:
* 日计划合并(§3.1)——出现 Set/Replace、缺失保留、标量空值显式清空;
* DELETED 不被日计划恢复(§3.3);FLOP/ADFT 增量合并(§3.2/§3.3);
* 整包校验(§4 步骤 2:声明数量、航班标识、运营日推导)失败整包拒绝。
*/
class FlightStateEngineTest {
@@ -20,7 +21,7 @@ class FlightStateEngineTest {
private val day = LocalDate.of(2026, 12, 15)
@Test
fun `snapshot replaces scalars and clears absent ones`() {
fun `day plan merges scalars overwriting overlaps retaining absent and clearing on explicit empty`() {
val current = FlightSnapshot(
"121", day, FlightState.ACTIVE, 5,
scalars = mapOf("FLNO" to "CA001", "REMC" to "old-note"),
@@ -28,25 +29,66 @@ class FlightStateEngineTest {
)
val next = FlightStateEngine.snapshotState(
current,
ScheduleRecord("121", scalars = mapOf("FLNO" to "CA002")),
ScheduleRecord("121", scalars = mapOf("FLNO" to "CA002", "CNCL" to "")),
operationDay = day,
keepDeleted = false,
)
assertEquals("CA002", next.scalars["FLNO"])
assertFalse(next.scalars.containsKey("REMC")) // 缺失 = Clear(§5.4
assertEquals(emptyList<Map<String, String>>(), next.collections["GTDT"]) // 缺失 = Replace 空集
assertEquals(6, next.stateVersion) // 每次成功写入 +1(§4
assertEquals("CA002", next.scalars["FLNO"]) // 重叠字段被覆盖(§3.1
assertEquals("old-note", next.scalars["REMC"]) // 缺失标量保留(§3.1/§7
assertEquals("", next.scalars["CNCL"]) // 空串 = 显式清空(落库置 NULL
assertEquals(listOf(mapOf("GATE" to "G1")), next.collections["GTDT"]) // 缺失集合保留
assertEquals(6, next.stateVersion) // 每次成功写入 +1
assertEquals(FlightState.ACTIVE, next.state)
}
@Test
fun `snapshot keeps DELETED state and flags revive conflict by caller`() {
fun `day plan replaces collections that are present in the record`() {
val current = FlightSnapshot(
"121", day, FlightState.ACTIVE, 3,
scalars = mapOf("FLNO" to "CA001"),
collections = mapOf("GTDT" to listOf(mapOf("GATE" to "G1"))),
)
val next = FlightStateEngine.snapshotState(
current,
ScheduleRecord(
"121",
scalars = mapOf("FLNO" to "CA002"),
collections = mapOf("GTDT" to listOf(mapOf("GATE" to "G2"), mapOf("GATE" to "G3"))),
),
operationDay = day,
keepDeleted = false,
)
assertEquals(listOf(mapOf("GATE" to "G2"), mapOf("GATE" to "G3")), next.collections["GTDT"])
assertEquals(4, next.stateVersion)
}
@Test
fun `new flight snapshot carries only its record scalars and full collection key set`() {
val next = FlightStateEngine.snapshotState(
null,
ScheduleRecord("121", mapOf("FLNO" to "CA001"), mapOf("GTDT" to listOf(mapOf("GATE" to "G1")))),
operationDay = day,
keepDeleted = false,
)
assertEquals(FlightState.ACTIVE, next.state)
assertEquals(1L, next.stateVersion)
assertEquals("CA001", next.scalars["FLNO"])
assertFalse(next.scalars.containsKey("REMC")) // 无历史可保留
assertEquals(10, next.collections.size) // 全键输出(§2.2
assertEquals(listOf(mapOf("GATE" to "G1")), next.collections["GTDT"])
assertEquals(emptyList<Map<String, String>>(), next.collections["DELY"])
}
@Test
fun `day plan keeps DELETED state for revive conflict handling`() {
val current = FlightSnapshot("121", day, FlightState.DELETED, 3, mapOf(), emptyMap())
val next = FlightStateEngine.snapshotState(
current, ScheduleRecord("121", mapOf("FLNO" to "CA001")), day, keepDeleted = true,
)
assertEquals(FlightState.DELETED, next.state) // §5.1 步骤 6:普通 SCHD 不恢复
assertEquals(FlightState.DELETED, next.state) // §3.3:日计划不恢复 DELETED
assertEquals(4, next.stateVersion)
}
@@ -63,51 +105,54 @@ class FlightStateEngineTest {
)
assertEquals("15DEC261900", next.scalars["ESTT"])
assertEquals("CA001", next.scalars["FLNO"]) // 缺失 = 保留(§6.1
assertEquals("CA001", next.scalars["FLNO"]) // 缺失 = 保留(§3.2
assertEquals(listOf(mapOf("GATE" to "G1")), next.collections["GTDT"])
assertEquals(2, next.stateVersion)
}
@Test
fun `validation rejects RECS mismatch and duplicate flid and day outside scope`() {
fun `validation accepts valid snapshot and rejects RECS mismatch`() {
val ok = FlightStateEngine.validateMessage(
1, listOf(ScheduleRecord("121", mapOf("SODT" to "15DEC261723"))), day, day, opDay,
1, listOf(ScheduleRecord("121", mapOf("SODT" to "15DEC261723"))), opDay,
)
assertTrue(ok is SnapshotValidation.Ok)
val recsMismatch = FlightStateEngine.validateMessage(
2, listOf(ScheduleRecord("121", mapOf("SODT" to "15DEC261723"))), day, day, opDay,
2, listOf(ScheduleRecord("121", mapOf("SODT" to "15DEC261723"))), opDay,
) as SnapshotValidation.Invalid
assertTrue(recsMismatch.flags.contains(SnapshotFlag.RECS_DROP))
}
@Test
fun `validation rejects duplicate flid and non computable operation day`() {
val duplicate = FlightStateEngine.validateMessage(
2,
listOf(
ScheduleRecord("121", mapOf("SODT" to "15DEC261723")),
ScheduleRecord("121", mapOf("SODT" to "15DEC261723")),
),
day, day, opDay,
opDay,
)
assertTrue(duplicate is SnapshotValidation.Invalid)
val outOfScope = FlightStateEngine.validateMessage(
1, listOf(ScheduleRecord("121", mapOf("SODT" to "20DEC261723"))), day, day, opDay,
val noSodt = FlightStateEngine.validateMessage(
1, listOf(ScheduleRecord("121", emptyMap())), opDay,
) as SnapshotValidation.Invalid
assertTrue(outOfScope.flags.contains(SnapshotFlag.DAY_MISMATCH)) // §5.2 覆盖范围校验
assertTrue(noSodt.flags.contains(SnapshotFlag.DAY_MISMATCH)) // 运营日不可计算 → 整包拒绝
val empty = FlightStateEngine.validateMessage(0, emptyList(), day, day, opDay) as SnapshotValidation.Ok
val empty = FlightStateEngine.validateMessage(0, emptyList(), opDay) as SnapshotValidation.Ok
assertTrue(empty.flags.contains(SnapshotFlag.EMPTY))
}
@Test
fun `validation rejects non numeric or oversized flid`() {
val bad = FlightStateEngine.validateMessage(
1, listOf(ScheduleRecord("ABC", mapOf("SODT" to "15DEC261723"))), day, day, opDay,
1, listOf(ScheduleRecord("ABC", mapOf("SODT" to "15DEC261723"))), opDay,
)
assertTrue(bad is SnapshotValidation.Invalid)
val tooLong = FlightStateEngine.validateMessage(
1, listOf(ScheduleRecord("1234567890123", mapOf("SODT" to "15DEC261723"))), day, day, opDay,
1, listOf(ScheduleRecord("1234567890123", mapOf("SODT" to "15DEC261723"))), opDay,
)
assertTrue(tooLong is SnapshotValidation.Invalid) // SIS §3.16.2 Number(1-12)
assertTrue(tooLong is SnapshotValidation.Invalid) // FLID 数字型 Number(1-12)
}
}
@@ -9,7 +9,7 @@ import org.junit.jupiter.api.Test
import java.sql.DriverManager
/**
* Flyway 迁移引擎端到端验证(docs/flight-state.md §3.2 表职责基线):
* Flyway 迁移引擎端到端验证(docs/flight-state.md §2 权威模型 + design.md §2.1):
* 1. V1__flight_state_baseline.sql 在真实 PostgreSQL 上自动迁移成功;
* 2. flyway_schema_history 落库且 success = true
* 3. 决策层/管道层/留痕层全表就绪;PIPELINE_LOCK 单行种子就位。
@@ -12,7 +12,7 @@ import org.junit.jupiter.api.Test
import java.time.Instant
/**
* 历史归档与物理清除(docs/flight-state.md §8.2,顺序不可颠倒):
* 历史归档与物理清除(docs/flight-state.md §6,顺序不可颠倒design.md §6.2):
* 历史存储未接通必须删 0 条;先归档确认再物理清除;
* 未经 FDEL 的航班在清除前补发删除事件。
*/
@@ -53,7 +53,7 @@ class HistorySweepJobTest {
val outcome = job.run(now)
assertEquals(0, outcome.purged) // §8.2 红线:先删历史再补当前态绝不允许
assertEquals(0, outcome.purged) // §6 红线:历史存储未接通必须删 0 条
assertTrue(f.findMainRow("F1") != null)
assertEquals(0, events.rows.size)
}
@@ -78,14 +78,14 @@ class HistorySweepJobTest {
assertEquals(2, outcome.selected)
assertEquals(1, outcome.archived)
assertEquals(1, outcome.purged)
assertEquals(null, f.findMainRow("F1")) // §8.2 步骤 3确认成功 → 物理删除
assertEquals(null, f.findMainRow("F1")) // §6:归档确认成功 → 物理删除
assertTrue(f.findMainRow("F2") != null) // 失败或不明确的保留重试(步骤 5)
assertEquals(0, events.rows.size) // DELETED 航班清除不再发业务删除事件
}
@Test
fun `never-fdel lifecycle purge emits tombstone before deletion`() {
val f = seededFlight("F3", deleted = false, idleDays = 30) // ACTIVE 且超兜底窗(§8.1
val f = seededFlight("F3", deleted = false, idleDays = 30) // ACTIVE 且超兜底窗(§6 静默判据
val events = StubMsgEvents()
val store = RecordingHistoryStore()
val job = HistorySweepJob(
@@ -94,7 +94,7 @@ class HistorySweepJobTest {
job.run(now)
// §7.3/§8.2 步骤 4:未经 FDEL 的航班,清除前补发一次删除事件
// §3.3/§5/§6:未经 FDEL、由生命周期直接清除的航班,清除前补发一次删除事件
val tombstone = events.rows.values.single { it.eventType == EventType.TOMBSTONE }
assertEquals("F3", tombstone.partitionKey)
assertTrue(tombstone.payloadJson.contains("\"deleted\":true"))
@@ -24,9 +24,9 @@ import org.junit.jupiter.api.Test
import java.time.LocalDate
/**
* FDEL§6.2+ ADFT(§6.3/§2.1)不变量:
* FDELdocs/flight-state.md §3.3+ ADFT(§3.3/§2.1)不变量:
* ACTIVE→DELETED 发布一次 tombstone 且明细保留;重复/迟到 FDEL 幂等不推进版本;
* ADFT 重激活恢复 ACTIVE;新实例建立;缺失标量不误删(§2.1 保守语义)。
* ADFT 重激活恢复 ACTIVE;新实例建立;缺失标量不误删(§3.3 保守 Set-only)。
*/
class FdelAndAdftProcessorTest {
@@ -84,7 +84,7 @@ class FdelAndAdftProcessorTest {
val version = f.findMainRow("121")!!.stateVersion
val result = proc.apply(head(), msg(), FlopPayload("121"))
assertEquals(ApplyResult.Succeeded, result) // §6.2 步骤 3幂等成功
assertEquals(ApplyResult.Succeeded, result) // §3.3:重复 FDEL 幂等成功
assertEquals(version, f.findMainRow("121")!!.stateVersion)
assertEquals(1, events.rows.values.count { it.eventType == EventType.TOMBSTONE })
}
@@ -97,7 +97,7 @@ class FdelAndAdftProcessorTest {
val result = FdelProcessor(StubPipelineTx(), StubPipelineLock(), f, events, null, ObjectMapper())
.apply(head(), msg(), FlopPayload("999"))
assertEquals(ApplyResult.Succeeded, result) // §6.2 步骤 4:迟到不报错
assertEquals(ApplyResult.Succeeded, result) // §3.3:迟到/不存在幂等成功
assertEquals(0, events.rows.size)
}
@@ -118,7 +118,7 @@ class FdelAndAdftProcessorTest {
assertEquals(ApplyResult.Succeeded, result)
val main = f.findMainRow("121")!!
assertEquals(FlightState.ACTIVE, main.state) // §6.3 生命周期重激活
assertEquals(FlightState.ACTIVE, main.state) // §3.3 生命周期重激活
assertEquals(LocalDate.of(2026, 12, 15), main.operationDay)
assertEquals("CA002", f.loadFullSnapshot("121")!!.scalars["FLNO"])
}
@@ -32,8 +32,9 @@ import org.junit.jupiter.api.Test
import java.time.LocalDate
/**
* §5.1 applyScheduleRecords 不变量:重放幂等、完整性校验整包拒绝 DEAD(PROTOCOL)、
* 归属日冲突不落地、DELETED 不恢复且记冲突告警、成功路径版本推进+事件+留痕+待办预登记。
* 日计划主链路(docs/flight-state.md §3.1/§4)不变量:重放幂等、整包校验失败
* DEAD(PROTOCOL)、归属日冲突不落地、DELETED 不恢复且记冲突告警、
* 成功路径版本推进 + 事件 + 留痕 + 待办预登记。
*/
class ScheduleProcessorTest {
@@ -107,7 +108,7 @@ class ScheduleProcessorTest {
assertEquals(1, log.entries.size)
assertEquals(SnapshotResult.COMMITTED, log.entries.single().result)
assertEquals(1, log.entries.single().upserted)
assertEquals(1, todo.count()) // §7.2 事务内预登记
assertEquals(1, todo.count()) // design.md §3.3/§6.1 事务内预登记
}
@Test
@@ -120,7 +121,7 @@ class ScheduleProcessorTest {
val result = processor(proc = proc, flights = flights, log = log)
.applyScheduleRecords(head(), message(makeBody("121" to "15DEC261723")))
assertEquals(ApplyResult.ReplaySkipped, result) // §5.1 步骤 2
assertEquals(ApplyResult.ReplaySkipped, result) // §4 重放判定:幂等成功
assertNull(flights.findMainRow("121"))
assertEquals(SnapshotResult.REPLAY_SKIPPED, log.entries.single().result)
}
@@ -132,7 +133,7 @@ class ScheduleProcessorTest {
val schdBody = ScheduleBody(recsDeclared = 2, records = makeBody("121" to "15DEC261723").records)
val result = processor(flights = flights, log = log).applyScheduleRecords(head(), message(schdBody)) as ApplyResult.DeadProtocol
assertTrue(result.flags.contains(SnapshotFlag.RECS_DROP)) // §5.2 RECS = 实收数
assertTrue(result.flags.contains(SnapshotFlag.RECS_DROP)) // §4:声明数量不符整包拒绝
assertNull(flights.findMainRow("121"))
assertEquals(SnapshotResult.ROLLED_BACK, log.entries.single().result)
}
@@ -140,7 +141,7 @@ class ScheduleProcessorTest {
@Test
fun `same flid across operation days is rejected whole-batch without writes`() {
val flights = StubFlightState()
// 预置 121 已归属 12-15;报文声称 12-16 → §5.3 第四行
// 预置 121 已归属 12-15;报文声称 12-16 → §2.1 归属冲突
flights.persistFullState(
com.gzzn.omms.msgexchange.domain.flight.FlightSnapshot(
"121", LocalDate.of(2026, 12, 15), FlightState.ACTIVE, 1, mapOf("SODT" to "15DEC261723"), emptyMap(),
@@ -178,7 +179,7 @@ class ScheduleProcessorTest {
)
assertEquals(ApplyResult.Succeeded, result)
assertEquals(FlightState.DELETED, flights.findMainRow("121")!!.state) // §5.1 步骤 6 不恢复
assertEquals(FlightState.DELETED, flights.findMainRow("121")!!.state) // §3.3:日计划不恢复
assertEquals(8L, flights.findMainRow("121")!!.stateVersion)
assertEquals(SnapshotResult.COMMITTED, log.entries.single().result)
assertTrue(log.entries.single().flags.contains(SnapshotFlag.SCHD_REVIVE_CONFLICT))
@@ -193,7 +194,7 @@ class ScheduleProcessorTest {
proc.insert(msgId)
val p = processor(proc = proc, flights = flights, log = log, todo = todo, tx = TxRunner { true })
// §9:数据库/内部故障 → 异常上抛,MessageProcessor 记 FAILED(INFRA) 退避;不写任何终态
// design.md §2.3:数据库/内部故障 → 异常上抛,MessageProcessor 记 FAILED(INFRA) 退避;不写任何终态
org.junit.jupiter.api.Assertions.assertThrows(IllegalStateException::class.java) {
p.applyScheduleRecords(head(), message(makeBody("121" to "15DEC261723")))
}