supply-intelligence/tech/G4_REMOTE_GATEWAY_INTEGRATION_PRD_2026-05-10.md

G4 真实远端 Gateway 集成验证 PRD

文档版本：v1.0 日期：2026-05-10 作者：PM（生产门禁收口） 状态：待 TechLead 评审

---

1. 概述

Supply-Intelligence 的 G1（smoke 主链）、G2（inspect/metrics）、G3（rollback 演练）已在本地与 tksea 服务器完成。当前生产门禁为 REQUEST_CHANGES，唯一阻断项是 G4：真实远端 gateway 集成验证。

G4 不是新增功能，而是对已有 gateway publish / consume / ack 链路在共享预发环境中的端到端实证要求。supply-intelligence 作为事件生产者，sub2api / tokens-reef 作为下游消费者，必须在共享环境中留下可复核的双侧对账记录。

---

2. 目标

在共享预发环境中完成一次闭环验证，证明：

1. supply-intelligence 产生的 package_change_event 能被远端系统（sub2api / tokens-reef）真实消费。
2. 消费的 EVENT_ID 在 supply-intelligence 侧与远端侧均可被独立查询，且状态一致。
3. 远端消费失败时，supply-intelligence 侧不会误标为 applied，而是进入 retry 或保持 pending。
4. 验证过程可复现、可脚本化、可归档为 QA 复核证据。

---

3. 范围

3.1 In Scope

• supply-intelligence 共享预发环境（当前为 tksea 43.155.133.187:8081）的事件 publish 与 consume-once API。
• sub2api / tokens-reef 作为远端 consumer 对 consume-once 的调用及后续处理。
• 双侧 EVENT_ID 对账机制的定义与验证脚本。
• 共享环境中 gateway runtime 的暂停/恢复操作（避免与远端 consumer 竞争单 ack 事件）。
• G4 验证证据包的格式、归档位置与 QA 复核流程。

3.2 Out of Scope

• supply-intelligence 核心 publish / consume / ack 业务逻辑的代码级改造（主链路已在 G1-G3 验证通过）。
• sub2api / tokens-reef 内部业务规则的深度改造（如 token 配额算法、模型路由策略）。
• 多 consumer 独立 ack schema 的长期重构（已知当前为单 ack 设计，G4 通过操作规程规避竞争）。
• 非 gateway 链路（probe、discovery、admission）的额外验证。

3.3 假设与依赖

• 假设 sub2api / tokens-reef 在共享环境中已可运行（tksea 8080 端口已确认运行）。
• 假设 sub2api 侧至少能提供一张持久化表或一个查询接口，记录从 supply-intelligence 消费的事件及其处理结果。
• 假设 supply-intelligence 与 sub2api 在共享环境中网络可达（同服务器已满足）。
• 依赖 sub2api 侧负责人提供消费端的最小实现或已有 bridge 的扩展方案。
• 依赖 TechLead 在 G4 验证前确认单 ack schema 的临时操作规程（暂停 gateway runtime）。

---

4. 用户场景

4.1 主流程：共享环境端到端对账

1. 前置：执行人调用 POST /gateway/runtime/pause 暂停 supply-intelligence 内置 gateway runtime。
2. Publish：执行人调用 POST /publish/package-event 产生一个真实 EVENT_ID。
3. 远端消费：sub2api 以 consumer=sub2api（或已有 consumer 名称）调用 POST /gateway/consume-once 拉取事件。
4. 远端处理：sub2api 将事件应用到自身系统（更新模型列表、路由规则或至少写入持久化消费记录表），并在本地记录 processing_result。
5. Ack：supply-intelligence 的 consume-once 内部自动将事件 ack 为 applied（若 sub2api 调用成功）或 failed（若处理返回失败）。
6. 双侧对账：执行人运行对账脚本，输入 EVENT_ID，查询 supply-intelligence 的 package-changes / admission-state 与 sub2api 侧的持久化记录，比对 event_id、package_id、status、consumer、timestamp。
7. 恢复：执行人调用 POST /gateway/runtime/resume 恢复 gateway runtime。
8. 归档：执行人保存命令、stdout、关键 JSON 片段到证据包目录。

4.2 异常流：远端消费失败

1. sub2api 调用 consume-once 成功获取事件，但在后续处理时抛出业务错误（如模型不存在、数据库冲突）。
2. sub2api 不向 supply-intelligence 发送额外 ack（consume-once 已完成 ack）。
3. 如果 sub2api 需要标记失败，当前单 ack schema 下 consume-once 已返回 applied/ failed。因此 TechLead 必须选择以下策略之一：
   • 策略 A：sub2api 在本地记录失败，对账时以 sub2api 本地记录为准；supply-intelligence 侧状态视为传输层 ack。
   • 策略 B：改造 consume-once 调用方式，使 sub2api 先读取事件但不自动 ack，处理成功后再显式调用 POST /gateway/package-changes/{event_id}/ack。
4. 无论采用哪种策略，QA 必须能在对账脚本中明确区分"supply-intelligence 侧状态"与"sub2api 侧真实处理结果"。

4.3 边缘流：gateway runtime 未暂停导致事件被抢走

1. 若执行人未暂停 gateway runtime，内置 consumer 会在 1 秒内自动消费并 ack 新 publish 的事件。
2. sub2api 再次调用 consume-once 时，该事件状态已为 applied，items 列表中不再包含此事件。
3. 对账脚本检测到 sub2api 侧无此 EVENT_ID 记录，判定为 mismatch。
4. 处置：本场景作为 G4 验证的负向测试用例，用于证明单 ack schema 的竞争风险真实存在；正式 G4 验证必须通过 pause runtime 规避。

4.4 边缘流：重复 publish

1. 同一 EVENT_ID 被重复 publish 时，supply-intelligence 返回 HTTP 409（duplicate_publish_request 或 publish_already_applied）。
2. 远端 consumer 不应收到重复事件。对账脚本验证 sub2api 侧同一 EVENT_ID 仅出现一次。

4.5 边缘流：unauthorized consumer

1. sub2api 使用的 consumer 名称若未关联目标事件的 account_id，则 isAuthorizedForEvent 返回 false。
2. consume-once 的 items 列表中不包含该 unauthorized 事件。
3. 事件在 supply-intelligence 侧保持 pending，不会被错误消费。

---

5. 验收标准（AC）

每条 AC 必须可被 QA 或自动化脚本在共享环境中执行，并给出二元判定（通过 / 不通过）。

AC1：远端 consumer 可达性

• 判定方法：从 sub2api 所在主机执行 curl -fsS -X POST "${SUPPLY_URL}/internal/supply-intelligence/gateway/consume-once?consumer=sub2api"，HTTP 状态码必须为 200，响应 JSON 必须包含 consumer 和 items 字段。
• 通过标准：HTTP 200 且 JSON schema 符合 ConsumeOnceOutput 定义。

AC2：真实事件被远端消费

• 判定方法：在 supply-intelligence 侧执行 publish 产生 EVENT_ID evt-g4-{timestamp}；随后从 sub2api 侧调用 consume-once；检查 sub2api 侧持久化存储中是否存在该 EVENT_ID 的记录。
• 通过标准：sub2api 侧数据库表或审计日志中至少存在一条记录，其 event_id 字段等于 evt-g4-{timestamp}。

AC3：supply-intelligence 侧事件终态正确

• 判定方法：在 AC2 完成后，调用 GET /internal/supply-intelligence/gateway/package-changes 与 GET /internal/supply-intelligence/models/{platform}/{model}/admission-state，检查该 EVENT_ID 的 gateway_sync_status。
• 通过标准：对于成功的远端消费，gateway_sync_status 为 applied；对于明确失败的远端消费，gateway_sync_status 为 failed。不允许为 pending。

AC4：双侧状态可对账

• 判定方法：执行对账脚本（待 TechLead 提供，路径建议 scripts/g4_reconcile.sh），输入 EVENT_ID，脚本分别查询 supply-intelligence 与 sub2api 两侧。
• 通过标准：脚本输出 JSON 必须包含 match=true，且两侧 event_id、package_id、status（或 processing_result）一致；脚本执行时间不得超过 60 秒。

AC5：远端消费失败时的状态隔离

• 判定方法：制造一个远端处理失败的场景（例如 sub2api 消费后记录 processing_result=failed，或在 consume-once 前模拟 sub2api 内部错误）；检查 supply-intelligence 侧事件状态与 sub2api 侧记录。
• 通过标准：若采用策略 A（传输层 ack），supply-intelligence 侧可为 applied，但 sub2api 侧必须记录 processing_result=failed，对账脚本输出 match=false 并标注原因；若采用策略 B（显式 ack），supply-intelligence 侧必须为 failed。不允许出现"supply-intelligence 侧 applied 且 sub2api 侧无记录"的幽灵状态。

AC6：gateway runtime 暂停不影响 API 可用性

• 判定方法：在 gateway runtime 暂停期间（paused=true），重复执行 AC1 的 consume-once 调用，同时检查 healthz 与 runtime-status。
• 通过标准：consume-once API 返回 200；healthz 返回 ok；runtime-status 返回 paused=true；gateway runtime 恢复后 paused=false。

AC7：完整闭环证据归档

• 判定方法：执行人在共享环境中完成 AC1-AC6 后，将产物写入 reports/production/evidence-g4-{date}/ 目录。
• 通过标准：目录中必须包含以下文件，且时间戳在 24 小时内：
  • 00_preflight.json（healthz + runtime-status 演练前）
  • 01_publish.json（publish 响应）
  • 02_consume_once.json（sub2api 侧调用 consume-once 的响应）
  • 03_sub2api_record.sql 或 .json（sub2api 侧持久化记录查询结果）
  • 04_reconcile.json（对账脚本输出）
  • 05_runtime_after_resume.json（恢复后的 runtime-status）

---

6. 边缘情况与失败路径

场景	预期行为	验证方式
gateway runtime 未暂停，事件被内置 consumer 抢走	sub2api consume-once 返回空 items；对账 mismatch	AC4 负向测试
sub2api 调用 consume-once 时 supply-intelligence 宕机	sub2api 收到 HTTP 5xx 或连接超时；事件保持 pending	检查 supply-intelligence 重启后事件状态仍为 pending
sub2api 消费后宕机，未写入本地记录	对账时 sub2api 侧 not_found；supply-intelligence 侧可能已 applied	AC5 明确失败策略
重复调用 consume-once 同一 cursor	返回空 items 或 next_cursor 为空；无重复 ack	AC4 验证 sub2api 侧无重复记录
使用未授权的 consumer 名称	consume-once 不返回该账号事件；事件保持 pending	负向测试：publish 后换 consumer 名称调用，验证 items 为空
网络分区导致 consume-once 超时	sub2api 侧重试；supply-intelligence 侧事件状态不变	模拟超时后重试，验证事件未被错误 ack

---

7. 上线与运营准备

7.1 共享环境配置清单

• supply-intelligence 在 tksea 的 BASE_URL 已确认（当前 43.155.133.187:8081）。
• sub2api / tokens-reef 在 tksea 的地址与数据库连接串已确认（当前 8080 端口，PostgreSQL 本地）。
• sub2api 侧 consumer 名称已确定（建议 sub2api 或沿用 sub2api-bridge）。
• sub2api 侧持久化表已创建（至少含 event_id, package_id, status, consumed_at, processing_result 字段）。
• supply-intelligence 侧 gateway runtime 可在验证前被手动暂停。

7.2 对账脚本

• TechLead 需提供 scripts/g4_reconcile.sh，输入 EVENT_ID 与两侧 BASE_URL，输出 JSON 对账结果。
• 脚本必须返回明确 exit code：0（match）、1（mismatch）、2（not_found / 查询失败）。

7.3 监控与告警

• G4 验证期间，共享环境必须保持 /metrics 可访问。
• 对账脚本执行后，必须记录 supply_intelligence_gateway_events_processed_total 与 supply_intelligence_gateway_failed_events 的采样值。
• 若 G4 验证重复执行超过 3 次仍 mismatch，值班人员必须通知 TechLead 排查，禁止强行修改数据通过门禁。

7.4 回滚预案

• 若 G4 验证导致 sub2api 侧数据异常，sub2api 侧负责人应使用自身系统的回滚机制恢复。
• supply-intelligence 侧可通过 gateway/runtime/pause 停止事件下发，已 ack 的事件不可回滚（事件日志性质）。
• 若需要撤销已 publish 的 package，使用 supply-intelligence 的 publish 替换机制（发布新 package-event），而非删除历史 event。

7.5 值班 runbook

1. 执行 G4 前，确认 runtime-status 中 started=true，然后执行 runtime/pause。
2. 执行 publish，记录返回的 EVENT_ID。
3. 等待 sub2api 侧执行 consume-once（或手动触发）。
4. 运行 g4_reconcile.sh。
5. 若 match=true，执行 runtime/resume，归档证据包。
6. 若 match=false，保持 paused 状态，通知 TechLead 与 sub2api 侧负责人，排查后重新执行。

---

8. 依赖与风险

依赖项	状态	风险描述	缓解措施
sub2api 侧 consumer 实现	缺失	sub2api 当前未配置 supply-intelligence 集成，无持久化消费记录	sub2api 侧负责人需在 G4 前完成最小消费记录表与查询接口
单 ack schema	已知限制	同一时间只能有一个 consumer ack 事件；gateway runtime 会与 sub2api 抢事件	G4 验证期间通过 runtime/pause 规避；长期需 TechLead 评估多 consumer schema 改造
网络稳定性	中风险	tksea 同服务器网络应稳定，但跨容器/进程调用仍可能失败	对账脚本增加重试与超时；失败时标记为 not_found 而非误报 match
证据包人工操作	中风险	执行人可能遗漏归档步骤或时间戳不一致	对账脚本自动将结果写入文件；QA 复核时检查文件存在性与时间戳
sub2api 业务逻辑不可用	低风险	若 sub2api 内部业务系统暂无法处理 package change，bridge 只能写日志	PRD 接受"持久化消费记录表"作为最低证据，不要求立即触发完整业务闭环

---

9. 阶段门控结论

9.1 当前信息是否足够进入 TechLead 设计阶段？

结论：足够。

依据：

1. G4 缺口已被精确识别，不是模糊的"缺集成"，而是"缺远端 consumer 消费 + 双侧对账证据"。
2. supply-intelligence 侧的 API（publish、consume-once、package-changes、admission-state、runtime pause/resume）已经存在且经 G1-G3 验证稳定。
3. sub2api-bridge 已提供技术方向参考（pull 模式、写日志表），TechLead 只需在此基础上扩展为持久化记录 + 查询接口。
4. 单 ack schema 的限制已被识别，并有明确的临时操作规程（pause runtime）。
5. 所有验收标准均已量化（HTTP 200、60 秒、match=true/false、特定 JSON 字段）。

9.2 TechLead 必须产出的设计决策

1. 策略选择：采用策略 A（传输层 ack + sub2api 本地记录 processing_result）还是策略 B（显式 ack 接口）？
2. sub2api 侧最小实现：确定 consumer 名称、持久化表 schema、查询接口路径。
3. 对账脚本：scripts/g4_reconcile.sh 的实现（语言、两侧查询方式、输出 schema）。
4. 多 consumer 长期方案：是否在 G4 之后启动多 consumer 独立 ack schema 的改造？（当前 G4 不要求改造）。

9.3 QA 可提前准备的内容

1. 基于本 PRD 的 AC 编写自动化测试用例框架（即使 sub2api 侧尚未 ready，也可 mock 远端查询接口）。
2. 审核证据包目录结构与命名规范。
3. 准备负向测试用例（unauthorized consumer、重复 publish、runtime 未暂停）。

---

10. 下游关注点摘要

10.1 给 TechLead

• 核心决策：G4 只需要证明"远端真实消费"，不需要一次性完成完美的双向 ack。请尽快确认策略 A 或 B，以便 QA 编写对账脚本。
• 已知债务：CountRetryablePendingPackageEvents 与 ListRetryablePendingPackageEvents 当前忽略 consumer 参数（QA 报告 4.1）。G4 使用单 consumer 验证，暂不触发该债务，但请记录到后续迭代 backlog。
• 实现量评估：sub2api 侧最小改造量约为：创建一张消费记录表 + 一个查询接口 + 扩展 bridge 逻辑。若已有 sub2api-bridge，改造量预计在 1-2 人日。

10.2 给 QA

• 测试重点：不要只验证"consume-once 返回 200"，必须验证 EVENT_ID 在 sub2api 侧有持久化记录。
• 负向用例：务必执行"runtime 未暂停"场景，证明单 ack 竞争真实存在，且 pause 是 G4 的必要前置步骤。
• 证据完整性：严格按照 AC7 的 6 个文件清单审核证据包，缺少任一文件即判定 G4 不通过。

10.3 给 XL（执行/运维）

• 执行顺序：必须先 pause → publish → 等待 sub2api 消费 → 对账 → resume。任何跳过 pause 的执行均视为无效证据。
• 环境保真：G4 验证期间，tksea 上的 supply-intelligence 与 sub2api 配置不得被其他测试干扰。建议预约独占窗口。
• 产物路径：证据包统一存放于 reports/production/evidence-g4-YYYY-MM-DD/，由 QA 复核后合并到 SHARED_ENV_EVIDENCE_RUN_YYYY-MM-DD.md。

---

附录 A：自检清单

返回本 PRD 时，以下条目已逐项确认：

• 已明确真实目标，不是只复述功能
• 已写清 In Scope / Out of Scope
• 每个 AC 都可被 QA 或测试用例直接验证
• 已覆盖异常流、边缘流与失败路径
• 已补齐上线、运营、监控、回滚要求
• 已明确当前是否可进入 TechLead 阶段
• 已给出 TechLead / QA / XL 的下游关注点摘要
• 没有使用"优化、支持、友好、尽量、快速"等模糊词替代明确要求