v2.6 设置页一键刷新缺失封面

- POST /api/music/refresh-covers (requireAdmin)
- 设置页封面维护卡片 + 前端事件
- 真实场景验证：清空封面后可刷回

HANDOFF.md

@@ -456,4 +456,24 @@ python test_enrich.py  # 给 5 首补封面（已跑过，5/5 成功）
 ### 18.7 未做
 - **播放延迟调节**（HLS_TIME 运行时热更新）：老板明确暂缓。
 - 用户密码/管理员密码的 UI 设置界面（现走环境变量）。
-- 会话表已有 role 列，但登录失败锁定的 failMap 是内存态，重启清零（可接受）。
+- 会话表已有 role 列，但登录失败锁定的 failMap 是内存态，重启清零（可接受）。
+---
+
+## 19. v2.6 一键刷新缺失封面（已完成 2026-09-25）
+
+### 19.1 需求
+设置页加「刷新缺失封面」按钮：为所有没有封面的音乐重新匹配网易云封面。
+
+### 19.2 实现
+- **后端**：`routes/music.js` 新增 `POST /api/music/refresh-covers`（`requireAdmin`）。遍历 `cover` 和 `cover_remote` **都为空**的歌曲，逐首调 `enrichSong` 重匹配，返回 `{total, success, fail, details}`。
+- **HTML**：`index.html` 设置页新增「封面维护」卡片（`#btnRefreshCovers` + `#coverRefreshProgress`），位于缓存管理和运行配置之间。
+- **前端**：`app.js` 绑定按钮 → confirm 确认 → POST → 显示「共 N 首，成功 X，失败 Y」→ 刷新资源列表 + 收听页封面。
+
+### 19.3 验证
+- admin 调用 → `{total:0}`（无缺失时正常）；user 调用 → **403**。
+- **真实场景**：手动清空 1 首歌封面 → 调接口返回 `{total:1, success:1}` → 复查无封面歌曲数归 0 ✅。
+
+### 19.4 工具坑（重要教训）
+- **powershell Select-String 行号 ≠ replace_lines 行号**（差约 2 行，因换行/编码处理不同），导致多段 replace_lines 反复错位、文件被搞乱。
+- **正解**：用 node 写查找小工具（`fs.readFileSync(f,"utf8").split("\n").forEach`），行号与 replace_lines 完全一致。改前必查、改后必 `node --check`。
+- 文件搞乱时：`git checkout <commit> -- <file>` 从最近提交恢复，比手工修快且稳。