mtfyun/reader
1
0 Fork 0
mirror of https://github.com/hectorqin/reader.git synced 2026-11-13 06:20:54 +08:00
Code Issues Packages Projects Releases Wiki Activity
20 Commits 16 Branches 1 Tag
058bee57a57301f95fdca93d4d59370e45c8e5e2
Commit Graph
8 Commits
Author SHA1 Message Date
cnb.dQC5J6ohAGA 5f1e29a3e5 fix(server,docs): 目录书页面清单成为契约，修正三处会让书静默消失的缺陷 2026-09-16 18:40:37 +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 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
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 664141f0f1 feat: 支持 txt 与漫画等多种格式，格式层改为注册表 
原先只认 .epub 和 .pdf，本地书库里占很大比重的 txt 长篇与漫画
（cbz、图片目录）会整片「消失」—— 用户能看到文件在 NAS 上，却在
书架里找不到，这是最让人困惑的一类问题。

格式列表硬编码在三处（扫描器白名单、parseBookFile 分支、content-type
映射表），加一种格式要同时改三处，漏掉任何一处就得到一个「扫到了但读不
出来」的安静 bug。这次把格式收进注册表，并补齐四种格式。

新增格式
- cbz / zip：按包内页序自然排序翻页，扫描时不解压到磁盘
- 漫画目录：一个目录一本书，子目录为卷，支持卷/页两级寻址
- txt：UTF-8 严格解码失败才回退 GB18030（UTF-16 BOM 也识别），
  按中文网文章节标题分章，正文可按章节或字节偏移读取
- 单张图片按单页读物入库
- 明确不支持 cbr/rar：需要非自由解压实现，与单容器约束冲突

格式层
- registry.ts 定义 handler 契约（parse/manifest/asset）与扩展名路由，
  扫描器与 HTTP 层只与它对话；扩展名白名单、能力声明、遍历过滤都自动派生
- zip-reader.ts 自研只读 ZIP，只用 node:zlib。JsZip 会把整包解压进内存，
  而漫画动辄几百 MB，首次扫描真实漫画库会 OOM
- natural-sort.ts 自研自然排序：page10 必须排在 page2 之后，
  否则整本漫画的阅读顺序是乱的；不用 localeCompare 是因为 ICU 行为
  在不同平台上不一致
- epub 章节返回前重写章节内的相对资源引用，否则 WebView 里图片/字体/
  样式全部 404；绝对 URL、data: URI 与文内锚点保持原样，脚注不会坏

修复
- 目录型读物认领后，其内部文件从索引中排除，否则同一部漫画会以
  「系列 + 每卷 + 每页」的形式重复出现
- 目录认领顺序改为从外往里：反过来的话一部漫画会变成 N 本独立卷
- 主键新增原地编辑规则：txt/漫画没有内嵌标识，追加一章会算出新 id
  并把读者进度留在旧记录上。现在同路径原地编辑算更新，移动/重命名
  仍走内容哈希规则，所以进度都保得住
- 损坏的 .cbz 仍然入库并记录失败原因，而不是静默从书架消失
- PDF 不再用正则猜页数（会匹配到无关的 /Count 并报出错误页数，
  让客户端分页错乱），改为诚实上报 null
- 清理已迁出的 parseBookFile / pdfInfo / SUPPORTED_EXTENSIONS

测试
- 新增 65 个用例（共 92 个）：真实 zip 与真实文件，不用 mock；
  fixtures 由测试自己生成，不需要签入二进制
- 覆盖自然排序、编码探测、ZIP 边界（ZIP64/加密/超大条目）、
  目录认领、原地编辑、只读约束、各格式的读取端点
 2026-09-16 14:31:15 +08:00
cnb.dQC5J6ohAGA 2233b295bb feat: 初始化自部署书库服务端 
按产品设计 v0.2 落地服务端，覆盖第一版范围中的扫描、元数据、权限与同步。

核心决策：
- 书籍主键用 dc:identifier + 内容哈希，不用文件路径。
  重命名/移动不丢进度，副本自动合并，重新编码的文件保持独立。
- 库目录只读挂载，写操作全部落到 DATA_DIR。
  启动时断言 DATA_DIR 不在 BOOKS_DIR 内，路径解析统一走 resolveInside
  拦截逃逸，扫描不跟随符号链接。
- 元数据优先级：手动修改 > 内嵌 > provider > 文件名解析。
  手动修改独立成表，扫描永远碰不到，可单字段撤销。
- 中文文件名解析采取保守策略，无证据时不猜测作者方向。
- 离线合并用 LWW，笔记删除写墓碑，批次单事务。
- 无原生编译依赖：node:sqlite 与 scrypt 均为内置模块。

交付：
- Fastify + TypeScript 服务端，Docker 单容器
- 27 个自动化测试用例全部通过
- AGPL-3.0，README 做到一条命令跑起来
- CNB 流水线：typecheck / test / build
 2026-09-16 14:07:25 +08:00