feat(control-plane): harden host-scoped reconcile and acceptance evidence

- add batch-scoped reconcile_runs persistence and queries
- route batch detail and reconcile writes through batch_id/host_id
- refresh production boards with host-scope acceptance artifacts
- include latest real-host acceptance evidence for self_service and subscription
This commit is contained in:
phamnazage-jpg
2026-05-18 22:22:22 +08:00
parent 71cbaf5fa6
commit 85d495dd16
332 changed files with 5561 additions and 422 deletions

View File

@@ -1,111 +1,86 @@
# sub2api-cn-relay-manager 执行板
日期2026-05-13
当前 GateREQUEST_CHANGES
目标:实现 implementation plan 全量能力,达成独立控制面、零侵入宿主、一键导入国产模型,并补齐回滚/对账/HTTP API/交付物
日期2026-05-18
当前 GateAPPROVED按 PRD 首版范围放行;代码门禁通过,真实宿主 fresh redeploy 复验已确认 self_service / subscription 访问链路可打通,且已补充 reconcile host-scope acceptance artifact
目标:实现独立控制面、零侵入宿主、导入国产模型并具备可运维的导入/回滚/访问闭环
## 当前真实状态
## 本轮已完成
模块完成 gate新增执行要求后续每个大模块都必须执行
- `go test` 通过不算完成;每次完成大模块后,必须补做:
1. 两阶段 review先对规划/设计文档做实现对齐检查,再做代码质量 review
2. execution board 当前状态同步
3. 若发现实现/设计漂移,优先修正文档结论或回退模块状态,不维持虚假 `COMPLETED`
- 本板从本次起按上述 gate 维护。
1. 宿主身份模型统一
- host 注册时持久化 `auth_type/auth_token`
- import / reconcile / rollback-provider / access 运行时链路切换为 `host_id` 主键
- provider status / resources / access status / import-batches 支持 `host_id` 查询维度
2. managed_resources 宿主维度收口
- 新增迁移 `0004_host_identity_and_managed_resources.sql`
- `managed_resources` 唯一键提升为 `(host_id, resource_type, host_resource_id)`
- 仓储与服务查询切换为 host-scoped 语义
3. reconcile run 结果按批次收口
- 新增迁移 `0006_reconcile_runs_batch_scope.sql`
- `reconcile_runs` 补充 `batch_id`batch detail 仅返回本批次 reconcile 记录
4. capability probe 收敛为无副作用探测
- 不再对真实创建接口发送空 `POST`
5. rollback-provider 风险收敛
- 改为优先按已记录批次资源 `RollbackStoredResources()` 回滚
- 缺少已记录资源时拒绝危险删除
6. 文档真相同步
- 新增 `docs/2026-05-18-PRODUCTION_REMEDIATION_TASK_BOARD.md`
- 下调 `DEPLOYMENT.md` 中未实现的 `/metrics` / 限流 / 监控承诺
7. 真实宿主重新验收已执行
- `self_service` 新 artifact`artifacts/real-host-acceptance/20260518_self_service_reaccept_v6`
- `subscription` 新 artifact`artifacts/real-host-acceptance/20260518_subscription_reaccept_v6`
- 两轮都完成了 `preview-import / import / access-preview / status / reconcile / rollback` 全链路落盘
8. reconcile host-scope 证据已补强
- `self_service``artifacts/real-host-acceptance/20260518_reconcile_hostscope_self_service`
- `subscription``artifacts/real-host-acceptance/20260518_reconcile_hostscope_subscription`
- 已补齐 `status / resources / reconcile / batch detail / rollback` 的 host-scoped artifact验证 batch detail 的 reconcile 视图按 batch 收口
已完成:
- 项目骨架与配置加载
- SQLite 最小状态库hosts/packs/providers
- SQLite 运行态状态库扩展import_batches / items / managed_resources / probe_results / access_closure_records / reconcile_runs
- sub2api HostAdapter 基础创建/探测能力
- HostAdapter 删除能力group/channel/accountplan 接口已补)
- 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 / reconcileOpenAPI 草案已同步扩展
- 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 执行记录
- `gofmt -l .` ✅ 空输出
- `go vet ./...`
- `go test ./...`
- `go test -race ./...`
- `go test -cover ./internal/...`
- `internal/access`: `77.3%`
- `internal/pack`: `72.7%`
- `internal/provision`: `74.6%`
- `internal/store/sqlite`: `61.3%`
- `go test ./tests/integration/... -count=1`
## P0必须先完成
## 本轮真实宿主复验结果
### P0-1 状态库扩展并接入运行链
- 状态COMPLETEDschema/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 可写入读取,并被运行链消费
1. `self_service`(最新 fresh redeploy 复验)
- 证据目录:`artifacts/real-host-acceptance/20260518_redeploy_matrix`
- 初始状态:普通用户 key 未绑定 group、用户余额为 0 时,`/v1/models` 返回 `403`
- 修正后对普通用户执行“key 绑定标准 group + 用户余额=10”后`04-self-after-balance.headers.txt` 显示 `HTTP/1.1 200 OK`
- 结论`self_service` 主链路已在 fresh host 上真实打通;当前关键前置条件已收敛为 runbook 中明确记录的普通用户创建 / key-group 绑定 / 余额要求,而不是代码级阻塞。
2. `subscription`(最新 fresh redeploy 复验)
- 证据目录:`artifacts/real-host-acceptance/20260518_redeploy_matrix`
- 修正后:创建 subscription 类型 group、完成普通用户订阅分配、并把普通用户 key 绑定到该 group 后,`06-subscription-after-assign.headers.txt` 显示 `HTTP/1.1 200 OK`
- 结论:`subscription` 主链路也已在 fresh host 上真实打通;其可用前提不是“宿主自动初始化一切”,而是显式完成 subscription group / user subscription / key binding 这一套运营动作。
### P0-2 import preview + naming
- 目标:导入前可输出 create/reuse/conflict不盲写宿主
- 范围:`preview_service.go``naming.go``import_preview_test.go`
- 验证:`go test ./tests/integration -run TestImportPreview -v`
## 剩余项非阻塞P2 / 运营前置)
### P0-3 真实 rollback 闭环
- 状态PARTIALstrict 自动回滚 + 手动 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`
1. 结构债务仍存在
- access / reconcile 尚未完全按 implementation plan 物理拆分
- 无内置 scheduler/jobs
2. 运营前置动作需要 runbook 化执行
- 真实宿主初始化不会自动创建普通用户;验收或上线前必须显式创建普通用户并留存可复用凭据
- `self_service` 需要普通用户 key 绑定目标标准 group且通常还需要可用余额
- `subscription` 需要 subscription 类型 group + 普通用户订阅分配 + key/group 绑定
3. 标准多阶段 Dockerfile 在受限网络环境下仍不稳
- 当前推荐 `scripts/build_local_image.sh` + `Dockerfile.local`
### P0-4 正式 pack install 生命周期
- 状态COMPLETEDzip/目录装载、宿主版本兼容性校验、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 全量收口
1.`docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md` 准备真实宿主普通用户与凭据
2. 按目标模式完成必要的 key/group/billing(or subscription) 绑定
3. 使用 `scripts/build_local_image.sh``scripts/real_host_acceptance.sh` 复跑并归档现场 artifact
4. 若现场前置满足,本项目按 PRD 首版范围可直接上线
## 禁止错误结论
- `go test ./...` 当前通过 ≠ implementation plan 全部实现
- CLI 最小导入闭环 ≠ 独立控制面已完成
- 资源创建成功 ≠ 用户访问闭环已长期可运维
- ❌ 历史失败 artifact ≠ 当前 fresh redeploy 仍失败
- ❌ capability probe 无副作用 ≠ 所有宿主版本都已真实兼容
- ❌ rollback-provider 已改安全路径 ≠ 历史脏资源自动消失
-`HTTP 200` ≠ 宿主初始化会自动准备普通用户/订阅/余额;这些仍是显式运营前置