# 架构与数据边界 本文记录**为什么这样设计**，尤其是那些一旦写错就很难回头的决策。 早期产品设计中的约束在这里落成了实现，逐条对应；当前行为以代码和 API 文档为准。 来源扩展与插件系统的设计、接口及实施状态见 [来源插件系统设计](source-plugins.md)。该文档区分目标架构和当前开发切片，本页现有本地书籍身份及兼容约束继续适用。 --- ## 1. 数据边界 | 位置 | 内容 | 读写 | | --- | --- | --- | | `BOOKS_DIR` (`/books`) | 用户自己的电子书；管理员可执行文件管理操作 | 按挂载权限读写 | | `DATA_DIR` (`/data`) | SQLite、封面缓存、扫描记录、上传暂存、令牌密钥和插件数据 | 读写 | | 客户端本地 | 离线书文件缓存、本地进度 | 读写 | 服务端是唯一真相源。客户端只承担「渲染 + 缓存」。 ### 数据目录边界 `src/config/index.ts` 在启动时断言 `DATA_DIR` 不在 `BOOKS_DIR` 内，否则拒绝启动。这是运行时硬约束。 `BOOKS_DIR` 是否只读由部署挂载权限决定：只读挂载适合浏览和阅读；可写挂载允许管理员文件管理器上传、改名、移动、删除和新建目录。 扫描器与所有文件访问都经过 `src/lib/paths.ts` 的 `resolveInside()`—— 唯一的路径解析出口，`../` 逃逸会抛 `PATH_TRAVERSAL`。 扫描时也**不跟随符号链接**：指向挂载点外的软链会读到用户没打算共享的文件。 封面缓存写在 `DATA_DIR/covers/`，不写在书旁边；服务端也不会创建 `.calibre` 或其它书旁元数据文件。 --- ## 2. 书籍主键 ```ts 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` 整个批在**一个事务**里。断网不会留下写了一半的进度。 ### 「最近阅读」是书架的一个排序，不是第二排封面 `SyncService.recentlyRead` 注入 `ShelfService`，把书行的组装交给它，自己只负责 「按最近阅读时间排序」和那两个进度字段。 理由是一次已经发生过的漂移。#40 的「书架上点击继续阅读，提示书本不在书架上」 的根因就在这条缝里，而且是两层： - **可见性判据**曾经是 `hidden = 0` 就完了，而书架还要求「存在一个未丢失的文件」。 于是一本文件被删掉、或唯一副本在没插上的移动盘上的书，仍然被画在「继续阅读」 这一行里，点开必然 404 —— 那句话是真的，错的是那张卡片，而它正画在同一屏 「共 N 本」的下面。修法是把判据做成同一句话，而不是教客户端先查一遍： 先查一遍只会把「读者点不开的书」修成「读者看不见的书」。 - **字段形状**：端点返回进度行自己的命名（`bookId` / `updatedAt`），而客户端的 `ContinueReadingItem extends Book` 读 `id`。`title` 和 `coverUrl` 恰好两种拼法 同名，所以卡片画得好好的，点下去却把 `{ id: undefined }` 交给路由—— `#/book/undefined`、404、然后被报成「这本书不在书架上了」。 两个手写类型之间的字段名漂移，中间没有任何一个请求里出现过正确的那个名字。 一条规则：**一个屏幕上的同一本书，只能是同一个对象。** 所以书行只在 `ShelfService` 里组装一次（`toDto` / `getMany`），其它接口要书行就调它； 「最近更新」被覆盖层影响，卡片也得跟着变。 **那条「继续阅读」横排本身已经没有了**，而它消失的方式正是上面这条规则的另一半： 十张卡片画的是下面网格里已经有的那十本。现在同一个 `/library/continue` 端点还在被调， 但它只是**排序键**——`recent` 这个顺序需要 `lastReadAt`，而那不在 `BookDto` 上。 于是「同一本书只有一个对象」推进了一步：同一本书在一屏上也只有**一张封面**， 而“我读到哪了”由那张封面自己的进度条回答。 ### 「在不在书架上」只有一句话，两个屏幕都念它 一次报告（#40「补全完善书架的加入、移除逻辑」）把同一个问题从两端问了一遍， 两端答得不一样，而且**各自看起来都对**： - **服务端**：`/books` 说「`user_books.hidden = 0` **且**存在一个未丢失的文件」， `/library/browse` 的 `shelfState` 只读 `hidden = 0`。一行 `hidden = 0`、 文件掉了的书于是**同时**是「不在书架上」（书架）和「在书架上」（书库文件页）。 把这两种状态分开描述，等于让两个屏幕各自说一半真话，而读者没有任何办法知道 哪一半是旧的。 现在 `shelfState` 走的是同一对条件，`'off'` 就是「书架上没有它」。 - **客户端**：书库浏览页和书架页各自实现了一遍「书 ↔ 文件」的 join（按文件主名匹配）， 以及各自一套动作文案。两份实现就是两次漂移机会，而漂移的形态是**同一屏上 同一本书两个名字**——这不是假设，这个 bug 在「最近阅读」那条缝里已经发生过一次 （§5）。 那个 join 后来被**整个删掉**了，而且它应该更早就被删掉：它不是一个实现得不够好的 join，它是一个**不需要存在**的 join。卡片手里有 `book.id`，服务端的 `book_files` 早就知道这个 id 的文件在哪，客户端却拿**书名**去和文件名对——而书名不等于文件名是 **常态**（扫描器从文件里读书名），列表还是分页的。「找不到「xxx」在磁盘上的路径」 就是这样来的。写入现在带 id（`docs/api.md` §`/library/browse/shelf`）， 两个方向的措辞留在 `web/src/ui/shelf-membership.ts`，两个屏幕都调它， 而「书 ↔ 文件」的连接**不在客户端**。 这条值得当成一条规则：**客户端不应该重建服务端已经知道的事实。** 一个 join 只要有一端是猜的，它的失败就长得像「这本书不存在」，而不是像 「这个 join 猜错了」——读者拿到的是一句关于他自己书架的错误陈述。 **为什么「写完之后要重读」是这条规则的必然结果。** `shelfState` 是**响应字段**， 不是客户端的记忆：书库页写入之后如果只弹一句报告，卡片上的「加入书架」按钮就还在， 而它的下一次点击什么都不会发生。写入路径因此在同一个 `try` 里先重读、再报告—— 顺序不能反，反了就是「重读把报告覆盖掉」的那个老问题（§5 里 `manager-status` 已经为此改过一次）。 **「移除」这件事为什么必须在书架那一屏。** 书库**曾经**能下架，但书库是**管理员那一半** （§7 的路由按角色守），成员打不开。只有书库能下架，等于只有管理员能整理自己的书架。 所以书架上每张封面自己带一个「⋯」，写入前用一个确认框说清「磁盘上的文件一个都不会动」—— 那句话才是读者真正在问的。`docs/ui.md` §3.5.2/§3.5.3 写的是它的形状与命中区。 **两个方向现在只在读者那两屏上，而文件页只剩「写盘」。** #40 的下一轮把文件页的 「从书架拿掉」拿掉了，理由不是位置而是**语义**：文件页上其他每一个控件都改挂载盘， 而 `下架` 改的是一行 `user_books`、一个文件都不动。它因此是那个菜单里唯一后果和页面 承诺对不上的条目，而它挨着的就是「删除」。`docs/ui.md` §3.5.1。 **浏览页问的是索引，不是读者自己的书架。** 它原来读 `/books`（也就是书架）， 于是返回的每一本都已经在书架上——这一页存在的那个动作（「加入书架」）**永远画不出来**： 一个商城只陈列你已经买过的东西。现在它读 `scope=library`（`docs/api.md`）， 每一项带 `shelfState`，于是「这一页有 N 本还不在书架上」和封面上的角标说的是同一件事。 **离线镜像是缓存，所以「少了一本书」它自己推不出来。** `offline.replaceBooks` 只会**加**：它拿到的是一页书，它没有任何办法知道「这一页里没有的那本书」是读者刚拿掉的、 还是这一次没请求到。于是书架在**冷启动的第一帧**画的是 `offline.books()`， 而那一帧里被拿掉的书还在——在线时下一帧会被服务端的答案替换掉，离线时永远不会。 所以移除路径显式调一次 `offline.removeBooks(result.books)`，而且是在 `refresh`**之后**： 放在前面只有在「服务端已经不再返回这本书」时才正确，而那正好是把镜像写成 「一个带 bug 的缓存」的那个假设。`result.books` 是服务端自己说它改过的那几本， 两边都是它说了算。 ### 增量拉取 `GET /api/v1/sync?since=<上次的 serverTime>`。客户端记住上次返回的 `serverTime`， 每次只拿增量。移动网络下重连很便宜。 ### 一次写入只发一个请求 `POST /api/v1/sync` 的响应**就是合并后的状态**（服务端在两个接口上返回同一份 `pull`）。所以推完之后**不要再拉一次**——`SyncEngine` 直接拿 push 的返回值喂给 `applyPulled`，没有东西可推（空闲轮询）时才真的发 `GET`。 之前不是这样：push 的返回值被丢掉，然后为了同一份数据再发一个 `GET`。于是读者每 翻一页都发一个 POST **加** 一个 GET，网络面板里就是成对出现的 `sync` ——这正是 「sync 接口在不停重复」的来源。 ### 分页的位置：服务端切页，客户端算不了 两个列表的 `total` 和「这一页是哪些行」必须是**同一次行走**的结果。分开算 （第二次 `readdir`、或者一个缓存的计数）会让摘要、分页器和它下面那几行在任何一次 磁盘变化之后互相矛盾，而读者没有办法判断三个数字里哪个是旧的。所以 `BrowseService.list` 一次走完整个目录，用遍历的结果同时产出计数和这一页。 书库的分页上界（`BROWSE_PAGE_SIZE_MAX`）是刻意的：一个目录可以是文件系统里的 任何东西，把四千行发给浏览器再丢掉 3940 行是那个让屏幕显得坏掉的请求，而调用方 不应该能用一个参数换回它。 ### 状态只在变化时广播 `setState` 先比对新旧 state/message，相同就直接返回。阅读页的状态监听会重绘整棵 chrome 树，而一个同步循环本来会通知三次（进门 `syncing`、出门 `idle`、再加一次 多余的 `emit()`），30 秒轮询让这件事在读者什么都不做时也持续发生。 --- ## 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. 客户端渲染 > 界面层的外观规范（图标、设计令牌、焦点、状态表达、文案）在 > [`ui.md`](ui.md)。§8 这一章讲的是**渲染**：分页、注入、量测、以及哪些界面 > 该用组件描述、哪些必须保持命令式。两者的边界是刻意分开的——排版层对书不动手 > （见 §8 与 §9），界面层的外观则必须统一。 已落地。产品设计里的关键决策：**不要直接套 Readium Mobile**。 Readium 用 Readium CSS 主动接管排版、覆盖出版方样式，这与本产品 「忠实还原精排书设计」的核心差异化直接冲突。 实际方案： - 原生外壳（Kotlin）只负责：文件与缓存、手势、账号、连通性 - 渲染层是 **WebView + 自研 CSS 干预策略**，保留作者样式、只做最小覆盖 - 参考 readium-css 的变量组织方式，但**不引入它的默认接管行为** ### UI 框架选型：Preact，而且只用在「没有布局要量测」的那一半 界面原来是纯命令式 DOM：每个屏幕在构造函数里建好全部节点、把它们存成实例字段， 再由若干 `render*()` 方法在状态变化时挑选该改哪个。它有两个具体的坏味道： 1. **同一份状态有多个副本。** 分段控件的选中态既在 `settings` 里也在 `aria-pressed` 上，两者靠点击处理器手工同步；`LoginScreen` 的通知、错误、 注册开关、按钮文案是四个节点被五个地方改。改一处漏一处不会报错。 2. **重建与状态的矛盾。** 朗读引擎行必须在 HTTP 能力探测回来时重新生成， 而整块面板重建会丢掉读者在面板里的滚动位置，于是长出一套 「只替换 `[data-speech=group]`」的定点重建。 选型的硬约束有三个，都来自「一份产物两个宿主」： - **单文件 bundle、`base: './'`**：WebView 从 `https://appassets...` 加载， 不能按需拉分片，所以框架必须能被 tree-shake 进一个文件。 - **体积**：这是要打进 APK、也要由 NAS 上的 Node 托管的资源。 - **不认识的东西不能碰布局**：阅读舞台的分页依赖 `getBoundingClientRect()`， 虚拟 DOM 不能在它和布局之间。 对比过的四个： | 方案 | gzip 净成本 | 结论 | | --- | --- | --- | | Preact + `preact/hooks` | 最小 | **选用**（无 `preact/compat`、无 `react-dom`，仅这两个模块） | | React + react-dom | ~45KB | 一个阅读器不该为 `react-dom` 付这个价钱 | | Vue 3 runtime | ~34KB | 需要 SFC 预编译或运行时模板编译，产物形状与单文件 bundle 相冲 | | 纯 Web Components / lit | ~5KB / ~7KB | 手写 `render()` 等于自建一个更窄的框架；lit 又把模板塞进字符串，失去类型检查 | **边界写在 `ReaderScreen` 里，而不是靠自觉**：舞台（`stage`）由类持有、 交给 `ReaderView`，并通过一个 ref 回调挂进组件树；组件只决定它**放在哪** （状态行与页脚之间，stacking context 来自这里），内容一概不碰。于是： - 排版、分页、shadow root、手势、量测：**零框架**。 - 顶栏、页脚进度、目录、设置面板、朗读条、状态行、书架、登录、书库： `ChromeState` 的函数。 副作用也是可见的：`settingsPanel` 那套「只重建朗读行」的定点更新没有了， 探测答案回来时只是改状态，Preact 的 diff 让读者的滚动位置天然保住。 组件只用了 `preact` 与 `preact/hooks`（`useState` / `useRef` / `useEffect`）， 没有引入 `@preact/signals` 之类的额外状态层——屏幕自己就是状态的持有者， `update()` 把整份状态交给树。少一个依赖，就少一处「值在哪」的歧义。 ### 路由：URL 就是屏幕 界面的第二个结构性问题不是「怎么画」，而是「在哪」。最初的 shell 用 `showShelf()` / `openBook()` / `showManager()` 加一个 `pendingBook` 字段来换屏， URL 从头到尾不变。手机上这一点几乎看不见——直到读者按返回键：Android 的返回手势 交给 Activity，Activity 看到 WebView 没有历史，于是**直接从书架上退出应用**。 浏览器上则更糟，地址栏是自托管书库唯一的分发方式，而它既不能分享也不能收藏： 一本书链接不出去，刷新永远回到书架。 所以路由是**值**，不是调用：`ui/router.ts` 把 fragment 解析成 `{ name: 'shelf' } | { name: 'library', path } | { name: 'book', bookId }`， shell 渲染 router 报上来的那个 route，导航就是改 URL、让变化回流。 **为什么用 fragment 而不是 `history.pushState` 的路径。** 同一份产物要被两个宿主加载， 而两个宿主都服务不了任意路径：Android 从 `https://appassets.androidplatform.net/` 加载（那里没有服务端，除文档本身以外的路径全是 404），H5 由 reader 服务端托管， 而它没有「客户端路由回落到 `index.html`」这条规则。路径式路由会在 `vite dev` 里一切正常， 在两个生产宿主里 404。fragment 是 URL 里唯一保证属于客户端的一段，所以它是唯一 三处都成立的方案——代价是一个 `#`。 **返回走应用自己的轨迹，不是 `history.back()`。** 应用里的「返回」意思是「上一个屏幕」， 而浏览器历史里可能有登录表单、`vite dev` 的页面、甚至别的站点。`Router` 自己维护一条 屏幕轨迹，`back()` 从它上面弹；轨迹为空时（新标签页里粘贴的链接）就**替换**成父级路由， 而不是压入——否则那个粘贴的链接会永远压在书架上，返回键会一次次把读者送回书里。 **进入文件夹是 `replace`，不是 `push`。** 书库是一个带面包屑的屏幕，走进子目录是同一个 屏幕改自己的参数，所以它覆写当前条目而不是新增。压栈的话，读者走过四个文件夹再按返回， 会一个一个退出来——而面包屑存在的意义正是为了不用这样做。 **书架和书库是两个路由，不是同一屏幕的两个标签。** `#/shelf` 与 `#/library/<路径>`。 两者差的是数据源（`books` 表 vs 挂载目录），而这恰好是「标签」这种做工会同时坏掉的三件事： 标签切换进同一段历史，于是 Back 变成「退回上一个标签」而不是离开屏幕；`#/library/科幻` 是要能发给别人的链接，标签不产出链接；一个屏幕塞两个标题就得再占一行标签栏。 两个路由共用一个 **切换控件**（书架右上是「书库」，书库左上是「书架」），而不是共用一个 屏幕——控件是一步，轨迹是两条。 **页在 URL 里。** `#/shelf/3`、`#/library/科幻/2`。两个列表都分页，页是**位置**： 没有它，「我读到第三屏了」只存在于一个滚动偏移里，重绘就没了，而 Back 无处可回。 书架的 `page` 是自己的一段（`#/shelf/<页>`），书库的页是路径之后的**后缀** （`#/library/<路径>/<页>`）——把最后一段数字读成页只在一个前提下成立：只有 `routeHash` 会写这种 URL。一个真的叫 `2` 的文件夹是 `#/library/2`（前面没有段）， 所以它仍然是文件夹。 **书库自己也是两半个，而它们是两条路由，不是标签。** `#/library/<路径>` 是 **浏览页**（读者那一半：商城式布局、搜索框、封面网格），`#/library/files/<路径>` 是 **文件管理页**（管理员那一半：文件行，且每一行控件都写磁盘）。URL 是 `#/library[/files][/<路径>][/<页>][?q=<搜索>]`。 这一版**改了上一版**：上一版把两半做成一个屏幕的两个页签，理由是「标签进历史会让 Back 走标签」。那条理由在下一层就不成立了——两半**不是同一份数据的两种读法**：一个问 `books` 表（书名、封面），一个问挂载目录（文件名、大小、扫描标记），端点不同、 一页条数不同、受众不同。共用一个头部会逼着两边都让步，而最大的代价是可达性： `#/library/科幻` 这条**能给别人的链接**离「能删书的那一页」只差一次页签点击。 所以两半是两个路由，`files` 段只在紧跟路由之后那一格被读走——一个真叫 `files` 的 文件夹是 `#/library/files/files`，仍然是文件夹。搜索是 `?q=`：自由文本、可以没有、 并且落在路径之外，所以文件夹里叫什么都无所谓。 其余的路由理由（页在 URL 里、哈希说不出来的从轨迹里带、屏幕不自己改页、登录不是路由） 原封不动。`fromShelf` 那一条现在也决定了**哪一半**的 `back()` 是回书架还是退出应用。 **哈希说不出来的两件事，从轨迹里带。** `#/shelf` 对所有文件夹是同一条 URL， `#/library` 也说不清读者是怎么到这儿的。所以 `Router` 在解析当前哈希时会把上一次 路由里的两件事带过来：书架的 `libraryPath` / `libraryPage`（切回来时回到原来那个 文件夹和那一页），以及书库的 `fromShelf`（离开书库时是回书架还是退出应用）。 这两件事都必须**由路由带**而不是由屏幕记：屏幕是 `replace` 遍历文件夹的， 它记的是「进来的那个文件夹」，而读者已经走到别处了。 **屏幕不自己改页。** 翻页是导航：分页器上报意图 → shell 写 URL → URL 回落到 `showPage(page)`。这一趟往返就是页能活过 Back、Forward、刷新的全部原因。 **登录不是路由。** 「登录页」是一个瞬时状态，给它一个 URL 等于给门一个门牌。真正需要 活下来的东西是读者**本来要去的地方**，所以它存在 `App.pending` 里：带着 `#/book/` 进来而尚未登录时，这个 route 会等在登录页后面，登录完成后直接落到那本书上， 而不是落到一个他从未见过的书架。 各屏仍然是有 `element` 和 `dispose()` 的类——路由不认识框架，屏幕也不认识 hash。 两者之间唯一的交汇点是 `RouteLocation`，屏幕通过它的 `back()` 请求离开。 ### `mountUI`：类与组件之间唯一的接缝 屏幕仍然是类，仍然有 `element` 和 `dispose()`——路由不需要知道框架， `ReaderScreen` 这种以命令式为主的屏幕也不必假装自己不是。 `mountUI(container, tree, initial)` 返回 `{ element, update, unmount }`， `update` 传入「整棵树应该是什么状态的函数」的那个值。测试保持原样： 断言仍然打在真实 DOM 上（`test/manager.test.ts` 一行没改逻辑，只改了 import 后缀）。 **unmount 之后的 update 会被丢弃，这一点是有意的。** 每个屏幕都是异步加载的， 每个屏幕也都可能在加载完成前被离开——读者点开一本书又马上按返回，深链在书架还在取数据 时就把它换掉了。`dispose()` 取消不掉一个已经在飞的 promise，所以那个延续会跑在一个 已经不在屏幕上的屏幕上并调用 `patch()`。没有这道闸，它会往一个刚刚被 Preact 清空的容器 里重新画**整棵树**：书架那条迟到的响应会把自己一整屏封面画进文件列表里，而之后的 `render(null)` 也清不掉它们，因为在 Preact 看来它们从来不是自己的孩子。 所以一个标志位就顶得上每个屏幕各写一个取消令牌，而且没法在哪一个屏幕里漏掉。 ### 只有一份渲染层 Android 不重写渲染，它加载的是同一份 `web/` 产物。这不是为了省事， 而是因为排版策略一旦有第二份实现就一定会分叉，而排版正是差异点所在。 两边共用的抽象在 `web/src/core/platform.ts`：传输、键值存储、二进制存储、连通性。 Android 只覆盖它真正能做得更好的部分——连通性和设备名——其余全部复用。 ### 有一条退出通道：整页图与文档可以由原生画 「只有一份渲染层」是默认，不是教条。有一类内容在 WebView 里是不划算的： **整页就是一整张图**。渲染一页漫画，WebView 要付：字节跨进渲染进程、在渲染进程里 解码成位图、跑一次样式与布局、再合成一次。对一章文字这些都是必要的；对 「把这张图画满屏幕」则全是白付的，在手机上就是一次翻页卡顿。 所以有一条明确划出的通道：固定版式的整页图由原生画。 规则写死在契约里，也是它能成立的原因： - **只画整页图。** 漫画页、单张扫描图。任何带文字排版的内容留在 WebView， 因为忠于精排是差异点，而它只有一份实现。 - **全有或全无。** 要么解出位图并显示，要么返回 `false` 让 WebView 照常渲染。 没有中间态，也不会出现「该有图的地方是空白」。宿主拒绝、格式不支持、 payload 坏了、桥接抛异常，四种情况都落到同一条回退路径上。 - **不在 UI 线程解码，位图有上限。** 先读文件头拿真实尺寸，再按视口下采样分配。 一张 4000 万像素的扫描图如果先分配再缩放，就是把目标机型 OOM 掉。 契约横跨三种语言，所以谁也无法用类型系统保证它们一致，`android/scripts/check-shell.sh` 里加了静态校验：渲染模式的词表（`RenderMode`）必须覆盖壳里分支的那几个值， 原生侧的可解码媒体类型必须包含客户端会产出的那些。词表写错一边， 结果不是编译失败，而是**所有页都静默走慢路径**——所以这条检查不是锦上添花。 壳版本 2 引入这套接口。客户端把「壳版本 < 2」当作「没有原生渲染器」处理， 照常在 WebView 里画一切：为了一点性能就拒绝在旧 APK 上运行是错的交换。 ### 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**。 但隔离是双向的：**文档里的选择器进不去 shadow root**。这不是风格问题， 它决定了两条规则各自该写在哪儿，搞错了不会报错、只会静默失效： - `.book-flow`（正文列：版心宽度、页边距、字号缩放、分页列）、`.fixed-page`、 朗读高亮、翻页动画——这些元素在 shadow root **里**，所以规则必须注入到 shadow root **里**（见 `ui/shadow.ts` 的 `FLOW_STYLESHEET`）。 写在 `styles/reader.css` 里等于删除：正文列会以浏览器默认样式渲染， 没有版心、没有边距、翻页模式没有列。而外围 chrome 在文档里、样式完全正常， 所以看上去不像样式表丢了，只像「阅读器没有页边距这个功能」。 - `.book-host`、亮度过场（`::after` 伪元素）、`book-content` 的 `display` ——这些是 shadow **host** 本身，属于文档树，所以规则写在 `styles/reader.css`。 - host 上的状态属性（`data-paginated`、`data-animating`）只能用 `:host(...)` 选择：从 shadow root 内部无法用类选择器匹配 host。 写成 `.book-host[data-paginated] .book-flow` 永远不会匹配， 于是翻页模式静静地不产生任何列，翻页也就无处可翻。 两条规则里的**值**不重复：全部是自定义属性，而属性本身定义在 `:root` 上， shadow root 会继承。 ### 窗口化的三个接缝 「一份产物两个宿主」和「一千二百章的书不能先下载整本」是同一件事的两面， 而窗口是这件事的传输边界。跨过它有三个必须写死的地方： - **换窗口和落到章节是一次操作。** 只换窗口会留下*上一章*在屏幕上： 宿主内容没动、`currentSectionIndex` 还指着旧窗口的下标、页脚还在报读者刚离开的章节。 这正是「点击章节没有反应」的症状。 - **窗口接口只有一个名字。** 客户端建的 `StagedDoc` 叫 `setWindow`， `StagedBook` 接口叫 `loadWindow`，屏幕曾经用鸭子类型去猜——猜错了， 于是每次跨窗口跳转都是静默的空操作。现在由 `adoptWindow()` 一处识别。 - **窗口由 manifest 的 `groups` 算出来，不是由「40 章」算出来。** 漫画按*卷*开窗，而卷不是 40 页。`spine / 40` 会请求一个不存在的组， 跳转就落到空处。 另外，位置必须按**整书坐标**判断，不能按窗口内的下标： 在窗口最后一章时下标是 39，拿它和窗口长度 40 比会得出「已经是最后一章」， 而后面还有八十章。窗口长度是传输细节，不该决定书在哪里结束。 ### 阅读位置格式 ### 书不能联网 加载时把章节里所有本地引用改写成内部 `reader-res:` 协议，渲染层从内存资源表解出； 绝对 URL 原样保留，然后被 CSP 挡掉。这样一本来路不明的书无法把阅读行为报到远端。 资源按需解出而不是预展开——不然打开一本带大图的 EPUB 会先把整个包塞进内存。 ### 阅读位置格式 `r1:<偏移>:<章节 id>`。三点都是踩过之后定的： - **版本前缀**：服务端把 locator 当不透明字符串长期保存，客户端将来改格式时必须 能认出「这不是我认识的格式」。`r1` 给了这个能力。 - **章节 id 放最后**：章节 id 是文件路径，会含冒号。只从前两个冒号切、剩下全保留， 是唯一不会丢数据的解析方式。 - **偏移是章节内的比例**，不是像素、不是 CSS 列号。列号会随字号变化， 于是读者一调字号，位置就跳到另一个句子上——阅读 App 能犯的最让人恼火的错误之一。 ### 待发送队列，而不是「每次都全发」 离线队列记的是**脏集合**：哪些记录还没送到服务端，而不是「当前全部状态」。 两者在一种情况下结果不同，而这种情况一定会发生：记录在请求发出之后、响应到达之前 被修改了（读者在同步进行时翻了一页）。脏集合下，这次更新仍然是脏的，要等**它自己** 的确认才清除；「全发」模式下，它会被那个更早的响应顺手清掉，然后永远送不到服务端—— 一个丢失的阅读位置，是这个产品最不能有的失败。 ### 离线队列的抗崩 队列在本地镜像里，不在内存里。所以读到一半直接杀进程，位置不会丢—— 下一次启动接着送。笔记删除同样写墓碑后再入队，避免离线设备让已删笔记复活。 ### TXT 的编码与章节 本地书库里 TXT 占比很大，而它既没有结构也没有编码声明。 编码：先严格校验 UTF-8（自己实现，不用 `TextDecoder` 的宽松模式——宽松模式永远 「成功」，于是你永远发现不了自己解错了）。校验失败**不是**按顺序试 GB18030 再试 Big5，而是两种都解一遍再挑更干净的那个。原因值得写下来： 这两个编码的字节范围重叠得很厉害，同一串字节通常**两边都能解出合法字符**， 所以「先试 A 再试 B」永远不会走到 B，繁体 Big5 的书会以简体码表解出一整本乱码。 真正的证据在各自码表的空洞里——解出来变成私用区字符、替换字符、或者一片汉字里 冒出的假名。按这个打分选优，才能既救回繁体，也不牺牲占多数的简体。 结果里带 `guessed` 标记，界面上告诉用户选了哪个并允许手动覆盖。 章节：TXT 没有目录，只能从标题推断。策略是**宁可少认，不要错认**—— 一个 800 字的段落以「第三章」开头时不能当标题，而正文里提到「他在第二章读过」 更不能当标题。两条都有测试固定住。推断不出章节时按长度分段： 一本五千章的网文如果变成一整节，分页会直接卡死。 ### 漫画的页序 按自然序排（`1, 2, 10` 而不是 `1, 10, 2`）。排错不是观感问题，是故事被静默打乱。 文件名无信息量时用页序当标题，因为 `a1b2c3.png` 对读者没有意义。 ### 目录书：什么算一页，谁说了算 一个目录变成一本书之后，「这本书有哪些文件」不能由 API 层临时拼：manifest 告诉客户端 哪些路径构成这本书，`/books/:id/file` 就服务哪些路径。两边必须是**同一份清单**。 这一条是被一个真实缺陷定出来的。此前 API 层自己拼路径，用的是 `items[].title`—— 对散图恰好等于文件名，对**压缩包里的页**则是包内条目名（`001.png`），那不是一个库内路径。 于是这样一个卷的每一页都 404，漫画打开就是空白，而且服务端日志里只有 404，看不出原因。 现在清单由页面遍历给出，并且**一个压缩包算一页**：它的路径是 `第01卷.cbz`， 是客户端真能拿来发请求的东西；包内页码由 `/assets?ref=page:卷:页` 寻址，不是路径， 也就不该出现在 `files` 里。清单是契约，不是清单式的描述——多一条会被拒，少一条会 404。 顺带一个同类缺陷：`第01卷.cbz` 与 `第02卷/` 并列时，整卷系列在书架上会**整体消失**。 `.cbz` 本身注册为一种书，于是这个目录被判成「书架」而不再交给漫画目录处理器； 卷子目录里只有图片、不构成书，所以也没有留下任何条目。两边都不认，书就不见了。 判据因此改成按**上下文**问：一个 zip 在书架语境里是书，在漫画目录候选里是页材料。 同一个布局还有两处更细的坑，都会让整卷系列消失或读错页，值得一并记下： - **「卷」的判据不能在最后加一句 `images === 0`。** 整卷系列里放一张封面扫描是常态， 而 `images === 0` 会把这种目录判成「不是漫画」——它就是上面那个消失缺陷的另一条路径。 判据改成逐个来源问：卷压缩包的页就在包里，**一个压缩包本身就是一卷**；卷子目录要往下看 才知道有没有页。一张散图既不能否定同级存在的整卷，也不该在只有它自己的时候被当成书 （那条由 `MIN_IMAGES` 管）。 - **页的引用是 `page:<卷>:<页>`，不是 `page:<下标>`。** manifest 与 `/file` 都从同一次 页面遍历取引用（`files[].ref`），而不是让 API 层从路径或下标反推。「一个压缩包算一页」 意味着它在列表里的下标和它在卷里的位置无关：按 `page:1` 去问一卷，格式处理器解不出这个 引用，异常回退到「当普通文件发」的分支，于是客户端请求一页、拿到的是那个压缩包—— 状态码还是 200，只有翻页时才会发现内容不对。 ### 一页一个 section 漫画和 PDF 是 `layout: 'fixed'`，每页一个 section，由分页器整屏推进。 固定布局的宿主不做滚动容器——在横向分页器里嵌一个滚动区会产生 Android 上经典的「页面自己往边上飘」bug。 --- ## 9. 界面设置与朗读 ### 为什么设置不跟着账号同步 同一份「设置」里其实住着两类东西： | 类别 | 例子 | 真相源 | | --- | --- | --- | | 屏幕与环境的属性 | 字号、主题、亮度、页边距 | 本机 | | 读者的属性 | 阅读位置、笔记、高亮 | 账号 | 把第一类推到服务端，结果就是把手机上的字号搬到平板上打开——这是所有人都讨厌的行为。 所以 `SettingsStore` 存在设备本地（`reader.settings.v1`），同步层完全不知道它存在。 ### 新增的每一个排版开关，默认值都是「不动」 这条不是风格问题，是 §8 那个承诺的直接推论。「忠于精排」在实现上只有一种写法： **除非不设就会坏，否则不设**。 所以行距的默认值是字符串 `inherit`，字体和文本对齐同样；它们经 CSS 自定义属性 继承进 shadow root，书里写死的值自然胜出。字号改的是容器的基准字号，不是每段的大小， 所以 `font-size: 14px` 的段落保持原样，`1.2em` 的段落跟着滑块走。 页边距是唯一一个「用户值必然生效」的排版项。它不是给书的，是给**行宽**的： 一行 40 个汉字在手机上没法读，而约束行宽不能靠改 `p` 的 margin——那正是要避免的编辑。 改成给容器加内边距，作者的样式一条都不用动。 亮度做成了 `mix-blend-mode: multiply` 的覆盖层而不是调色板：换主题应该保留 纸与字的对比关系，直接改颜色会把文字一起压暗，那正是「亮度」滑杆最常见的失败。 ### 三个朗读引擎，一个队列 朗读有三条来源，而客户端的其余部分不需要知道正在用哪一条： | 引擎 | 声音来自 | 什么时候用 | | --- | --- | --- | | `native` | Android 外壳的 `TextToSpeech` | 有 `speech` 接口的外壳（版本 ≥ 3） | | `system` | WebView / 浏览器的 `speechSynthesis` | 默认。免费、离线、无往返 | | `http` | 服务端的 `TTS_URL`，经 `/api/v1/tts` 代理 | 前两者都不可用时 | `auto` 的优先级是 native → system → http，理由不是「谁更好」而是**谁知道得更多**： - native 排在 system 前面，尽管 WebView 自己也有合成器。因为那是**两个不同的引擎**： 手机系统装好的中文语音经常不在 WebView 的 `getVoices()` 列表里， 于是读者听到英文或听不到声音，而 Web 层拿到的列表本身就是缺的，修不了。 这是「朗读没有中文声音」最常见的原因，唯一的解法是直接问平台。 - http 排最后，因为它的每一句都要一次请求，而且它需要一个配了 `TTS_URL` 的服务端。 三者的**暂停语义真的不同**，所以它们不是同一个基类： - `speechSynthesis` 能暂停，`TextToSpeech` 不能（只能 stop），`