reader/docs/architecture.md

架构与数据边界

本文记录为什么这样设计，尤其是那些一旦写错就很难回头的决策。 产品设计文档（v0.2）里的约束在这里落成了实现，逐条对应。

---

1. 数据边界

位置	内容	读写
BOOKS_DIR (/books)	用户自己的电子书	只读
DATA_DIR (/data)	SQLite、封面缓存、令牌密钥	读写
客户端本地	离线书文件缓存、本地进度	读写

服务端是唯一真相源。客户端只承担「渲染 + 缓存」。

只读挂载的强制手段

src/config/index.ts 在启动时断言 DATA_DIR 不在 BOOKS_DIR 内，否则拒绝启动。 这不是文档里的君子协定，是运行时会拦下来的硬约束。

扫描器与所有文件访问都经过 src/lib/paths.ts 的 resolveInside()—— 唯一的路径解析出口，../ 逃逸会抛 PATH_TRAVERSAL。 扫描时也不跟随符号链接：指向挂载点外的软链会读到用户没打算共享的文件。

封面缓存写在 DATA_DIR/covers/，不写在书旁边。

---

2. 书籍主键

id = sha256( (dc:identifier ?? '').toLowerCase() + '\0' + sha256(fileBytes) )

为什么不用文件路径

用户的真实行为是持续整理书库：改名、分目录、加前缀。

场景	路径做主键	当前设计
重命名 三体.epub → 刘慈欣 - 三体 (修订版).epub	进度全丢	进度保留
移动到另一个目录	进度全丢	进度保留
同一本书放两份	书架出现两条	合并成一条
重新编码的同名文件	误认为同一本	视为不同副本

第二列是自建书库产品最常见的差评来源，所以这条必须在上线前定死。

为什么哈希也要参与

只用 dc:identifier 不行：很多自制/盗版 EPUB 没有 identifier，或者多本书共用 一个占位 identifier。只用哈希也不行：同一本书不同来源的副本哈希不同，无法合并。

两者结合：identifier 提供稳定的锚点，哈希保证「字节不同就是不同的副本」。 identifier 缺失时退化为纯哈希，行为仍然正确（只是无法跨副本合并）。

文件表与书表的分离

book_files 记录磁盘上的文件（rel_path、size、mtime），books 记录书。 多对一：一本书可以有多份副本。

文件被删时 missing=1，不立即删记录——用户可能只是临时拔了移动硬盘。 但一旦这本书已经有了别的可用文件，旧的行就是纯噪声，会被清掉， 否则反复整理书库会让文件表无限增长。

只有「没有任何可用文件」且「用户没手动加进书架」的书才会被删除。 宁可显示一本暂时不可用的书，也不能删掉读者精心整理过的书架条目。

---

3. 增量扫描

两阶段变更检测（Scanner.indexFile）：

1. mtime + size：便宜，跳过绝大多数文件
2. 内容哈希：权威，确认字节真的变了

只有第一阶段判断"可能变了"才读文件算哈希。所以每 60 秒轮询一次也很轻。

Scanner.scan() 对并发调用做去重（共享同一个 Promise）， 避免定时器和手动触发同时砸磁盘。

---

4. 元数据优先级链

1. 手动修改（metadata_overrides 表）
2. EPUB 内嵌（dc:* + calibre meta）
3. provider 补丁（只填空缺）
4. 文件名解析

关键实现细节

books 表存的是第 2/3/4 层的结果。第 1 层单独一张表，读取时叠加 （ShelfService.toDto → applyOverrides）。

这样做的原因：扫描器可以放心地刷新 books 表，因为手动修改根本不在那张表里， 不可能被覆盖。

books.source 记录的是基础值的来源（embedded / filename / provider:x）， 不记录 manual。手动修改过的字段由 DTO 的 manualFields 单独返回。 保持来源干净，撤销单个字段时才能正确回落到原始值。

文件名解析的保守策略

中文电子书里 书名 - 作者 和 作者 - 书名 都极常见，没有标记时无法区分。

因此只在有证据时才切分：

• 《书名》 → 这一侧是书名
• 著 / 编 / 译 → 这一侧是作者
• 一侧是中文人名（2-4 字且首字为常见姓氏）→ 另一侧是书名
• 一侧是拉丁文人名 → 另一侧是书名
• 都不满足 → 整串保留为书名，作者留空

最后一条是刻意的：漏一个作者，读者手动补一下就好；猜错一个作者， 书就被归到错误的人名下，而且他未必会发现。

其余正则也踩过坑，值得记下来：

• 系列正则 [【\[]...[】\]] 里 \[ 在字符类中不转义，会把分隔符 ' - ' 吃掉， 导致 金庸 - 射雕英雄传 变成 title=金庸, author=射雕英雄传。改成显式括号对匹配。
• 「（第1卷）」这种卷标，书名是作品本身，不是「第」。要先剥离再切分作者， 且剥离要按完整括号组做，否则会留下 射雕英雄传（第1卷 这样的半截括号。

---

5. 同步与冲突合并

为什么是 last-writer-wins

一台设备属于一个读者。多设备之间不存在"编辑冲突"，只存在"某台设备落后了"。 所以 LWW 是正确语义，不需要 CRDT 或向量时钟的复杂度。

墓碑

笔记删除写 deleted=1 而不是 DELETE。

否则：手机离线时删了一条笔记 → 平板（也离线，数据更旧）重连 → 把笔记推回来 → 已删除的笔记复活。墓碑让这个时序变得无害。

批次原子性

SyncService.push 整个批在一个事务里。断网不会留下写了一半的进度。

增量拉取

GET /api/v1/sync?since=<上次的 serverTime>。客户端记住上次返回的 serverTime， 每次只拿增量。移动网络下重连很便宜。

---

6. 认证与安全

• scrypt 做口令哈希（内置模块，无原生依赖）。比较用 timingSafeEqual。
• 登录时即便用户不存在也跑一次哈希比较，避免用时间差枚举用户名。
• 访问令牌是 HS256 签名的无状态令牌；刷新令牌是不透明随机串存库，可按设备撤销。
• 改口令 / 停用账号会撤销该用户所有会话。
• 每个请求都从库里重读用户，不信任令牌里的 role——停用账号立即失效。
• 刷新令牌轮转：用过即废，降低泄露窗口。

不要重新引入原生依赖

镜像构建的稳定性直接决定部署成功率，而部署门槛是最大的获客阻力。 better-sqlite3、argon2、bcrypt 都需要构建时的 make/gcc， 在部分 NAS 环境会直接装不上。

node:sqlite 和 node:crypto 的 scrypt 都是内置的，所以当前依赖树里 没有任何需要编译的包。

---

7. 向后兼容承诺

自部署用户不会及时升级。所以：

• API 只做加法：加字段、加端点。不改已有字段语义、不删端点。
• 数据库 schema 用 CREATE TABLE IF NOT EXISTS，升级时新增列/表，不动旧的。
• 错误响应格式全站统一，客户端可以一直用同一套解析逻辑。

---

8. 客户端渲染

已落地。产品设计里的关键决策：不要直接套 Readium Mobile。 Readium 用 Readium CSS 主动接管排版、覆盖出版方样式，这与本产品 「忠实还原精排书设计」的核心差异化直接冲突。

实际方案：

• 原生外壳（Kotlin）只负责：文件与缓存、手势、账号、连通性
• 渲染层是 WebView + 自研 CSS 干预策略，保留作者样式、只做最小覆盖
• 参考 readium-css 的变量组织方式，但不引入它的默认接管行为

只有一份渲染层

Android 不重写渲染，它加载的是同一份 web/ 产物。这不是为了省事， 而是因为排版策略一旦有第二份实现就一定会分叉，而排版正是差异点所在。

两边共用的抽象在 web/src/core/platform.ts：传输、键值存储、二进制存储、连通性。 Android 只覆盖它真正能做得更好的部分——连通性和设备名——其余全部复用。

Android 用 https 资产源，不用 file://

把打包好的 Web 应用塞进 assets，最直觉的加载方式是 file:///android_asset/...。 这条路对这个产品是走不通的：从 file:// 源发出的 fetch() 是不透明的跨源请求， 所有访问服务端的调用都会被拦，而通常的绕法是把 web security 关掉—— 那就等于把 WebView 变成一扇敞开的门。

用 WebViewAssetLoader 从 https://appassets.androidplatform.net/ 提供同样的文件， 拿到的是一个正常的安全源：请求按普通 CORS 走，正好和服务端的 CORS 策略对上； isSecureContext 为真，IndexedDB 等 API 与浏览器里行为一致。 这一个选择就是「一份 bundle 两个宿主」能成立的前提。

精排 CSS：干预策略

按重要程度排序的三条原则，写在 web/src/styles/reader.css 里：

1. 不设任何属性，除非不设会坏。
2. 每个可调项都是默认 inherit 的可继承自定义属性——「关」的意思是「不动它」， 不是「用我们的默认值」。这一点很关键：给行距写死一个具体值，会把一本按章节 变行距的书压平。
3. 任何改变作者意图的行为都是用户主动开启，且持久化，绝不是默认。

实际 override 只有七处，每处都在 CSS 注释里写了为什么：图片/表格/pre 在窄屏会撑破 布局、ruby 振假名在 16px 下按默认 50% 太小、长中文标题不换行会溢出。除此之外不动。

对比一下被删掉的做法：reset 样式表、统一的「阅读主题」、给 p 加边距。 它们都能让排版「看起来一致」，而一致性恰恰是这里要避免的东西。

书的样式隔离在 shadow root 里

书里一条 p { color: red } 不能改到书架，App 的 .topbar 也不能被书撞上。 iframe 同样能隔离，但每次换章要重建文档：滚动位置丢失、Android 上内存翻几倍。 shadow root 拿到完整样式隔离且没有文档边界，App 还能进去做分页和取选中。 关键是不往 shadow root 里注入任何 reset。

书不能联网

加载时把章节里所有本地引用改写成内部 reader-res: 协议，渲染层从内存资源表解出； 绝对 URL 原样保留，然后被 CSP 挡掉。这样一本来路不明的书无法把阅读行为报到远端。 资源按需解出而不是预展开——不然打开一本带大图的 EPUB 会先把整个包塞进内存。

阅读位置格式

r1:<偏移>:<章节 id>。三点都是踩过之后定的：

• 版本前缀：服务端把 locator 当不透明字符串长期保存，客户端将来改格式时必须 能认出「这不是我认识的格式」。r1 给了这个能力。
• 章节 id 放最后：章节 id 是文件路径，会含冒号。只从前两个冒号切、剩下全保留， 是唯一不会丢数据的解析方式。
• 偏移是章节内的比例，不是像素、不是 CSS 列号。列号会随字号变化， 于是读者一调字号，位置就跳到另一个句子上——阅读 App 能犯的最让人恼火的错误之一。

待发送队列，而不是「每次都全发」

离线队列记的是脏集合：哪些记录还没送到服务端，而不是「当前全部状态」。

两者在一种情况下结果不同，而这种情况一定会发生：记录在请求发出之后、响应到达之前 被修改了（读者在同步进行时翻了一页）。脏集合下，这次更新仍然是脏的，要等它自己 的确认才清除；「全发」模式下，它会被那个更早的响应顺手清掉，然后永远送不到服务端—— 一个丢失的阅读位置，是这个产品最不能有的失败。

离线队列的抗崩

队列在本地镜像里，不在内存里。所以读到一半直接杀进程，位置不会丢—— 下一次启动接着送。笔记删除同样写墓碑后再入队，避免离线设备让已删笔记复活。

TXT 的编码与章节

本地书库里 TXT 占比很大，而它既没有结构也没有编码声明。

编码：先严格校验 UTF-8（自己实现，不用 TextDecoder 的宽松模式——宽松模式永远 「成功」，于是你永远发现不了自己解错了）。校验失败再依次试 GB18030、Big5。 结果里带 guessed 标记，界面上告诉用户选了哪个并允许手动覆盖。

章节：TXT 没有目录，只能从标题推断。策略是宁可少认，不要错认—— 一个 800 字的段落以「第三章」开头时不能当标题，而正文里提到「他在第二章读过」 更不能当标题。两条都有测试固定住。推断不出章节时按长度分段： 一本五千章的网文如果变成一整节，分页会直接卡死。

漫画的页序

按自然序排（1, 2, 10 而不是 1, 10, 2）。排错不是观感问题，是故事被静默打乱。 文件名无信息量时用页序当标题，因为 a1b2c3.png 对读者没有意义。

一页一个 section

漫画和 PDF 是 layout: 'fixed'，每页一个 section，由分页器整屏推进。 固定布局的宿主不做滚动容器——在横向分页器里嵌一个滚动区会产生 Android 上经典的「页面自己往边上飘」bug。