msgexchange-v2/docs/reference.md

参考注册表：参数、指标、模块、错误分类

本文件是可派生事实的唯一出处：参数默认值、指标名、模块入口、错误分类。正文（design.md）只引 PARAM:<完整键>，不写数值。

维护规则：新增或改名一个 msgx.* 键、增删一个指标名，必须同步本文件（人工核对，本项目不做 CI 校验）。mailbox.*、datasources.*、kafka.* 属基础设施键，按 §1.3 成组登记。

1. 参数注册表

「依据」列含义：契约 = 由 contracts.md 的 C-x 决定；现役 = 沿用 legacy 行为基线；假定 = 无依据的占位值，必须在对应 Q 关闭后重评；安全默认 = 关闭态，需显式开启。

1.1 管道节奏与重试（msgx.pipeline.*）

参数	默认	单位	依据	说明
msgx.pipeline.poll-interval	1s	Duration	现役	收报轮询节奏；决定队头与空洞检查频率
msgx.pipeline.claim-batch	50	条	假定	单轮领取上限；过大延长单轮事务
msgx.pipeline.max-attempts	5	次	假定	处理与投递共用；达到即转 DEAD(EXHAUSTED)
msgx.pipeline.backoff-ms	[1000,2000,4000,8000]	ms / 档	假定	档位数必须 = max-attempts − 1，启动自检拦截错位
msgx.pipeline.backoff-cap-ms	60000	ms	假定	单档封顶；默认表内无档触及
msgx.pipeline.head-deadline	10m	Duration	假定	仅用于队头滞留告警，不作终态判据（判据只由 max-attempts）。代码注释仍写「毒丸升级」，属待收敛的表述差 [G-HEAD-DEADLINE]
msgx.pipeline.max-commit-delay	5m	Duration	假定（无依据）	空洞老化阈值；由 C-2 决定，不可由 SIS Expiry 推导（Q2）
msgx.pipeline.overdue-backfill（R）	30d	Duration	契约（R ≤ R_keep）	进入强补写窗口、取消退避的阈值；不是兜底保证，不保护重放窗口（Q6）
msgx.pipeline.backfill-batch	100	条	假定	回填扫描单批条数
msgx.pipeline.backfill-max-attempts	100	次	改作告警阈值	不再是放弃判据：暂时性故障按 R 超期放弃（见 design「回填」）。该键保留为单行重试的告警阈值 [G-BACKFILL-ABANDON-BYTIME]
msgx.pipeline.backfill-backoff-ms	目标参数（未实现）	ms / 档	假定	回填独立退避表；当前不存在，回填沿用 backoff-ms [G-BACKFILL-BACKOFF]
msgx.pipeline.backfill-backoff-cap-ms	目标参数（未实现）	ms	假定	回填退避封顶；旧文档「封顶 15 分钟」无对应配置键，已作废 [G-BACKFILL-BACKOFF]
msgx.pipeline.cutover-watermark	不设置	min|zero|max|<id>	一次性运维决策	显式播种水位；非法值由启动自检挡下；升级实例拒绝重新播种
msgx.pipeline.late-detect-period	60s	Duration	假定	只读迟到检测周期；≤0 关闭；机制为临时观测（见 design 扫描路径）
msgx.pipeline.late-detect-batch	200	条	假定	每轮复查的空洞 ID 上限
msgx.pipeline.delivery-batch	200	条	假定	KAFKA:msg 每轮每目标领取上限
msgx.pipeline.delivery-drain-rounds	10	轮	假定	连取批数上限，让出循环跑 schd flush，防状态通知被积压饿死
msgx.pipeline.autostart	false	布尔	安全默认	启动即拉起收报 / 主泵 / 投递循环；需真实仓储或 msgx.stubs=true
msgx.pipeline.event-retention	目标参数（未实现）	Duration	假定	已 SENT 事件行保留期，由维护作业清理；缺失则 outbox 无限增长 [G-EVENT-RETENTION]

1.2 其它 msgx.*

参数	默认	依据	说明
msgx.service-name	msgexchangeapi	契约冻结	服务注册名；影子实例用独立名
msgx.register-eureka	true	现役	服务注册开关；影子对拍期置 false
msgx.stubs	true（dev profile）	安全默认	内存适配器；生产禁止，生产 profile 不设置该键
msgx.schd.flush-period	3s	现役	schd 聚合周期
msgx.schd.flush-limit	500	假定	聚合批上限
msgx.operation-day.zone	Asia/Shanghai	现役	运营日推导时区
msgx.operation-day.cutoff-hour	0	假定（占位）	切日边界；待业务确认
msgx.identity.include-day-boundary	false	安全默认	身份是否加日期边界；影响去重语义，不能当调优项切换（Q11）
msgx.health.backlog-cache-ttl-ms	30000	假定	积压快照缓存窗口；0 = 不缓存；/health 与 /metrics 共用同一快照
msgx.history.history-store-enabled	false	安全默认	历史存储门控；关闭时历史清理删 0 条
msgx.history.cancelled-hours	48	假定	历史清理的取消态判据窗口
msgx.history.terminal-hours	48	假定	历史清理的终态判据窗口
msgx.history.deleted-hours	48	假定	历史清理的已删除判据窗口
msgx.history.idle-hours	168	假定	历史清理的静默期判据
msgx.history.snap-log-retention-days	90	假定	SCHD_SNAP_LOG 保留天数

1.3 信箱与外部依赖（成组登记）

参数组	默认	依据	说明
mailbox.processed-value	PROCESSED	契约（C-5／Q7）	处理标记写入值；仅限库方认可值集
mailbox.shared-mysql.enabled	false	安全默认	真实信箱接线门控
mailbox.shared-mysql.connect-timeout-ms / socket-timeout-ms	3000 / 30000	假定	有界外部调用；Connector/J 默认无限等待，必须显式
mailbox.shared-mysql.pool-connection-timeout-ms / pool-validation-timeout-ms	5000 / 3000	假定	池级超时
mailbox.shared-mysql.url / username / password	环境变量	安全	零入库，见 .env.example
datasources.default.connection-timeout / validation-timeout / idle-timeout / max-lifetime	5000 / 3000 / 300000 / 1800000	假定	自有 PG 池（毫秒数，非 Duration 字面量）
datasources.default.data-source-properties.connectTimeout / socketTimeout	3 / 30	假定	驱动级超时（秒），防网络黑洞
kafka.producers.default.acks	all	契约（architecture D3）	允许环境变量覆盖
kafka.producers.default.enable-idempotence	true	契约（D3）	允许环境变量覆盖
kafka.producers.default.max-in-flight-requests-per-connection	5	与 D3 不一致	D3 要求 1；切流前必须收敛 [G-KAFKA-D3]

环境变量清单以 .env.example 为准。

2. 指标与健康

指标	含义	期望方向
msgx.pipeline.backlog.unfinished	未处理完的消息条数	长期 > 0 且不降 → 积压
msgx.pipeline.backlog.oldest_unprocessed_seconds	最老未处理消息的信龄	持续增长 → 队头卡住
msgx.pipeline.backfill.unmarked_terminal	已终态但未打标的条数	不降 → 回填失败
msgx.pipeline.backfill.abandoned	已放弃自动回填的条数	非 0 需人工对账
msgx.pipeline.backfill.oldest_unmarked_seconds	最老待回填年龄	决定实际回填延迟
msgx.pipeline.watermark.lag	水位落后信箱最新 ID 的距离	增长 → 收报停滞
msgx.pipeline.hole.aged_out.total	永久空洞放行次数	突增 → ID 序列大量空位
msgx.pipeline.late_arrival.detected.total	迟到到达命中数	> 0 表示上游提交确实晚于水位推进，需要与库方对契约

取数规则：统一走 BacklogSnapshotProvider（PARAM:msgx.health.backlog-cache-ttl-ms），/health 与 /metrics 共用同一快照——backlog() 是 PROC_STATE 的全表聚合，不能被高频抓取打穿；无法取数上报 NaN，无可比记录的年龄/滞后类仪表上报 -1，都不伪造 0。日志出口故障不得阻塞业务线程。

作业健康：回填扫描的存活性与延迟需要独立可观测（作业心跳、扫描积压、实际回填延迟），因为回填的唯一驱动是扫描作业 [G-JOB-HEARTBEAT]。

3. 模块入口

关注点	主要入口
收报与兼容接口	ingress/InboxPoller.kt、InboxService.kt、InboxController.kt
解码	codec/JacksonXmlCodec.kt、SisWireMapper.kt、SisMessageBody.kt
调度与处理	processing/Pump.kt（含 MessageProcessor）、DynamicProcessors.kt（FLOP/FDEL/ADFT）、Identity.kt
日计划	processing/ScheduleProcessor.kt；请求协调尚无实现（REQ_TRACK 仓储见 infra/persistence/）
回填与投递作业	processing/BackfillService.kt、jobs/JobRunner.kt、HistorySweepJob.kt、delivery/Dispatcher.kt
持久化与恢复	infra/persistence/、infra/retry/（ProcFailure / ReplayService / FailureScheduler）
启停与配置	PipelineLifecycle.kt、config/PipelineProps.kt、config/HistoryProps.kt
指标与健康	infra/metrics/PipelineMetrics.kt、infra/health/BacklogSnapshotProvider.kt
迁移	src/main/resources/db/migration/（V1 基线、V2 生命周期、V3 HOL 起点、V4 回填闭环、V5 切流播种；oracle11g/ 为占位）

4. 错误分类与重放白名单

错误类别	触发	处置	可重放
MALFORMED	报文非法或原文缺失	立即 DEAD	否
PROTOCOL	整包协议拒绝（运营日冲突、声明数不符、缺载荷）	立即 DEAD，整包不落地	否
CODEC_ERROR	解码能力问题	FAILED 退避	是
UNSUPPORTED	处理器或快照能力未实现	FAILED 退避，受尝试上限约束	是
INFRA	基础设施或执行异常	FAILED 退避	是
EXHAUSTED	尝试次数耗尽	DEAD；ERROR_CLASS 被覆写为 EXHAUSTED（原始类别不保留，LAST_ERROR 留文本）	是

回填放弃原因：MISSING_ROW（信箱行不存在，确定性结论）、TRANSIENT_DEADLINE（暂时性故障持续到 R 仍未打标）。两者都不写 BACKFILL_AT，都不等于标记已确认；R 之前不放弃。