feat(codec): 观测未落库的 SRVT/VIPF 集合

SRVT/VIPF 只保留在 wire/domain 并计数告警，不落明细表、不参与合并：出现事实不再被静默丢弃，为 Q13 定案提供真实流量证据（[G-SRVT-VIPF]）。 - wire DTO：SRVT/SERVICEDATA、VIPF/VIPDATA 与嵌套 VIPT（OPER 为元素属性） - 出现即留键：缺席与"出现但为空"不再等价；已落库 10 类集合语义不变 - 新增 msgx.pipeline.codec.srvt_seen.total / vipf_seen.total（reference.md 已登记） - 一并提交此前的 MAFL 文档改动（INV-21/INV-22、flight-state §2.3、G-MAFL 措辞）
2026-09-13 09:21:51 +08:00
parent b8738554e6
commit 17a4bfe91b
11 changed files with 283 additions and 18 deletions
@@ -19,6 +19,32 @@ data class ScheduleBody(
    val records: List<ScheduleRecord>,
 )

+/**
+ * 只保留在 wire/domain、尚未映射到持久化明细的集合键（`[G-SRVT-VIPF]`）。
+ *
+ * 它们不参与合并、不进快照、不落库；保留的目的是不让入站事实在解码层被静默抹平，并让真实
+ * 流量里的出现情况可观测——决定"缺席是否等于删除"的 `Q13` 需要真实报文才能定案。
+ */
+private val UNPERSISTED_COLLECTION_KEYS: Set<String> = setOf("SRVT", "VIPF")
+
+/**
+ * 一条解码载荷里各未落库集合命中的**记录数**（`[G-SRVT-VIPF]`）。
+ *
+ * 按记录计（一条记录带该段即算 1），不按段内元素计；只返回命中项。载荷类型不在
+ * [ScheduleBody] / [FlopPayload] 之内时返回空——调用方不得据此改变处理结果。
+ */
+fun unpersistedCollectionHits(body: Any?): Map<String, Int> {
+    val perRecord = when (body) {
+        is ScheduleBody -> body.records.map { it.collections }
+        is FlopPayload -> listOf(body.collections)
+        else -> return emptyMap()
+    }
+    if (perRecord.isEmpty()) return emptyMap()
+    return UNPERSISTED_COLLECTION_KEYS
+        .mapNotNull { key -> perRecord.count { key in it }.takeIf { it > 0 }?.let { key to it } }
+        .toMap()
+}
+
 /**
 * Wire DTOs for SIS in docs/legacy/SIS_AODB_RMS-V0.1.md.
 * SIS permits a subsystem to ignore standard fields it does not use; those fields are
@@ -105,6 +131,10 @@ data class FlightRecordXml(
    @param:JacksonXmlElementWrapper(useWrapping = false) @param:JacksonXmlProperty(localName = "CHOT") val chot: List<ChotXml> = emptyList(),
    @param:JacksonXmlElementWrapper(useWrapping = false) @param:JacksonXmlProperty(localName = "ROUT") val rout: List<RoutXml> = emptyList(),
    @param:JacksonXmlElementWrapper(useWrapping = false) @param:JacksonXmlProperty(localName = "ERUT") val erut: List<RoutXml> = emptyList(),
+    // SRVT/VIPF 用可空表达"段是否出现"：null = 未出现；出现即为列表（空元素得到一行空行）。
+    // 两者都不落明细表、不参与合并，清空语义待 `Q13`（`[G-SRVT-VIPF]`）。
+    @param:JacksonXmlElementWrapper(useWrapping = false) @param:JacksonXmlProperty(localName = "SRVT") val srvt: List<SrvtXml>? = null,
+    @param:JacksonXmlElementWrapper(useWrapping = false) @param:JacksonXmlProperty(localName = "VIPF") val vipf: List<VipfXml>? = null,
 )

@JsonIgnoreProperties(ignoreUnknown = true)
@@ -198,3 +228,44 @@ data class RoutXml(
    @param:JacksonXmlProperty(localName = "SCAT") val scat: String? = null,
    @param:JacksonXmlProperty(localName = "SCDT") val scdt: String? = null,
 )
+
+/**
+ * SIS `SRVT`/`SERVICEDATA`（SCHD）与 `OPT_SERVICEDATA`（FLOP）：一次服务明细，可重复出现。
+ *
+ * 字段形态以 `docs/legacy/unisysaodbsis.xsd` 为准。`OPER` 是元素属性，SIS 正文未记载其值域；
+ * `SANR`/`SARR` 只出现在 FLOP 的 `OPT_SERVICEDATA`。协议未给序号属性，故没有源序号。
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+data class SrvtXml(
+    @param:JacksonXmlProperty(isAttribute = true, localName = "OPER") val oper: String? = null,
+    @param:JacksonXmlProperty(localName = "SRTC") val srtc: String? = null,
+    @param:JacksonXmlProperty(localName = "SRQT") val srqt: String? = null,
+    @param:JacksonXmlProperty(localName = "SRST") val srst: String? = null,
+    @param:JacksonXmlProperty(localName = "SRET") val sret: String? = null,
+    @param:JacksonXmlProperty(localName = "SRPR") val srpr: String? = null,
+    @param:JacksonXmlProperty(localName = "SANR") val sanr: String? = null,
+    @param:JacksonXmlProperty(localName = "SARR") val sarr: String? = null,
+)
+
+/**
+ * SIS `VIPF`/`VIPDATA`（SCHD）与 `OPT_VIPDATA`（FLOP）：一位 VIP，可重复出现。
+ *
+ * `VIPT` 按 XSD 至多一个；SIS 正文"每个 VIP 重复"的说法与之冲突，形态以 XSD 为准。
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+data class VipfXml(
+    @param:JacksonXmlProperty(isAttribute = true, localName = "OPER") val oper: String? = null,
+    @param:JacksonXmlProperty(localName = "VPCD") val vpcd: String? = null,
+    @param:JacksonXmlProperty(localName = "VFES") val vfes: String? = null,
+    @param:JacksonXmlProperty(localName = "VIPT") val vipt: ViptXml? = null,
+)
+
+/** SIS `VIPT`/`VIPTXNDATA`：VIP 关联的服务交易明细，嵌套在 [VipfXml] 内。 */
+@JsonIgnoreProperties(ignoreUnknown = true)
+data class ViptXml(
+    @param:JacksonXmlProperty(isAttribute = true, localName = "OPER") val oper: String? = null,
+    @param:JacksonXmlProperty(localName = "VSCD") val vscd: String? = null,
+    @param:JacksonXmlProperty(localName = "VTQY") val vtqy: String? = null,
+    @param:JacksonXmlProperty(localName = "VTST") val vtst: String? = null,
+    @param:JacksonXmlProperty(localName = "VTET") val vtet: String? = null,
+)
@@ -33,18 +33,42 @@ internal object SisWireMapper {
        ).forEach { (key, value) -> value?.let { put(key, it.trim()) } }
    }

-    private fun FlightRecordXml.collections(): Map<String, List<Map<String, String>>> = linkedMapOf(
-        "GTDT" to gtdt.map { it.toMap("GTNO" to it.gtno, "GATE" to it.gate, "PGOT" to it.pgot, "PGCT" to it.pgct, "GOTM" to it.gotm, "GCTM" to it.gctm, "GTYP" to it.gtyp) },
-        "CKDT" to ckdt.map { it.toMap("CKNO" to it.ckno, "CHKC" to it.chkc, "CCLS" to it.ccls, "PCOT" to it.pcot, "PCCT" to it.pcct, "COTM" to it.cotm, "CCTM" to it.cctm, "CTYP" to it.ctyp) },
-        "CLDT" to cldt.map { it.toMap("CLNO" to it.clno, "BELT" to it.belt, "BCLS" to it.bcls, "PCOT" to it.pcot, "PCCT" to it.pcct, "FBAG" to it.fbag, "LBAG" to it.lbag, "BTYP" to it.btyp) },
-        "PSDT" to psdt.map { it.toMap("PSNO" to it.psno, "PSST" to it.psst, "STST" to it.stst, "STET" to it.stet) },
-        "CHDT" to chdt.map { it.toMap("CHNO" to it.chno, "CHUT" to it.chut, "CHCLS" to it.chcls, "PCBT" to it.pcbt, "PCET" to it.pcet, "CBTM" to it.cbtm, "CETM" to it.cetm, "CHTYP" to it.chtyp) },
-        "DELY" to dely.map { it.toMap("CODE" to it.code, "STRT" to it.strt, "DURA" to it.dura, "REMC" to it.text) },
-        "ABTM" to abtm.map { it.toMap("ASNO" to it.asno, "ABDG" to it.abdg, "ABOP" to it.abop, "AOTM" to it.aotm) },
-        "CHOT" to chot.map { it.toMap("CSNO" to it.csno, "CHID" to it.chid, "CHST" to it.chst, "CHTM" to it.chtm) },
-        "ROUT" to rout.map { it.toMap("RTNO" to it.rtno, "APCD" to it.apcd, "SCAT" to it.scat, "SCDT" to it.scdt) },
-        "ERUT" to erut.map { it.toMap("RTNO" to it.rtno, "APCD" to it.apcd, "SCAT" to it.scat, "SCDT" to it.scdt) },
-    ).filterValues { it.isNotEmpty() }
+    /**
+     * 已落库的 10 类集合：缺席（字段默认空列表）不产生键，出现但为空的元素得到一行空行 `[{}]`；
+     * `filterValues` 去掉的正是"缺席"，避免整包凭空清空本地明细（合并语义见 flight-state.md §3.1）。
+     *
+     * `SRVT`/`VIPF` 尚未有明细表（`[G-SRVT-VIPF]`）：只用"键是否存在"表达段是否出现，保留原始
+     * 内容与顺序，不参与合并、不判断清空语义（`Q13`）——出现（哪怕为空）与缺席不再被抹平。
+     */
+    private fun FlightRecordXml.collections(): Map<String, List<Map<String, String>>> {
+        val mapped = linkedMapOf(
+            "GTDT" to gtdt.map { it.toMap("GTNO" to it.gtno, "GATE" to it.gate, "PGOT" to it.pgot, "PGCT" to it.pgct, "GOTM" to it.gotm, "GCTM" to it.gctm, "GTYP" to it.gtyp) },
+            "CKDT" to ckdt.map { it.toMap("CKNO" to it.ckno, "CHKC" to it.chkc, "CCLS" to it.ccls, "PCOT" to it.pcot, "PCCT" to it.pcct, "COTM" to it.cotm, "CCTM" to it.cctm, "CTYP" to it.ctyp) },
+            "CLDT" to cldt.map { it.toMap("CLNO" to it.clno, "BELT" to it.belt, "BCLS" to it.bcls, "PCOT" to it.pcot, "PCCT" to it.pcct, "FBAG" to it.fbag, "LBAG" to it.lbag, "BTYP" to it.btyp) },
+            "PSDT" to psdt.map { it.toMap("PSNO" to it.psno, "PSST" to it.psst, "STST" to it.stst, "STET" to it.stet) },
+            "CHDT" to chdt.map { it.toMap("CHNO" to it.chno, "CHUT" to it.chut, "CHCLS" to it.chcls, "PCBT" to it.pcbt, "PCET" to it.pcet, "CBTM" to it.cbtm, "CETM" to it.cetm, "CHTYP" to it.chtyp) },
+            "DELY" to dely.map { it.toMap("CODE" to it.code, "STRT" to it.strt, "DURA" to it.dura, "REMC" to it.text) },
+            "ABTM" to abtm.map { it.toMap("ASNO" to it.asno, "ABDG" to it.abdg, "ABOP" to it.abop, "AOTM" to it.aotm) },
+            "CHOT" to chot.map { it.toMap("CSNO" to it.csno, "CHID" to it.chid, "CHST" to it.chst, "CHTM" to it.chtm) },
+            "ROUT" to rout.map { it.toMap("RTNO" to it.rtno, "APCD" to it.apcd, "SCAT" to it.scat, "SCDT" to it.scdt) },
+            "ERUT" to erut.map { it.toMap("RTNO" to it.rtno, "APCD" to it.apcd, "SCAT" to it.scat, "SCDT" to it.scdt) },
+        ).filterValues { it.isNotEmpty() }.toMutableMap()
+        srvt?.let { mapped["SRVT"] = it.map(::srvtRow) }
+        vipf?.let { mapped["VIPF"] = it.map(::vipfRow) }
+        return mapped
+    }
+
+    /** `SRVT` 一行：`OPER` 取自属性；`VIPT_*` 前缀供嵌套字段使用，避免与外层 `OPER` 撞键。 */
+    private fun srvtRow(x: SrvtXml): Map<String, String> = x.toMap(
+        "OPER" to x.oper, "SRTC" to x.srtc, "SRQT" to x.srqt, "SRST" to x.srst,
+        "SRET" to x.sret, "SRPR" to x.srpr, "SANR" to x.sanr, "SARR" to x.sarr,
+    )
+
+    private fun vipfRow(x: VipfXml): Map<String, String> = x.toMap(
+        "OPER" to x.oper, "VPCD" to x.vpcd, "VFES" to x.vfes,
+        "VIPT_OPER" to x.vipt?.oper, "VIPT_VSCD" to x.vipt?.vscd, "VIPT_VTQY" to x.vipt?.vtqy,
+        "VIPT_VTST" to x.vipt?.vtst, "VIPT_VTET" to x.vipt?.vtet,
+    )

    private fun Any.toMap(vararg values: Pair<String, String?>): Map<String, String> = values.mapNotNull { (key, value) ->
        value?.trim()?.let { key to it }