feat: productize ingest lifecycle and library health

docker/README.md

@@ -99,6 +99,47 @@ docker compose up -d --build
 
 容器内置 FFmpeg 和 FFprobe（FFmpeg 套件自带），一键导入过程中的格式转换（WAV/APE/AIFF/WV/TTA → FLAC）和音频完整性验证自动使用容器内的工具。
 
+## 运维与可观测性
+
+### 依赖自检
+
+部署后可用依赖自检确认外部工具就绪：
+
+```bash
+docker compose exec mangtool wget -q -O- http://localhost:8080/api/health/dependencies
+```
+
+返回 `ffmpegAvailable`/`ffprobeAvailable` 及版本行；任一为 false 时导入会在预检阶段直接报错。
+
+### 导入报告与歌词统计
+
+每次导入在工作根目录 `Rejected/Reports/` 下写入结构化 JSON 报告（逐文件结果 + 歌词 有/无/失败 统计）。前端「一键导入」页可实时查看歌词统计并「下载导入报告」。歌词的有无与失败**绝不影响音频入库**。
+
+### 任务取消与重启恢复
+
+- 取消：`POST /api/ingest/cancel`，只停止后续文件处理，已入库文件保留，未处理文件留在 `Input/`。
+- 重启恢复：任务状态持久化于 `工作根目录/.mangtool/ingest-tasks.json`；容器重启后仍在运行的任务标记为 `interrupted`，重新导入只处理未完成文件（已完成文件已移出 `Input/`，不会重复搬运）。
+
+### Library 健康检查（只读）
+
+```bash
+# 只读扫描（不修改任何文件）
+docker compose exec mangtool wget -q -O- --post-data='' http://localhost:8080/api/library/health/scan
+```
+
+修复动作（歌词回填、删除孤立侧车等）必须在请求体显式 `confirm=true` 才会执行，否则仅演练。
+
+### 备份与恢复
+
+导入为「移动」语义，批量导入前建议对宿主机工作目录做快照：
+
+```bash
+# 在挂载的宿主机数据目录（默认 docker/data）执行
+tar czf mangtool-backup-$(date +%Y%m%d).tgz -C /path/to/MusicWork Library Rejected .mangtool
+```
+
+`Library/` 为必备成品数据；`Rejected/Reports/` 便于追溯；`.mangtool/` 为任务状态。恢复时解压回原数据目录即可，Navidrome 直接扫描 `Library/`，无需外部数据库。
+
 ## 常见问题
 
 ### 构建失败