99 lines
3.9 KiB
Markdown
99 lines
3.9 KiB
Markdown
> [!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 完成后记录以下内容：
|
||
- 变更文件：
|
||
- 关键改动：
|
||
- 测试命令：
|
||
- 测试结果：
|
||
- 风险与后续：
|