chore: sync local project state

prd/PM_GATEWAY_CLOSURE_PRD_2026-05-08.md

@@ -0,0 +1,226 @@
+# 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 前置审查