dl-organizer/TMDB_REFACTOR_PLAN.md

> [!NOTE]
> Status: Historical snapshot. Current refactor results and validated baseline are tracked in `CHANGELOG.md` (updated 2026-04-07).

# TMDB Enrichment 重构执行计划

## 1. 目标与范围
- 目标：提升 `vlm enrich` 在 TMDB 场景下的正确性、稳定性、可观测性。
- 范围：`src/vlm/providers/tmdb.py`、`src/vlm/enrichment.py`、`src/vlm/cli.py`、配置与测试。
- 非目标：不改动 CLI 命令名和现有核心参数，不引入复杂依赖。

## 2. 设计原则
- 简洁优先：保留现有调用链，避免过度抽象。
- 统计真实：`api_calls` 仅统计真实外部请求。
- 错误可解释：区分鉴权、限流、无匹配、服务异常。
- 向后兼容：默认配置缺省时仍可运行，行为可预测。

## 3. 分阶段计划

### 阶段 0：基线确认
- 记录当前测试基线：
  - `uv run pytest tests/test_enrichment.py tests/test_cli_enrich.py`
- 记录当前运行基线：
  - `uv run vlm enrich --input identities.json --refresh-all`
- 输出基线报告（用于对比重构前后变化）。

### 阶段 1：TMDB Provider 重构
- 新增 TMDB HTTP 访问层（可内聚在 provider 文件内）：
  - 统一请求构建（query/header/timeout）。
  - 统一响应解析与错误分类。
- 错误分类与策略：
  - `401/403`：鉴权失败，停止该条 provider 请求并记录原因。
  - `404`：资源缺失，返回无匹配。
  - `429`：指数退避重试（含上限）。
  - `5xx`：有限重试，最终记录失败。
- 保留最小调用路径：`search -> details`。

### 阶段 2：Enrichment 统计与语义修复
- 统一并明确统计口径：
  - `api_calls`：真实发起的远程请求次数。
  - `enriched`：获得有效 provider 或翻译结果的记录数。
  - `skipped`：未产生 enrich 结果的记录数。
- 增加 skip/reason 聚合（建议键）：
  - `no_key`、`no_match`、`rate_limited`、`provider_error`、`invalid_input`。
- 保持 `needs_review` 判定逻辑稳定且可解释。

### 阶段 3：CLI 进度与结果展示
- TTY：保留 `click.progressbar`。
- 非 TTY：保留分段文本进度（每 5% 或固定步进）。
- 结束摘要补充原因分布：
  - 示例：`Skip reasons: no_key=4632 no_match=0 provider_error=0`

### 阶段 4：配置与文档
- 配置补全（默认模板）：
  - `enrichment.api_keys.tmdb`
  - `enrichment.tmdb.language`（默认 `zh-CN`）
  - `enrichment.tmdb.region`（可选）
  - `enrichment.tmdb.include_adult`（默认 `false`）
- README 增加：
  - key 配置示例。
  - 常见错误排查（401/429/0 enriched）。
  - 小样本验证流程。

### 阶段 5：测试与回归
- Provider 测试：
  - 鉴权失败、限流重试、5xx 重试、无匹配。
- Enrichment 测试：
  - 统计口径、skip reason 聚合、无 key 场景。
- CLI 测试：
  - 非 TTY 进度输出、摘要 reason 输出。
- 回归测试：
  - `uv run pytest` 全量通过。

## 4. 任务拆解（执行顺序）
1. Task A：实现 TMDB 请求层与错误分类。`[已完成]`
2. Task B：重构 `TMDBProvider.enrich()` 以接入请求层。`[已完成]`
3. Task C：重构 enrichment 统计与 reason 聚合。`[已完成]`
4. Task D：更新 CLI 输出（进度与摘要）。`[已完成]`
5. Task E：补全配置模型与默认配置导出。`[已完成]`
6. Task F：补充/修复测试并回归。`[已完成]`
7. Task G：更新 README 与变更说明。`[待执行]`

## 5. 验收标准
- 功能：
  - 有 key 时可正常 enrich，统计准确。
  - 无 key 时不误报 `api_calls`，输出原因可解释。
- 质量：
  - 新增测试覆盖关键分支，相关测试通过。
  - 无破坏性 CLI 变更，现有命令仍可用。
- 体验：
  - 非 TTY 场景有清晰进度和失败原因摘要。

## 6. 执行记录模板
每个 Task 完成后记录以下内容：
- 变更文件：
- 关键改动：
- 测试命令：
- 测试结果：
- 风险与后续：