refactor(server): 迁移到 Fastify 5 + 完善文档与路由参数适配

README.md

@@ -12,26 +12,30 @@
 
 ```bash
 npm install
-npm start        # 默认端口 3300，可用 PORT 环境变量修改
+npm start        # 默认端口 16688，可用 PORT 环境变量修改
 npm test         # 运行冒烟测试（自动启动/关闭本地服务器）
 ```
 
 ## HTTP 接口
 
+规范风格使用路径参数；旧版 query 风格（如 `/url?source=kw&id=228908`）保留兼容，已标记 deprecated。
+
 | 接口 | 说明 |
 | --- | --- |
 | `GET /search?name=xxx&singer=xxx&source=kw&page=1&limit=20` | 搜索歌曲（source 省略则聚合所有平台） |
 | `GET /find?name=xxx&singer=xxx&albumName=xxx&interval=xxx` | 精确匹配搜索（跨平台去重排序） |
-| `GET /url?source=kw&id=228908&quality=320k` | 获取播放地址（quality: 128k/320k/flac/flac24bit） |
-| `GET /lyric?source=kw&id=228908` | 获取歌词（返回 lyric/tlyric/lxlyric） |
-| `GET /pic?source=kw&id=228908` | 获取封面 |
-| `GET /boards?source=kw` | 榜单列表 |
-| `GET /board?source=kw&id=93&page=1` | 榜单详情 |
-| `GET /hotSearch?source=kw` | 热搜列表 |
-| `GET /songList?source=kw&page=1` | 歌单列表 |
+| `GET /url/:source/:id?quality=320k` | 获取播放地址（quality: 128k/320k/flac/flac24bit） |
+| `GET /lyric/:source/:id` | 获取歌词（返回 lyric/tlyric/lxlyric） |
+| `GET /pic/:source/:id` | 获取封面 |
+| `GET /boards/:source` | 榜单列表 |
+| `GET /boards/:source/:boardId` | 榜单详情 |
+| `GET /hot-search/:source` | 热搜列表 |
+| `GET /song-list/:source?page=1` | 歌单列表 |
+| `GET /sources` | 平台列表（音质与能力） |
 | `GET /health` | 健康检查 |
+| `GET /docs` `/redoc` `/openapi.json` | 接口文档（Swagger UI / ReDoc / OpenAPI 3.1） |
 
-统一返回格式：`{ code: 0, data: ... }` 成功；`{ code: 非0, msg: ... }` 失败。
+统一返回格式：`{ code: 0, data: ... }` 成功；`{ code: 非0, msg: ... }` 失败。状态码语义：422 参数校验失败、404 接口或平台不存在、405 方法不允许（带 Allow 头）、502 上游平台失败。
 
 所有接口默认返回 `Access-Control-Allow-Origin: *`，可直接在浏览器/前端调用。
 
@@ -45,10 +49,18 @@ npm test         # 运行冒烟测试（自动启动/关闭本地服务器）
 
 ```
 src/
-  server.js         HTTP 服务器入口（npm start 实际启动文件）
-  index.js          SDK 根模块（工具函数聚合导出）
+  server.js         HTTP 服务器入口（npm start 实际启动文件，Fastify）
+  routes.js         业务路由（JSON Schema 校验 + OpenAPI 元数据）
   smoke-test.js     冒烟测试（自动启动本地服务器）
+  index.js          SDK 根模块（工具函数聚合导出）
+  http/             HTTP 层
+    api-error.js    业务错误类型（404/502 等 → 统一 JSON 响应）
+  openapi/          文档层
+    components.js   OpenAPI 共享 schema（与路由校验同源）
+    ui.js           ReDoc 页面模板
   apis/             各平台 URL 直连实现（kw/kg/tx/wy/mg/bd）
+    lx-source.js    lx 聚合源懒加载入口
+    lx-source-ivm.js isolated-vm 隔离执行器
   common/           公共模块
     request.js      HTTP 请求（可取消、自动 JSON 解析、gzip/deflate 解压）
     utils.js        工具函数（sizeFormate/formatPlayTime/dateFormat 等）
@@ -58,17 +70,17 @@ src/
     lyricDecode.js  酷我/QQ 歌词解码（替代原 Electron 主进程处理器）
     qrcDecode.js    QQ 歌词 3DES 解密（纯 JS 移植）
     lyricUtils/kg.js 酷狗 krc 歌词解码
-musicSdk/          洛雪音乐聚合 SDK（搜索/歌词/榜单等核心逻辑）
+musicSdk/           洛雪音乐聚合 SDK（搜索/歌词/榜单等核心逻辑，TypeScript 源码）
   index.js          平台聚合入口
   request.js        SDK 请求模块（转接 src/common/request.js）
   message.js        SDK 消息模块（转接 src/common/message.js）
 ```
 
+> TypeScript 源码（`src/apis/index.ts`、`musicSdk/**/*.ts`）经 `npm run build`（tsc）就地发射为 `.js` 产物后运行。
+
 ## 关于 lx-music-source-v5.js
 
-项目目录下的 `lx-music-source-v5.js` 是第三方混淆音源脚本。由于内容不可审计，且 Node.js `vm` 不是安全沙箱，服务器代码中**不再直接加载或执行该脚本**，也不依赖它获取播放地址。
-
-如需复用其服务端能力，需要其提供去混淆源码或完整 API 文档。当前 `docs/lx-source-signing.md` 记录了已逆向出的确定性签名部分（`e`、`s2`、`s3`），但脚本内部用于 `to` / `si` 的混淆逻辑尚未安全还原，因此未集成到生产路径。
+项目目录下的 `lx-music-source-v5.js` 是第三方混淆音源脚本（`lx` 平台）。由于内容不可审计，它**不会在服务器进程内直接执行**，而是通过 `src/apis/lx-source-ivm.js` 使用 isolated-vm 硬隔离加载：脚本在独立 V8 沙箱中发起网络请求，服务器只做日志审计与 HTTP 白名单管控。其请求签名中的 `to`/`si` 两项为脚本内部哈希，无法脱离脚本复算，直连签名方案已放弃，详见 `docs/lx-source-ivm.md`。
 
 ## 已知限制