refactor(ingress): 信箱边界层契约重构——发现与处理标记解耦、回填事实并入 PROC_STATE
收报扫描不再以 DATE_PROCESSED 为谓词:终态而未回填的行(解码失败死信等)会永久占据 有限批次,累积到 claim-batch 后收报整体停摆(US-01 条目 3 / message-lifecycle §5.3)。 ingress/InboxPoller.kt:按 ID 区间升序有界读取(ID > W),水位落 INBOX_CURSOR 并与入队 同一 PG 事务推进(中断后重扫补建);遇空洞即停,空洞超过 pipeline.max-commit-delay 判定 为永久并放行——否则水位永久停摆于一次自增回滚留下的空位。删除 InboxEnqueue(改由 insertIfAbsent 幂等入队)与 poller 内的回填扫描(消除 ingress→jobs 反向依赖)。 infra/persistence:端口按事实重画为 readRange/maxId/markProcessedIfUnmarked,标记 UPDATE 带 DATE_PROCESSED IS NULL 守卫,只把空标写为已处理(§11 单调,重复执行无副作用)。 回填事实并入 PROC_STATE(RECEIVED_AT/BACKFILL_AT/NEXT_AT/ATTEMPTS/ERROR),BACKFILL_TODO 随 V2 迁移下线;终态与回填意图是同一条 UPDATE,由处理器在自己的业务事务内落库, message-lifecycle §4 登记的两个崩溃窗口(提交后回填前崩溃、待办二次落账失败)不再是缺口。 processing/BackfillService.kt(取代 BackfillSweepJob):终态提交后立即尝试一次,失败按 30s→15min 指数退避重试;扫描条件「终态 + 未确认标记 +(已到期 或 接收时间早于 NOW − R)」 使 §5.2 的超期期限 R 覆盖退避,中间态永不补写。死信同样可补写——回填只需消息 ID, 不再依赖 META。Pump 改用可注入 Clock。 infra/health:InboxLifecycleHealthIndicator 输出积压条数、最老未处理信龄、未回填终态数与 水位滞后(OPS-2 / §5.3 验收)。预计消化时长需吞吐采样,留待接入指标注册表时补。 配置:pipeline.max-commit-delay / overdue-backfill / backfill-batch、mailbox.processed-value (Q2/Q6/Q7 未书面确认前取保守初值,不得为提速下调)。 不变量回归测试:死信不阻断后续发现、水位遇空洞即停与老化放行、终态+意图同事务、 超期 R 覆盖退避、中间态不补写、标记单调;InboxLifecycleJdbcSqlTest 以 H2 的 PostgreSQL 兼容模式直连验证上述 SQL 语义(不依赖 docker)。libs.h2 由 testRuntimeOnly 提为 testImplementation 以支持该用例。 验证:gradle clean test --offline → 78 tests / 0 failures / 1 skipped (PG Testcontainers 集成用例在本机无 docker 时按既有约定 assumeTrue 跳过)。
This commit is contained in:
@@ -19,6 +19,9 @@ msgx:
|
||||
backoff-ms: [1000, 2000, 4000, 8000, 16000] # 指数退避,单次封顶 60s
|
||||
backoff-cap-ms: 60000
|
||||
head-deadline: 10m # 队头滞留上界 = 最坏 HOL 时长(毒丸升级)
|
||||
max-commit-delay: 5m # §5.1 空洞老化:W+1 空洞超过该时延判定为永久(Q2 最大提交时延)
|
||||
overdue-backfill: 30d # §5.2 超期补写期限 R:≥ 人工重放期限 + 人工处置期限(Q6)
|
||||
backfill-batch: 100 # 回填扫描单批条数
|
||||
autostart: false # U07:启动即拉起 Pump/Dispatcher 循环;需真实仓储或 msgx.stubs=true 才开启(dev 见 application-dev.yml)
|
||||
schd:
|
||||
flush-period: 3s # KEEP 现役推送节律
|
||||
@@ -41,8 +44,9 @@ micronaut:
|
||||
port: 8080
|
||||
# 管理端点(U03/N32):/env、/beans 默认 sensitive;仅开发/影子环境放开——见 application-dev.yml
|
||||
|
||||
# 自有 PostgreSQL:全部内部状态(PIPELINE_LOCK/PROC_STATE/MSG_EVENT/REQ_TRACK/BACKFILL_TODO/
|
||||
# FLIGHT_SCHD 及明细表/SCHD_SNAP_LOG;迁移 db/migration/V1__flight_state_baseline.sql)。
|
||||
# 自有 PostgreSQL:全部内部状态(PIPELINE_LOCK/PROC_STATE/MSG_EVENT/REQ_TRACK/INBOX_CURSOR/
|
||||
# FLIGHT_SCHD 及明细表/SCHD_SNAP_LOG;迁移 db/migration/V1__flight_state_baseline.sql +
|
||||
# V2__inbox_lifecycle.sql——V2 起回填意图并入 PROC_STATE,BACKFILL_TODO 已下线)。
|
||||
# 数据层实装前 enabled=false(stub 模式不建连)。
|
||||
datasources:
|
||||
default:
|
||||
@@ -62,6 +66,7 @@ flyway:
|
||||
# 处理回填;出站写 COUTMSGS;不建表/schema,ACM2-12)。驱动/依赖与信箱适配层
|
||||
# (CminmsgMailbox/OutboxMailbox)随 U05 批次引入。
|
||||
mailbox:
|
||||
processed-value: PROCESSED # §5.2 处理标记写入值(Q7:值集与写权限以库方契约为准)
|
||||
shared-mysql:
|
||||
enabled: false
|
||||
url: ${MSGX_MAILBOX_URL}
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
-- =====================================================================
|
||||
-- V2:信箱生命周期边界层(权威设计:docs/message-lifecycle.md §2/§4/§5.1/§5.2)
|
||||
-- ---------------------------------------------------------------------
|
||||
-- 三处契约级修正,均只动自有 PG(共享 MySQL 不建表、不改结构,红线不破):
|
||||
-- 1. 消费水位 W 落库(INBOX_CURSOR):只随新 ID 成功入队推进、遇空洞即停,
|
||||
-- 与入队同事务——中断后 W 未前进,重扫即补建(§4 第一行);
|
||||
-- HOLE_SINCE 支撑"空洞老化",避免一次自增回滚空位永久停摆水位(§5.1)。
|
||||
-- 2. 回填事实并入 PROC_STATE:终态与回填意图同一条 UPDATE 落下,
|
||||
-- 消除"业务已提交、回填待办未记"与"待办二次落账失败"两个崩溃窗口(§4);
|
||||
-- BACKFILL_TODO 随之下线(它承载的 sndr/type/styp/seqn 从未参与回填,
|
||||
-- 共享信箱回填只需要 MSG_ID——§5.2 补写同样如此)。
|
||||
-- 3. 超期补写判据 RECEIVED_AT(§5.2 的 R)与 OPS-2「最老未处理信龄」锚点。
|
||||
-- =====================================================================
|
||||
|
||||
-- ① 消费水位:单行游标(CURSOR_ID 恒为 1)
|
||||
CREATE TABLE INBOX_CURSOR (
|
||||
CURSOR_ID INT NOT NULL PRIMARY KEY, -- 恒为 1
|
||||
COMMITTED_UP_TO BIGINT NOT NULL, -- 水位 W:连续上界,无空洞
|
||||
HOLE_SINCE TIMESTAMP(6) WITH TIME ZONE, -- W+1 处空洞首次观测时刻;无空洞为 NULL
|
||||
UPDATED_AT TIMESTAMP(6) WITH TIME ZONE NOT NULL
|
||||
);
|
||||
-- 初值 0:首轮从最小 ID 起重扫全部信箱行,入队幂等(ON CONFLICT DO NOTHING),
|
||||
-- 上线即自愈既有"已入队未回填"造成的窗口污染。
|
||||
INSERT INTO INBOX_CURSOR (CURSOR_ID, COMMITTED_UP_TO, HOLE_SINCE, UPDATED_AT) VALUES (1, 0, NULL, now());
|
||||
|
||||
-- ② PROC_STATE:接收时间 + 回填事实(替代 BACKFILL_TODO)
|
||||
ALTER TABLE PROC_STATE ADD COLUMN RECEIVED_AT TIMESTAMP(6) WITH TIME ZONE;
|
||||
ALTER TABLE PROC_STATE ADD COLUMN BACKFILL_AT TIMESTAMP(6) WITH TIME ZONE; -- 非空 = 已确认信箱行持有标记
|
||||
ALTER TABLE PROC_STATE ADD COLUMN BACKFILL_NEXT_AT TIMESTAMP(6) WITH TIME ZONE; -- 非空 = 待回填(终态同事务登记)
|
||||
ALTER TABLE PROC_STATE ADD COLUMN BACKFILL_ATTEMPTS INT NOT NULL DEFAULT 0;
|
||||
ALTER TABLE PROC_STATE ADD COLUMN BACKFILL_ERROR VARCHAR(512);
|
||||
|
||||
-- 存量行接收时间:无法跨库回读 DATE_RECEIVED,以入队时间为下界(§5.2 判据只会偏晚,不会提前补写)
|
||||
UPDATE PROC_STATE SET RECEIVED_AT = UPDATED_AT WHERE RECEIVED_AT IS NULL;
|
||||
|
||||
-- 存量终态行补登记回填意图:立即交给回填扫描(已持有标记的行由空标守卫返回 0 行,幂等)
|
||||
UPDATE PROC_STATE SET BACKFILL_NEXT_AT = now()
|
||||
WHERE STATE IN ('SUCCEEDED', 'SKIPPED', 'DEAD') AND BACKFILL_AT IS NULL;
|
||||
|
||||
-- 回填扫描索引:仅覆盖未确认标记的行
|
||||
CREATE INDEX idx_proc_backfill_due ON PROC_STATE (BACKFILL_NEXT_AT) WHERE BACKFILL_AT IS NULL;
|
||||
|
||||
-- ③ BACKFILL_TODO 下线(回填意图已并入 PROC_STATE,机制收敛为一套;索引随表一并释放)
|
||||
DROP TABLE BACKFILL_TODO;
|
||||
Reference in New Issue
Block a user