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 恢复项

- [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`
- [x] 宿主演化：V2 pipeline 已从 API/CLI 入口接到真实 provision adapter
- [x] 异步确认：`ConfirmationWorker` 已由 API/CLI create-run 路径自动驱动
- [x] 闭环验证：`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] run 级请求上下文（`host_id / subscription_users / subscription_days / probe_api_key`）已持久化，支持重启后恢复 validate
- [x] `/api/batch-import/runs*` 已接到 V2 projection
- [x] CLI `batch-import` 已通过 `ActionSet.CreateBatchImportRun` 进入真实 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`、`internal/store/migrations/0009_batch_import_run_request_context.sql`
- Projection / API / CLI：`internal/batch/status_projection.go`、`internal/app/http_batch_import.go`、`internal/app/batch_runtime.go`、`internal/app/batch_runtime_background.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`、`internal/app/batch_runtime_background_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` 72.9%
  - `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 的同步入口驱动链
- `internal/app/batch_runtime_background.go` 已补后台 runtime scheduler；`running` run 在控制面重启后会继续被拾取并推进
- `internal/store/sqlite/import_run_items_repo.go` 已补原子 lease 获取；不会再在 lease 落库前并发双发 confirmer
- `internal/app/http_batch_import.go` / `internal/app/http_batch_runs.go` 已补 `cursor/next_cursor`，且 run 列表 `q` 可命中 `run_id / provider_id / base_url`
- `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 设计已按基线计划恢复实现”