155 lines
5.2 KiB
Markdown
155 lines
5.2 KiB
Markdown
|
# B2/B3/B4 实施规格（2026-05-07）
|
|||
|
|
|
|||
|
|
状态：当前有效
|
|||
|
|
范围：candidate 状态收敛、publish 事务闭环、admission-state API 真正接线
|
|||
|
|
真源：
|
|||
|
|
- tech/CURRENT_SOURCE_OF_TRUTH_2026-05.md
|
|||
|
|
- tech/BASELINE_TECHLEAD_V2.md
|
|||
|
|
- tech/GATEWAY_CONSUMER_DECISION_2026-05.md
|
|||
|
|
|
|||
|
|
## 1. 目标
|
|||
|
|
|
|||
|
|
把 supply-intelligence 从“各子模块最小骨架存在”推进到“candidate -> admission -> draft package -> publish -> gateway sync state -> admission-state 查询”这一条真实生产闭环更接近可验状态。
|
|||
|
|
|
|||
|
|
本轮不扩范围到独立平台化、重基础设施、自动注册，只做当前收口板 B2/B3/B4。
|
|||
|
|
|
|||
|
|
## 2. 当前已验证现状
|
|||
|
|
|
|||
|
|
1. `go test ./...` 当前通过。
|
|||
|
|
2. `internal/domain/types.go` 中 candidate 状态枚举已不包含 `pending_admission` / `admitted`。
|
|||
|
|
3. `internal/httpapi/server.go` 的 `parseDiscoveryCandidateStatus()` 已只接受：
|
|||
|
|
- discovered
|
|||
|
|
- testing
|
|||
|
|
- test_passed
|
|||
|
|
- test_failed
|
|||
|
|
- retry_pending
|
|||
|
|
- ignored
|
|||
|
|
- published
|
|||
|
|
- deprecated
|
|||
|
|
- closed
|
|||
|
|
4. `internal/httpapi/server.go` 已存在 `/internal/supply-intelligence/models/{platform}/{model}/admission-state` 路由与 handler。
|
|||
|
|
5. `internal/publish/service.go` 目前只支持“追加 package published event”，还不是“运营确认上架事务”。
|
|||
|
|
6. `internal/admission/service.go` 在测试通过后会创建/更新 draft package，并把 candidate 置为 `test_passed`。
|
|||
|
|
7. `internal/httpapi/admission_state_api_test.go` 目前只验证 candidate/package/event 聚合读取，不验证真实 publish 事务。
|
|||
|
|
|
|||
|
|
## 3. 本轮必须收敛的缺口
|
|||
|
|
|
|||
|
|
### B2. candidate 状态与 admission 流转
|
|||
|
|
|
|||
|
|
必须满足：
|
|||
|
|
- admission 只允许 `discovered` / `retry_pending` 进入执行。
|
|||
|
|
- admission 执行开始后置为 `testing`。
|
|||
|
|
- admission 失败后置为 `test_failed` 或 `retry_pending`（本轮沿用现状失败归 `test_failed`）。
|
|||
|
|
- admission 成功后置为 `test_passed`。
|
|||
|
|
- publish 成功后 candidate 必须从 `test_passed` -> `published`。
|
|||
|
|
- 不允许重新引入旧状态口径。
|
|||
|
|
|
|||
|
|
### B3. publish 事务闭环
|
|||
|
|
|
|||
|
|
必须新增真实语义：
|
|||
|
|
- 输入不再只是 event append 所需字段。
|
|||
|
|
- 以 `platform + model`（必要时 package/candidate）为主键读取当前真实状态。
|
|||
|
|
- 仅当 candidate 最新状态为 `test_passed` 且 package 当前为 `draft` 时允许发布。
|
|||
|
|
- 发布动作要同时完成：
|
|||
|
|
1. package `draft -> active`
|
|||
|
|
2. candidate `test_passed -> published`
|
|||
|
|
3. 追加 `supply_package_published` event，默认 `gateway_sync_status=pending`
|
|||
|
|
- 明确 `published != applied`：gateway applied 仍由 ack 驱动。
|
|||
|
|
|
|||
|
|
### B4. admission-state API
|
|||
|
|
|
|||
|
|
必须返回当前组合真相：
|
|||
|
|
- latest candidate truth
|
|||
|
|
- current package truth
|
|||
|
|
- latest matching package event truth
|
|||
|
|
- gateway sync status
|
|||
|
|
|
|||
|
|
并在 publish 事务跑完后能够体现：
|
|||
|
|
- candidate_status = published
|
|||
|
|
- package_status = active
|
|||
|
|
- gateway_sync_status = pending（直到 ack）
|
|||
|
|
|
|||
|
|
## 4. 最小改动设计
|
|||
|
|
|
|||
|
|
### 4.1 repository / app 适配层
|
|||
|
|
|
|||
|
|
尽量不改 repository 主接口的大结构，只补 publish service 所需最小能力，优先复用已有：
|
|||
|
|
- `GetLatestDiscoveryCandidateContext()`
|
|||
|
|
- `GetSupplyPackage()`
|
|||
|
|
- `UpsertSupplyPackage()`
|
|||
|
|
- `UpdateCandidateStatus()`
|
|||
|
|
- `AppendPackageEventContext()`
|
|||
|
|
|
|||
|
|
如 publish 包直接依赖 domain/repository 成本更低，可在 publish 内定义更完整 repo interface，再由现有 repository.Repository 满足。
|
|||
|
|
|
|||
|
|
### 4.2 publish service 新增主入口
|
|||
|
|
|
|||
|
|
建议新增：
|
|||
|
|
- `PublishDraft(ctx, PublishDraftInput) (PublishDraftOutput, error)`
|
|||
|
|
|
|||
|
|
输入最小字段：
|
|||
|
|
- event_id
|
|||
|
|
- platform
|
|||
|
|
- model
|
|||
|
|
- actor/source（可选；本轮如无真实审计先留空）
|
|||
|
|
- occurred_at（可选）
|
|||
|
|
|
|||
|
|
输出最小字段：
|
|||
|
|
- candidate
|
|||
|
|
- package
|
|||
|
|
- event
|
|||
|
|
- gateway_sync_status
|
|||
|
|
|
|||
|
|
保留 `RecordPackagePublished()` 兼容测试/已有接口，但 HTTP 主入口要逐步切换为真正发布语义，而不是“外部直接塞 event”。
|
|||
|
|
|
|||
|
|
### 4.3 HTTP API
|
|||
|
|
|
|||
|
|
当前 `/internal/supply-intelligence/publish/package-event` 若继续存在，本轮将其语义提升为“确认发布 draft package”，不再允许脱离 candidate/package 真相直接伪造 event。
|
|||
|
|
|
|||
|
|
请求体建议最小化为：
|
|||
|
|
- event_id
|
|||
|
|
- platform
|
|||
|
|
- model
|
|||
|
|
- occurred_at
|
|||
|
|
|
|||
|
|
如果保留 package_id/version 也应以服务端真相为准，不信任调用方覆盖 package 当前状态。
|
|||
|
|
|
|||
|
|
## 5. 验证标准
|
|||
|
|
|
|||
|
|
必须新增/更新测试覆盖：
|
|||
|
|
|
|||
|
|
1. publish 成功：
|
|||
|
|
- candidate `test_passed -> published`
|
|||
|
|
- package `draft -> active`
|
|||
|
|
- event appended with pending sync
|
|||
|
|
|
|||
|
|
2. publish 拒绝：
|
|||
|
|
- candidate 不是 `test_passed` 时拒绝
|
|||
|
|
- package 不是 `draft` 时拒绝
|
|||
|
|
- candidate/package 不存在时拒绝
|
|||
|
|
|
|||
|
|
3. admission-state：
|
|||
|
|
- publish 后查询可看到 `published + active + pending`
|
|||
|
|
- ack 后查询可看到 `applied/failed`
|
|||
|
|
|
|||
|
|
4. 全量验证：
|
|||
|
|
- `go test ./...`
|
|||
|
|
|
|||
|
|
## 6. 不做项
|
|||
|
|
|
|||
|
|
本轮明确不做：
|
|||
|
|
- 审计表完整补齐
|
|||
|
|
- actor/审批链完整产品化
|
|||
|
|
- DB 事务级锁语义重构
|
|||
|
|
- gateway 实际远端集成
|
|||
|
|
- auto-supply / deep registration
|
|||
|
|
|
|||
|
|
## 7. 完成定义
|
|||
|
|
|
|||
|
|
仅当以下同时成立，B2/B3/B4 才能算完成：
|
|||
|
|
- 代码不再只有“event append 记录器”语义
|
|||
|
|
- publish 真正驱动 candidate/package 状态变化
|
|||
|
|
- admission-state 能反映 publish 后组合真相
|
|||
|
|
- 新增测试通过
|
|||
|
|
- `go test ./...` 通过
|