314 lines
8.2 KiB
Markdown
314 lines
8.2 KiB
Markdown
> [!NOTE]
|
||
> Status: Historical snapshot. Current refactor results and validated baseline are tracked in `CHANGELOG.md` (updated 2026-02-16).
|
||
|
||
# VLM 代码改进清单
|
||
|
||
本文档记录对 Video Library Manager (VLM) 项目的代码审查发现的问题及对应解决方案。排除 AI/OpenAPI 相关问题。
|
||
|
||
---
|
||
|
||
## 高优先级（确信度 ≥ 0.9）
|
||
|
||
### 1. 时间戳未统一使用 UTC
|
||
|
||
**问题描述**
|
||
|
||
多处使用 `datetime.now()` 未指定 timezone，与项目约定「timestamps in UTC」不一致，可能导致：
|
||
- 序列化为 ISO 时缺少 `+00:00` 后缀
|
||
- 多环境部署时依赖本地时区，行为不一致
|
||
|
||
**涉及文件**
|
||
|
||
| 文件 | 行号 |
|
||
|------|------|
|
||
| `planner.py` | 51 |
|
||
| `executor.py` | 89, 119, 471 |
|
||
| `state.py` | 104, 139, 173 |
|
||
| `quarantine.py` | 61, 529 |
|
||
|
||
**确信度**: 0.95
|
||
|
||
**解决方案**
|
||
|
||
1. 在 `vlm/utils.py` 或现有模块中定义：
|
||
|
||
```python
|
||
from datetime import datetime, timezone
|
||
|
||
def utc_now() -> datetime:
|
||
"""Return current UTC time (timezone-aware)."""
|
||
return datetime.now(timezone.utc)
|
||
```
|
||
|
||
2. 全局替换所有 `datetime.now()` 为 `utc_now()` 或 `datetime.now(timezone.utc)`
|
||
3. 在 `load_plan`、`load_rollback_log` 等反序列化时，对 naive datetime 做 `replace(tzinfo=timezone.utc)` 以保持向后兼容
|
||
|
||
---
|
||
|
||
### 2. 未使用的依赖 ffmpeg-python
|
||
|
||
**问题描述**
|
||
|
||
`pyproject.toml` 声明 `ffmpeg-python>=0.2.0`，但代码中未 import。scanner 使用 `subprocess` 直接调用 ffprobe。
|
||
|
||
**确信度**: 0.95
|
||
|
||
**解决方案**
|
||
|
||
从 `pyproject.toml` 的 dependencies 中移除 `ffmpeg-python`。若未来改用 ffmpeg-python 库再添加。
|
||
|
||
---
|
||
|
||
### 3. Parser 中 video extensions 硬编码
|
||
|
||
**问题描述**
|
||
|
||
`parser.py` 第 100、169 行使用固定扩展名列表 `['.mp4', '.mkv', ...]`，与 `config.video_extensions` 不一致。
|
||
|
||
- 用户在 config 中新增扩展（如 `.ts`），scan 能发现，但 parse 去扩展名时不会匹配
|
||
- 如 `Movie (2020).ts` 可能得到错误的 title 解析
|
||
|
||
**确信度**: 0.9
|
||
|
||
**解决方案**
|
||
|
||
1. `parse_movie` / `parse_series` 增加可选参数 `extensions: list[str]`
|
||
2. CLI parse 命令调用时传入 `config.video_extensions`
|
||
3. 默认值使用与 config 相同的列表以保持向后兼容
|
||
|
||
---
|
||
|
||
### 4. 抽出统一的 I/O 层
|
||
|
||
**问题描述**
|
||
|
||
数据读取和转换分散在各 CLI 命令中，同一份 identities JSON 在 analyze、plan 等处有重复且略有不同的转换逻辑。新增字段时需多处同步，易遗漏。
|
||
|
||
**确信度**: 0.9
|
||
|
||
**解决方案**
|
||
|
||
新增 `vlm/io.py`，集中：
|
||
|
||
- `load_inventory_csv(path) -> list[VideoFile]`
|
||
- `save_inventory_csv(files, path, library_root)`
|
||
- `load_identities_json(path) -> dict`
|
||
- `save_identities_json(data, path)`
|
||
- `identities_to_plan_input(data) -> list[(VideoFile, Identity | None)]`
|
||
- `identities_to_analysis_input(data) -> (list[MovieIdentity], list[SeriesIdentity], list[VideoFile])`
|
||
|
||
CLI 只调用这些函数，不再直接解析和构造 dataclass。
|
||
|
||
---
|
||
|
||
### 5. Analyze 阶段 VideoFile metadata 丢失
|
||
|
||
**问题描述**
|
||
|
||
`identities.json` 不含 `size_bytes`、`resolution`、`codec` 等，CLI 构造 `VideoFile` 时用 0 或 None，导致 `compare_quality()` 无法有效比较，duplicate 报告信息不足。
|
||
|
||
**确信度**: 0.9
|
||
|
||
**解决方案**
|
||
|
||
1. **方案 A**：analyze 命令同时接受 `--inventory`，从 inventory.csv 加载 metadata 并与 identities 按 path 合并
|
||
2. **方案 B**：parse 输出时在 identities 中附带 size/resolution/codec（从 inventory 合并），避免 analyze 再读 inventory
|
||
|
||
---
|
||
|
||
## 中优先级（确信度 0.8–0.89）
|
||
|
||
### 6. 拆分 CLI 为 commands 子模块
|
||
|
||
**问题描述**
|
||
|
||
`cli.py` 约 1700 行，混合参数定义、业务逻辑、I/O、输出展示，维护和单测困难。
|
||
|
||
**确信度**: 0.85
|
||
|
||
**解决方案**
|
||
|
||
```
|
||
src/vlm/
|
||
cli.py # main、参数、ctx 传递、调用 commands
|
||
commands/
|
||
__init__.py
|
||
scan.py # scan_cmd(ctx, ...)
|
||
parse.py # parse_cmd(ctx, ...)
|
||
enrich.py
|
||
analyze.py
|
||
plan.py
|
||
execute.py
|
||
report.py # 或按子命令拆分
|
||
quarantine.py
|
||
state.py
|
||
config_cmd.py
|
||
```
|
||
|
||
每个 `*_cmd` 接收 `ctx` 和参数，CLI 只做装饰与调用。单测可直接测 `*_cmd` 函数。
|
||
|
||
---
|
||
|
||
### 7. Provider last_request_count 非正式接口
|
||
|
||
**问题描述**
|
||
|
||
`enrichment.py` 使用 `getattr(provider, "last_request_count", 1)` 统计 API 调用，依赖实现细节。
|
||
|
||
**确信度**: 0.85
|
||
|
||
**解决方案**
|
||
|
||
1. 在 `providers/base.py` 的 `EnrichmentProvider` 协议中显式声明 `last_request_count: int` 属性
|
||
2. TMDBProvider 确保实现该属性
|
||
3. enrichment 通过协议访问，去掉 `getattr`
|
||
|
||
---
|
||
|
||
### 8. 异常捕获过宽
|
||
|
||
**问题描述**
|
||
|
||
约 20+ 处 `except Exception`，容易吞掉逻辑错误，难以区分可恢复错误与编程错误。
|
||
|
||
**涉及**：`cli.py`、`enrichment.py`、`executor.py`、`quarantine.py` 等。
|
||
|
||
**确信度**: 0.8
|
||
|
||
**解决方案**
|
||
|
||
- 针对预期异常（`FileNotFoundError`、`json.JSONDecodeError`、`ValueError`）分别处理
|
||
- 保留顶层 `except Exception` 作为兜底，记录完整 traceback 后 `sys.exit(1)`
|
||
- 避免在业务逻辑深处宽泛捕获
|
||
|
||
---
|
||
|
||
### 9. Enrichment 主循环过长
|
||
|
||
**问题描述**
|
||
|
||
`enrich_identities_data` 主循环约 80 行，混合迭代、缓存、API 调用、统计、payload 合并，可读性和可测性差。
|
||
|
||
**确信度**: 0.8
|
||
|
||
**解决方案**
|
||
|
||
拆分为：
|
||
|
||
- `_process_single_record(record, media_type, ...) -> None`
|
||
- `_fetch_from_providers(record, media_type, providers, ...) -> tuple[dict, int, list, str]`
|
||
- `_update_stats(stats, ...) -> None`
|
||
- 主循环只负责迭代与调用上述函数
|
||
|
||
---
|
||
|
||
## 较低优先级（确信度 0.7–0.79）
|
||
|
||
### 10. Duplicate 检测 file_map 使用 filename 作为 key
|
||
|
||
**问题描述**
|
||
|
||
`analysis.py` 第 87 行：
|
||
|
||
```python
|
||
file_map = {file.filename: file for file in files}
|
||
```
|
||
|
||
同 filename 不同路径会互相覆盖（如 `/a/Movie.mkv` 与 `/b/Movie.mkv`），导致 identity 映射到错误 VideoFile。
|
||
|
||
**确信度**: 0.75
|
||
|
||
**解决方案**
|
||
|
||
- 使用 `str(file.path)` 作为 key
|
||
- 确保 identity 与 VideoFile 的关联方式一致（如通过 path 或 (path, filename) 建立映射）
|
||
|
||
---
|
||
|
||
### 11. MovieIdentity / SeriesIdentity 字段重复
|
||
|
||
**问题描述**
|
||
|
||
两个 dataclass 有约 10 个共同 enrichment 字段，新增时需改两处，合并逻辑需分支处理。
|
||
|
||
**确信度**: 0.7
|
||
|
||
**解决方案**
|
||
|
||
- **方案 A**：抽取 `EnrichmentMixin` 基类，`MovieIdentity` / `SeriesIdentity` 继承
|
||
- **方案 B（推荐）**：引入 `EnrichmentPayload` dataclass，两个 Identity 通过 `enrichment: EnrichmentPayload` 组合，侵入较小
|
||
|
||
---
|
||
|
||
### 12. Config 体积膨胀
|
||
|
||
**问题描述**
|
||
|
||
`Config` 约 50 个字段，enrichment/TMDB 相关占多数，职责混杂。
|
||
|
||
**确信度**: 0.7
|
||
|
||
**解决方案**
|
||
|
||
拆分 `EnrichmentConfig`、`TMDBConfig` 等子配置，通过嵌套或组合放入主 Config。
|
||
|
||
---
|
||
|
||
### 13. review_status 与 needs_review 语义重叠
|
||
|
||
**问题描述**
|
||
|
||
`review_status`（pending/approved/rejected）与 `needs_review`（bool）含义重叠，易混淆。
|
||
|
||
**确信度**: 0.75
|
||
|
||
**解决方案**
|
||
|
||
- 在 docstring 或文档中明确定义：`needs_review = (review_status == 'pending') and ...`
|
||
- 或在模型中合并为单一状态枚举，避免两个字段语义交叉
|
||
|
||
---
|
||
|
||
## 低优先级（确信度 < 0.7）
|
||
|
||
### 14. config_init 与 ctx 一致性
|
||
|
||
**问题描述**
|
||
|
||
`config init` 未使用 `@pass_context`，与同组其他命令风格不一致，但当前不依赖 ctx，非功能性 bug。
|
||
|
||
**确信度**: 0.5
|
||
|
||
**解决方案**
|
||
|
||
若其他 config 子命令均用 `@pass_context`，可统一为 `config_init` 也接收 ctx 以保持风格一致；否则可保持现状。
|
||
|
||
---
|
||
|
||
### 15. CLI 延迟 import
|
||
|
||
**问题描述**
|
||
|
||
各命令在函数体内才 `import`，错误在首次执行该命令时才暴露，依赖关系不直观。
|
||
|
||
**确信度**: 0.6
|
||
|
||
**解决方案**
|
||
|
||
可接受；若希望启动时即发现依赖问题，可改为模块级 import，但会增加启动开销。
|
||
|
||
---
|
||
|
||
## 执行建议
|
||
|
||
| 阶段 | 项目 | 说明 |
|
||
|------|------|------|
|
||
| 第一批 | 1, 2, 3 | 改动小、风险低、收益明确 |
|
||
| 第二批 | 4, 5 | 需要一定重构，与 I/O 设计相关 |
|
||
| 第三批 | 6, 7, 8, 9 | 结构性改进，建议分步完成 |
|
||
| 第四批 | 10–15 | 按需和档期安排 |
|
||
|
||
---
|
||
|
||
*文档生成日期：2025-02-10*
|