sub2api-cn-relay-manager/docs/EXECUTION_BOARD.md

# sub2api-cn-relay-manager 执行板

日期：2026-05-13
当前 Gate：REQUEST_CHANGES
目标：实现 implementation plan 全量能力，达成独立控制面、零侵入宿主、一键导入国产模型，并补齐回滚/对账/HTTP API/交付物。

## 当前真实状态

模块完成 gate（新增执行要求，后续每个大模块都必须执行）：
- 仅 `go test` 通过不算完成；每次完成大模块后，必须补做：
  1. 两阶段 review（先对规划/设计文档做实现对齐检查，再做代码质量 review）
  2. execution board 当前状态同步
  3. 若发现实现/设计漂移，优先修正文档结论或回退模块状态，不维持虚假 `COMPLETED`
- 本板从本次起按上述 gate 维护。

已完成：
- 项目骨架与配置加载
- SQLite 最小状态库（hosts/packs/providers）
- SQLite 运行态状态库扩展（import_batches / items / managed_resources / probe_results / access_closure_records / reconcile_runs）
- sub2api HostAdapter 基础创建/探测能力
- HostAdapter 删除能力（group/channel/account；plan 接口已补）
- HostAdapter 资源枚举能力（groups/channels/plans/accounts）
- import strict 模式自动回滚已接入
- 手动 rollback CLI（`rollback-provider`）已接入，支持按 provider 名称规则回收 group/channel/plan/accounts
- pack 目录装载与 checksum/schema 校验
- 正式 pack install 生命周期已接入：支持 zip/目录装载、宿主版本兼容校验、pack/provider 元数据持久化、CLI `install-pack`
- CLI `import-provider` 导入闭环已接入 SQLite 运行态持久化（host/pack/provider/import/probe/access）
- CLI `preview-provider` 预检查入口
- 最小 HTTP 控制面已接入：admin token 鉴权 + `/api/packs/install` + `/api/providers/{providerID}/preview-import` + `/api/providers/{providerID}/import` + `/api/import-batches/{batchID}` + `/api/providers/{providerID}/status` + `/api/providers/{providerID}/resources` + `/api/providers/{providerID}/access/status` + `/api/providers/{providerID}/rollback` + `/api/providers/{providerID}/reconcile`
- preview 已接入宿主资源快照查询
- 账号探测与 `/v1/models` 网关访问验证

未完成的关键事实：
- 状态库已接入 `import-provider` 运行链并可持久化 host/pack/provider/import/probe/access；最小 HTTP 控制面已补齐 batch detail / provider status / resources / access status / rollback / reconcile，OpenAPI 草案已同步扩展
- preview/import/rollback/reconcile 已有 CLI 与最小 HTTP 入口，但仍缺少 hosts 管理面与更完整的批次/对账操作文档输出
- 宿主资源枚举已实现，但尚未对真实 sub2api 版本做兼容性实测
- 最小 reconcile / drift detection 已接入，当前实现仍是 `internal/provision/batch_detail_and_reconcile_service.go` 内联版本，但已补齐对最新 batch 的 account smoke probe 重跑、access closure 复检与 reconcile summary 持久化；状态仍未完全对齐 implementation plan 目标中的 `internal/reconcile/*` 结构，且真实宿主兼容性实测未完成
- OpenAPI 草案已覆盖 status/resources/access-status，但仍未收口 hosts 契约与生产级文档细节
- 无 scheduler/jobs
- 已补齐 Dockerfile / compose / .env.example / deployment 文档，并新增 distribution smoke test；但尚无真实容器启动 E2E 执行记录

## P0（必须先完成）

### P0-1 状态库扩展并接入运行链
- 状态：COMPLETED（schema/repo、`import-provider` 运行链消费、`batch detail` / `provider status` / `resources` / `access status` / `reconcile` 查询面均已接入）
- 目标：补齐 implementation plan 所需核心表与 repo
- 范围：`import_batches`、`import_batch_items`、`managed_resources`、`probe_results`、`access_closure_records`、`reconcile_runs`
- 验证：`go test ./tests/integration -run 'TestStore(Runtime|Init)' -count=1`
- 完成判据：表存在、约束有效、事务回滚有效、repo 可写入读取，并被运行链消费

### P0-2 import preview + naming
- 目标：导入前可输出 create/reuse/conflict，不盲写宿主
- 范围：`preview_service.go`、`naming.go`、`import_preview_test.go`
- 验证：`go test ./tests/integration -run TestImportPreview -v`

### P0-3 真实 rollback 闭环
- 状态：PARTIAL（strict 自动回滚 + 手动 rollback CLI + HTTP rollback API 已完成；真实宿主兼容性实测未完成）
- 目标：strict 失败自动清理，支持手动 rollback
- 前置：HostAdapter 增加 DeleteGroup/DeleteChannel/DeletePlan/DeleteAccount/ListManagedResources
- 验证：`go test ./internal/provision ./tests/integration ./cmd/cli -run 'TestRollback|TestExecuteRollbackProviderWritesSummary|TestSub2APIHostAdapterListManagedResources' -v`

### P0-4 正式 pack install 生命周期
- 状态：COMPLETED（zip/目录装载、宿主版本兼容性校验、pack/provider 元数据持久化、CLI `install-pack` 已接入）
- 目标：支持 zip/目录装载、宿主版本兼容性校验、pack/provider 元数据持久化
- 验证：`go test ./internal/pack ./internal/provision ./cmd/cli ./tests/integration -v`

## P1（形成真正控制面）

### P1-1 Access 独立模块化
- 状态：PARTIAL（访问闭环校验/订阅分配/网关探测已从 `import_service` 抽离到 `internal/access/closure.go`，但 implementation plan 目标结构中的 `planner.go` / `subscription_service.go` / `self_service_checker.go` 仍未落地）
- 目标：将访问闭环从 import_service 解耦为 `internal/access/*`
- 设计对齐复核：当前已完成的是“最小闭环抽离”，未达到 implementation plan 中 Access 子模块拆分粒度；因此不再维持 `COMPLETED`
- 验证：`go test ./internal/access ./internal/provision -count=1`

### P1-2 Reconcile / Drift Detection
- 状态：PARTIAL（最小 reconcile API + drift 计数写入已接入；本轮新增 account smoke probe 重跑、access closure 复检、`active/degraded/drifted` 状态语义与回写验证，但 implementation plan 目标中的 `internal/reconcile/*` 结构、`failed` 语义收口与真实宿主兼容性实测仍未完成）
- 目标：拉宿主快照，对比状态库，重跑 probe，标记 drifted
- 验证：`go test ./internal/provision ./internal/app ./tests/integration -run 'TestReconcileService|TestAPIReconcileProviderReturnsSummary|TestStore(Runtime|Init)' -count=1`

### P1-3 HTTP API + OpenAPI
- 状态：PARTIAL（`/api/packs/install`、`/api/providers/{providerID}/preview-import`、`/api/providers/{providerID}/import`、`/api/import-batches/{batchID}`、`/api/providers/{providerID}/status`、`/api/providers/{providerID}/resources`、`/api/providers/{providerID}/access/status`、`/api/providers/{providerID}/rollback`、`/api/providers/{providerID}/reconcile` 已接入；OpenAPI 草案已同步扩展，但 hosts 管理面仍缺失）
- 目标：暴露 hosts / packs/install / providers preview-import / imports rollback / access / reconcile
- 验证：`go test ./internal/app ./cmd/server ./tests/integration -run 'TestAPI|TestBootstrap' -v`

## P2（工程化交付）

### P2-1 Scheduler / Jobs
- 目标：支持定时 reconcile 与手动触发
- 验证：`go test ./tests/integration -run TestCLIScheduler -v`

### P2-2 Distribution Artifacts
- 状态：PARTIAL（已补齐 `Dockerfile` / `.env.example` / `docker-compose.yml` / `docs/DEPLOYMENT.md`，并新增 distribution smoke test；但尚无真实容器启动与镜像构建 E2E 记录）
- 目标：Dockerfile / .env.example / docker-compose / deployment 文档 / e2e 脚本
- 验证：`go test ./tests/integration -run TestDistributionArtifactsExistAndReferenceRequiredEnv -v`

### P2-3 CLI 面板补齐
- 目标：`host add` / `pack install` / `provider import` / `reconcile run`
- 验证：CLI 集成测试 + `go test ./...`

## 当前执行顺序
1. P1-1 Access 模块继续拆分到 implementation plan 粒度
2. P1-2 Reconcile 结构化与真实宿主兼容性实测
3. P1-3 Hosts 管理面 / OpenAPI 收口
4. P2-1 Scheduler / Jobs
5. P2-2 Distribution 容器级 E2E 验证
6. P2-3 CLI 全量收口

## 禁止错误结论
- `go test ./...` 当前通过 ≠ implementation plan 全部实现
- CLI 最小导入闭环 ≠ 独立控制面已完成
- 资源创建成功 ≠ 用户访问闭环已长期可运维