mirror of
https://github.com/hectorqin/reader.git
synced 2026-11-10 21:11:08 +08:00
hectorqinandClaude Opus 5.5
120827bad6
Audit of README, docs/, android/README.md, android/contract.md and CLAUDE.md against the current server, web and Android code: V3 navigation and settings locations, Docker Hub release images, GitHub clone URL and CI, missing API endpoints and error codes, architecture of lazy chunks/themes/sources, media pages and routes, the Android bridge contract, and the new file-management and member-upload permissions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
33 lines
3.6 KiB
Markdown
33 lines
3.6 KiB
Markdown
# 影音模块架构
|
||
|
||
影音覆盖电影、剧集、音乐和有声书，在统一应用外壳（首页、书架、影音、我的）中使用 `#/media/...` 路由，与阅读共用 V3 主题（`shared/theme`）；服务端在独立 Worker 线程中运行。首页（`#/`）汇总继续阅读与继续观看/收听，阅读正文引擎由 React 页面托管生命周期。
|
||
|
||
## 数据与服务边界
|
||
|
||
- 阅读与账号数据保存在 reader.db，影音目录、版本、章节、收藏、播放进度和配置保存在 media.db。两库及签名密钥必须成对备份和恢复。
|
||
- 主服务先开放阅读，再异步启动影音 Worker。准备中返回 MEDIA_STARTING，失败返回 MEDIA_UNAVAILABLE；不会把影音启动或扫描任务排入阅读请求队列。
|
||
- MediaLibraries 管理媒体库权限与接入配置；MediaStorage 隔离本地目录和 OpenList。媒体资源引用不是外部下载 URL。
|
||
- MediaScanner 收集资源与资料，发布阶段通过独立事务原子更新目录，保留稳定身份、人工整理及已存在的进度。目录或远端旁车读取失败不发布不完整快照。
|
||
- 查询线程、发布线程及账号权限投影的边界见[写入隔离](media-write-isolation.md)。
|
||
|
||
## 领域结构
|
||
|
||
媒体库限定内容类型和访问范围。作品（电影、剧集、单集、歌手、专辑、曲目或有声书）可以包含多个版本；版本包含有序章节或播放部分，每部分引用一个文件资源。一个文件可产生多个内嵌章节，因此文件、作品、版本、章节不能混用身份。
|
||
|
||
手工调整作品归属、版本合并或拆分不会移动源文件；扫描保留人工组织和资料覆盖。不同版本不会因名称相同就自动混合播放。
|
||
|
||
## 元数据与播放
|
||
|
||
本地库使用 ffprobe 探测标签、编码、时长和章节，并读取同目录 NFO、封面、歌词、字幕。在线资料由 TMDB 和 MusicBrainz 适配器提供；用户审阅候选后确认覆盖，原文件不写回。
|
||
|
||
OpenList 使用 fs/list 与 fs/get，只读扫描，按需解析临时下载地址。播放方式由服务配置「媒体播放」决定：自动（默认）和直连模式在流票据鉴权后以 307 跳转让浏览器直连临时地址，失败或需要时由 Reader 授权接口代理 Range；代理模式始终经服务端转发。令牌不交给前端或下载源；远程内嵌资料暂不探测。具体配置与驱动限制见[OpenList](media-openlist.md)。
|
||
|
||
Web 音频使用浏览器媒体能力，视频采用 DPlayer；Android 使用 Media3。播放会话、流票据、进度并发和即时撤权由服务端控制。后台授权与进程恢复见[后台播放](media-background-auth.md)。不提供转码、TVBox/JAR、云盘登录或影音离线下载。
|
||
|
||
## 代码与维护入口
|
||
|
||
- 服务端：[media 模块](../server/src/media/)、[HTTP 路由](../server/src/http/routes/media.ts)（在影音 Worker 中注册）、[主线程转发](../server/src/http/routes/media-proxy.ts)。
|
||
- 前端：[media feature 模块](../web/src/features/media/)、[React 页面路由](../web/src/app/router/routes.tsx)。
|
||
- [使用说明](media-user-guide.zh-CN.md)、[导航约定](media-navigation.md)、[验证方式](media-validation.md)、[性能测量](media-catalog-performance.md)。
|
||
- [冻结的 v2 原型](prototypes/media/v2-review/index.html)是布局参考；实际功能、地址和主题生命周期以源码及当前说明为准。当前设计基准是 [V3 统一原型](prototypes/Reader%20V3%20·%20统一设计系统与完整原型.html)。浏览器评审截图和报告写入被忽略的 `artifacts/media`（影音评审工具）或 `artifacts/ui-review`（`npm run ui:review`），不提交到 `docs/`。
|