supply-intelligence/tech/PRODUCTION_P0_P1_P2_BOARD_2026-05-08.md

# Supply-Intelligence 生产上线 P0/P1/P2 收敛板（2026-05-08）

状态：当前有效
仓库：`/home/long/project/立交桥/projects/supply-intelligence`
目标：把当前已完成的 B2/B3/B4 实现闭环，继续推进到“可生产上线判定”所需的最小生产门禁。

## 0. 当前结论

当前结论：REQUEST_CHANGES

已完成事实：
- publish 已不再只是 event append；已驱动 candidate `test_passed -> published`、package `draft -> active`
- admission-state 已能反映 publish 后组合态以及 ack 后 gateway_sync_status 变化
- 相关 targeted tests 已通过：
  - `go test ./internal/publish ./internal/httpapi ./internal/app ./internal/repository`

仍不能宣称可生产上线的原因：
- PostgreSQL 持久化路径与内存仓储语义未收敛，当前 publish 主链路缺少数据库事务/并发保护证据
- 发布幂等、重复发布、冲突发布、ack 重放/乱序等生产失败路径证据不足
- 缺少基于 PostgreSQL 的真实端到端链路验证与上线证据包

## 1. 已复核事实基线

### 1.1 代码级事实
- `internal/publish/service.go` 已存在 `PublishDraft(ctx, PublishDraftInput)` 主入口
- `internal/httpapi/server.go` 的 `/internal/supply-intelligence/publish/package-event` 已切到真实发布语义
- `internal/httpapi/admission_state_api_test.go` 已验证 publish 后 `published + active + pending` 以及 ack 后 `applied`
- `internal/gatewayconsumer/service.go` 已具备最小 `consume-once -> ack -> snapshot` 路径

### 1.2 当前生产差距（实测/读码得出）
1. `internal/repository/postgres.go`
   - `AppendPackageEventContext()` 仍是 `ON CONFLICT (event_id) DO NOTHING`，但上层未把冲突解释为幂等成功/重复请求拒绝的明确产品语义
   - `UpdateCandidateStatus()`、`UpsertSupplyPackage()`、`AppendPackageEventContext()` 彼此独立执行，未处于同一数据库事务
   - 全文件未见 `Begin/Commit/Rollback/FOR UPDATE`，说明 publish 主链路当前没有 PostgreSQL 事务级一致性保护
2. 目前通过的测试主要基于内存仓储；尚未看到 PostgreSQL 集成测试证明：
   - 并发双发布只会成功一次
   - 重复 event_id 的幂等语义稳定
   - package/candidate/event 在异常中不会出现部分提交
3. 仓库虽已有 `docker-compose.yml`、`migrations/`、`internal/repository/postgres.go`，但未形成 production gate 所需的真实 E2E 证据链

## 2. 分级任务板

## P0. 生产阻塞项（不上这些，不能判定可上线）

### P0-1. PostgreSQL 发布事务原子化
- Owner：Engineer
- 目标：把 publish 主链路收敛为单事务提交，而不是多次独立写入
- 代码落点：
  - `internal/repository/interfaces.go`
  - `internal/repository/postgres.go`
  - `internal/publish/service.go`
  - 可能新增 `internal/repository/postgres_publish_tx_test.go`
- 必须达成：
  - candidate 状态更新、package 状态更新、event append 在同一 DB 事务中完成
  - 任一步失败时整体回滚
  - 明确重复 publish 的返回语义（幂等成功或冲突失败，必须固定）
- 验证：
  - `go test ./internal/publish ./internal/repository`
  - 至少一条 PostgreSQL 集成测试证明回滚语义
- 当前状态：**completed** — `PostgresRepository.PublishPackageAtomically` 已实现 `BEGIN/UPDATE/UPSERT/INSERT/COMMIT`，`TestPostgresPublishPackageAtomicallyRollsBackOnDuplicateEvent` 通过

### P0-2. 重复发布/并发发布保护
- Owner：Engineer
- 目标：防止同一 `platform+model` 或同一 draft package 被重复发布
- 代码落点：
  - `internal/publish/service.go`
  - `internal/repository/postgres.go`
  - `internal/repository/memory.go`
  - 相关 `*_test.go`
- 必须达成：
  - candidate 已 `published` 或 package 已 `active` 时再次发布，有明确拒绝/幂等语义
  - 并发双发布测试下，最终只能有一个成功结果
  - event 不可重复污染 downstream queue
- 验证：
  - 并发测试 / 重复调用测试通过
- 当前状态：**completed** — 已补充 `TestPostgresPublishPackageAtomicallyConcurrentDoublePublish`，验证并发双发布时仅一个成功、无脏数据

### P0-3. PostgreSQL 真实链路 E2E
- Owner：QA
- 目标：在 PostgreSQL 环境下验证最小生产主链路
- 链路：candidate -> admission(test_passed) -> publish -> package-changes -> consume-once -> ack -> admission-state
- 代码/资产落点：
  - 现有 `docker-compose.yml`
  - `migrations/`
  - 新增 `internal/...` PostgreSQL 集成测试或 `scripts/` 验证脚本
- 必须达成：
  - 不是仅 `go test ./...`，而是真实 PostgreSQL 状态可读回
  - admission-state 能反映 pending/applied/failed
  - gateway snapshot 与 event ack 状态一致
- 验证：
  - 可复现命令 + 实际输出
- 当前状态：**completed** — `TestPostgresE2EPublishConsumeAckAdmissionState` 已覆盖完整链路，`TestPostgresE2EPublishConsumeAckAdmissionStateRequiresAuthorizedConsumer` 验证未授权消费过滤

## P1. 上线前必须补齐项（P0 完成后，仍建议上线前补齐）

### P1-1. 失败补偿与错误语义收敛
- Owner：TechLead -> Engineer
- 目标：补明确的失败模型，而不是只靠 internal_error
- 范围：
  - 发布冲突
  - event 已存在
  - ack 重放
  - ack 目标不存在
  - consumer apply failed 的重试/终态语义
- 交付：错误码/状态机/handler 响应语义收敛
- 验证：针对失败路径的 HTTP/API 测试
- 当前状态：**completed** — 已有明确错误码（`ErrInvalidPublishInput`/`ErrCandidateNotPublishable`/`ErrPackageNotPublishable`/`ErrDuplicatePublishRequest`/`ErrPackageAlreadyPublished`）、重试策略（1m/5m/15m，最多2次）、终态定义（applied/pending/failed），consumer 测试覆盖所有失败路径

### P1-2. gateway consumer 生产约束验证
- Owner：QA
- 目标：验证 gateway 侧不是“最小骨架可跑”，而是生产语义可解释
- 必查：
  - 未授权 account 过滤
  - pending-only 消费
  - apply failed 后状态可见
  - snapshot 与 event ack 不漂移
- 验证：definition -> assembly -> call -> entry 四层核查 + targeted tests
- 当前状态：**completed** — `TestServiceConsumeOnceSkipsUnauthorizedEvents`、`TestPostgresE2EPublishConsumeAckAdmissionStateRequiresAuthorizedConsumer`、`TestServiceConsumeOnceFailedDoesNotDriftSnapshot` 等已覆盖

### P1-3. 上线证据包
- Owner：XL
- 目标：形成真正可用于上线判定的证据包
- 必须包含：
  - 通过命令
  - 覆盖的关键链路
  - 明确未覆盖项
  - 可宣称项 / 不可宣称项
  - 回滚方式
- 当前状态：**completed** — 已归档 `reports/production/SHARED_ENV_EVIDENCE_RUN_2026-05-09.md` 及 tksea 版本，含 G1-G3 证据

## P2. 可上线后补项（不阻塞首版上线判定）

### P2-1. actor / 审批链 / 审计增强
- Owner：PM -> TechLead -> Engineer
- 说明：当前 publish 语义可先无完整审批产品化，但上线后应补 actor、审批来源、审计追踪
- 当前状态：pending

### P2-2. 真实远端 gateway 集成
- Owner：DevOps/Engineer
- 说明：当前 `consume-once` 仍偏本地 apply/ack 语义，后续应补真实下游系统契约
- 当前状态：**conditional_debt** — 首版上线允许携带，必须在第一个迭代周期内补清（建议 2 周内）

### P2-3. 观测与运行基线
- Owner：DevOps
- 说明：补指标、告警、日志字段、发布/ack 异常观测面
- 当前状态：pending

## 3. 推荐执行顺序
1. P0-1 PostgreSQL 发布事务原子化
2. P0-2 重复发布/并发发布保护
3. P0-3 PostgreSQL 真实链路 E2E
4. P1-1 / P1-2
5. P1-3 上线证据包

## 4. 明确禁止的错误结论
- 不得把内存仓储测试通过等同于 PostgreSQL 生产可用
- 不得把 `published` 等同于 `gateway applied`
- 不得把 `ON CONFLICT DO NOTHING` 视为已完成幂等设计
- 不得把缺少事务保护的多次独立写入视为“发布事务已完成”
- 不得在缺少 PostgreSQL E2E 证据时宣称可上线