79797644e1
Extract review-plan, report, quarantine, state, and config handlers into commands/ with shared cli_helpers; remove unused exceptions and duplicate plan summary wrappers. Archive superseded review markdown, sync docs to 517-test baseline, and fix empty series titles when only a quality tag remains. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
3.9 KiB
3.9 KiB
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.tmdbenrichment.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. 任务拆解（执行顺序）
- Task A：实现 TMDB 请求层与错误分类。
[已完成] - Task B：重构
TMDBProvider.enrich()以接入请求层。[已完成] - Task C：重构 enrichment 统计与 reason 聚合。
[已完成] - Task D：更新 CLI 输出（进度与摘要）。
[已完成] - Task E：补全配置模型与默认配置导出。
[已完成] - Task F：补充/修复测试并回归。
[已完成] - Task G：更新 README 与变更说明。
[待执行]
5. 验收标准
- 功能：
- 有 key 时可正常 enrich，统计准确。
- 无 key 时不误报
api_calls，输出原因可解释。
- 质量：
- 新增测试覆盖关键分支，相关测试通过。
- 无破坏性 CLI 变更，现有命令仍可用。
- 体验：
- 非 TTY 场景有清晰进度和失败原因摘要。
6. 执行记录模板
每个 Task 完成后记录以下内容：
- 变更文件：
- 关键改动：
- 测试命令：
- 测试结果：
- 风险与后续：