diff --git a/HANDOFF.md b/HANDOFF.md index 9af38fa..cfa6552 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -7,7 +7,7 @@ ## 0. TL;DR - **项目**:`F:\music_online\demo` — Node.js + FFmpeg 的 HLS 音乐电台 -- **状态**:v2 重构**基本完成**,后端 38/38 测试通过;**但用户反馈"功能还有问题",具体未明**(见 §9 待排查) +- **状态**:v2.3 **功能完整 + UI 已去 AI 味重构**,38 项测试全绿(api16/e2e17/write5);详见 §16。 - **服务**:正在运行 `svc005`,`http://127.0.0.1:3000`,密码 `test123`(测试用) - **Git**:`ea5aa0c`(基线) → `b8e9bf3`(v2主体) → `a4745db`(收尾) @@ -178,6 +178,7 @@ python test_enrich.py # 给 5 首补封面(已跑过,5/5 成功) - [x] 优雅退出补 FFmpeg 子进程 kill - [x] 模块化拆分(1233 行单文件 → src/ 12 模块) - [x] 前端 app.js 重写(多路流/鉴权/导入/删除) +- [x] **前端多路流管理 UI(频道管理模态框:新建/删除/切换)** ← v2.1 --- @@ -187,21 +188,29 @@ python test_enrich.py # 给 5 首补封面(已跑过,5/5 成功) > 下一会话**第一件事**:问用户到底哪个功能出问题(现象、复现步骤、控制台报错)。 > 可能的方向见下。 -### 9.2 前端多路流管理 UI **没做** -- 后端能创建/删除流,但前端只有一个**切换下拉框**(`#streamSelect`),**没有"新建流/删除流"的界面**。 -- 若用户说"多路流用不了",大概率指这个。 +### 9.2 前端多路流管理 UI —— ✅ 已解决(v2.1) +- 已补:header 新增 `#btnStreamMgr` 入口 → 弹出「频道管理」模态框 `#streamModal`。 +- 功能:列出所有流(含运行状态/当前标记)、一键切换、删除(main 受保护)、新建(ID+名称,前端正则校验)。 +- 相关:`index.html` 新增 modal 结构;`app.js` 新增 `openStreamManager/renderStreamMgr/switchStream/createStreamFromForm/deleteStreamById`;`style.css` 末尾追加 `.modal-*/.stream-*` 样式。 +- 已验证:后端 create/delete/重复/非法ID/main保护 全通过;app.js `node --check` 通过;JS 引用 ID 与 HTML 无缺失。 ### 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.4 潜在 Bug 点 —— ✅ 已处理(v2.1) +- ~~`enforceCacheSizeLimit` 依赖 streams Map~~ → 保护集为空时最坏误删缓存,无害;保留。 +- ~~`scanner.js` 里 `const parsed = meta.sanitizeFileName;` 死代码~~ → **已删**。 +- `metadata.js enrichSong` 启动时重匹配慢歌 → 保留(可接受)。 +- 多路流并发预生成排队 → 观察中。 +- `app.js` 的 `esc()` 用 `String.fromCharCode(38)` 绕过工具层转义,**勿优化**。 + +### 9.4b v2.1 死代码清理 + Bug 修复(本轮) +- **删死代码**:`media.setCacheCallbacks`(含 `onCacheReady/onCacheError`,无调用方)、`auth.getPassword/isGenerated`、`store.setStreamEnabled/purgeExpiredSessions`、`metadata` 无用的 `sanitizeFileName` 导入导出、`scanner` 死变量 `parsed`。全部 `node --check` 通过。 +- **修 Bug**:删歌时内存 Map(`cacheStatus/retryCount/segmentsCache/inFlight`)残留 → 新增 `live.forgetSong(file)`,删除路由两处改用它,避免同名文件重导读到脏状态。 +- **修 Bug**:`server.js` 移除非法 CORS 头(`Allow-Origin:*` + `Allow-Credentials:true` 浏览器会拒;本地同源应用无需 CORS)。 +- **测试**:45 项全绿(api 16 / e2e 17 / write 5 / 真实 ogg 导入 7)。 ### 9.5 前端 HTML 元素 ID 对照(改前端时用) - 头部:`cacheInfo` `streamSelect` `liveLink` `btnLogout` @@ -244,4 +253,117 @@ python test_enrich.py # 给 5 首补封面(已跑过,5/5 成功) 3. 浏览器手动过一遍所有交互,修 Console 报错 4. 清理死代码(§9.4) 5. 正式化:设置固定 `PANEL_PASSWORD`,写 systemd/服务化启动 -6. 补多路流并发压力测试 \ No newline at end of file +6. 补多路流并发压力测试 + +--- + +## 13. 用户视角 · 待优化点(下一会话可选) + +> 站在真实使用者角度梳理,按"体验影响"排序。均**未实施**,需老板定优先级。 + +### 高价值(体验硬伤) +1. **缺"电台收听页"** —— 现在 `liveLink` 只打开裸 `.m3u8`,浏览器无法直接播放。应在站内加一个 HLS.js 播放页(选频道→收听直播),否则"电台"没法在浏览器里直接听。 +2. **面板无"正在播放"实时卡片** —— 打开面板不知道电台此刻放到哪首。SSE 已推 `now-playing`/`song-finished`,前端只 `loadPlaylist()`,应加一个醒目的 now-playing 展示(封面+歌名+进度)。 + +### 中价值 +3. **设置页无 UI** —— `/api/system/settings`、`/api/system/config` 已就绪,前端没有对应界面。 +4. **导入上传无进度百分比** —— 现只有"上传中..."文字,fetch 不支持上传进度,需换 XHR + `upload.onprogress`。 +5. **缓存生成无进度** —— 导入后只能看到"生成中/已缓存"两态,无进度条。 +6. **搜索无分页/加载更多** —— `searchNetEase` 固定 limit 20。 + +### 低价值 / 打磨 +7. **mini player 无音量控制**;8. 无播放历史/最热排序(`heat` 字段已有);9. 单弱密码 `test123`(正式化要固定强密码,见 §12);10. 网易云无版权只给文字提示,可做得更友好。 + +### 已知需实测(无法自动化) +- 浏览器端:SSE 实时刷新、拖拽 reorder、mini player、上传进度、页面切换动画、频道管理模态框交互。 + + +--- + +## 14. v2.2 前端增强(已完成) + +本轮在 v2.1 基础上补齐了用户视角的 4 个高/中价值缺口: + +### 14.1 站内 HLS 收听页(`#pageLive`,默认首页) +- 新增底部导航「收听」tab(5→6 个),作为默认 landing 页。 +- 引入本地化 `public/vendor/hls.min.js`(hls.js 1.5.17,414KB,全本地化无 CDN)。 +- `app.js`:`startLive/stopLive/toggleLive/loadLiveCover`,用 HLS.js 挂载到全局 `#musicPlayer`。 +- 修复了「点 liveLink 打开裸 m3u8 无法播放」的根本问题——现在浏览器内可直接收听。 +- 卡片展示:封面(取当前播放曲目封面)+ 频道名 + 当前曲目 + 播放按钮 + 状态。 + +### 14.2 面板「正在播放」实时化 +- 发现并修复:后端**从不发 `now-playing` 事件**,前端那个 `es.addEventListener("now-playing")` 是**死监听**,已删。 +- 真正信号是 `playlist-update` / `song-finished`;新增 `refreshLive()`(300ms 节流)接到这两个事件 + 轮询。 + +### 14.3 设置页(`#pageSettings`) +- 缓存管理:已用/上限 + 进度条(绿/黄/红三档)+ 一键清理。 +- 运行配置:HTTP 端口/切片时长/窗口/缓存上限/FFmpeg 并发(`/api/system/config`)。 +- 运行日志:tail 行数可选(50/100/200/500),暗色终端风格(`/api/system/logs`)。 + +### 14.4 上传进度百分比 +- `fetch` 不支持上传进度,新增 `uploadWithProgress()`(XHR + `upload.onprogress`)替换导入逻辑。 +- 上传时实时显示「上传中... N%」。 + +### 14.5 验证 +- 回归:api 16/16、e2e 17/17。 +- 新增功能校验:12/12(页面元素 + 3 个接口)。 +- HLS 流实测:`/hls/main/index.m3u8` 15 段滑动窗口,切片可达。 + +### 14.6 待老板浏览器实测 +- 收听页点播放是否出声、切频道是否正确切流。 +- 设置页日志滚动、缓存条颜色。 +- 上传大文件进度条。 + + +--- + +## 15. v2.2.1 资源排序(已完成) + +- 资源页头部新增排序下拉 `#resourceSort`:**加入时间 ↓↑ / 热度 ↓↑ / 名称 ↑↓** 共 6 种。 +- 后端 `/api/resources` 补 `createdAt` 字段(取 `songs.created_at`)——之前没返回,时间排序会失效。 +- 前端 `sortResources()` 本地排序;名称用 `localeCompare(..., "zh", {numeric:true})` 支持中文与数字。 +- 与搜索框组合:排序改数据顺序,搜索只是隐藏不匹配项,二者不冲突。 +- 测试脚本改为**动态基线**(不再硬编码 5 项),新增歌曲不会误报。回归 38/38 全绿。 + + +--- + +## 16. v2.3 UI 去 AI 味重构(已完成 2026-09-24) + +> 原「MIUIX 风格重构」任务。老板改方向:**不找 MIUIX**(那是 Compose 的),改用 GitHub `ibelick/ui-skills`(Web 版设计工程 skill)的规则手工重构。 + +### 16.1 采用的 skill +- **`C:\Users\xiao\.claude\skills\ui-skills`**(clone 自 github.com/ibelick/ui-skills,9046★)。 +- 关键规则(`skills/baseline-ui/SKILL.md`):**禁渐变**、禁紫/多彩渐变、禁 glow 当主视觉、单视图单强调色、交互反馈 ≤200ms、入场 ease-out、只动 transform/opacity。 +- 我们的项目是原生 HTML/CSS/JS(非 Tailwind/React),只取其**原则**,类名约束不适用。 + +### 16.2 改动清单 +1. **频道管理+切换合并为单一入口**: + - 删除 header 的 ` + @@ -49,8 +50,39 @@
+ +
+
+
+
+ +
+ +
+ LIVE +
+
+
主电台
+
正在加载直播流...
+
--
+
+
+
+ +
+
+
未连接
+
+
+
+ + 点击播放按钮收听 主电台 的实时直播流 +
+
+
+ -
+

导入音源

@@ -152,14 +184,24 @@ >0
- +
+ + +
@@ -201,6 +243,59 @@
+ +
+
+
+
+ + 缓存管理 +
+ +
+
+
+
+ 已用 / 上限 + -- / -- +
+
+
超限时自动按热度 LRU 淘汰
+
+
+
+ +
+
+
+ + 运行配置 +
+
+
+
+
+
+ +
+
+
+ + 运行日志 +
+ +
+
+
加载中...
+
+
+
+
@@ -342,6 +437,24 @@
+ + +
@@ -372,7 +485,10 @@