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 仅接到 placeholder create action，尚未进入真实 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/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