docs(acm2-74): consolidate design documentation
This commit is contained in:
windyboy
+30
-30
@@ -1,12 +1,12 @@
|
||||
# 参考注册表：参数、指标、模块、错误分类
|
||||
# 参考注册表：参数、指标、代码入口、错误分类
|
||||
|
||||
本文件是**可派生事实**的唯一出处：参数默认值、指标名、模块入口、错误分类。正文（design.md）只引 `PARAM:<完整键>`，不写数值。
|
||||
本文件是**可派生事实**的唯一出处：参数默认值、指标名、模块与代码入口、错误分类。正文只引 `PARAM:<完整键>`，不写数值。
|
||||
|
||||
维护规则：新增或改名一个 `msgx.*` 键、增删一个指标名，必须同步本文件（人工核对，本项目不做 CI 校验）。`mailbox.*`、`datasources.*`、`kafka.*` 属基础设施键，按 §1.3 成组登记。
|
||||
维护规则：新增或改名一个 `msgx.*` 键、增删一个指标名，必须同步本文件（人工核对，本项目不做 CI 校验）。`mailbox.*`、`datasources.*`、`kafka.*` 属基础设施键，成组登记。
|
||||
|
||||
## 1. 参数注册表
|
||||
|
||||
「依据」列含义：**契约** = 由 contracts.md 的 `C-x` 决定；**现役** = 沿用 legacy 行为基线；**假定** = 无依据的占位值，必须在对应 `Q` 关闭后重评；**安全默认** = 关闭态，需显式开启。
|
||||
「依据」列含义：**契约** = 由 [specification.md](specification.md) 的 `C-x` 决定；**现役** = 沿用 legacy 行为基线；**假定** = 无依据的占位值，必须在对应 `Q` 关闭后重评；**安全默认** = 关闭态，需显式开启。
|
||||
|
||||
### 1.1 管道节奏与重试（`msgx.pipeline.*`）
|
||||
|
||||
@@ -18,17 +18,17 @@
|
||||
| `msgx.pipeline.backoff-ms` | `[1000,2000,4000,8000]` | ms / 档 | 假定 | **档位数必须 = `max-attempts − 1`**，启动自检拦截错位 |
|
||||
| `msgx.pipeline.backoff-cap-ms` | `60000` | ms | 假定 | 单档封顶；默认表内无档触及 |
|
||||
| `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.overdue-backfill` | `30d` | Duration | 契约（`R ≤ R_keep`） | 即 `R`：进入强补写窗口、**取消退避**的阈值；**不是兜底保证**，不保护重放窗口（`Q6`） |
|
||||
| `msgx.pipeline.backfill-batch` | `100` | 条 | 假定 | 回填扫描单批条数 |
|
||||
| `msgx.pipeline.backfill-scan-period` | `30s`（代码常量，无配置键） | Duration | 现役 | 回填扫描作业周期；批次积压与单行超时会延长实际标记延迟（`CLM-9`） |
|
||||
| `msgx.pipeline.backfill-max-attempts` | `100` | 次 | 假定 | 单行重试的**告警阈值**；放弃判据是 `R` 超期，不是次数（见 design「回填」） |
|
||||
| `msgx.pipeline.backfill-backoff-ms` | `30000` | ms | 假定 | 回填独立退避起步间隔；`BackfillService` 指数退避的首档 `[G-BACKFILL-BACKOFF ✓]` |
|
||||
| `msgx.pipeline.backfill-backoff-cap-ms` | `900000` | ms | 假定 | 回填退避封顶（15 分钟）`[G-BACKFILL-BACKOFF ✓]` |
|
||||
| `msgx.pipeline.backfill-max-attempts` | `100` | 次 | 假定 | 单行重试的**告警阈值**；放弃判据是 `R` 超期，不是次数 |
|
||||
| `msgx.pipeline.backfill-backoff-ms` | `30000` | ms | 假定 | 回填独立退避起步间隔；`BackfillService` 指数退避的首档 |
|
||||
| `msgx.pipeline.backfill-backoff-cap-ms` | `900000` | ms | 假定 | 回填退避封顶（15 分钟） |
|
||||
| `msgx.pipeline.cutover-watermark` | 不设置 | `min\|zero\|max\|<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` | `7d` | Duration | 假定 | 已 `SENT` 事件行保留期，由清理作业删除 `sent_at < now - retention` 的行；`[G-EVENT-RETENTION]` |
|
||||
| `msgx.pipeline.event-retention` | `7d` | Duration | 假定 | 已 `SENT` 事件行保留期，由清理作业删除 `sent_at < now - retention` 的行 |
|
||||
|
||||
### 1.2 其它 `msgx.*`
|
||||
|
||||
@@ -49,7 +49,7 @@
|
||||
| `msgx.history.deleted-hours` | `48` | 假定 | 历史清理的已删除判据窗口 |
|
||||
| `msgx.history.idle-hours` | `168` | 假定 | 历史清理的静默期判据 |
|
||||
| `msgx.history.snap-log-retention-days` | `90` | 假定 | `SCHD_SNAP_LOG` 保留天数 |
|
||||
| `msgx.proc-state.archive-after` | `1d` | 假定 | **未实现**（`[G-PROC-HST]`）；终态记录归档阈值，建议范围 1～7 天；见 `US-11` |
|
||||
| `msgx.proc-state.archive-after` | `1d` | 假定 | 终态记录归档阈值，建议范围 1～7 天；目标表见 `G-PROC-HST`，见 `US-11` |
|
||||
|
||||
### 1.3 信箱与外部依赖（成组登记）
|
||||
|
||||
@@ -57,14 +57,14 @@
|
||||
|---|---|---|---|
|
||||
| `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` | `1` | 契约（D3） | 启动自检钉住三项联合满足 D3；允许环境变量覆盖 |
|
||||
| `mailbox.shared-mysql.connect-timeout-ms` | `3000` | 假定 | 有界外部调用；Connector/J 默认无限等待，必须显式；同组 `socket-timeout-ms=30000` |
|
||||
| `mailbox.shared-mysql.pool-connection-timeout-ms` | `5000` | 假定 | 池级连接超时；同组 `pool-validation-timeout-ms=3000` |
|
||||
| `mailbox.shared-mysql.url` | 环境变量 | 安全 | 零入库，见 `.env.example`；同组 `username` / `password` |
|
||||
| `datasources.default.connection-timeout` | `5000` | 假定 | 自有 PG 池（毫秒数，非 Duration 字面量）；同组 `validation-timeout=3000`、`idle-timeout=300000`、`max-lifetime=1800000` |
|
||||
| `datasources.default.data-source-properties.connectTimeout` | `3` | 假定 | 驱动级连接超时（秒）；同组 `socketTimeout=30` |
|
||||
| `kafka.producers.default.acks` | `all` | 契约（`D3`） | 允许环境变量覆盖 |
|
||||
| `kafka.producers.default.enable-idempotence` | `true` | 契约（`D3`） | 允许环境变量覆盖 |
|
||||
| `kafka.producers.default.max-in-flight-requests-per-connection` | `1` | 契约（`D3`） | 启动自检钉住三项联合满足 `D3`；允许环境变量覆盖 |
|
||||
|
||||
环境变量清单以 `.env.example` 为准。
|
||||
|
||||
@@ -83,27 +83,27 @@
|
||||
| `msgx.pipeline.job.ticks.total` | 作业 tick 完成次数 | 不增长 → 作业停摆 |
|
||||
| `msgx.pipeline.job.failures.total` | 作业 tick 抛错次数 | 增长 → 扫描/历史作业异常 |
|
||||
| `msgx.pipeline.job.last_sweep_selected` | 上一轮回填扫描选中的待办条数（扫描积压） | 持续顶到批次上限 → 扫描吃不消 |
|
||||
| `msgx.pipeline.codec.srvt_seen.total` | 入站记录中出现 `SRVT` 段的条数（尚未落明细表，`[G-SRVT-VIPF]`） | > 0 → 真实流量确有该段，按真实报文定案 `Q13` |
|
||||
| `msgx.pipeline.codec.vipf_seen.total` | 入站记录中出现 `VIPF` 段的条数（尚未落明细表，`[G-SRVT-VIPF]`） | 同上 |
|
||||
| `msgx.pipeline.processing.ignored.total` | 命中 US-04 忽略清单的报文条数 | 增长是正常流量；归零反而需确认配置是否丢失 |
|
||||
| `msgx.pipeline.codec.srvt_seen.total` | 入站记录中出现 `SRVT` 段的条数（`G-SRVT-VIPF`） | > 0 → 真实流量确有该段，按真实报文定案 `Q13` |
|
||||
| `msgx.pipeline.codec.vipf_seen.total` | 入站记录中出现 `VIPF` 段的条数（`G-SRVT-VIPF`） | 同上 |
|
||||
| `msgx.pipeline.processing.ignored.total` | 命中 `US-04` 忽略清单的报文条数 | 增长是正常流量；归零反而需确认配置是否丢失 |
|
||||
|
||||
取数规则：统一走 `BacklogSnapshotProvider`（`PARAM:msgx.health.backlog-cache-ttl-ms`），`/health` 与 `/metrics` 共用同一快照——`backlog()` 是 `PROC_STATE` 的全表聚合，不能被高频抓取打穿；**无法取数上报 `NaN`，无可比记录的年龄/滞后类仪表上报 `-1`，都不伪造 0**。日志出口故障不得阻塞业务线程。进程内计数类指标不经快照，重启归零。
|
||||
|
||||
作业健康：回填的唯一驱动是扫描作业，因此作业存活必须独立可观测——`msgx.pipeline.job.heartbeat_age_seconds` / `ticks.total` / `failures.total` 是作业心跳，`msgx.pipeline.job.last_sweep_selected` 是扫描积压，`msgx.pipeline.backfill.oldest_unmarked_seconds` 是实际回填延迟；作业线程停摆由 `/health` 的作业指示器判 `DOWN`（心跳超过 `3 × 扫描周期`，周期是代码常量）。
|
||||
|
||||
## 3. 模块入口
|
||||
## 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`、`config/OperationDayProps.kt`（含运营日时区启动自检） |
|
||||
| 收报与兼容接口 | `ingress/InboxPoller.kt`、`ingress/InboxService.kt`、`ingress/InboxController.kt` |
|
||||
| 解码与忽略规则 | `codec/JacksonXmlCodec.kt`、`codec/XmlCodec.kt`、`codec/SisWireMapper.kt`、`codec/SisMessageBody.kt`、`processing/IgnoreRules.kt` |
|
||||
| 调度与处理 | `processing/Pump.kt`（含 `MessageProcessor`）、`processing/DynamicProcessors.kt`（FLOP/FDEL/ADFT）、`processing/ScheduleProcessor.kt`、`processing/Identity.kt`、`processing/MessageLifecycleGate.kt` |
|
||||
| 回填与投递 | `processing/BackfillService.kt`、`delivery/Dispatcher.kt`、`infra/kafka/KafkaDeliveryPort.kt` |
|
||||
| 维护作业 | `jobs/JobRunner.kt`、`jobs/HistorySweepJob.kt`、`jobs/EventCleanupJob.kt`、`infra/persistence/SnapshotLogPurge.kt` |
|
||||
| 持久化与恢复 | `infra/persistence/`（含 `jdbc/JdbcPgRepositories.kt`、`jdbc/JdbcCminmsgInboxRepository.kt`）、`infra/retry/`（`ProcFailure` / `ReplayService` / `FailureScheduler`） |
|
||||
| 启停与配置 | `PipelineLifecycle.kt`、`config/PipelineProps.kt`、`config/HistoryProps.kt`、`config/OperationDayProps.kt`（含运营日时区启动自检）、`config/MailboxProps.kt`、`config/KafkaD3Check.kt`（`D3` 三联合启动自检） |
|
||||
| 指标与健康 | `infra/metrics/PipelineMetrics.kt`、`infra/metrics/JobActivity.kt`、`infra/health/BacklogSnapshotProvider.kt`、`infra/health/JobRunnerHealthIndicator.kt` |
|
||||
| 迁移 | `src/main/resources/db/migration/`（单基线 `V1__flight_state_baseline.sql`：原 V1–V10 的净结构已合并，迁移链收敛为一条；`oracle11g/` 为占位） |
|
||||
| 迁移 | `src/main/resources/db/migration/`（单基线 `V1__flight_state_baseline.sql`；`oracle11g/` 为占位） |
|
||||
|
||||
## 4. 错误分类与重放白名单
|
||||
|
||||
|
||||
Reference in New Issue
Block a user