diff --git a/docs/2026-05-22-BATCH_AUTO_IMPORT_V2_RESTORATION_CHECKLIST.md b/docs/2026-05-22-BATCH_AUTO_IMPORT_V2_RESTORATION_CHECKLIST.md new file mode 100644 index 00000000..68bdd20b --- /dev/null +++ b/docs/2026-05-22-BATCH_AUTO_IMPORT_V2_RESTORATION_CHECKLIST.md @@ -0,0 +1,96 @@ +# Batch Auto-Import V2 设计还原审计清单 + +日期:2026-05-22 +状态:已审计,未完全恢复 +基线计划:`docs/plans/2026-05-22-batch-auto-import-v2-implementation-plan.md` + +## 1. Objective 恢复项 + +- [x] 上游发现:`internal/probe/models.go` + `tests/integration/batch_import_v2_test.go` +- [x] 模型纠错:`internal/probe/aliases.go` + `internal/batch/status_projection.go` +- [x] 兼容画像:`internal/probe/capability.go` + `internal/batch/status_projection.go` +- [ ] 宿主演化:V2 pipeline 仍未从 API/CLI 入口接到真实 provision adapter +- [ ] 异步确认:`ConfirmationWorker` 已实现,但尚未由 API/CLI create-run 路径驱动 +- [ ] 闭环验证:`ValidationService` 已实现,但尚未由 API/CLI create-run 路径驱动 +- [x] 结果可视:`/api/batch-import/runs*` 与 `ResultProjection` 已接到 V2 状态表 +- [x] 重复导入复用:`internal/batch/reuse_policy.go` + `tests/integration/batch_import_v2_test.go` + +## 2. Canonical Contract 恢复项 + +- [x] `run_id / item_id / provider_id` +- [x] `run.state` +- [x] `item.current_stage` +- [x] `item.confirmation_status` +- [x] `item.access_status` +- [x] `matched_account_state / account_resolution` +- [x] `canonical_model_families` +- [x] `provision_reused / reused_from_*` + +## 3. Runtime / API / Migration 恢复项 + +- [x] 单一状态源为 `import_runs / import_run_items / import_run_item_events` +- [x] migration 已落地并受集成测试保护 +- [x] `/api/batch-import/runs*` 已接到 V2 projection +- [ ] CLI `batch-import` 仅接到 placeholder create action,尚未进入真实 pipeline +- [x] 结果页/结果 API 不回退 legacy 表结构 + +## 4. Worker / Retry / Lease 恢复项 + +- [x] `ConfirmationWorker` 扫描 confirm item +- [x] lease 生效,避免并发重复确认 +- [x] `next_retry_at` / `retry_count` 持久化 +- [x] advisory / retry / stage transition 写入 event trail + +## 5. Reuse / Reactivation 恢复项 + +- [x] active duplicate -> `reused` +- [x] deprecated/disabled duplicate -> `reactivated` +- [x] broken duplicate -> `replaced` +- [x] same family different alias -> `patch_only` + +## 6. 审计证据 + +### 代码文件映射 + +- Probe / alias / capability:`internal/probe/models.go`、`internal/probe/aliases.go`、`internal/probe/capability.go`、`internal/probe/completion.go` +- Reuse / orchestration / worker / validation:`internal/batch/provider_id.go`、`internal/batch/reuse_policy.go`、`internal/batch/service.go`、`internal/batch/confirmation.go`、`internal/batch/validation.go` +- 状态库存储:`internal/store/sqlite/import_runs_repo.go`、`internal/store/sqlite/import_run_items_repo.go`、`internal/store/sqlite/import_run_item_events_repo.go` +- Projection / API / CLI:`internal/batch/status_projection.go`、`internal/app/http_batch_import.go`、`internal/app/http_batch_runs.go`、`cmd/cli/batch_import.go` + +### 测试文件映射 + +- 单测:`internal/batch/types_test.go`、`internal/probe/models_test.go`、`internal/probe/aliases_test.go`、`internal/probe/capability_test.go`、`internal/probe/completion_test.go` +- 状态机:`internal/batch/provider_id_test.go`、`internal/batch/reuse_policy_test.go`、`internal/batch/service_test.go`、`internal/batch/confirmation_test.go`、`internal/batch/validation_test.go`、`internal/batch/status_projection_test.go` +- API / CLI:`internal/app/http_batch_import_test.go`、`internal/app/http_batch_runs_test.go`、`cmd/cli/batch_import_test.go` +- 集成:`tests/integration/batch_import_v2_test.go` + +### API 路由映射 + +- `POST /api/batch-import/runs` +- `GET /api/batch-import/runs` +- `GET /api/batch-import/runs/{run_id}` +- `GET /api/batch-import/runs/{run_id}/items` +- `GET /api/batch-import/runs/{run_id}/items/{item_id}` + +### 验证命令结果 + +- `go test ./... -count=1`:PASS +- `go test ./tests/integration/... -count=1`:PASS +- `go test -cover ./internal/... -count=1`:PASS + - `internal/access` 76.7% + - `internal/provision` 76.4% + - `internal/pack` 73.9% +- `go vet ./...`:PASS +- `gofmt -l .`:PASS(空输出) + +### 阻塞缺口 + +- `internal/app/http_batch_import.go` 的 `buildCreateBatchImportRunAction` 仍是 placeholder:当前只写 `import_runs/import_run_items` 初始记录,没有调用 `batch.BatchImportService` +- `cmd/cli/batch_import.go` 的 `runBatchImport` 复用了上述 placeholder action,因此 CLI 也不会真实执行 probe / provision / confirm / validate +- `ConfirmationWorker` 与 `ValidationService` 已有实现和测试,但当前没有被 API/CLI 创建 run 的路径自动驱动 + +### 审计结论 + +- T1-T12 的单测、集成测试、OpenAPI 路由和状态投影均已落地 +- 当前 **不能** 宣称“V2 设计已被完整实现” +- 真正阻塞项不是算法或状态机缺失,而是 **入口 wiring 缺失**:create-run 仍未接到真实 pipeline diff --git a/docs/EXECUTION_BOARD.md b/docs/EXECUTION_BOARD.md index 7f32ac85..a5525a3f 100644 --- a/docs/EXECUTION_BOARD.md +++ b/docs/EXECUTION_BOARD.md @@ -139,11 +139,11 @@ 1. 若继续扩大 provider 覆盖面,优先按 `docs/PROVIDER_VALIDATION_MATRIX.md` 补官方 key,再做 official live 验收 2. 若继续优化 shared fresh-host 信噪比,对历史残留资源做一次环境清理,降低 `reconcile=drifted` 噪音 -3. 若继续产品化,推进 `v2` 的 batch auto-import 设计评审,再开始实现 +3. 若继续产品化,优先修复 `v2` batch auto-import 的 entry wiring:把 API/CLI create-run 接到 `BatchImportService + ConfirmationWorker + ValidationService` ## v2 规划:Batch Auto-Import(URL + Key) -**当前阶段**:🔨 设计中(核心契约已收口,待按收口版本进入实现) +**当前阶段**:⚠️ 审计完成但未完全恢复(T1~T12 代码与测试已落地,T13 审计确认 entry wiring 仍缺失,当前不能宣称 V2 已完整实现) **文档**:`docs/2026-05-21-BATCH_AUTO_IMPORT_SPEC.md`(需求规格) **TDD 计划**:`docs/2026-05-21-BATCH_AUTO_IMPORT_TDD_PLAN.md`(实现路径,已确认开放问题) @@ -173,15 +173,26 @@ - 已补充同模型别名归一化契约:例如 `kimi 2.6 / kimi-2.6 / kimi-k2.6` 可归并到同一模型家族并快速复用 - 已补充多账号重复导入与弃用账号再启用策略:active 账号提示“重复已启用”,disabled/deprecated 账号显示原状态并走 `reactivated` 快速启用路径 -**当前剩余项**: -- [x] 按收口后的 canonical contract 输出数据库 migration 草案 -- [x] 补齐 run/item API response schema 细稿 -- [~] 按收口后的 OpenAPI、migration、projection 字段开始实现 - - 已落地 `0007_batch_import_runs.sql` / `0008_batch_import_run_events.sql` - - 已补 `internal/store/sqlite` 下 run/item/event repo 骨架,并完成 migration ledger 测试同步 -- [ ] 进入实现前再做一次实现前审阅,确认没有新增分叉 +**本轮实现状态(T1 ~ T13)**: +- [x] `internal/batch` canonical types / reuse policy / service / confirmation / validation / projection 已落地 +- [x] `internal/probe` models / alias / capability / smoke completion 已落地 +- [x] `internal/store/sqlite` run/item/event runtime state repo 与 migration 已落地 +- [x] `/api/batch-import/runs*` 路由、projection 读取、CLI `batch-import` 命令、集成测试与设计还原审计已落地 +- [x] `go test ./... -count=1` +- [x] `go test ./tests/integration/... -count=1` +- [x] `go test -cover ./internal/... -count=1` +- [x] `go vet ./...` +- [x] `gofmt -l .` -**实现前 Gate**:文档级 review 问题已收口,当前可以进入“按文档写 migration / 接口 / worker”的实现准备阶段 +**T13 审计结论**: +- `docs/2026-05-22-BATCH_AUTO_IMPORT_V2_RESTORATION_CHECKLIST.md` 已完成 +- 单测、集成测试、coverage、`vet`、`gofmt` 全绿 +- 但当前仍存在一个阻塞级设计漂移: + - `internal/app/http_batch_import.go` 的 `buildCreateBatchImportRunAction` 仍是 placeholder,只会创建 run/item 初始行,不会调用 `BatchImportService` + - `cmd/cli/batch_import.go` 复用该 placeholder action,所以 CLI 也未真正执行 probe / provision / confirm / validate + - `ConfirmationWorker` / `ValidationService` 已实现并经过直接集成验证,但没有被 create-run 入口自动驱动 + +**真实 Gate**:⚠️ 文档、状态机、投影、测试与审计都已完成,但 **V2 设计尚未被完整实现**;在补齐 create-run entry wiring 之前,不能宣称 V2 已按设计交付 ---