supply-intelligence/prd/PM_GATEWAY_CLOSURE_PRD_2026-05-08.md

PM 收口定义：Gateway 契约 / 重试 / 灰度回滚 / 巡检门禁（2026-05-08）

状态：当前有效 阶段门控结论：可进入 TechLead 设计 仓库：/home/long/project/supply-intelligence 上游真源：

• tech/CURRENT_SOURCE_OF_TRUTH_2026-05.md
• tech/BASELINE_TECHLEAD_V2.md
• tech/GATEWAY_CONSUMER_DECISION_2026-05.md
• tech/PRODUCTION_LAUNCH_CLOSURE_BOARD_2026-05-08.md

0. 当前门控结论

• 当前结论：可进入 TechLead
• 阻塞项：当前仓库已经有 package event + ack 与 metrics 暴露，但缺少“生产口径”层面的明确边界：
  1. 哪些 gateway 失败允许自动重试，哪些必须停在 failed 等人工处置
  2. published、pending、applied、failed 分别代表什么上线口径
  3. 什么条件允许灰度继续，什么条件必须回滚
  4. 上线后 24h / 72h 巡检要看哪些事实项
• 进入下一阶段前必须补齐：本文件定义的契约、重试、灰度/回滚、巡检判定线

1. 背景

当前项目已经完成最小内部主链：

• package 发布后可写入 gateway package event
• gateway 消费方可以拉取 changes 并 ack
• /metrics、/healthz、routing-state、admission-state 已有最小实现

但这些只是“实现能力存在”，还不等于“生产上线口径清晰”。 当前缺的是把生产上线剩余阻塞项写成可以被 TechLead、QA、Engineer 直接执行和验收的 PM 定义。

2. 目标

本轮目标不是新增功能范围，而是把上线收口定义清楚，使团队可以围绕以下四个问题收敛：

1. gateway 与 supply-intelligence 的真实契约边界是什么
2. gateway 消费失败时的重试与终态口径是什么
3. 灰度、止损、回滚、恢复推进的业务判定线是什么
4. 上线后巡检如何判断“继续观察”“停止放量”“触发回滚”

成功定义

满足以下四条即视为 PM 收口定义完成：

1. TechLead 可以据此直接拆出文件级实现任务
2. QA 可以据此做设计审查并给出是否可进入实现的结论
3. Engineer 可以据此实现重试、runbook、观测接入与测试
4. XL 可以据此判断上线推进、暂停或回滚

失败判定线

出现以下任一情况，视为 PM 定义未完成，不得进入实现：

1. 仍无法区分自动重试失败与人工介入失败
2. 仍无法判断 published != applied 下的真实上线状态
3. 仍没有可执行的灰度/回滚判定条件
4. 巡检项仍停留在“看日志/看指标大概正常”这类模糊表达

3. 范围

In Scope

1. gateway package change 拉取与 ack 的生产口径
2. gateway 消费失败分类与重试规则
3. 灰度放量、暂停、回滚、回滚后复核的业务判定线
4. 上线后 24h / 72h 巡检项与升级路径
5. 与当前最小主链直接相关的监控/门禁要求

Out of Scope

1. 重新定义历史 PRD 中的 pricing / prediction / 大盘扩张能力
2. 引入 MQ、Kafka、Redis、Temporal 等新基础设施作为本轮收口前置
3. 扩大到 NewAPI / Sub2API 的事件 ack 闭环
4. 替代 TechLead 做文件级设计、函数签名和实现细节

假设与依赖

1. 当前首期默认事件型消费方仍是 gateway
2. 当前生产主链仍基于 event + ack，不改成强耦合同步 RPC
3. 当前仓库已有最小事件、ack、metrics、healthz 能力可复用
4. 若部署侧需要真实告警平台或演练环境，可由 TechLead 建议引入 DevOps，但 PM 先定义口径

4. Gateway 契约边界定义

4.1 角色边界

• supply-intelligence 负责：
  1. candidate 通过后将 package 置为 active
  2. 生成 gateway_package_event
  3. 提供 package-changes 拉取接口
  4. 接收 ack(applied|failed) 并更新同步状态
• gateway 负责：
  1. 周期拉取 package changes
  2. 对每个 event 执行本地应用
  3. 对每个尝试结果显式 ack
  4. 对无法安全自动恢复的失败保留 failed，并交由人工或后续受控重试流程处理

4.2 状态语义

• candidate_status=published：上游已完成运营确认，可被下游消费；不表示已生效
• gateway_sync_status=pending：event 已生成，但 gateway 尚未给出最终消费确认
• gateway_sync_status=applied：gateway 已成功消费并确认生效
• gateway_sync_status=failed：gateway 已尝试消费但未成功，本次 event 不得继续被当作“已生效”

4.3 明确禁止

以下判断一律视为错误：

1. package active 就等于已进入 gateway 路由
2. event 已写入表就等于发布完成
3. 没有 ack 也可以口头认定“应该已经生效”
4. failed 可以无限自动重试直到成功

5. Gateway 失败重试口径

5.1 失败分类

A. 可自动重试失败

满足以下任一条件，可进入自动重试：

1. gateway 拉取 / 应用过程中的瞬时网络错误
2. 临时 5xx 或超时，且没有证据表明请求已被部分应用
3. gateway 自身短暂不可用，但恢复后重新消费不会造成重复副作用

B. 不可自动重试失败（终态 failed）

满足以下任一条件，不得自动重试，必须停在 failed：

1. 参数/契约错误：字段缺失、版本不兼容、必要上下文缺失
2. 幂等冲突或语义冲突：重复应用会引发错误路由或覆盖错误状态
3. 安全或权限错误：鉴权失败、consumer 不被授权
4. 明确业务拒绝：gateway 判定该 event 不符合当前接入条件

5.2 自动重试上限

• 每个 event 最多允许 3 次自动重试
• 建议退避窗口：首次失败后 1 分钟、第二次 5 分钟、第三次 15 分钟
• 第 3 次仍失败，必须转最终 failed，等待人工处理，不得继续隐式重试

5.3 自动重试成功后的口径

• 只有最终 ack=applied，该 event 才能被计为“gateway 已生效”
• 自动重试期间，灰度放量和成功统计都必须按“未完全生效”处理

5.4 人工处置要求

对最终 failed 的 event，必须至少有以下信息可供人工判断：

1. event_id
2. package_id / platform / model
3. consumer
4. 最近失败原因
5. 已尝试次数
6. 最后失败时间
7. 人工重试或回滚建议入口

6. 灰度推进 / 停止 / 回滚判定线

6.1 上线前放量前提

同时满足以下条件才允许开始灰度：

1. /healthz 正常
2. /metrics 可访问
3. 至少完成一轮桌面演练：publish -> package-changes -> ack
4. 没有遗留 failed event 处于未评估状态
5. QA 已确认设计与实现门禁通过

6.2 允许继续灰度的条件

灰度期间同时满足以下条件，可继续推进：

1. 新产生 event 在 15 分钟内达到 applied 的比例 >= 95%
2. 没有连续 3 个 event 落入最终 failed
3. 没有出现 consumer 未授权、契约不兼容、错误模型路由这类结构性错误
4. 没有因本轮变更触发需要人工紧急修复的生产事故

6.3 必须暂停放量的条件

出现以下任一情况，必须暂停继续放量，但不一定立即全量回滚：

1. 15 分钟窗口内 event applied 比例 < 95%
2. 自动重试中的 event 积压超过 10 条
3. metrics 或 health 检查不可用，导致无法判断真实状态
4. 单一模型/单一平台出现重复 failed，怀疑为契约或实现错误

6.4 必须回滚的条件

出现以下任一情况，必须触发回滚：

1. 连续 3 个 event 最终 failed
2. 出现错误模型上线、错误 package 生效、错误 consumer 应用这类错误发布
3. ack 语义异常，导致无法确认哪些 event 已真实生效
4. 监控面失真：无法区分 pending / applied / failed 的真实规模
5. 出现已证实的契约不兼容，继续重试无意义

6.5 回滚成功判定线

回滚后必须同时满足以下条件才算回滚完成：

1. 回滚目标 event 或 package 已被明确撤销或替换
2. 不再有新增由本次发布导致的 failed 积压
3. healthz 正常
4. metrics 可恢复显示 pending/applied/failed 状态
5. 责任人完成一次回滚后确认记录

7. 上线后巡检门禁

7.1 首 24 小时巡检项

必须检查：

1. gateway_events_processed_total 是否持续增长
2. 新 event 从产生到 applied 的时延是否稳定
3. 是否出现最终 failed event；若有，是否已处置
4. 是否存在长期 pending 未落态 event
5. 是否能按 platform 查看 account status / routing enabled 数量

7.2 首 72 小时巡检项

除 24h 项外，新增检查：

1. 是否存在平台维度持续失败集中在单一 provider
2. 是否存在 repeated retry 但最终都失败的模式
3. 灰度期间是否出现“已发布但未生效”被误判为成功的流程偏差
4. 观测与 runbook 是否足以支持值班同学独立处置

7.3 异常升级路径

• 单条 event failed：工程值班处理
• 同平台连续失败：升级 TechLead
• 契约级错误、授权错误、错误路由：升级 XL + TechLead，暂停放量
• 监控缺失导致状态不可判定：升级 XL，停止继续上线

8. 验收标准

AC-1 契约边界

必须能二元判断：

• 是否明确了 supply-intelligence 与 gateway 的职责边界
• 是否明确了 published != applied
• 是否明确了 pending / applied / failed 的业务含义

AC-2 重试口径

必须能二元判断：

• 是否定义了可自动重试失败与不可自动重试失败
• 是否定义了重试上限与最终 failed 口径
• 是否定义了 failed 后的人工处置信息要求

AC-3 灰度/回滚

必须能二元判断：

• 是否有开始灰度前提
• 是否有继续、暂停、回滚三类明确判定线
• 是否有回滚完成判定线

AC-4 巡检门禁

必须能二元判断：

• 是否定义了 24h / 72h 检查项
• 是否定义了异常升级路径
• 是否要求巡检基于可访问指标和状态事实，而不是口头判断

9. 给下游的交接摘要

• 给 TechLead：把本文件的失败分类、重试上限、灰度/回滚判定线、巡检项映射到具体文件、脚本、metrics 和测试任务
• 给 QA：重点检查设计是否真正区分自动重试与终态 failed，是否能验证 published/pending/applied/failed 语义，以及 runbook/观测是否可执行
• 给 Engineer：实现目标不是“再补一个文档”，而是把重试状态、runbook 支撑、指标/巡检接入做成可测代码与脚本
• 给 XL：当前 PM 门已经补齐，可直接推进 TechLead 设计与 QA 前置审查