sub2api-cn-relay-manager/docs/2026-05-22-BATCH_AUTO_IMPORT_V2_RESTORATION_CHECKLIST.md

Batch Auto-Import V2 设计还原审计清单

日期：2026-05-22 状态：已审计，已恢复 基线计划：docs/plans/2026-05-22-batch-auto-import-v2-implementation-plan.md

1. Objective 恢复项

• 上游发现：internal/probe/models.go + tests/integration/batch_import_v2_test.go
• 模型纠错：internal/probe/aliases.go + internal/batch/status_projection.go
• 兼容画像：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 路径自动驱动
• 结果可视：/api/batch-import/runs* 与 ResultProjection 已接到 V2 状态表
• 重复导入复用：internal/batch/reuse_policy.go + tests/integration/batch_import_v2_test.go

2. Canonical Contract 恢复项

• run_id / item_id / provider_id
• run.state
• item.current_stage
• item.confirmation_status
• item.access_status
• matched_account_state / account_resolution
• canonical_model_families
• provision_reused / reused_from_*

3. Runtime / API / Migration 恢复项

• 单一状态源为 import_runs / import_run_items / import_run_item_events
• migration 已落地并受集成测试保护
• /api/batch-import/runs* 已接到 V2 projection
• CLI batch-import 已通过 ActionSet.CreateBatchImportRun 进入真实 pipeline
• 结果页/结果 API 不回退 legacy 表结构

4. Worker / Retry / Lease 恢复项

• ConfirmationWorker 扫描 confirm item
• lease 生效，避免并发重复确认
• next_retry_at / retry_count 持久化
• advisory / retry / stage transition 写入 event trail

5. Reuse / Reactivation 恢复项

• active duplicate -> reused
• deprecated/disabled duplicate -> reactivated
• broken duplicate -> replaced
• 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/batch_runtime.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/batch 75.4%
  • internal/probe 78.2%
  • internal/provision 76.4%
  • internal/pack 73.9%
• go vet ./...：PASS
• gofmt -l .：PASS（空输出）

已修复缺口

• internal/app/http_batch_import.go 的 buildCreateBatchImportRunAction 已改为先解析已注册 host，再委托 batchImportRuntimeRunner.execute
• internal/app/batch_runtime.go 已把 BatchImportService + ConfirmationWorker + ValidationService 串成 create-run 的同步入口驱动链
• cmd/cli/batch_import.go 继续复用 ActionSet.CreateBatchImportRun，因此 CLI create-run 也随入口修复自动进入真实 pipeline
• internal/app/http_batch_import_test.go 已新增真实 stub 回归，直接验证 create-run 最终把 item 推进到 current_stage=done 且 access_status=active

审计结论

• T1-T12 的单测、集成测试、OpenAPI 路由和状态投影均已落地
• T13 审计中识别出的 入口 wiring 缺失 已修复，并已通过最新一轮全量验证命令确认
• 当前 可以 宣称“V2 设计已按基线计划恢复实现”