niuniu/supply-intelligence
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
supply-intelligence/tech/GATEWAY_CONSUMER_DECISION_2026-05.md
Your Name afdbea6fb5 feat: bootstrap supply intelligence baseline
2026-05-07 10:16:46 +08:00

6.8 KiB
Raw Permalink Blame History

Supply-Intelligence 首期消费闭环决议（2026-05）

状态：当前有效决议 作用：消除“只有接口定义，没有首期真实消费方与调用落点”的设计歧义。 适用范围：/home/long/project/立交桥/projects/supply-intelligence/ 下当前收敛规划包。 真源索引：本决议受 /home/long/project/立交桥/projects/supply-intelligence/tech/CURRENT_SOURCE_OF_TRUTH_2026-05.md 纳管；若与历史草案冲突，以真源索引定义的优先级解释。

1. 结论

首期默认消费闭环采用：

  • package 发布链路：gateway 作为首期默认消费方，使用 pull package-changes + ack 机制完成闭环
  • account 状态链路：立交桥 / supply-api 内部主链路直接读取 routing-state 或等价 snapshot，不通过 gateway event ack 闭环

这意味着必须明确区分两类链路：

  1. 账号可路由状态链路：查询型消费
  2. package 发布生效链路：事件型消费

不得混用以下错误口径：

  • published = 已进入 gateway 路由
  • active package = 下游已消费成功

正确口径：

  • published 仅表示 supply-intelligence 侧已完成运营确认与 package 激活
  • 只有 gateway 对 package event 完成 ack(result=applied) 后，才能宣称“已被 gateway 消费生效”

2. 首期默认路径

2.1 账号状态链路

生产主链路：

  1. probe 执行
  2. evaluator 分类为 success / explicit_failure / inconclusive
  3. state machine 生成状态迁移
  4. 写回 supply account 健康状态与审计
  5. 立交桥内部路由决策读取 GET /internal/supply-intelligence/accounts/{account_id}/routing-state

说明：

  • 这是查询型读取，不需要 event ack。
  • 若调用方读取失败，不回滚 supply-intelligence 已落库状态，只记录消费侧问题。

2.2 package 发布闭环

生产主链路：

  1. 运营确认发布 candidate
  2. package draft -> active
  3. candidate test_passed -> published
  4. 写入 gateway_package_events
  5. gateway 拉取 GET /internal/supply-intelligence/gateway/package-changes?cursor=...
  6. gateway 应用变更到自身路由/缓存
  7. gateway 调用 POST /internal/supply-intelligence/gateway/package-changes/{event_id}/ack
  8. gateway_sync_status 变为 applied 或 failed

说明：

  • 这是事件型闭环。
  • pending 表示 supply-intelligence 已发布，但 gateway 尚未确认消费。
  • failed 表示 gateway 已消费尝试但未成功，需要运营或工程介入。

3. 为什么不用首期强耦合同步 RPC

首期明确不采用：

  • “发布时同步调用 gateway 管理接口，成功后才算发布成功”

原因：

  1. 这会把 supply-intelligence 与 gateway 强耦合在单次事务中
  2. 会把下游暂时不可用放大成上游发布不可用
  3. 不符合当前“立交桥延伸项目、简洁架构、最小生产闭环”的收敛目标

因此首期选择：

  • 上游发布成功与下游消费成功解耦
  • 用 event + ack 明确消费状态

4. 首期真实代码落点（实现约束）

以下是首期必须存在的真实调用落点；只有接口定义不算完成。

4.1 supply-intelligence / supply-api 侧

  • /home/long/project/立交桥/supply-api/internal/supplyintelligence/publish/service.go
    • PublishCandidate(...)
    • AppendGatewayPackageEvent(...)
  • /home/long/project/立交桥/supply-api/internal/supplyintelligence/integration/http_internal.go
    • GetAccountRoutingState(...)
    • ListGatewayPackageChanges(...)
    • AckGatewayPackageChange(...)
  • /home/long/project/立交桥/supply-api/internal/supplyintelligence/repository/gateway_repo.go
    • InsertGatewayPackageEventTx(...)
    • AckGatewayPackageEventTx(...)

4.2 gateway 侧（首期必须由消费方实现的真实入口）

  • 必须存在一个实际消费入口，完成：
    1. 周期拉取 package changes
    2. 应用变更
    3. 回写 ack
  • 若 gateway 已有内部刷新链路，可复用，但必须补齐 ack 回写
  • 若 gateway 无现成入口，则新增最小 poller；禁止为了这件事引入 MQ/Kafka/新总线

5. QA 必查真实调用链路

QA 编码后必须至少验证以下四层：

链路 A：账号状态查询型消费

  • 定义：GetAccountRoutingState
  • 装配：internal route mounted
  • 调用：立交桥 / supply-api 实际路由决策点调用该接口或等价函数
  • 入口：真实请求/真实调用路径可达

链路 B：package 事件发布

  • 定义：AppendGatewayPackageEvent
  • 装配：publish 流程内注入 repository
  • 调用：PublishCandidate 成功路径真实调用写事件
  • 入口：运营确认发布入口可真实触达该调用链

链路 C：gateway 拉取消费

  • 定义：ListGatewayPackageChanges
  • 装配：internal route mounted
  • 调用：gateway 真实 poller / 既有刷新链调用
  • 入口：消费方真实任务/刷新入口存在，不是只留 TODO

链路 D：gateway ack 回写

  • 定义：AckGatewayPackageChange
  • 装配：ack route mounted
  • 调用：gateway 应用成功/失败后真实回写
  • 入口：event 状态确实从 pending -> applied|failed

6. published / applied 语义约束

状态含义必须统一：

  • candidate published：上游已完成运营确认
  • package active：上游已允许被消费
  • gateway sync pending：下游尚未确认
  • gateway sync applied：下游已确认消费并应用
  • gateway sync failed：下游消费尝试失败

禁止：

  • UI 文案把 published 写成“已进路由”
  • 测试把 package active 当成“下游已完成同步”
  • QA 把 event 表存在当成“消费闭环成立”

7. 与 NewAPI / Sub2API 的边界

首期不要求 NewAPI / Sub2API 实现 event ack 闭环。 它们的首期边界为：

  • 只读拉取账号状态
  • 只读拉取已允许暴露的模型/结果

即：

  • gateway 是首期必须闭环的事件型消费方
  • NewAPI / Sub2API 是首期只读适配消费方

8. 门控要求

在下一轮 QA 设计审查或编码后审查中，若以下任一项缺失，则不得给 APPROVED：

  1. 没有明确的首期默认消费方
  2. 没有明确区分查询型链路与事件型链路
  3. 没有明确 published != applied
  4. 没有真实代码落点要求
  5. 没有 ack 回写要求

9. 对旧文档的覆盖关系

本决议用于覆盖旧文档中以下错误或过时口径：

  • “调用 gateway 管理接口热更新即完成闭环”
  • “上架成功即下游已生效”
  • “gateway 会消费”但没有实际消费者与 ack 机制

如与以下文件冲突，以本决议为准：

  • /home/long/project/立交桥/projects/supply-intelligence/specs/功能清单.md
  • /home/long/project/立交桥/projects/supply-intelligence/tech/INTERFACE.md
  • /home/long/project/立交桥/projects/supply-intelligence/tech/HLD.md
  • /home/long/project/立交桥/projects/supply-intelligence/tech/BASELINE_TECHLEAD_V2.md（若后续未同步更新相应段落，应以本决议补充解释）
Reference in New Issue View Git Blame Copy Permalink