 hectorqin
|
ecb2ef4806
|
fix(web): 修复阅读页章节跳转失灵，补齐上一章/下一章
|
2026-09-17 23:52:11 +08:00 |
|
 cnb.dQC5J6ohAGA
|
dbaac99b45
|
feat(web): 界面加路由，首页重做
首页（书架）此前是纯命令式拼出来的，而整个客户端没有任何路由：URL 从头到尾不变，
返回键、刷新、分享、收藏一概不成立。
## 路由
`ui/router.ts` 把 fragment 解析成 route，shell 渲染 router 报上来的那个：
#/shelf 书架
#/book/<id> 阅读器
#/library/<路径> 书库里的目录
用 fragment 而不是路径，是因为同一份产物要被两个宿主加载，而两个都服务不了任意路径：
Android 从 appassets.androidplatform.net 加载（那里没有服务端），H5 由 reader 服务端
托管（没有客户端路由回落）。路径式路由会在 vite dev 里正常、在两个生产宿主里 404。
返回走应用自己的屏幕轨迹，不走 history.back()：应用里的「返回」是「上一个屏幕」，
而浏览器历史里可能有登录表单或别的站点。轨迹为空时（新标签页里粘贴的链接）替换成父级，
而不是压入——否则那个链接会永远压在书架后面。
走进书库子目录用 replace：书库是一个带面包屑的屏幕，走目录是同一个屏幕改自己的参数。
压栈的话，读者走过四个文件夹再按返回会逐层退出来。
带着链接进来而尚未登录时，route 存在 App.pending 里等在登录页后面，登录后直接落到
目标屏幕，而不是落到一个他从未见过的书架。
Android 外壳的返回手势不需要改动：它看的是 WebView 的 canGoBack()，而路由现在真的
往 WebView 历史里写——之前那段注释描述的行为，从这次起才成立。
## 首页
- 先看到书，再看到控件：标题和封面在最上面，搜索在后，排序与数量贴在它们作用的那一节上。
旧版把搜索框、数量、四个排序 chip 依次排在封面之前，三行控件才轮到第一本书。
- 排序栏是唯一吸顶的东西，它承载的是读者会滚回去改的两件事。
- 空状态给一条出路（打开书库管理 / 刷新 / 清除搜索），而不是一句「书库还是空的」。
- 冷启动画骨架屏，且按当前密度画——密度不对的骨架屏会让读者看到布局动两次。
- 封面缺图时把书名画成封面，而不是一个灰色方块。
## 顺手修掉的 5 个真缺陷
1. mountUI 在 unmount 之后仍会渲染。屏幕是异步加载的，离开后那条迟到的响应会把
整棵树画进一个刚被清空的容器；书架迟到的响应会把自己一屏封面画进书库管理器。
2. --safe-left/-right/-top/-bottom 从未在生效的样式表里定义过，只有一份没人 import 的
死样式表定义过。未定义的自定义属性会让整个 calc() 失效并静默丢弃声明。
3. 封面在 flex 列里没有显式宽度，aspect-ratio 盒子因此收缩到内容宽度：只有书名的封面
塌成 42px、有图的占满卡片，整排看起来参差不齐。
4. 阅读列在宽屏上被拉伸到 9 列 45px 的封面。现在内容列封顶 68rem，封面随断点变大。
5. 删掉 web/src/ui/styles.css——414 行从未被引用的旧样式，以及 .book-highlight 等
已经没有任何代码产出的规则。
## 验证
- web 全量 284 项测试通过（新增 router 19 项 + 链接契约 4 项）。
- typecheck / build / check-shell.sh / build-web-assets.sh 均通过。
- 真浏览器实测：深链直开、刷新不丢、返回离开屏幕、登录后落回目标、书库走目录、
空搜索、粘性工具栏、深浅色、390px 与 1440px 两档宽度。
- 体积：251KB → 252KB（gzip 79.1KB）。
|
2026-09-17 18:49:53 +08:00 |
|
 CodeBuddy
|
586bec25b1
|
refactor(web): 界面层迁移到 Preact，排版层保持命令式
书架、登录、书库管理、以及阅读器的铬层（顶栏/页脚/目录/设置面板/朗读条）
从「构造函数建节点 + 实例字段 + 若干 render*()」改成组件树 + 单一状态。
阅读舞台——分页、注入文档、shadow root、量测列宽——仍然零框架。
为什么换：
- 同一份状态有多个副本。分段控件的选中态既在 settings 又在 aria-pressed 上，
靠点击处理器手工同步；LoginScreen 的通知/错误/注册开关/按钮文案是四个节点
被五个地方改，漏一处不报错。
- 重建与状态互相矛盾。朗读引擎行要在 HTTP 能力探测回来时重新生成，而整块
面板重建会丢掉面板滚动位置，于是长出一套「只替换 [data-speech=group]」
的定点重建；改成组件后探测只是改状态，diff 天然保住滚动位置。
边界（写在 ReaderScreen 里，不靠自觉）：
- stage 由类持有并交给 ReaderView，只通过 ref 回调挂进组件树；组件决定它
放在哪，内容一概不碰。mountUI() 是组件树与类式屏幕之间唯一的接缝，
路由仍不认识框架，测试仍打在真实 DOM 上。
配套：
- toolkit.tsx：IconButton / Button / Segmented / SwitchRow / Scrim 这些原语
各把 a11y 与状态细节收在一处，消掉两处手工 aria-pressed 同步。
- vendor/preact.ts：框架唯一入口，只 re-export preact 与 preact/hooks，
无 preact/compat、无 react-dom、无额外 signals 依赖。
- tsconfig: jsx=react-jsx, jsxImportSource=preact。
- 修一处回归：书库管理的状态行改由 listing 推导，写入结果跨重载保留。
验证：web 全量 260 项测试通过（manager.test.ts 断言逻辑未改），
typecheck、build、android check-shell.sh、build-web-assets.sh 均通过。
产物 235KB → 245KB（gzip 71.2KB → 77.2KB）。
|
2026-09-17 17:52:18 +08:00 |
|
|
cnb.dQC5J6ohAGA
|
b7ffa42c80
|
feat(library): 支持上传书籍与批量管理
|
2026-09-17 16:50:47 +08:00 |
|
|
cnb.dQC5J6ohAGA
|
282e0426c2
|
feat(library): 新增书库管理页面
|
2026-09-17 12:54:52 +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
|
75718e9fb7
|
merge: 合并 main 并解决阅读界面与分窗读取的冲突
|
2026-09-16 23:11:10 +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
|
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
|
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
|
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 |
|
|
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 |
|