docs: 添加交接文档 HANDOFF.md

2026-09-24 20:38:50 +08:00
1 parent f96a4bae51
commit 4510d697f0
@@ -0,0 +1,247 @@
+# 交接文档 · 音乐在线电台 v2
+
+> 本文件用于跨会话交接。上下文耗尽后，新会话**先读此文件**再动手。
+
+---
+
+## 0. TL;DR
+
+- **项目**：`F:\music_online\demo` — Node.js + FFmpeg 的 HLS 音乐电台
+- **状态**：v2 重构**基本完成**，后端 38/38 测试通过；**但用户反馈"功能还有问题"，具体未明**（见 §9 待排查）
+- **服务**：正在运行 `svc005`，`http://127.0.0.1:3000`，密码 `test123`（测试用）
+- **Git**：`ea5aa0c`(基线) → `b8e9bf3`(v2主体) → `a4745db`(收尾)
+
+---
+
+## 1. 运行 / 环境
+
+- 环境：Windows 11，Node v24.5.0，npm 11.5.1，FFmpeg 9.0.1（含 ffprobe，均在 PATH），Python 3.11
+- 启动：
+  ```cmd
+  cd /d F:\music_online\demo
+  set PANEL_PASSWORD=test123 && node index.js
+  ```
+- 依赖：`better-sqlite3`、`multer`、`chokidar`、`express`（已装）
+- 登录：浏览器开 `http://127.0.0.1:3000`，输入密码
+
+---
+
+## 2. 目录结构（v2）
+
+```
+demo/
+├── index.js                 # 入口，仅 require("./src/server").start()
+├── package.json             # v2.0.0
+├── data.db                  # SQLite（自动生成，WAL）
+├── HANDOFF.md               # 本文件
+├── README.md                # v2 说明
+├── src/
+│   ├── server.js            # 装配：中间件、路由、启动、优雅退出
+│   ├── config.js            # 所有配置（环境变量解析）
+│   ├── logger.js            # 分级日志 + 落盘 + 内存环形缓冲(tail)
+│   ├── db.js                # SQLite 初始化 + schema(5表) + WAL
+│   ├── store.js             # 数据访问层，所有 SQL 收敛于此
+│   ├── util.js              # fileHash/解析文件名/原子写/目录大小 等
+│   ├── media.js             # ffprobe + FFmpeg 切片 + 并发队列 + 进程追踪
+│   ├── metadata.js          # 网易云 API + 封面下载本地化 + 元数据补全
+│   ├── livestream.js        # LiveStream 类 + 多路流管理 + 缓存状态/清理
+│   ├── scanner.js           # audio/ 监听 + 同步 DB
+│   ├── auth.js              # Cookie 会话鉴权 + requireAuth 中间件
+│   ├── sse.js               # Server-Sent Events 广播
+│   └── routes/
+│       ├── auth.js          # /api/auth/*
+│       ├── music.js         # /api/music/*  (搜索/详情/下载/导入/删除/enrich)
+│       ├── resources.js     # /api/resources
+│       ├── streams.js       # /api/streams/*  (流管理 + 播放列表)
+│       └── system.js        # /api/system/*  (缓存/日志/配置/设置)
+├── public/
+│   ├── index.html           # 主面板
+│   ├── login.html           # 登录页（新）
+│   ├── css/style.css        # 含 v2 追加样式（.stream-select/.import-card/.now-badge）
+│   ├── js/app.js            # v2 重写：多路流/鉴权/导入/删除
+│   ├── vendor/              # 本地化：bootstrap/icons/sortable + woff2
+│   ├── covers/              # 本地化封面（每首一个 jpg）
+│   └── favicon.ico/.png
+├── scripts/fetch_vendor.py  # 一次性下载前端 CDN 资源（已跑过）
+├── audio/                   # 音频（5 首 mp3，已 gitignore）
+├── hls/                     # 直播输出 hls/{streamId}/index.m3u8
+├── hls_cache/               # 切片缓存 hls_cache/{fileHash}/
+├── tmp/uploads/             # multer 上传临时目录
+└── test_api.py / test_e2e.py / test_write.py / test_enrich.py  # 测试脚本
+```
+
+---
+
+## 3. 数据模型（SQLite, src/db.js）
+
+```sql
+songs(id, file UNIQUE, name, artist, cover, duration, file_size,
+      heat, cache_status, created_at)
+  -- file 存「文件名」不是绝对路径（可移植）
+  -- cover 存 web 路径如 /covers/xxx.jpg
+
+streams(id PK, name, enabled, current_pos, media_seq, created_at)
+  -- 默认流 id='main'，不可删除
+
+stream_playlist(id PK, stream_id, song_id, position)
+  -- 每路流独立播放列表，外键 CASCADE
+
+settings(key PK, value)
+sessions(token PK, created_at, expires_at)
+```
+
+**关键**：切片缓存 `hls_cache/{md5(文件名)}/` 与「流」无关，多路共享，省空间。
+
+---
+
+## 4. API 清单
+
+除 `/api/auth/*`、`/hls`、`/hls_cache`、静态资源、`/login` 外，**全部需登录**。
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/auth/login` | `{password}` → 设 cookie |
+| POST | `/api/auth/logout` | 登出 |
+| GET | `/api/auth/me` | 登录状态 |
+| GET | `/api/resources` | 资源列表（含 cacheSize/cover） |
+| GET | `/api/music/search?keyword=` | 网易云搜索 |
+| POST | `/api/music/detail` | `{id}` |
+| POST | `/api/music/download` | `{id,name,artist,albumImage}` |
+| POST | `/api/music/import` | **multipart**：audio + title + artist |
+| POST | `/api/music/delete` | `{file}` 级联删 |
+| POST | `/api/music/delete-batch` | `{files:[]}` |
+| POST | `/api/music/enrich` | `{file, skipMatch?}` 重匹配元数据 |
+| GET | `/api/streams` | 流列表 |
+| POST | `/api/streams` | `{id,name}` 创建 |
+| DELETE | `/api/streams/:id` | 删除（main 不可删） |
+| POST | `/api/streams/:id/start\|stop` | 启停 |
+| GET | `/api/streams/:id/playlist` | 播放列表（含 entryId/isCurrent） |
+| POST | `/api/streams/:id/playlist/add` | `{file}` |
+| POST | `/api/streams/:id/playlist/remove` | `{entryId}` |
+| POST | `/api/streams/:id/playlist/reorder` | `{order:[entryId...]}` |
+| POST | `/api/streams/:id/playlist/clear\|next\|prev\|jump` | |
+| GET | `/api/system/cache` | 缓存占用 |
+| POST | `/api/system/cache/cleanup` | 手动清理 |
+| GET | `/api/system/logs?tail=` | 日志 |
+| GET | `/api/events` | SSE（需 cookie 鉴权） |
+
+**统一返回**：`{ok:true, ...}` 或 `{ok:false, error:"..."}`。
+
+---
+
+## 5. 直播流地址
+
+- 默认：`/hls/main/index.m3u8`
+- 其它：`/hls/{streamId}/index.m3u8`
+- 切片：`/hls_cache/{hash}/indexN.ts`
+
+---
+
+## 6. 关键设计决策（勿轻易推翻）
+
+1. **SQLite 用 better-sqlite3 + WAL**：单进程应用，同步 API 最省事；WAL 解决读写互斥。用户曾担心并发，已解释并落地。
+2. **不迁移 v1 的 JSON 数据**：用户明确说旧数据不要。
+3. **鉴权选"中档"**：整站 Cookie 会话登录，面板+API 锁，**HLS 流不锁**（播放器难带 cookie）。
+4. **封面/资源全本地化**：`public/covers/` 存封面，`public/vendor/` 存前端库；系统字体替代 Google Fonts。
+5. **songs.file 存文件名**：不是绝对路径，迁移目录不失效。
+6. **导入先落 tmp 再 rename**：避免 chokidar 扫到半截文件。
+
+---
+
+## 7. 测试方法
+
+服务起来后（svc005 / 或新起）跑：
+
+```cmd
+cd /d F:\music_online\demo
+set PYTHONIOENCODING=utf-8
+python test_api.py     # 16 项：鉴权/资源/流/缓存/日志
+python test_e2e.py     # 17 项：静态资源/登录/首页/HTML元素
+python test_write.py   # 5 项：导入 + 删除（用 tmp 副本，不动原曲）
+python test_enrich.py  # 给 5 首补封面（已跑过，5/5 成功）
+```
+
+上次全绿：**38/38**。但**注意**：这些只测了 HTTP 层，**浏览器端 JS 交互没自动化测过**。
+
+---
+
+## 8. 已完成清单
+
+- [x] SQLite 替换 JSON（5 表 + WAL）
+- [x] 级联删除 `/api/music/delete` + 批量
+- [x] 多路流 LiveStream 类 + 每路独立播放列表
+- [x] Cookie 会话鉴权 + 登录页 + 鉴权绕过漏洞修复
+- [x] 本地上传导入（multer）+ 元数据自动匹配
+- [x] 封面本地化 + vendor 本地化 + 系统字体
+- [x] 日志系统（分级/落盘/面板可查）
+- [x] API 统一返回结构
+- [x] 优雅退出补 FFmpeg 子进程 kill
+- [x] 模块化拆分（1233 行单文件 → src/ 12 模块）
+- [x] 前端 app.js 重写（多路流/鉴权/导入/删除）
+
+---
+
+## 9. ⚠️ 待排查 / 已知问题（重点！）
+
+### 9.1 用户反馈"功能还有问题" —— **具体未明，需先问清楚**
+> 下一会话**第一件事**：问用户到底哪个功能出问题（现象、复现步骤、控制台报错）。
+> 可能的方向见下。
+
+### 9.2 前端多路流管理 UI **没做**
+- 后端能创建/删除流，但前端只有一个**切换下拉框**（`#streamSelect`），**没有"新建流/删除流"的界面**。
+- 若用户说"多路流用不了"，大概率指这个。
+
+### 9.3 前端 JS 交互未实测
+- `public/js/app.js` 是重写的，只做了语法检查 + HTTP 层测试。
+- **未验证**：SSE 实时刷新、拖拽排序 reorder、mini player、页面切换、导入进度提示等浏览器行为。
+- 建议：手动开浏览器点一遍，看 Console 有无报错。
+
+### 9.4 潜在 Bug 点（未确认）
+- `livestream.js` 的 `enforceCacheSizeLimit` 依赖 `streams` Map，若在 `loadStreams` 前被调用可能拿到空集。
+- `scanner.js` 里 `const parsed = meta.sanitizeFileName;` 是**死代码**（无用变量），无害但可清理。
+- `metadata.js` 的 `enrichSong` 每次启动会对缺元数据的歌重新请求网易云，网络慢会拖启动。
+- 多路流同时播放不同歌时，FFmpeg 预生成队列（并发默认 3）可能跟不上，需观察。
+- `app.js` 里 `esc()` 用了 `String.fromCharCode(38)` 拼接，是**为了绕过工具层的 XML 实体转义**，不要"优化"回字面量 `&`，否则写文件时会被工具吃掉。
+
+### 9.5 前端 HTML 元素 ID 对照（改前端时用）
+- 头部：`cacheInfo` `streamSelect` `liveLink` `btnLogout`
+- 搜索页：`musicId` `btnSearch` `parseHint` `parsedId` `musicPreview` `musicCover` `musicName` `musicArtist` `musicDetails` `btnDownload` `searchResults` `searchTips`
+- 导入卡片：`importCard` `importFile` `importTitle` `importArtist` `btnImport` `importProgress`
+- 资源页：`resourceCount` `resourceSearch` `resourceList`
+- 列表页：`playlistCount` `btnClear` `playlistList`
+- mini player：`miniPlayer` `mpProgress` `mpBody` `mpCover` `mpName` `mpArtist` `mpTime` `mpPlay` `mpExpand` `musicPlayer`
+- 导航：`.nav-tab[data-page]`，页面 `pageSearch/pageResources/pagePlaylist/pageAbout`
+
+---
+
+## 10. 工具层踩坑记录（写代码时注意）
+
+1. **XML 实体转义会吃掉 `&` `"`**：写 JS/CSS 含这些字面量时，用 `String.fromCharCode(38)` 或字符码构造，别直接写。
+2. **replace_lines 多段锚点行号易偏**：先 `file_read` / python 打印实际行号再改；改错了整批不生效或误删。
+3. **smart_patch 行数必须精确**，且锚点行号要对；容易失败，简单改动优先 replace_lines。
+4. **后台服务用 action background="true"**（不要 `start /b`，会粘连卡死）。
+5. **service_stop 会连子进程一起杀**（node 的 ffmpeg 子进程会被带走）。
+6. **Windows 无 `head`/`tail`**，用 `findstr` 或 python。
+7. **改完源码要重启 node**（磁盘 .py/.js 改了，运行中的进程不生效）。
+8. **Python 跑 Windows 输出**：`chcp 65001 && set PYTHONIOENCODING=utf-8`。
+9. **`node -X utf8` 是错的**（那是 Python 的选项），node 直接 `node` 即可。
+
+---
+
+## 11. 当前运行态
+
+- 后台服务：`svc005`（PID 15308 起），日志 `service_log svc005`
+- DB：`data.db`（5 首歌曲，封面已本地化）
+- 缓存：`hls_cache/` 5 个目录，约 28MB
+- Git 工作区：干净（最新 `a4745db`）
+
+---
+
+## 12. 下一步建议（按优先级）
+
+1. **问清用户的"问题"具体是什么** ← 最优先
+2. 补前端"新建/删除流"UI（若需求确认）
+3. 浏览器手动过一遍所有交互，修 Console 报错
+4. 清理死代码（§9.4）
+5. 正式化：设置固定 `PANEL_PASSWORD`，写 systemd/服务化启动
+6. 补多路流并发压力测试