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 完成后记录以下内容：

• 变更文件：
• 关键改动：
• 测试命令：
• 测试结果：
• 风险与后续：