mtfyun/reader
1
0 Fork 0
mirror of https://github.com/hectorqin/reader.git synced 2026-11-13 14:31:11 +08:00
Code Issues Packages Projects Releases Wiki Activity
54 Commits 19 Branches 1 Tag
b289c86ca4c6600a8fa949fc6a8f127b0e693e4a
Commit Graph
54 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
cnb.dQC5J6ohAGA b289c86ca4 合并来自 auto/library-manager-eaa9 的合并请求 #25 
feat(library): 新增书库管理页面

PR-URL: #25
 2026-09-17 13:43:08 +08:00
cnb.dQC5J6ohAGA be606c0184 fix 2026-09-17 13:42:22 +08:00
cnb.dQC5J6ohAGA 282e0426c2 feat(library): 新增书库管理页面 2026-09-17 12:54:52 +08:00
cnb.dQC5J6ohAGA d5c4a13c45 合并来自 auto/fix-android-image-d4a4 的合并请求 #23 
fix(ci): Android 任务改用真实存在的 SDK 镜像

PR-URL: #23
 2026-09-17 12:29:56 +08:00
cnb.dQC5J6ohAGA 15be9105b1 fix(ci): Android 任务改用真实存在的 SDK 镜像 
androidsdk/android-35 在 Docker Hub 上不存在（该命名空间只发布到
android-31），prepare 阶段 docker pull 直接失败，流水线进不到任何
stage。改用含 platforms;android-35 的 mobiledevops/android-sdk-image。
 2026-09-17 12:27:38 +08:00
cnb.dQC5J6ohAGA 27547da43a 合并来自 fix/android-ci-assets-gaps 的合并请求 #21 
fix(ci): 让 assets 流水线真正验证产物会被打进 APK

PR-URL: #21
 2026-09-17 12:25:00 +08:00
cnb.dQC5J6ohAGA baf63c5b28 fix(ci): 让 assets 流水线真正验证产物会被打进 APK 
web-assets-ci 只跑了 build-web-assets.sh，证明脚本写完了 assets，却没证明
Gradle 会读那个目录 —— 而这两处此前就是漂移的：

- build.gradle.kts 的 assets.srcDirs 指向 android/app/web-assets，
  那是没有任何脚本写入的第三个路径；真正的产物落在
  android/app/src/main/assets/web-assets。于是 staged 的 bundle 不是 assets
  源，APK 照常构建成功，但里面没有客户端，启动即白屏。
- 注释依赖的 README.txt 占位文件已在 c18664f 被删除，所以干净 checkout 里
  这个目录根本不存在，assets.srcDirs 指向一个不存在的路径。
- build-web-assets.sh 的 rm -rf "$dest" 会把那个占位文件一起删掉，
  即使它还在，每次本地构建后工作树都会变脏。

改动：

- build.gradle.kts：assets.srcDirs 指向脚本实际写入的目录，注释写准。
- 恢复 web-assets.sh 目录下的 README.txt 占位，让目录进版本库。
- build-web-assets.sh：清理产物时保留 README.txt，不再制造脏工作树。
- 新增 verify-web-assets.sh：校验产物存在且是构建出的客户端、Gradle 声明的
  路径与产物路径一致、占位文件确实被 git 跟踪。
- .cnb.yml：web-assets-ci 增加该 stage，并把脚本自身 / build.gradle.kts /
  assets 目录纳入 ifModify —— 改这些本来不会触发任何验证。
- PR 侧补 android-contract-checks：桥接契约与渲染词表校验不需要 JDK/SDK，
  秒级，不该等到 main 的完整构建才发现。

验证：check-shell / build-web-assets / verify-web-assets 全部通过；
把 assets.srcDirs 改回错误路径可复现失败。.cnb.yml 通过语法/语义/Schema 校验。
 2026-09-17 10:30:00 +08:00
cnb.dQC5J6ohAGA f16ce0224e 合并来自 auto/docker-data-perm-f5ef 的合并请求 #20 
fix(docker): 允许非 root 用户写入挂载的 /data

PR-URL: #20
 2026-09-17 10:22:22 +08:00
cnb.dQC5J6ohAGA a2f17240c3 合并来自 fix/docker-image-pipeline-dind 的合并请求 #19 
fix(ci): 镜像发布改用 dind，插件任务拉不到自建镜像

PR-URL: #19
 2026-09-17 10:17:17 +08:00
cnb.dQC5J6ohAGA 0f53088ffe fix(docker): 允许非 root 用户写入挂载的 /data 
服务端以非特权用户 `reader` 运行，镜像里构建时做的 `chown /data` 在
`/data` 被 **挂载** 时完全失效：bind mount 的属主来自宿主机目录，宿主机上
`./data` 不存在时 Docker 会以 root:root 新建它，于是服务端写签名密钥时
直接以 `EACCES: permission denied, open '/data/token.secret'` 崩溃退出。
命名卷继承镜像的 chown，所以只有 bind mount 受影响，而 compose 与 README
推荐的正是 bind mount，等于默认路径就是坏的。

改动：

- 新增 `server/docker-entrypoint.sh`：以 root 启动，只在启动时把 /data
  这一层的属主改成 reader（不递归整棵树，避免大缓存目录每次重启都被
  chown），随后用 su-exec 降权到 reader 再 exec 服务端。服务端仍是 pid 1，
  main.ts 的 SIGTERM/SIGINT 优雅退出照常工作。若容器本来就不是 root
  启动（`--user`），脚本直接 exec 命令，不尝试改属主。
- `server/Dockerfile`：装 su-exec（约 10KB；alpine 的 busybox 没有等价的
  setpriv，util-linux 又不在基础镜像里），加 ENTRYPOINT。去掉 `USER reader`，
  因为降权改由入口脚本完成。
- `server/src/config/index.ts`：写密钥失败时，EACCES/EPERM/EROFS 不再只抛
  errno，而是报出「DATA_DIR 必须可写」并给出两种修法（改宿主机属主，
  或设 READER_TOKEN_SECRET 跳过写文件）。这是自部署最高频的坑，
  直接给出下一步能省掉一整轮排查。
- 新增 `server/test/config.test.ts`：覆盖密钥持久化与复用的稳定性、
  READER_TOKEN_SECRET 优先时不落盘、目录不可写时错误信息含修法、
  DATA_DIR 落在 BOOKS_DIR 内被拒。权限用例在非 root 下运行，
  以 root 跑测试时跳过。
- README 增加「故障排查」小节，写明成因与 4 步自查。

验证：`npm run typecheck` 通过；`npm test` 149 项 148 通过 1 跳过
（跳过项即需非 root 的权限用例，已用非 root 单独跑通）；以非 root 手动
复现 EACCES 路径，确认错误信息与修法正确；入口脚本的 chown + 降权流程
手动模拟通过。
 2026-09-17 10:16:11 +08:00
CodeBuddy 6bacf0121d docs(ci): 把注释里 docker-image 的历史与取舍写准 
远端分支上的合并保留的是 dind 方案，功能配置没问题，但注释里「为什么不用
kaniko」那段写的还是合并前的说法，与最终落地的实现有两处对不上：

- 只说了「docker.build 的产物不在 registry 上」，没写清真正卡住的是
  `image:` 必须与已构建镜像匹配这个约定，而它匹配失败时的表现形式恰好是
  `docker pull` 404 —— 也就是这次踩了八次的坑。
- 没提 `dockerfile-caches` 那个完整仓库地址能跑通的原因（它指向的是
  docker.build 算出来的缓存 digest），而那正是 dind 方案要绕开的东西。

只改注释，不动任何流水线行为。

Ref: #16
 2026-09-17 10:15:39 +08:00
cnb.dQC5J6ohAGA 2842b0168a Merge remote-tracking branch 'origin/main' into fix/docker-image-pipeline-dind 
# Conflicts:
#	.cnb.yml
 2026-09-17 10:14:57 +08:00
CodeBuddy 43ed4987d6 fix(ci): 镜像发布改用 dind，插件任务拉不到自建镜像 
`docker-image` 流水线从建立起来就没成功过一次，八次 push 构建全部在发布
这一步失败。根因一直没被定位到：插件任务（带 `image:` 的任务）的镜像名
必须是一个真实存在、可被 pull 的镜像引用。

前几轮修复都在调 `image:` 的写法，但那个值本身就不可能是对的：
`docker.build` 构建出来的镜像只存在于 runner 的本地 dockerd 里，而 CNB
起插件任务容器时走的是 `docker pull <image>`，不查本地。于是无论写成
`Dockerfile`、`kaniko.Dockerfile`、`.ci/kaniko` 还是 `.ci/kaniko/Dockerfile`，
结果都是同一类错误：

- 被当成 Docker Hub 官方镜像 → `pull access denied` / 404
- 含大写或非法字符 → `invalid reference format`

更早一轮加 root entry 也解决不了问题：`docker.build` 那步确实成功了，但它
只是给流水线级 `docker.image` 用的，对插件任务的 `image:` 没有帮助。

改为 CNB 官方的 `services: docker` + `docker build` / `docker push`。
换成 dind 之后整条链路只剩标准 Docker：不需要 kaniko，就不必再为保住
`COPY server/...` 的大小写而绕开工作区，`GIT_CLONE_PATH` 与
`--context-sub-path` 两个补丁一起消失；CNB 起 dind 服务时也会自动登录
制品库，`docker login` 那一步同样不再需要。

镜像路径走「同名制品」规则 `docker.cnb.cool/hectorqin/reader`，与 README
和 docker-compose.yml 里引用的地址一致；用 `CNB_REPO_SLUG_LOWERCASE`
拼而不是写死，避免仓库路径带大写时被 Docker 拒绝。

删除随之失去用途的根目录 `Dockerfile` 与 `kaniko-plugin.sh`。

Ref: #16
 2026-09-17 10:13:26 +08:00
cnb.dQC5J6ohAGA b6ed2d2e75 test(ci): point image at the fully qualified cached image 
CNB only maps image: to the built docker.build image when the value is a
bare name matching the dockerfile. Pointing at the registry path is a
workaround for that mapping not happening, and it may pull something that
looks nothing like the Dockerfile in this repo. Trying it to isolate the
mapping logic.

Ref: #16
 2026-09-17 10:12:29 +08:00
cnb.dQC5J6ohAGA ab0f9ace7f test(ci): quote the image name so it is not treated as a variable 
CNB substitutes $VAR everywhere in the config, and the bare word
`dockerfile` collides with the `dockerfile` its own job context defines —
the value was substituted with the empty string, so the runner pulled "".
Quoting defers substitution; a literal with no $ in it survives it.

Ref: #16
 2026-09-17 10:10:23 +08:00
cnb.dQC5J6ohAGA 6658224479 fix(ci): lowercase the image name that refers to the root Dockerfile 
CNB matches `image:` to `docker.build.dockerfile` case-insensitively
(`library/dockerfile` and `library/Dockerfile` name the same file), but
the value is also used verbatim as an image name, and Docker rejects
uppercase repository names. `dockerfile` satisfies both.

Ref: #16
 2026-09-17 10:07:47 +08:00
cnb.dQC5J6ohAGA fab37fb08c refactor(ci): put the kaniko Dockerfile at the repo root 
`docker.build.dockerfile` and `image:` are resolved by the platform before
`GIT_CLONE_PATH` takes effect, so at that moment the cwd is the workspace,
one level above the git repo root that a build context must live in. The
only path that is stable across both is a file at the root itself.

`kaniko.Dockerfile` + `kaniko/plugin.sh` therefore never resolved, and
`image: kaniko.Dockerfile` was fed straight to `docker pull` as an image
name. Both now sit at the root as `Dockerfile` and `kaniko-plugin.sh`.

Renaming the root Dockerfile means this repo no longer has an ambiguous
one at the top: the reader's own image is built from `server/Dockerfile`
and referenced as such. Dockerfile keeps its own ignore rules (it reads
`.dockerignore` in its directory), but the context here is one file wide,
so this is not a real concern.

Ref: #16
 2026-09-17 10:05:47 +08:00
cnb.dQC5J6ohAGA 76489296b3 fix(ci): give the kaniko image a lowercase name 
CNB passes the `image:` string straight to `docker pull`, and Docker
rejects any uppercase character in a repository name, so
`kaniko.Dockerfile` failed with `invalid reference format`. The value
just has to be a lowercase name; the build still comes from
`docker.build.dockerfile`.

Ref: #16
 2026-09-17 10:01:58 +08:00
cnb.dQC5J6ohAGA 015bd5ada1 合并来自 auto/fix-android-image-4a3c 的合并请求 #18 
fix(ci): Android 构建镜像改用 Docker Hub 官方命名空间

PR-URL: #18
 2026-09-17 10:01:08 +08:00
cnb.dQC5J6ohAGA 263793f9b6 refactor(ci): move the kaniko bits to the repo root 
CNB limits a `docker.build` context to the git repo root, and that root
is the pipeline's cwd, so `.ci/kaniko/Dockerfile` did not resolve at all
and the stage died on `docker pull .ci/kaniko`.

Move the Dockerfile to `kaniko.Dockerfile` and its script to
`kaniko/plugin.sh`, both at the root, and refer to the built image by the
same name as the Dockerfile that produced it. The `by` list only ever
matches paths relative to that root.

Ref: #16
 2026-09-17 09:59:51 +08:00
cnb.dQC5J6ohAGA 1d9bc48b46 fix(ci): drop the docker login stage, the kaniko image has no docker CLI 
The debug kaniko image is deliberately empty apart from the executor, so
`docker login` failed with `docker: not found`. The plugin takes the
credentials as parameters anyway, which is where the registry auth comes
from, so the separate stage was never doing anything for us.

Ref: #16
 2026-09-17 09:57:16 +08:00
cnb.dQC5J6ohAGA ec5fa83046 修复dockerfile 2026-09-17 09:55:13 +08:00
cnb.dQC5J6ohAGA 2a61eff97f fix(ci): give the kaniko image a root entry so CNB can start it 
CNB starts every pipeline container with `-u root`, and the kaniko
official image ships without `/etc/passwd` at all. The image built fine
and pushed fine, but running it failed at container start with
`unable to find user root: no matching entries in passwd file`.

Add the single account record. Nothing changes about which user the
container runs as; there was simply no name for uid 0.

Ref: #16
 2026-09-17 09:55:10 +08:00
cnb.dQC5J6ohAGA 666a1c29f9 fix(ci): list plugin.sh in build.by so the image build can find it 
CNB only puts the files named in `build.by` into the build context of a
`docker.build` environment image, and silently omits everything else
rather than failing. The kaniko image's `COPY .ci/kaniko/plugin.sh` was
therefore reading from an empty "client dir", which is why the build
failed with `"/.ci/kaniko/plugin.sh": not found` while the file is very
much in the repository.

The Dockerfile itself is exempt from the filter, so `dockerfile:` alone
had looked sufficient.

Ref: #16
 2026-09-17 09:53:32 +08:00
cnb.dQC5J6ohAGA 5ae1e965dc fix(ci): Android 构建镜像改用 Docker Hub 官方命名空间 2026-09-17 09:52:28 +08:00
cnb.dQC5J6ohAGA 4037a7f082 feat(ci): 合并后自动构建并推送 reader 镜像到制品库 
Ref: #16
 2026-09-17 09:51:58 +08:00
CodeBuddy 8982399e4a feat(ci): push the reader image to the CNB registry on main 
The repo had CI for the server, the client and the Android shell, but no
pipeline produced a container image, so `docker-compose.yml`'s
`cnb.cool/hectorqin/reader` was never updated by this repo.

Add a `docker-image` pipeline on `main` that builds `server/Dockerfile`
and pushes `docker.cnb.cool/hectorqin/reader` tagged with the branch name
and the short commit. It only runs when `server/`, `web/` or a build file
changed: the image contains those two and nothing else, and tagging a
documentation-only commit would just pile up identical layers.

The build uses a local copy of the market's kaniko plugin instead of the
published one. Two reasons, both from the repo's Windows-first workflow:

- Windows git checks the workspace out with lowercase directory names,
  and kaniko's default snapshotter keeps only all-uppercase paths, so
  `COPY server/...` fails with "no such file or directory". The copy runs
  with `--snapshot-mode=redo`, the tar-based snapshotter, which does not
  do that mapping.
- The upstream plugin never exposes `--context-sub-path`, so the fix has
  nowhere to go. The copy adds it, plus `--skip-tls-verify-registry` for
  the internal `docker.cnb.cool` address.

`GIT_CLONE_PATH` moves the workspace into `/tmp` so the pipeline's own
`.ci/kaniko/` files do not land in the build context, since a context must
stay inside the git repo root.

Ref: #16
 2026-09-17 09:51:12 +08:00
cnb.dQC5J6ohAGA 49edb577e2 合并来自 feat/http-tts-and-shelf 的合并请求 #15 
feat: HTTP TTS 与双端兼容朗读，书架体验与自定义设置

PR-URL: #15
 2026-09-17 09:46:14 +08:00
cnb.dQC5J6ohAGA 0370cd98e8 feat: HTTP TTS 与双端兼容朗读，书架体验与自定义设置 
朗读（Closes #13 的朗读部分）

新增服务端 HTTP TTS 代理与客户端第二、第三个朗读引擎，三者在同一个
SpeechEngine 接口下可切换：

- 服务端 GET /api/v1/tts 代理 TTS_URL 指向的合成服务（edge-tts / Piper
  等兼容形态），只代理不内置合成模型；GET /api/v1/tts/voices 回答
  「这个实例能用什么」，未配置时返回 http:false 而不是 404。
  按句合成、磁盘缓存、上游返回非 audio/* 时明确报错（一个指到网页的
  TTS_URL 会以 200 返回 HTML，塞进 audio 里既没声音也没事件）。
  /tts 是精确的查询串令牌白名单项之一：<audio src> 无法带 Authorization。
- 客户端 HttpTtsEngine 用 <audio> 而不是 Web Audio，事件驱动推进队列。
- 客户端 NativeTtsEngine 走 Android 外壳新增的 speech 接口（shell v3）：
  WebView 自带的合成器与系统的是两个引擎，手机系统装好的中文语音经常
  不在 getVoices() 里，这是「朗读没有中文声音」最常见的原因。
- speechAvailability 决定 auto 用哪个引擎：native → system → http。
- 原 TtsEngine 抽出 loadQueue/onChunk/onState 为公开字段以结构化满足接口。

书架

- 排序：最近更新 / 最近入库 / 书名 / 作者，中文按数字大小排。
  排序规则抽到 shelf-order.ts，离线路径与服务端用同一条规则。
- 密度、作者显隐、封面进度条；搜索一键清空 + 回车即搜；下拉刷新。
- 服务端 BookDto 增加 addedAt，否则客户端离线排序无法复现服务端结果。

自定义设置

- 朗读引擎可选（引擎多于一个时才显示该行）；音调行只对有声调的引擎出现。
- 书架设置独立成 sheet，与阅读面板分开。

测试与文档

- server: tts.test.ts（10 例）。web: tts-http / speech / shelf-order
  新增 39 例，合计 245 passing。
- android/scripts/check-shell.sh 修正为同时校验嵌套的 speech 接口，
  之前它只能看到一个顶层接口。
- README / docs/api.md / docs/architecture.md 补齐三个引擎的取舍、
  环境变量与错误码。

Ref: #13
 2026-09-16 23:29:41 +08:00
cnb.dQC5J6ohAGA 3910c95661 合并来自 auto/reader-ui-tts-4e4f 的合并请求 #14 
feat: 丰富阅读界面设置并支持系统 TTS 朗读

PR-URL: #14
 2026-09-16 23:11:26 +08:00
cnb.dQC5J6ohAGA 75718e9fb7 merge: 合并 main 并解决阅读界面与分窗读取的冲突 2026-09-16 23:11:10 +08:00
cnb.dQC5J6ohAGA d82fcf7010 合并来自 feat/lazy-chapters-native-pages 的合并请求 #12 
feat(reader): 按窗口读取、真机可编译的 Android 壳，以及分章契约的收口

PR-URL: #12
 2026-09-16 23:08:15 +08:00
cnb.dQC5J6ohAGA 058bee57a5 feat(web): 丰富阅读界面设置并支持系统 TTS 朗读 2026-09-16 22:55:58 +08:00
CodeBuddy b9b9c63605 merge: 把 main 合并进按窗口读取分支，并修正目录书页契约的两处缺陷 
冲突只有两处文档（README 的测试计数与端点清单、docs/api.md 的 /manifest 说明），
两边各自都是对的，所以按并集处理：计数取本分支的实际值，端点清单保留 main 新增的
/items、/toc、/file、/library/formats。

合并后按契约把两边一起验了一遍，发现目录书这条链路上有两个会被静默吞掉的缺陷，
都是「服务端仍回 200、读者看到的是坏内容」那一类：

1. 「卷」的判据里有一句 `images === 0`。整卷系列里放一张封面扫描是常态，于是
   `第01卷.cbz` 与 `第02卷/` 并列、旁边再有张图时，整个系列会被判成「不是漫画」，
   而它也不是别的格式的书——书架上直接消失。判据改成按来源问：压缩包的页就在包里，
   一个压缩包本身就是一卷；卷子目录要往下看才知道有没有页。散图仍由 MIN_IMAGES 管，
   既不能否定同级存在的整卷，也不该在自己是唯一页源时被当成书。

2. 页的资源引用被 API 层按「列表下标」拼成了 `page:<index>`，而这个格式的引用形态是
   `page:<卷>:<页>`。「一个压缩包算一页」意味着一个卷在列表里的下标与它在卷里的位置
   无关，于是按 `page:1` 去问一卷时格式处理器解不出引用，异常回退到「当普通文件发」，
   客户端请求一页、拿到的是那个压缩包——状态码 200，内容不对。引用现在由同一次页面
   遍历给出（manifest 的 files[].ref），/file 原样回传，不再有第二处实现。

顺带修正三处文档与实际不符的地方：`.cbr`/`.rar` 并未被解析（原「不做」清单暗示只有它
不做）、嵌套深度措辞与实现（读到第 4 层，且内嵌压缩包不展开）、README 的测试计数。

server 137/137（typecheck + test + build），web 179 vitest + 29 node:test（typecheck + test + build）。
 2026-09-16 22:49:45 +08:00
cnb.dQC5J6ohAGA 88ab67fcde 合并来自 auto/docs-page-contract-2285 的合并请求 #11 
fix(server,docs): 目录书页面清单成为契约，修正三处会让书静默消失的缺陷

PR-URL: #11
 2026-09-16 22:35:15 +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
cnb.dQC5J6ohAGA 5f1e29a3e5 fix(server,docs): 目录书页面清单成为契约，修正三处会让书静默消失的缺陷 2026-09-16 18:40:37 +08:00
cnb.dQC5J6ohAGA 533a70213d 合并来自 auto/init-server-scaffold-81b3 的合并请求 #10 
merge: 解决 auto/init-server-scaffold-81b3 与 main 的冲突

PR-URL: #10
 2026-09-16 18:18:21 +08:00
cnb.dQC5J6ohAGA c2afda5391 merge: 把 main 合并进 auto/init-server-scaffold-81b3 
main 引入了漫画目录书与逐页取图，本分支引入了格式注册表、H5 客户端与
Android 外壳。两边都改到了扫描器、metadata、library 路由与 web 客户端，
所以冲突不是文本级的，需要按语义逐项合并。

逐项取舍：

- scanner：本分支的注册表版本胜出。main 的 `collectComicDirectories` /
  `indexComicDirectory` / `comicOf`、`SUPPORTED_EXTENSIONS` 等常量都属于
  注册表之前的设计，保留两套会让目录书被索引两次。
- metadata：`parseBookFile` / `pdfInfo` 已被格式层取代，移除；`BookFormat`
  保持开放字符串，格式集合由注册表定义。
- library：`MIME_BY_EXT` 由注册表接管，避免 manifest 与下载端点对同一个
  文件报出不同的 content-type。单文件端点保留「目录书额外认领其目录下
  路径」的修复，否则漫画目录逐页取图全部 404。
- web：测试拆成两个运行器（vitest 与 node:test 互相无法执行对方用例），
  package.json / vite.config.ts 保留本分支的拆分。

合并后 server 128 项、web 147+26 项测试全部通过。

Ref: #9
 2026-09-16 18:13:39 +08:00
cnb.dQC5J6ohAGA ca68a03e5d merge: 解决 auto/init-server-scaffold-81b3 与 main 的冲突 
两个分支各自演进：一侧引入格式注册表、H5 客户端与 Android 外壳，另一侧
引入漫画目录书与逐页取图。冲突集中在扫描器、metadata、library 路由和 web
客户端，逐项按「两边能力都要保留」的原则合并。

合并后修复了 4 个被冲突掩盖的真实缺陷：

- scanner 同时保留了两套目录书实现，类型检查与测试均无法通过；改为统一
  走格式注册表，目录书在文件遍历之前发现，其内容不再重复入库。
- /manifest 的 files 对漫画目录书返回的是文件夹路径，客户端无法逐页取图；
  改为由 manifest 派生真实页路径。
- 单个文件端点只认 book_files 行，漫画目录书的每一页都 404；改为目录书
  额外认领其目录下的路径，并修正路径归一化使穿越尝试仍被拒绝。
- 目录书判定只看图片数量，会把夹着一本书的目录整体吞掉；改为注册表驱动
  的判定，含书籍文件的目录始终是书架。

同时修复了 web 端两套测试运行器互相无法执行对方用例的问题（vitest 与
node:test 混跑会静默跳过），以及 web 侧 5 处类型错误。

Ref: #9
 2026-09-16 18:04:11 +08:00
CodeBuddy 02453c93d3 docs: 更新 README / 架构 / API 文档 
记录本轮的四项决定与三个坑：
- 排版策略：出版方优先、变量层可被书拒绝、无 !important
- 渲染分工按内存而非速度划分
- 外壳用 Shadow DOM、书用 iframe 的完整理由
- column-fill 需要确定高度的实测结论
- 分窗与目录分离的原因
- 解析器版本机制与它解决的静默陈旧问题
- 子资源 query token 的白名单边界
 2026-09-16 15:49:22 +08:00
CodeBuddy 8e55dc23a3 fix(web,build): 无封面的书不再显示破图；镜像内置 H5 客户端 
- 没有封面的书（大部分 txt、不少 pdf）之前是一个 <img> 不设 src，
  浏览器渲染成破图图标 —— 那读起来像"这个书库坏了"，而事实是"这本书没有
  封面"，读者无从分辨。改为显示书名首字（相当于书脊），并在封面加载失败时
  也回落到同一占位。
- Dockerfile 加 web 构建阶段，`WEB_DIR=/app/public`，镜像里自带完整阅读器。
  构建失败必须让镜像失败：一个没有客户端的服务端会看起来部署成功，
  实际打开是落地页而不是阅读器。
- CI 拆成 server/web 两条，失败模式不同（读不了书 vs 白屏）。
- compose 构建上下文改为仓库根目录（从 ./server 构建会得到一个没有客户端的
  服务端）。

已按 Dockerfile 的三阶段在本机复现验证：web 构建产物 + 服务端 dist +
prune --omit=dev 后的 node_modules，用生产布局起服务，浏览器实测四个格式
全部正常、零控制台错误。
 2026-09-16 15:48:52 +08:00
CodeBuddy 8570fb12ef docs(android): 定义外壳与 H5 的接口契约，暂不写不可验证的代码 
本环境没有 JDK 与 Android SDK，编译不了的 APK 不放进来。

写下来的是已被验证的部分：
- 按 kind 分流的渲染分工（用户那条「epub 走 H5、其他走原生」），
  契约点在 web/src/ui/reader-view.ts 的 capabilities()
- 桥接对象契约（web/src/bridge.ts 已实现读取侧，且无桥时正常工作）
- 离线缓存与断点续传所需的接口，服务端已就绪
- 硬件键、返回回调的接法，以及明确标出哪些回调还没实现

同时写清开工需要什么（JDK/SDK/产物复制），避免下一轮重新推一遍。
 2026-09-16 15:29:11 +08:00
CodeBuddy 5e8d14b460 fix(web): 用 iframe 承载章节文档，浏览器实测逼出来的四处修正 
真机（Chromium，390x844）跑通整条链路后，之前"看起来对"的地方全都露馅了。
这一轮把渲染层按实测重做，四个都是必须修的：

1. **章节必须是真文档，不能是 shadow DOM 里的片段。**
   章节里的 <img src> 和 <link rel=stylesheet> 是浏览器自己去请求的，
   没法带 Authorization 头。把它们注入宿主文档的结果是每个插图、每个
   样式表都 401 —— 书渲染成无样式无图。iframe 是真浏览上下文，它的
   子资源请求是普通导航，URL 里带什么就发什么。所以：外壳用 shadow DOM
   （挡的是客户端样式往书里漏，这是它真正能挡的方向），书本身用 iframe。

2. **子资源的 token 只能走 query。**
   服务端新增 `queryTokenAllowed`，白名单式放行：仅 GET、仅
   /api/v1/books/*/assets|cover|content。触发扫描、写元数据这类端点一律
   不接受 URL 里的 token —— 那才是真正会泄到日志和 Referer 的地方。
   新增 5 个测试固定这条边界。

3. **`column-fill: auto` 需要确定高度，否则根本没有分页。**
   body 不设高度时它会撑到内容高度，整章排成一列，scrollWidth 等于
   clientWidth —— 翻页手势完全无效，一章只显示一页。修完 390px 宽的一章
   是 3732px / 9 页，翻页步长精确 422px（390 + 32 gutter）。
   同时去掉 scroll-snap：吸附目标是列边缘而不是我做出来的页边界，
   会导致 scrollLeft 落在两页之间、甚至一次跳两页。

4. **`pageWidth` 是上限不是实际宽度。**
   手机上 720px 的列比屏幕还宽，同样退化成"一章一页"。取
   min(读者设置, 实际宽度)。

另外发现并按格式分流修好的：PDF（kind=document）之前落进了图片翻页器，
读者看到的是一个破图；现在走 PdfReader。
封面 <img> 也漏了 token，一并改成 api.coverUrl()。

顺带把一个设计缺陷拆开了：目录不再从 manifest 的 groups 取。
groups 是传输分窗，它把目录显示成「第 1 章 – 第 40 章」——服务端的分页
边界漏进了 UI。新增 /books/:id/toc，按格式返回真正的目录
（epub 的 spine 标题、txt 的章节、漫画的卷），与分窗互不干扰。
 2026-09-16 15:28:34 +08:00
cnb.dQC5J6ohAGA cae76c2055 合并来自 auto/client-android-h5 的合并请求 #4 
feat: 客户端 Android 与 H5 双端，含精排渲染层

PR-URL: #4
 2026-09-16 15:17:40 +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
CodeBuddy 0a17174fb8 fix(server): 让解析器修复能真正到达已入库的书 
改 EPUB 读取时发现两个连在一起的坑，都会静默留疤：

1. `spineLength()` 用内存里的 zip 打开，但里面调用的 `readPackage` 又要求
   从文件读，于是每本 epub 的 page_count 都是 null 且不报错。
   `null` 同时也是"这个格式本来就报不出页数"的合法答案，下游无法区分。

2. 更麻烦的是：即使修好 1，已入库的书也修不回来。变更检测基于内容哈希，
   而解析器修复不改变任何字节，扫描恰好会跳过最需要重读的那些文件。
   于是坏结果永久留存——这正是这个 bug 在真实书库里的表现。

修法是给解析结果带上版本号：`book_files.parse_version` 记录是哪一版解析器
写下的，`PARSE_VERSION` 一旦提升就强制重解析一次。自部署用户不会按时升级，
所以版本得跟着数据行走，不能只活在进程里。

配套：schema 加一段可重复执行的增量迁移（SQLite 不支持 ADD COLUMN IF NOT
EXISTS，靠 duplicate column 错误判断已执行过），旧库能原地升级。

新增的日志出口 `lib/log.ts` 是因为扫描器和解析器跑在定时器里，没有请求
可以借 logger；静默正是 1 得以存在的原因。
 2026-09-16 14:48:35 +08:00
CodeBuddy d0a475919d feat(web): H5 客户端，精排 epub 渲染 + 多格式阅读 
用户的三个问题在这里落地：

1. 「H5 是一个完整的客户端」——同一份构建产物既由服务端托管（`/` 直接
   就是完整阅读器），也可被 Android 外壳打进 assets 复用，两种宿主只差
   一个 serverUrl。

2. 「纯 H5 时 epub 等资源是否需要 iframe 或 shadow DOM」——用 shadow DOM，
   但不是为了隔离出版方样式（那做不到也不该做：书必须能给自己排版）。
   它挡的是反方向：客户端自身的 CSS 不会漏进书里。iframe 只在 PDF 那一处
   用，因为 PDF 需要自己的浏览上下文，理由写在 render/container.ts 里。

3. 「Android 端 epub 用 H5 渲染，其他类型用原生」——按 kind 分流，
   capabilities() 明确声明：reflowable 走 WebView，paged/document 在
   Android 交回原生。理由写进 reader-view.ts：WebView 每页一个合成层，
   300MB 的画册在一台中端机上就是 OOM。

服务端同步配合的两处：
- 资源流式下发 + HTTP Range
- epub 按包内路径寻址、items/manifest 分窗

前端无框架：渲染热路径是命令式 DOM 操作，引框架只会把"最小覆盖 CSS"
的策略搞复杂；最终产物 35KB（gzip 10.7KB）。
 2026-09-16 14:45:04 +08:00
CodeBuddy 80454c2491 perf(server): 按需读取书籍容器，章节/页流式下发 
EPUB 与漫画此前每次 manifest / assets 请求都整包解压（EPUB 走 JSZip）。
一本 50MB 画册的每次翻章都会把整个压缩包读进内存；扫全库时更糟。

- EPUB 改走项目自研的 zip-reader，只读中央目录 + 按需解压条目
- 新增 ZipArchive.openStream()：stored 直接读，deflate 走流式 inflate，
  单页取图不再需要整包驻留
- 资源响应支持流式下发，seekable 资源支持 HTTP Range（断点续传、
  PDF 跳页、漫画跳卷都靠它）
- epub 章节改为按包内路径寻址（xhtml:OEBPS/ch1.xhtml），不再用 spine 下标：
  分窗加载后下标在不同窗口里指向不同章节
- items/manifest 支持 ?group=N 分窗，group 自带 offset，客户端拿到单窗
  也能定位到全书位置
- /manifest 直接带回可寻址结构，打开一本书从两次往返降到一次
 2026-09-16 14:40:28 +08:00
cnb.dQC5J6ohAGA ecc5327aba 合并来自 auto/support-more-formats 的合并请求 #3 
feat: 支持 txt 与漫画等多种格式，格式层改为注册表

PR-URL: #3
 2026-09-16 14:33:17 +08:00