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 时，以下条目已逐项确认：

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