niuniu/supply-intelligence

Fork 0

Files

Your Name 1c0084afe8 chore: sync local project state

2026-05-12 18:49:52 +08:00

14 KiB

Raw Permalink Blame History

QA G4 缺口结构化审查报告（2026-05-10）

审查人：QA（质量经理）审查对象：supply-intelligence 生产门禁 G4 缺口基础输入：

QA 生产门禁复核报告 2026-05-09
共享预发生产门禁执行板 2026-05-09
共享环境证据执行清单 2026-05-09
代码审查：internal/gatewayconsumer/service.go、internal/app/app.go、cmd/sub2api-bridge/main.go

1. 阶段门控结论

REQUEST_CHANGES

理由：

G1 Smoke 主链：已通过（本地 + tksea 双环境留痕）
G2 Inspect / retry / failed：已通过（本地 + tksea 双环境留痕）
G3 Rollback 演练：已通过（本地 + tksea 双环境三段状态留痕）
G4 真实远端 gateway 集成：未完成，且经代码审查确认当前代码不具备完成 G4 的技术基础

2. 审查输入清单

输入项	状态	说明
QA 生产门禁复核报告 2026-05-09	已读取	原始结论 REQUEST_CHANGES，G4 pending
共享预发生产门禁执行板 2026-05-09	已读取	明确 G4 必须提供下游侧留痕证据
共享环境证据执行清单 2026-05-09	已读取	明确 G4 不合格证据定义
internal/gatewayconsumer/service.go	已审查	发现默认 applier 为本地 mock
internal/app/app.go	已审查	发现 buildApp 未注入真实外部 gateway 客户端
cmd/sub2api-bridge/main.go	已审查	为反向 consume 桥接器，非 supply-intelligence 主动外呼链路
internal/integration/platform.go	已审查	HTTP client 仅用于 discovery/probe（上游供应商），不用于下游 gateway
tksea 环境部署状态	已知事实	已部署（43.155.133.187:8081），但 sub2api 未配置集成

3. Gap Taxonomy 分析（对 G4 缺口的归类）

重新评估后的缺口分类（基于代码事实）

分类	计数	说明
design_gap	0	架构层面已预留 applier 注入点（Service.SetApplier / Service.applier 字段），不构成设计缺口
implementation_gap	2	1) 默认 applier 为本地 mock/simulator；2) buildApp 装配层未实现也未注入任何真实外部 gateway 客户端
evidence_gap	1	G4 所需的下游侧日志/截图/trace 证据完全缺失
call_chain_gap	1	从 supply-intelligence 到真实远端 gateway 的 publish → consume → apply → ack 调用链未接通
contract_gap	1	runtime-status 暴露 consumer 查询参数，但 CountRetryablePendingPackageEvents 未按 consumer 过滤（已登记）

与先前 QA 报告的差异说明

原 QA 报告（2026-05-09）将缺口主要归类为 evidence_gap:3、implementation_gap:1、call_chain_gap:0。经本次代码审查后修正：

call_chain_gap 从 0 上调为 1：因为 supply-intelligence 当前在装配层（buildApp）完全没有接入任何外部 gateway 调用客户端，整个外部调用链处于物理断开状态。
implementation_gap 从 1 上调为 2：不仅 rollback runbook 缺自动化闭环，gateway consumer 的核心 applier 也是 mock 实现，且未提供可替换的真实实现。
evidence_gap 从 3 下调为 1：原先将 G1-G3 的共享环境证据也计入了 evidence_gap，但 G1-G3 实际上已在本地和 tksea 补做，仅剩 G4 证据缺失。

4. 关键调用链路核查（supply-intelligence 的外部集成链路：定义→装配→调用→入口）

4.1 链路定义（Definition）

文件：internal/gatewayconsumer/service.go
定义：type Service struct { ... applier func(context.Context, domain.PackageChangeEvent) (GatewayApplyResult, error) ... }
接口设计：通过 SetApplier 方法允许注入外部 applier 实现。接口设计合理，具备可扩展性。

4.2 链路装配（Assembly / Wiring）

文件：internal/app/app.go:68-70

代码：

gatewayConsumerService := gatewayconsumer.NewService(repo)
gatewayPoller := poller.NewGatewayPackagePoller(gatewayConsumerService)
gatewayRuntime := poller.NewRuntime(gatewayPoller, time.Second)

审查结论：未调用 SetApplier 注入任何真实外部 gateway 客户端。NewService(repo) 使用的是默认 mock applier。

4.3 链路调用（Invocation）

文件：internal/gatewayconsumer/service.go:146
代码：attempt, err := s.applier(ctx, event)

审查结论：实际执行的是 NewService 中硬编码的 mock 函数：

applier: func(_ context.Context, event domain.PackageChangeEvent) (GatewayApplyResult, error) {
    if strings.Contains(strings.ToLower(event.Model), "fail") {
        return GatewayApplyResult{AckResult: domain.GatewayAckResultFailed, ...}, nil
    }
    return GatewayApplyResult{AckResult: domain.GatewayAckResultApplied, Detail: "applied to gateway snapshot"}, nil
}

该 mock 不发起任何 HTTP 请求、不调用任何外部 RPC、不写任何下游系统。它只是根据 model 名称是否包含 "fail" 来模拟成功或失败。

4.4 链路入口（Entrypoint）

HTTP API：POST /internal/supply-intelligence/gateway/consume-once
入口存在且可用，但入口背后的处理逻辑当前仅连接本地 mock，未连接真实远端 gateway。

4.5 相关组件核查

cmd/sub2api-bridge/main.go：这是一个独立的反向桥接进程。它从 supply-intelligence 的 consume-once 接口拉取事件，再写入自己的 bridge log。它不是 supply-intelligence 主动 apply/ack 到下游 gateway 的链路，不能作为 G4 的合格证据。
internal/integration/platform.go：HTTP client 仅用于 discovery 和 probe（向上游供应商 OpenAI/Anthropic 查询模型列表和健康状态），与下游 gateway 无关。

4.6 调用链核查总结

环节	状态	说明
定义（applier 接口）	通过	已定义可注入的 applier 函数类型
装配（buildApp）	未通过	未注入真实 applier，使用默认 mock
调用（ConsumeOnce）	未通过	仅调用本地 mock，无外部网络交互
入口（HTTP API）	通过	入口存在，但后端未接通外部
下游侧留痕	未通过	无任何下游系统被调用，自然无留痕

结论：supply-intelligence 当前不具备完成 G4 的技术基础。publish → consume → ack 链路在代码层面闭合，但 apply 步骤完全在本地模拟完成，没有真实接通到外部 gateway。

5. G4 验证证据标准（什么样的证据才算合格）

G4 目标：证明当前共享环境不是仅本地 apply/ack 语义，而是已触达真实远端 gateway 路径。

5.1 合格证据（至少满足以下之一）

下游真实 gateway 侧日志/审计记录，能对应本次 EVENT_ID
- 必须包含：时间戳、EVENT_ID、请求来源 IP/服务名、处理结果（成功/失败/重试）
- 日志必须来自下游系统，而非 supply-intelligence 本仓库 stdout
下游真实 gateway 侧状态变化截图/导出
- 必须包含：操作前状态、操作后状态、EVENT_ID 关联信息、操作时间
- 必须能从下游系统的管理界面或数据库导出中追溯到本次事件
下游接口 trace / request-id / event-id 对账记录
- 必须包含：supply-intelligence 发出的 request-id 或 event-id、下游系统返回的 trace-id、两者的映射关系
- 对账记录必须覆盖 "发送 → 接收 → 确认" 完整闭环

5.2 不合格证据（明确定义）

只有本仓库内部 consume-once 输出（JSON 响应）
只有本地 snapshot 更新（UpsertGatewayAppliedSnapshot 结果）
只有 supply-intelligence 自身的 PostgreSQL 状态变更记录
没有任何下游侧（sub2api / tokens-reef / gateway）留痕
cmd/sub2api-bridge 的 bridge log（这是反向拉取，不是 supply-intelligence 主动 apply 到下游 gateway 的证据）

5.3 G4 证据归档格式要求

文件：reports/production/evidence-shared-<env>-<date>/04_remote_gateway_reconcile.txt
必须包含：
- 取证时间戳
- EVENT_ID
- 下游系统名称（如 sub2api / tokens-reef）
- 日志链接 / trace ID / request ID / 截图存放路径
- 责任人签名

6. 问题清单

Critical

C1. Gateway Consumer Applier 当前为 Mock 实现，未接入任何真实外部 Gateway

证据：internal/gatewayconsumer/service.go:107-112 默认 applier 为本地 simulator
影响：所有 consume-once 的 "applied" 状态均为本地模拟，不代表任何真实下游 gateway 已接收并处理事件。若此时上线，将导致生产环境中 supply-intelligence 与真实 gateway 状态长期不一致，形成 "假同步"。
建议：
1. Engineering 实现真实的外部 gateway applier（如 Sub2API HTTP Client、tokens-reef Client）
2. 在 buildApp 中根据环境变量或配置注入真实 applier
3. 真实 applier 需实现：认证、幂等发送、重试、超时、错误分类（retryable vs terminal）

C2. BuildApp 装配层未注入真实外部 Gateway 客户端

证据：internal/app/app.go:68-70 仅调用 gatewayconsumer.NewService(repo)，未调用 SetApplier
影响：即使存在真实 applier 实现，当前装配代码也不会使用它。
建议：修改 buildApp，增加基于配置的真实 applier 装配逻辑（如 GATEWAY_APPLIER_IMPL=sub2api 时注入 Sub2APIApplier）。

Important

I1. 缺乏真实下游 Gateway 的接口契约与认证设计文档

证据：代码仓库中无 sub2api/tokens-reef 的接口定义、OpenAPI 规格、或认证流程文档
影响：无法评估外部调用的安全性（API Key 管理、TLS、mTLS、请求签名等）
建议：Security 与下游接口责任人共同输出接口契约文档；DevOps 确认下游服务在共享预发环境的可访问性

I2. tksea 已部署但 sub2api 未配置集成，DevOps 侧未就绪

证据：QA 报告 7.3 节明确记录 "sub2api 尚未配置 supply-intelligence 集成"
影响：即使 Engineering 完成代码修改，也无法在 tksea 完成端到端验证
建议：DevOps 明确 sub2api 集成排期；在集成就绪后优先在 tksea 补做 G4

I3. sub2api-bridge 架构方向需澄清

证据：cmd/sub2api-bridge/main.go 是一个独立进程，反向 consume supply-intelligence 的事件
影响：当前架构是 "supply-intelligence 被动被拉取"，但 G4 要求证明 "已触达真实远端 gateway"。如果最终架构就是被动被拉取，则 G4 证据应体现为 sub2api 侧的 consume 日志；如果最终架构应是 supply-intelligence 主动推送，则当前 bridge 只是临时方案。
建议：架构评审确认 gateway 集成模式（push vs pull）

Minor

M1. runtime-status consumer 参数 contract drift

证据：internal/httpapi/server.go:400-411 与 internal/repository/postgres.go:614-622
影响：当前单 consumer 场景可接受；多 consumer 场景会导致计数不准确
建议：在下一运维硬化迭代中补齐

7. 升级建议（是否需要 Security / DevOps）

必须升级 Security

原因：真实外部 gateway applier 的实现涉及 API Key / Token 管理、TLS 配置、请求签名、下游认证流程。当前代码中完全缺失这些内容。
动作：Security 审查外部 gateway 接口的认证与鉴权设计；审查 API Key 的存储方式（环境变量 vs Secret Manager vs Vault）。

必须升级 DevOps

原因：tksea 环境已部署 supply-intelligence，但 sub2api 尚未配置集成。没有下游服务的配合，无法完成 G4。
动作：
1. DevOps 确认 sub2api / tokens-reef 在 tksea 的部署状态与可访问性
2. DevOps 提供共享预发环境的下游服务 BASE_URL、认证凭据、日志查询接口
3. DevOps 与 Engineering 联调 supply-intelligence → sub2api 的端到端连通性

建议升级 Engineering Lead

原因：G4 缺口不仅是"缺证据"，而是"缺实现"。需要 Engineering 排期实现真实 applier 与装配逻辑。
动作：将 G4 实现纳入 Sprint 计划，作为生产上线的 blocker。

8. 生产门禁复核结论

当前状态

代码级主链路：APPROVED（publish / consume / ack / admission-state / unauthorized / retry / rollback 均通过自动化测试）
共享环境 G1-G3：APPROVED（本地 + tksea 双环境已留痕）
共享环境 G4：BLOCKED（不具备技术基础 + 无证据）
整体生产门禁：REQUEST_CHANGES

放行条件（必须全部满足）

Engineering 实现真实的外部 gateway applier（非 mock）
buildApp 或对应装配代码注入真实 applier（支持环境切换）
DevOps 完成 supply-intelligence 与 sub2api / tokens-reef 的共享环境集成
在共享预发/灰度环境执行至少一次完整 publish → consume → apply → ack 闭环，并获取下游侧留痕证据
证据满足第 5 节定义的 G4 验证标准
QA 对证据包进行复核并归档

结论

当前 supply-intelligence 的 G4 缺口本质是 implementation_gap + call_chain_gap，而非单纯的 evidence_gap。在真实外部 gateway applier 实现并部署到共享环境之前，不得将生产门禁升级为 APPROVED。

9. 自检清单

已读取 QA 报告和执行板
结论基于真实文件或已知事实
对关键能力检查过真实调用链（已逐行审查 gatewayconsumer/service.go、app/app.go、integration/platform.go、sub2api-bridge/main.go）
已明确指出是否可进入下一阶段（不可，需先补齐 G4 实现与证据）
所有 Critical/Important 问题都有证据、影响和建议
没有用"基本没问题"替代结构化结论

报告生成时间：2026-05-10T19:22:00+08:00 审查人：QA（质量经理）

14 KiB Raw Permalink Blame History Unescape Escape