mtfyun/reader
1
0 Fork 0
mirror of https://github.com/hectorqin/reader.git synced 2026-11-12 14:01:00 +08:00
Code Issues Packages Projects Releases Wiki Activity
309 Commits 16 Branches 1 Tag
ci/github-actions
Commit Graph
5 Commits
Author SHA1 Message Date
hectorqin 47baee014e feat(ui): unify page feedback with global Notyf notifications 
Route login, shelf, library, file operations, reading, sources and extension feedback through one compact themed notification host. Keep native modal feedback in the top layer, escape remote text, update progress in place and let reading controls receive clicks beneath message text. Cover lifecycle, error handling and layout with unit and Chromium checks.
 2026-09-23 10:13:03 +08:00
hectorqin 558f44e206 feat(web,server): 书架默认按最近阅读排，书库拆成预览与文件两页 2026-09-19 14:17:55 +08:00
cnb.dQC5J6ohAGA b7ffa42c80 feat(library): 支持上传书籍与批量管理 2026-09-17 16:50:47 +08:00
cnb.dQC5J6ohAGA c18664f1e3 feat(reader): 按窗口读取、真机可编译的 Android 壳，以及分章契约的收口 
两件事：把 PR #8 里那四项合并进来（A 选项），然后把 issue 里一直没落地的
「一次只取一章」从服务端契约一路做到客户端。

## 一、PR #8 的四项（Android 外壳最值钱）

- Android 原生整页图渲染：NativePageView + 桥接 v2（renderPage/hidePage）。
  只画整页图，EPUB 永远留在 WebView；画不了就返回 false 回退，不出现空白页。
- 离线队列：脏集合语义固定为契约，补上「请求在途时位置被改写」的三条用例。
- TXT 编码探测：GB18030 与 Big5 都解一遍再按损坏证据评分选优。
  原来「先 GB18030 失败再 Big5」永远走不到第二步——两者字节范围重叠，
  同一串字节通常两边都能解出合法字符，繁体书会整本乱码。
- 格式嗅探：magic number 优先于扩展名，并明确拒绝非书籍的媒体容器。

## 二、Android 壳第一次真的编译通过

上一轮说「没有 JDK/SDK，只写了契约」，这一轮补上了环境并真的编译。
编译立刻暴露三处——都是只有编译才能发现的：

- colors.xml 的注释里写了 --reader-paper。XML 禁止注释中出现双连字符，
  AAPT 直接拒绝整个文件。Android 壳此前从未构建过，所以从未发现。
- NativePageView.kt 用了 Uint8Array。那是 JavaScript 类型，Kotlin 里不存在；
  桥接的另一侧是 ByteArray。
- AndroidManifest.xml 引用了 @mipmap/ic_launcher，而资源里没有这个文件。

三条都让 :app:assembleDebug 失败，也就是说这个 APK 此前根本产不出来。
现在是 BUILD SUCCESSFUL，产物 3.6MB。

## 三、分窗读取：从契约做到客户端

服务端：
- /manifest 省略 group 现在等价于 group=0。原来省略意味着「发全部条目」，
  于是一本 1200 章的书在它最需要快的那个请求（打开书）里收到 1200 条记录，
  等于分窗对不传参的客户端完全失效。要完整结构用 ?group=all。
- /toc 在没有 OPF 标题映射时回落到章节自身的第一个标题。手作 EPUB 大量
  没有标题映射，原来整本目录会读成「第 1 章 … 第 300 章」，等于没有目录。
- 扫描时的 spine 读取不再解析 NCX 与 nav：扫一遍全库本该只读一次包文档。
- 尾部 Range（bytes=-N）在超过 8MB 时退化为整包响应并撤回 Accept-Ranges。
  前向流无法跳到文件末尾，服务这种请求意味着为三个字节读完整个 400MB 漫画包。

客户端：
- 新增 formats/remote-zip.ts：走 HTTP Range 的只读 ZIP，让浏览器端也能不下整本书。
- 新增 formats/windowed.ts：分窗文档。分窗是传输边界，目录必须完整，两者分开
  —— 合在一起就是原来目录面板显示「第 1 章 – 第 40 章」的原因。
- reader-screen 接上 /toc，并且点击目录项会先取对应窗口再跳。

## 验证

server:  133/133（typecheck + test + build）
web:     179 vitest + 29 node:test（typecheck + test + build）
android: BUILD SUCCESSFUL，app-debug.apk 3.6MB
shell:   契约双向校验 + 渲染模式词表校验通过
 2026-09-16 19:51:38 +08:00
CodeBuddy 78bfe557c3 feat: 客户端 Android 与 H5 双端，含精排渲染层 
按产品设计 §5「原生外壳 + WebView 渲染」落地客户端，Android 与浏览器共用同一份
渲染层；同时把服务端的格式范围从 epub + pdf 扩展到 txt 与漫画。

## 为什么两端共用一份渲染层

Android 端不重写渲染。它是一个 Kotlin 原生外壳，只负责文件缓存、手势、账号与书架，
渲染复用 web/ 构建出的同一份产物。原因很直接：排版策略一旦有第二份实现就一定会分叉，
而「忠于精排」正是这个产品的差异点。

共用的抽象在 web/src/core/platform.ts（传输、键值存储、二进制存储、连通性）。
外壳只覆盖 WebView 做不到或做不好的三件事：

- 连通性：WebView 里的 navigator.onLine 只要有网卡就报「在线」，连上没有出口的
  Wi-Fi 时会骗人，客户端于是转圈而不是读缓存。改用平台的 NET_CAPABILITY_VALIDATED。
- 稳定的设备名：UA 里的型号会随 Chrome 升级变化，作为「上次在哪个设备读的」标签不可靠。
- 原生提示：一行 Kotlin 的 Toast，不用在 Web 层造通知 UI。

跨语言的接缝（Kotlin 桥接 ↔ TypeScript 声明）没法互相类型检查，因此加了
android/scripts/check-shell.sh 做双向契约校验，并接进 CI。

## 精排 CSS 策略

这是整个项目最产品化的一块 CSS，所以规则是写明的而不是凑出来的。

三条原则：不设任何属性除非不设会坏；每个可调项都是默认 inherit 的可继承自定义属性
（「关」的意思是「不动它」，不是「用我们的默认值」）；任何改变作者意图的行为都是
用户主动开启且持久化。

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

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

书的样式装进 shadow root。书里一条 p { color: red } 不能改到书架，App 的 .topbar
也不能被书撞上。用 iframe 也能隔离，但每次换章要重建文档，会丢滚动位置并在 Android
上多花几倍内存。关键是**不往 shadow root 里注入任何 reset**。

## 格式层

服务端只负责流式给出原始文件，拆包、编码、章节与分页都是渲染层的事——
这些恰好是产品要自己拿主意的部分。

- EPUB：OPF/spine/nav 解析，作者样式全部保留，相对引用改写成内部 reader-res: 协议，
  绝对 URL 原样保留交给 CSP 挡掉。加载器按文档逐个容错，一个坏章节不会毁掉整本书。
- TXT：先严格校验 UTF-8（自己实现，不用宽松模式——宽松模式永远「成功」，于是永远
  发现不了解错了），失败再依次试 GB18030 与 Big5，并把选择告诉用户、允许覆盖。
  章节只能从标题推断，策略是宁可少认不要错认：800 字的段落以「第三章」开头不算标题，
  正文里提到「他在第二章读过」也不算。两条都有测试固定。
- CBZ / 图片目录：自然序排页（1,2,10 而不是 1,10,2），一页一个 fixed-layout section。
  排错不是观感问题，是故事被静默打乱。
- 检测以魔数优先：本地库里 .txt 其实是 EPUB、.cbz 里其实是 PDF 的情况很多，
  按扩展名开错加载器只会得到一个看不懂的报错。

服务端扫描器相应扩展：txt/cbz 直接索引；图片目录按文件夹识别为一本书，
文件夹路径作为主键锚点，所以**往漫画文件夹加一页不会丢进度**——这条有测试。

## 客户端三态与离线队列

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

阅读位置格式 r1:<偏移>:<章节 id>。三点都是踩过之后定的：版本前缀（服务端把 locator
当不透明字符串长期保存，客户端将来改格式必须能认出「这不是我认识的格式」）、
章节 id 放最后（它是文件路径，会含冒号，只从前两个冒号切才不会丢数据）、
偏移是章节内的比例而非像素或列号（列号会随字号变化，于是读者一调字号位置就跳）。

TXT、漫画、PDF 的支持也一并接上，PDF 用浏览器自带阅读器保底可读。

## 服务端

- GET /books/:id/file?path=… ：按页取图。path 必须是这本书已登记的 rel_path，
  服务端按表精确匹配，不用 query 拼路径，所以穿越只会匹配到空。
- CORS 白名单（CORS_ORIGINS，默认回显任意来源）+ H5 静态托管（WEB_DIR）。
  托管在同一容器里，这才保住「一条命令跑起来」。
- Android 用 WebViewAssetLoader 从 https://appassets.androidplatform.net/ 提供
  打包好的客户端，而不是 file://。后者发出的 fetch 是不透明的跨源请求，所有访问
  服务端的调用都会被拦，而通常的绕法是把 web security 关掉——那等于把 WebView
  变成一扇敞开的门。用资产加载器拿到的是正常安全源，请求按普通 CORS 走，
  isSecureContext 为真，IndexedDB 等行为与浏览器一致。这一个选择是「一份 bundle
  两个宿主」能成立的前提。

## 过程中发现并修掉的问题

- **ETag 里塞了中文路径**：HTTP 头值必须是 ISO-8859-1，漫画页码路径是中文时会抛
  ERR_INVALID_CHAR，把一个正常的取图请求变成 500。改成对路径取散列。
- **漫画文件夹的主键用了页集合散列**：注释写的是「加一页不产生新书」，实现却是散列
  页集合，加一页就换 id、进度全丢。改成用文件夹路径作为锚点，和书用 dc:identifier
  作锚点是同一个道理。测试固定住了。
- **locator 解析与写出不对称**：写出是两段、解析却按三段切，导致位置根本存不回来。
  章节 id 含冒号时更糟。
- **离线队列的清理条件**：原本按「清空全部」处理，会把请求在途时产生的新位置一并
  抹掉。改成只清那一批、且只清时间戳吻合的条目。
- **测试自身的错误**：并发刷新去重的用例里，我一开始用 resolveRefresh?.() 调一个
  类型已收窄成 never 的变量，断言等于什么都没测；「outbox 为空时不推」的用例里把
  登录的 POST 也数了进去，断言恒不成立。两处都是测试写错了。
- **凭据用错了**：一个权限用例里我用 createAsAdmin 建账号却拿另一组凭据登录，
  401 被当成「越权被拒」而通过。这也是测试写错了。

## 验证方式

```
cd server && npm run typecheck && npm test && npm run build   # 37/37 通过
cd web    && npm run typecheck && npm test && npm run build   # 147/147 通过
sh android/scripts/check-shell.sh                             # 桥接契约双向校验通过
```

另用真实 HTTP 请求端到端验证过：注册 → 扫描 → 书架（四种格式全部可见）→ 漫画按页
取图（含中文路径 ETag）→ 列表页 → 进度同步 → 继续阅读；H5 静态托管、SPA 回落、
CORS 回显、路径穿越拒绝均按预期。

Android 壳本轮**没有真机编译验证**：环境里没有 JDK 和 Android SDK。Kotlin 侧做了
静态校验（包名与目录一致、项目内 import 可解析、桥接方法与 web 侧声明双向对齐），
并接进了 CI。第一次真机构建可能需要微调 Gradle 版本或 AGP 版本。

## 说明

- docker-compose.yml 与 Dockerfile 已改为从仓库根构建并打包 H5 产物；
  build 上下文变了，如果之前用了 `build: ./server` 需要改成根目录。
- iOS 未做设计（按设计文档 §7，等有赞助再说）。
- 移动端批注输入仍未做（先保证读，后补写）。

Ref: #1
 2026-09-16 14:49:11 +08:00