# API 参考 基础路径 `/api/v1`。除标注「公开」外都需要 `Authorization: Bearer `。 错误响应统一格式（请求体 / 查询参数校验失败时 `code` 为 `BAD_REQUEST`，未处理的服务端错误为 `INTERNAL`）： ```json { "error": { "code": "NOT_FOUND", "message": "book not found" } } ``` ## 兼容性承诺 只做加法。已有字段的语义不会改，端点不会删。 客户端可以按 `apiVersion` 判断能力，但不需要为小版本做分支。 --- ## 实例信息 ### `GET /instance` — 公开 ```json { "name": "reader", "apiVersion": 1, "registrationOpen": false, "registrationMode": "closed", "invitationRequired": false, "userCount": 3 } ``` 客户端用它区分「全新实例」（可以注册）和「已被占用」（需要管理员开账号）。 `apiVersion` 是**能力版本**，与包的版本号无关：只有在字段语义变化、客户端必须改行为时 才动它。加字段、加端点都不动——这正是「只做加法」能成立的原因。 ### `GET /health` — 公开 ```json { "status": "ok", "booksDir": "/books", "dataDir": "/data", "version": "0.1.0", "dataDirIsInsideBooks": false } ``` `dataDirIsInsideBooks` 恒为 `false`——为 `true` 时服务端根本不会启动。 暴露出来是为了让运维一眼确认挂载点就是自己以为的那个。 --- ## 书内搜索 ### `GET /books/:id/search?q=关键词&cursor=上一页游标` 仅允许搜索当前用户书架中的书籍，支持 TXT 和 EPUB。关键词去除首尾空白后搜索，原始长度限 1–200 个字符。响应不缓存。 ```json { "hits": [{ "title": "第一章", "excerpt": "匹配附近的文字", "anchor": { "sectionId": "chapter:0", "start": 10, "end": 12, "quote": "关键词", "prefix": "前文", "suffix": "后文" }}], "failures": [], "scanned": 8, "total": 30, "limited": false, "nextCursor": "8.签名" } ``` 服务端按需扫描正文，每页本地最多 8 章、远程最多 1 章，每页最多返回 200 条匹配；`limited` 表示达到匹配上限。客户端连续请求 `nextCursor`，最多展示 200 条。游标绑定书籍目录、版本、关键词和个人整理版本，条件变化需重新搜索。此接口不是预建全文索引。 单章限制 8 MiB；失败章节在 `failures` 中返回 `{title, code}`，保留其他章节结果。客户端停止请求会取消后续扫描。返回定位包含当前用户的个人纠错。 使用自定义 TXT 标题规则时返回 `400 SEARCH_LOCAL_LAYOUT`，客户端使用本地目录和缓存搜索并明确提示。断网时同样仅搜索已缓存内容，缓存不完整时提示结果可能不完整，不下载整书到浏览器搜索。 ## 认证 ### `POST /auth/register` — 公开 ```json { "username": "owner", "password": "至少8位", "displayName": "图书馆长" } ``` - 首个账号恒可注册，且自动成为 `admin` - 之后按管理员设置的注册策略开放；首次初始化时从旧 `ALLOW_REGISTRATION` 导入，随后以数据库配置为准。 - 邀请模式需要提交 `inviteCode`，无效、过期、停用或用尽的邀请码返回 `400 INVITE_INVALID`，未填写返回 `400 INVITE_REQUIRED`。普通注册只创建普通用户。 - 关闭时返回 `400 REGISTRATION_DISABLED` - 用户名 / 密码缺失或超长（用户名、显示名 ≤100，密码 ≤1024）返回 `400 BAD_REQUEST`；用户名少于 3 位返回 `409 USERNAME_TOO_SHORT`，密码少于 8 位返回 `409 PASSWORD_TOO_SHORT`，重名返回 `409 USERNAME_TAKEN` 返回 `201`： ```json { "user": { "id": "...", "username": "owner", "displayName": "图书馆长", "role": "admin", "createdAt": 1789537801289 }, "session": { "user": {...}, "accessToken": "...", "accessTokenExpiresAt": 1789624201289, "refreshToken": "...", "refreshTokenExpiresAt": 1821073801289 } } ``` ### `POST /auth/login` — 公开 `{ "username": "...", "password": "..." }` → 同上（不含 `user` 外包一层） 失败恒为 `401 BAD_CREDENTIALS`，不区分「用户不存在」和「密码错误」。 账号停用返回 `403 ACCOUNT_DISABLED`。 ### `POST /auth/refresh` — 公开 `{ "refreshToken": "..." }` → 新的 `session`。 **刷新令牌会轮转**：传入的那个立即作废。客户端必须持久化新的那个。 ### `POST /auth/logout` `{ "refreshToken": "..." }` → `{ "ok": true }`。幂等，重复调用不报错。 ### `GET /auth/me` → `{ "user": { ... } }` ### `POST /auth/password` `{ "currentPassword": "...", "newPassword": "..." }` → `{ "ok": true }` 当前密码错误返回 `401 BAD_CREDENTIALS`。会撤销该账号**所有**会话（含当前设备），需要重新登录。 --- ## 书架 ### `GET /books` 查询参数： | 参数 | 说明 | | --- | --- | | `search` | 匹配书名 / 作者 / 系列 / ISBN | | `author` `series` `tag` `format` | 精确过滤 | | `path` | 只返回**这个目录下**（含子目录）有文件的书。库内相对路径，`''` 等于不过滤 | | `scope` | `shelf`（默认）\| `library`。见下 | | `status` | `reading` \| `want` \| `finished`，仅书架范围生效，见 [`PUT /books/:id/reading-status`](#put-booksidreading-status) | | `sort` | `title` \| `author` \| `added` \| `updated`，默认 `added` | | `order` | `asc` \| `desc`，默认 `desc` | | `page` `pageSize` | 默认 1 / 50，`pageSize` 夹到 1–200 | ```json { "items": [ { "id": "...", "title": "三体", "author": "刘慈欣", "series": "地球往事", "seriesIndex": 1, "tags": ["科幻"], "format": "epub", "coverUrl": "/api/v1/books//cover", "fileSize": 1843, "source": "embedded", "manualFields": [] } ], "total": 1, "page": 1, "pageSize": 50 } ``` 只返回当前账号可访问的书籍；本地文件被删的书不会留在书架上。 `path` 是对 `book_files.rel_path` 的**前缀匹配**，带上分隔符：`path=科幻` 匹配 `科幻/…`，不会匹配到旁边的 `科幻小说`。`%` 和 `_` 在文件名里合法、在 `LIKE` 里是通配符， 两个都转义。 它就是书库**浏览页**（`#/library/<路径>`）的数据源：那一页是「这个文件夹里的**书**」， 而书是这个 DTO 的形状——拿 `/library/browse` 的文件行去画网格，是把文件名画在书名的 位置上。浏览页的搜索框就用上面那个 `search` 参数，所以它是**这个文件夹内**的筛选 （`path` 和 `search` 同时生效），而不是整个库的搜索；整个库的搜索是书架的事。 ### `scope`：书架，还是索引 默认的 `shelf` 是「**我能读什么**」：一行 `user_books`（`hidden = 0`）以及可用文件、已下载文件或属于当前用户的章节出版物。 它也是书架屏用的那个。 `scope=library` 是「**这个文件夹里有什么**」：每一个有活文件的书，**不管这本书在不在 调用者的书架上**，并且每一项多一个字段： ```json { "shelfState": "on" | "off" } ``` 它是浏览页用的那个，因为浏览页的存在理由就是「把这本书加入书架」——问书架的话， 返回的每一本都已经在书架上，`shelfState` 恒为 `'on'`，**那个动作永远画不出来**。 一个商城只陈列你已经买过的东西，就没有东西可以加。 `shelfState` **只在 `scope=library` 时出现**。书架自己的列表里它恒为 `'on'`， 一个常量字段是一个客户端迟早会画出来的字段。缺省与 `'off'` 是两个不同的事实 （老服务端没有这个字段 / 有字段且明确不在），客户端对缺省不画控件。 `library` 作用域里的排序键 `added` 用 `COALESCE(ub.added_at, b.updated_at)`： 没有 `user_books` 行的书在 `DESC` 下会被 SQLite 排在**最前**， 那个顺序读起来就是「读者从没上架过的那本书是他最近拿到的」。 `BookDto.addedAt` 本来就按同一规则兜底，所以两处说的一样。 客户端只在 `path=''` 时省略这个参数（省略等于根目录），**不发 `path=` 空串**： 一个空路径是根，一个「我传了个空的」不是同一个请求。 `source` 是基础元数据的来源，`manualFields` 列出被手动改过的字段。 ### `GET /books/:id` → `{ "book": {...}, "progress": {...} | null }` ### `GET /books/:id/manifest` 渲染器布局前需要的清单。**打开一本书就是这一次请求**，可寻址结构也在里面， 所以客户端拿到响应就能画出第一屏。**已经带上第一个窗口的可寻址结构**： `?group=N` 只换窗口，`groups` 始终完整。 ```json { "book": {...}, "contentUrl": "/api/v1/books//content", "coverUrl": "...", "files": [ { "rel_path": "小说/三体.epub", "size": 1843, "missing": 0 } ], "content": { "kind": "reflowable", "total": 42, "groups": [...], "items": [...] }, "kind": "reflowable", "total": 42, "groups": [...], "items": [...] } ``` `kind` / `total` / `groups` / `items` 与 `content` 的内容相同，同时放在顶层是**冗余的 兼容层**：它们先于 `content` 存在，且 `kind` 是外壳判断「谁来渲染」的唯一开关 （见 `android/contract.md`）。新客户端读 `content`，老客户端读顶层字段，两者都不会错。 **`files` 让客户端能区分「另一份副本」和「文件真的没了」**：`missing: 1` 表示行还在、 磁盘上没了。它同时是 `/books/:id/file` 的**契约**——manifest 列出哪些路径构成这本书， `/file` 就服务哪些路径，多一条也没有。两边的清单由**同一个页面遍历**生成， 所以不会互相漂移。 对单文件书，这里是文件表里的行（一般是 1 条）。对目录书，这里由格式处理器给出： 页面就是**页面自己的库内路径**，压缩包里的页面按**压缩包自己的路径**列出（一个压缩包算一页）， 包内页码由同一条目上的 `ref` 寻址——`ref` 是不透明引用，客户端原样回传 `/assets?ref=` 即可， 不要自己拼。 `?group=N` 会把 `items` 收窄到第 N 组，`groups` 仍然完整——这样打开一本 40 卷的漫画 只传一卷的条目。目录客户端用 `/toc`，不要自己拼 `groups` 的标题。 ### `GET /books/:id/items?group=N` `group` 省略时返回完整条目；传入 `group=N` 时只返回对应窗口。首次打开时应优先使用 `/manifest` 返回的窗口；文件书的 `/manifest` 默认是第一个窗口，这是刻意的： 不带参数的调用是「打开这本书」，它必须便宜。要完整结构用 `?group=all`。 书里有哪些**可寻址的单元**：章节、页、卷。这是客户端构建目录和分页的地方。 契约对所有格式一致，`kind` 字段告诉客户端该按什么方式渲染： | `kind` | 含义 | 典型格式 | | --- | --- | --- | | `reflowable` | 可重排文本，按章节加载 | epub | | `paged` | 固定页序的图片 | cbz、漫画目录、单图 | | `text` | 连续文本，可能带章节 | txt、chapters | | `document` | 不透明文档，客户端自己渲染 | pdf | | `single-image` | 单页图片 | 单个图片文件 | **章节按包内路径寻址，不按下标。** `items[].href` 是不透明的格式私有引用 （`xhtml:OEBPS/ch1.xhtml`、`page:17`、`chapter:4`），客户端原样回传即可。 下标只在一个窗口内成立：分窗返回的是 spine 的前缀，所以按下标算出的章节 在完整 spine 里指向另一章。 ```json { "kind": "paged", "total": 6, "groups": [ { "id": "v0", "seq": 0, "title": "第01卷", "count": 3 }, { "id": "v1", "seq": 1, "title": "第02卷", "count": 3 } ], "items": [ { "id": "0:0", "seq": 0, "title": "001.jpg", "kind": "page", "mediaType": "image/jpeg", "href": "page:0:0" } ] } ``` `groups` 是卷（漫画）或单一隐式分组（epub/txt）。`?group=N` 只返回第 N 组， 让客户端一次只取一卷而不是整个系列的几千页清单。 `total` 在格式无法廉价得知时为 `0`，`groups` 为空 —— 例如没有标题的纯文本。 不要把它当作错误。 ### `GET /books/:id/toc` 书的目录。**与 `/items` 分开**，因为两者要的性质相反：`/items` 是传输边界， 一次给一点；目录必须完整，否则跳转是残的。合成一个接口会让目录显示成 「第 1 章 – 第 40 章」——服务端的分页边界漏进 UI。 ```json { "toc": [ { "href": "xhtml:OEBPS/text/ch1.xhtml", "title": "第一章", "level": 0, "spine": 0 } ] } ``` `spine` 是全书下标，`/items?group=N` 的每个 group 都带 `offset`，所以客户端 拿到单窗也能把跳转落到正确章节，不需要把前面的 count 加一遍。 按格式：epub 取 spine 标题（NCX / nav），txt 取分章结果，漫画目录取卷， pdf / 单图没有独立目录，回落到 items。来源章节出版物（`chapters`）的目录取自当前快照， 响应额外带 `revision`。 ### `GET /books/:id/assets?ref=` 取单个资源。`ref` 是**不透明**的格式私有引用。客户端优先取 `items[].resourceRef`，字段不存在时取 `items[].href`，原样回传，不要自己拼。已有文件格式不需要 `resourceRef`。 | 格式 | ref 形态 | | --- | --- | | epub | `chapter:2`（第 3 章）、或包内资源路径 `OEBPS/images/pic.png` | | cbz | `page:17` | | 漫画目录 | `page:1:2`（第 2 卷的第 3 页） | | txt | `chapter:4` 或 `chunk:262144`（字节偏移） | | pdf | `document` | | chapters | `chapter-resource::`；稳定 href 不能用于取资源 | 响应带 `Cache-Control: private, max-age=31536000, immutable`：文件资源由内容身份寻址；章节资源引用同时包含目录 revision，所以同一个资源 URL 的内容保持不变。 ### 文件资源的流式与子资源行为 **流式下发，支持 Range。** 响应带 `Accept-Ranges: bytes` 时可以用 `Range: bytes=0-1023` 取片段（PDF 跳页、漫画跳卷、断点续传）。压缩方式为 `deflate` 的 zip 条目无法字节定位，会诚实上报 `Accept-Ranges: none` —— 让客户端知道，而不是白跑一次再发现。 **尾部范围（`bytes=-N`）在超过 8MB 时退化为整包响应。** 一个前向流无法「跳到文件末尾」， 服务这条请求意味着把整个文件读完再丢掉——对 400MB 的漫画包就是拿三个字节换一次全量读。 所以服务端会说 `Accept-Ranges: none` 并回 200，让客户端能做计划，而不是付出一次它没 预期到的下载。 **子资源可以带 `?access_token=`。** 章节里的 ``、`` 是浏览器 自己发起的，没法带 `Authorization` 头。这类请求允许把令牌放进 query， 但**仅限** `GET` + 下列端点： - `/api/v1/books/:id/assets` - `/api/v1/books/:id/cover` - `/api/v1/books/:id/content` 其他任何端点（含触发扫描、写元数据）都不接受 URL 里的令牌 —— URL 会进日志、 进历史、进 `Referer`，能改状态的令牌不该走那条路。 **epub 章节返回的是重写过的 HTML。** 章节内的相对资源引用（`images/pic.png`）已经被 服务端改写成指向本端点的绝对地址。客户端直接把 HTML 交给 WebView 即可，不需要自己 解析路径。绝对 URL、`data:` URI 和文内锚点（`#note7`）保持原样，所以脚注和外链仍然可用。 服务端重写出的地址带 `?__reader-book-resource__=1` 作为标记，客户端据此把它和书自己 写的外链区分开：带标记**且**同源的才允许取回，其余一律丢弃（书不能借阅读会话去访问 第三方）。标记是一本书也能写出来的字符串，所以它单独不构成许可，两个条件一起才是书 伪造不出来的组合。 **这三条允许名单决定的是「能不能取」，不是「怎么取」。** 重写出来的地址还要**带令牌** 才真的能取到：章节文档里的 ``、`` 和 CSS 的 `url(...)` 都是浏览器 自己发起的请求，用的是文档里的原始地址，读不到客户端内存里的会话。客户端在注入章节时 把令牌追加到这些地址上（`sanitiseInjectedContent` 的 `signAssetUrl`），**追加发生在 允许名单判定之后**——否则一本书只要写一个第三方地址，就能让读者把自己的令牌送出去。 这两半必须都在，缺一个的症状都是「图片加载不出来」而且**不会报错**：只丢属性不报错， 只回 401 也不报错。UI 评审的替身服务因此对 `/assets` 也做鉴权（`access_token` 或 `Authorization` 二者之一），否则它会替真实服务端放行，让「图片加载不出来」在评审里 永远查不出来。 ### `GET /library/formats` 本实例支持的格式清单，由格式注册表生成： ```json { "formats": [ { "format": "epub", "kind": "reflowable", "label": "EPUB（精排渲染，保留出版方样式）", "extensions": ["epub"], "directory": false } ] } ``` 客户端用它决定显示哪些入口，不必硬编码格式列表。 ### `GET /books/:id/content` 流式返回书文件，`Content-Type` 按格式给 `application/epub+zip` 或 `application/pdf`。 书内容按哈希不可变，所以带 `ETag`，客户端可以放心长缓存。支持 `Range: bytes=`，所以**离线下载可以续传**。 目录型书籍（漫画目录）没有单一文件，返回 `400 DIRECTORY_BOOK`； 这类书按 `items?group=N` 逐卷取图。来源章节出版物没有整书文件，返回 `400 CHAPTER_BOOK`； 文件已从磁盘消失返回 `404 FILE_MISSING`。 ## 书库（文件管理器） 书架回答「我能读什么」，这一组端点回答「磁盘上有什么」。两者的差别不是冗余： 书籍 DTO 里从来不带路径，所以「刚扫完目录但书架上看不到这本书」在本组端点之外 没有任何地方能解释清楚。这也是会**写** `BOOKS_DIR` 的一组端点（前提是挂载可写）。 路径都是**书库内相对路径**，`''` 表示根目录；每一个都会过 `resolveInside`，逃逸直接被拒。 > **信任边界**：路径上，挂载点就是边界，不再叠一层按路径的 ACL。**谁能写**由角色决定： > > | 端点 | 管理员 | 成员 | > | --- | --- | --- | > | `GET /library/browse`、`POST /library/browse/shelf` | ✓ | ✓（`shelf` 只改自己的书架） | > | `POST /library/browse/move` / `rename` / `mkdir` / `delete` / `metadata` | ✓ | `403 ADMIN_REQUIRED` | > | `GET /library/upload`、`POST /library/upload` | ✓ | 业务设置「书库 → 允许成员上传书籍」开启时（默认开启）✓，只能新增书籍文件（见下）；关闭时 `POST` 返回 `403 UPLOAD_DISABLED` | > | `POST /library/scan` | ✓ | `403 ADMIN_REQUIRED` | ### `GET /library/browse?path=<相对路径>&page=<页>` ```json { "path": "科幻/已读", "crumbs": [ { "name": "书库", "path": "" }, { "name": "科幻", "path": "科幻" } ], "parent": "科幻", "entries": [ { "name": "三体.epub", "path": "科幻/已读/三体.epub", "type": "file", "size": 1234567, "mtime": 1789537864820, "mode": 420, "hidden": false, "hiddenByRule": false, "scanned": true, "ext": "epub", "indexed": true, "shelfState": "on" } ], "total": 1, "dirs": 0, "files": 1, "size": 1234567, "writable": true, "name": "已读" } ``` `hidden` 是「以点开头」，`hiddenByRule` 是「落在扫描器跳过的目录里」， `scanned` 是「扫描器会把它当一本书」。 `shelfState` 是「**调用者**的书架有没有这本书」：`"on"` / `"off"`， 目录和不是书的条目是 `null`。「不在书架」这个状态是这个接口能回答、 而其它任何接口都回答不了的问题——读者把一本书从书架上拿掉之后， 书库页和书架页说的是两件不同的事，而只有前者知道原因。 它是按调用者算的（服务端用当前登录用户解析），不是条目自身的属性。 在书库页面里给每一行都画「在书架上」等于用一整列噪音盖住唯一一行例外， 所以界面只标记 `"off"`。 **被跳过的条目照样列出来。** `.trash`、`@eaDir` 这些目录是设计上不被扫描的， 在这里过滤掉就正好藏住了读者要找的那批文件——在磁盘上、但不在书架上。标记出来， 让界面能解释，而不是替读者决定不用知道。 `entries` 是**这一页**，`total` / `dirs` / `files` 是**整个目录**的。两者来自同一次 `readdir`，因为分开算会让摘要、分页器和它下面那几行在任何一次磁盘变化之后互相矛盾， 而读者没有办法判断三个数字里哪个是旧的。一页默认 200 条，`pageSize` 可以调小， 上界是 1000：书库面对的是文件系统，一个放四千张扫描件的目录是真实存在的， 把四千行发给浏览器再丢掉 3940 行，就是那个让屏幕显得坏掉的请求。 页码是非法的（`?page=abc`）时返回第一页而不是 400：页码是「列表里的一个位置」， 对一个读者无法处理的参数报错没有意义。超界由服务端夹（见 `BrowseService.list`）。 `writable` 是实际探测出来的（真的建一个临时目录再删），不是读 mode 位： `drwxr-xr-x` 的只读 bind mount 看起来可写，写起来 `EPERM`。 符号链接按链接本身显示（`lstat`），不跟随——扫描器也不跟随，跟随等于描述一棵 索引里并不存在的树，还会顺着链接走出挂载点。 ### `POST /library/browse/move` — 管理员 ```json { "paths": ["科幻/三体.epub"], "target": "科幻/已读" } ``` → `{ "moved": 1, "merged": 1, "target": "科幻/已读" }` `merged` 是随移动一起改写索引路径的条目数；当前实现中每移动一项计一次，与 `moved` 相同。 同挂载点内 `rename`，不复制删除：文件字节、`mtime`、`inode` 都不变，扫描器视为 无变化，书籍身份（`identifier + 内容哈希`）因此保持，进度和笔记都还在。 同时把索引指向新路径，不等下一次扫描——文件管理器关掉时就该是一致的。 整批一起校验、一起拒绝：一半成功的移动比拒绝难推理得多。 目标已有同名条目 → `409 DESTINATION_EXISTS`。合并还是报错只有调用方知道， 猜错就是数据丢失。把目录移进它自己 → `400 MOVE_INTO_SELF`。 ### `POST /library/browse/rename` — 管理员 ```json { "path": "科幻/三体.epub", "name": "三体（修订版）.epub" } ``` `name` 是单个路径段，不含斜杠。→ `{ "path": "科幻/三体（修订版）.epub" }` ### `POST /library/browse/mkdir` — 管理员 ```json { "path": "科幻", "name": "待整理" } ``` → `{ "path": "科幻/待整理" }` ### `POST /library/browse/delete` — 管理员 ```json { "paths": ["科幻/其他/球状闪电.epub"] } ``` → `{ "removed": 1 }` 递归删除，**不进回收站**。索引行不动，留给下一次扫描标记 `missing`： 删除本身已经是危险的那一半，再绑一次全量扫描会让界面等好几分钟才报告成功。 勾选过的那一行也会一直留着，和「共享目录没挂上」是同一种状态—— 「文件没了但书还记着」，比书架突然少一本好。 `paths` 必须是**非空字符串数组**：`"a"` 和 `["a"]` 只差一个键， 但把字符串悄悄包成数组，会让「删了 1 项」看起来像「删了很多项」。 只读挂载上任何写操作 → `403 READ_ONLY_MOUNT`。 ### `POST /library/upload` `multipart/form-data`。重复的 `file` 字段各带一个文件，字段 `path` 指定目标目录 （书库内相对路径，缺省根目录），字段 `onConflict` 决定重名怎么办。 ```json { "uploaded": [ { "path": "科幻/三体.epub", "originalName": "三体.epub", "name": "三体.epub", "size": 1234567, "kind": "file", "bookId": "…", "title": "三体" } ], "skipped": [ { "name": "坏.zip", "reason": "无法解压（METHOD_UNSUPPORTED）" } ], "scan": { "running": false, "scanned": 1, "added": 1, "updated": 0, "unchanged": 0, "removed": 0, "failed": 0, "lastError": null, "startedAt": 1789537864820, "finishedAt": 1789537864831, "durationMs": 11 } } ``` **这是往 `/books` 写入新书籍字节的端点。** `BOOKS_DIR` 可以按需以只读方式挂载， 也可以以可写方式挂载以启用上传和管理员文件管理。改名、移动、删除和新建目录等端点同样会修改 可写书库中的目录项；只读挂载时所有这些写操作统一返回 `403 READ_ONLY_MOUNT`。 **成员只能新增书籍。** 管理员的上传不受限制。成员能否上传由业务设置 `library.memberUpload` （「我的 → 系统设置 → 服务配置 → 书库 → 允许成员上传书籍」，默认开启）决定；关闭时成员的 `POST` 在读取请求体之前就返回 `403 UPLOAD_DISABLED`。开启时，成员（`role=member`）的上传： - 只保存扫描器能识别为书籍的文件（扩展名在 `GET /library/formats` 里），其余文件记入 `skipped`，原因「不是支持的书籍格式」。 - `.zip` / `.cbz` 按漫画压缩包原样保存，**不解包**——解包会把压缩包里的任意内容写进书库， 那属于文件管理。 - `onConflict=overwrite` 返回 `403 ADMIN_REQUIRED`，书库保持不变；`rename`（默认）、`skip`、 `fail` 可用。可以指定任意书库内目录作为 `path`，但不能新建目录（新建目录要管理员）。 上传流程： - **接收完成后才写入书库。** 请求体先流到 `DATA_DIR/uploads` 的暂存文件， 接收中断不会把未接收完整的文件写入 `BOOKS_DIR`。同文件系统通过 `rename` 移入； 不同文件系统遇到 `EXDEV` 时复制到目标，再删除暂存文件。跨文件系统复制不具备原子性。 - **名字不是路径。** 客户端送的是文件名，不是路径：斜杠、`..`、控制字符、会让扫描器 看不见的前导点，一律改写或拒绝，再过一遍 `resolveInside`。`C:\Users\me\我的书\三体.epub` 只会取最后一段。 - **写完就索引。** 文件在磁盘上、书架上看不到，正是文件管理器要解释的那种状态， 所以上传以一次增量扫描收尾，而不是等调度器。一次请求扫一次，不是每个文件扫一次。 `onConflict`： - `rename`（默认）— 保留两份，新的是 `三体 (2).epub` - `skip` — 保留磁盘上已有的那本，新来的记进 `skipped` - `overwrite` — 同一个路径，索引看到的是「原位编辑」，书保持身份，进度和笔记都在 - `fail` — 整批 `409 DESTINATION_EXISTS` 其他取值返回 `400 BAD_CONFLICT_POLICY`。请求不是 multipart 返回 `400 NOT_MULTIPART`，没有文件返回 `400 NO_FILES`。单文件上限 4 GiB，单次请求最多 20 个文件。`bookId` / `title` 只在文件是可识别的 书籍格式并已被索引时出现。 `.zip` / `.cbz` 会被当**合集**解开（`kind: "archive-entry"`）。这是读者真正下载到的 东西：四十卷装在一个包里。单层包裹目录会被抹平（`系列/第01卷.epub` 落成 `第01卷.epub`）， 更深的树保持原样——`系列/第01卷/001.jpg` 是一本**目录书**，抹平它正好毁掉扫描器要读的结构。 压缩包里的名字一个都不信：每个条目按自己的段重建成名字，`../../etc/passwd`、绝对路径、 控制字符全部落在目标目录里。条目解不开（加密、冷门压缩方法）只记 `skipped`， 不会因为一条坏条目丢掉另外三十九卷。 上传进的每一个字节都复制进了 `DATA_DIR`，请求结束（成功或失败）即删—— 一个上传不进去第二次的书库比没有这个功能更糟。 挂载只读 → 写入 `BOOKS_DIR` 前返回 `403 READ_ONLY_MOUNT`；请求暂存位于 `DATA_DIR`。 `GET /library/upload`（任何已登录用户）返回 `{ "writable": true, "allowed": true }`，让客户端在开始传 400MB 之前先问一句：`writable` 是书库根目录是否可写，`allowed` 是当前用户能否上传（管理员恒为 `true`，成员取 `library.memberUpload`）。 ### `POST /library/browse/metadata` — 管理员 ```json { "paths": ["科幻/合集", "科幻/合集/第三卷.epub"], "fields": { "author": "某某", "series": "合集", "tags": "科幻,合集" } } ``` → `{ "applied": 3, "books": ["…"], "failed": [ { "path": "空目录", "reason": "NOT_A_BOOK" } ] }` 一次改一批。手动覆盖层是按**书**存的，而书库是按批整理的：四十个「佚名」要的是 一次填同一个作者，不是四十个对话框。 `paths` 里给目录就等于给目录里扫描出来的每一本书：系列文件夹本身没有 `book_files` 行， 问它自己会什么都找不到。`fields` 与单本 `/books/:id/metadata` 同一份白名单—— 批量不是写那些接口从不暴露的列的许可证。 不是书的路径记进 `failed` 而不是整批失败：选目录时捎上一个 `.nfo` 很常见， 界面因此可以说「已更新 12 本，跳过 2 项」。 ### `POST /library/browse/shelf` ```json { "paths": ["旧扫描"], "action": "remove" } ``` ```json { "bookIds": ["b_9f2…"], "action": "remove" } ``` → 同 `metadata` 的结构。`action` 取 `add` / `remove` / `hide` / `unhide`， 其中 `add` 与 `unhide` 是同一个写、`remove` 与 `hide` 是同一个写 （两套名字来自早期想区分「加进书架」和「别再隐藏」的打算；只有一个标志位， 所以只有一对操作。名字保留是因为删掉一个已文档化的取值是破坏性变更）。 **目标两种命名，只收一种**：`paths`（文件管理器手里是路径）或 `bookIds`（一张卡片手里是 书）。`action` 不是这四个之一返回 `400 BAD_ACTION`。两个都给、或都不给，都是 400 `AMBIGUOUS_TARGETS`——两份命名说的是同一个写， 同时带上就是「调用方自己不知道该说哪一个」，合并还会让同一本书被写两次、被数两次。 **`bookIds` 是「从书架移除时，找不到「xxx」在磁盘上的路径」的修法**（#40）。 被拿掉过的那本书叫「半小时漫画宇宙大爆炸（半小时读完138亿年宇宙史，一口气搞懂大爆炸、 奇点、黑洞、引力波、暗物质……混子哥陈磊新作！）」，而磁盘上的文件不叫这个——扫描器是从 文件里读出书名的。客户端当时是这么补上路径的：列出**书库根目录的第一页**，拿书名和文件名 对（去掉扩展名）。这个猜测有两处必然失手：**书名不等于文件名**（常态，不是例外）， 以及**列表是分页的**（根目录第一页之外的书、任何子目录里的书，都不在那次查找里）。 两处都失手时读者被告知找不到这本书——在他要求把它从**自己的书架**上拿掉之后。 映射其实**已经在服务端**了（`book_files.book_id` → `rel_path`），客户端一直在猜一件 服务端已经知道的事。id 形式按 id 解析：书名和文件位置都不参与。 一个 id 指向的书**没有活下来的文件**（`book_files` 里没有 `missing = 0` 的行） 记进 `failed` 而不是猜一个路径——书的可见性判据本来就要求「存在一个未丢失的文件」， 给一本读者打不开的书写书架状态只是在那个判据之外留下一行。 **磁盘上什么都不会变**，这正是重点：「把这四十份扫描从书架上拿掉」和 「把这四十份扫描移进某个目录」在一行行列表里只差一个词，后果却完全不同， 所以是两个端点。`remove` 写的是 `hidden = 1` 而不是删行——书还在书库里、还在索引里， 读者放得回去；删行在书架上长得一样，却不可逆。 **`add` 必须清掉 `hidden`，不能只是「不存在才插入」。** 这是 #40 报的 「书库的书不再自动加入书架，需要手动加入」的服务端一半：被拿掉过的书**已经有**一行 `user_books`（就是 `remove` 为了可逆写下的那一行，`hidden = 1`），所以 `INSERT OR IGNORE` 会跳过它，书继续不在书架上——读者选中它、点「加入书架」、 然后什么都没发生。可逆性只存在于表结构里而不存在于端点里，就不是可逆性。 `add` 用 upsert：不存在则插入，存在则清标志（并在确实重新加入时刷新 `added_at`， 所以「最近入库」对一本没离开过的书仍然指它第一次入库的时间）。 **两个方向是同一对操作，所以「在不在书架上」只有一个定义。** `GET /books` 的判据是「`user_books` 行存在且 `hidden = 0`」**且**「存在一个未丢失的文件」， 本端点写的就是这两件事里的第一件，`/library/browse` 的 `shelfState` 读的是**两件**。 一行 `hidden = 0` 但文件掉了的书因此**不在书架上**，而不是「在书架上但你打不开」—— 把两种状态分开描述，会同时让书架和书库各自说一半真话。 `applied` 是这一批真正改动的行数，`failed` 是没能动的那几项——**用调用方自己那份 命名**（`paths` 进来的就是路径，`bookIds` 进来的就是 id），理由是调用方要能把它对回 自己手里那个东西。`reason` 有三种：`NOT_A_BOOK`（这个路径不是一本书，可能是目录或 `.nfo`）、`NO_LIVE_FILE`（这个 id 的书没有活文件）、`NO_PATHS` / `NO_BOOK_IDS` 是整批被拒而不是单条失败。 客户端把它当作**句子**的依据：「加入书架 0 本」紧挨着一个看起来能按的按钮， 就是「这个按钮坏了」的来源，所以不是书的那几项要单独报出来。 ### `GET /books/:id/file?path=` 流式返回这本书的**某一个**文件（二进制流，不是 JSON）。 只有一种格式需要它：以目录形式存放的漫画。它没有一个「书文件」可以整体下载， 客户端按页取。`path` 必须是 `/manifest` 的 `files` 里出现过的那个 `rel_path`—— 服务端只按这份清单精确匹配，**从不**用 query 拼路径，所以路径穿越只会匹配到空。 **`files` 是契约，不是清单。** 两边由同一个页面遍历生成：manifest 列出哪些路径构成 这本书，本端点就服务哪些路径。目录书的页面哪怕住在压缩包里，也按**压缩包自己的路径** 列出（`第01卷.cbz`），因为那才是能拿来发请求的路径；请求这个路径拿到的是**这一页的图**， 不是压缩包本身。压缩包内部的页码由 `/assets?ref=page:卷:页` 寻址，不是文件路径， 也永远不会出现在 `files` 里。 manifest 的每个条目还带 `ref`，即这个文件对应的**资源引用**。要按页取用 `/assets?ref=`， 引用**原样**回传——它不是路径，也不是下标：卷的边界只有格式处理器知道， 客户端从 `rel_path` 反推会让「第 1 页」指向另一页。 响应与 `/content` 一致，但 `ETag` 是按文件而非按书。 ### `GET /books/:id/cover` 返回封面。无封面时 `404 NO_COVER`。缓存头是 `immutable`（封面随书籍主键变化）。 ### `PATCH /books/:id/metadata` ```json { "title": "三体（修订版）", "tags": "科幻,雨果奖", "seriesIndex": 1 } ``` 可改字段：`title` `author` `publisher` `language` `isbn` `description` `series` `seriesIndex` `pubdate` `tags`（`tags` 用逗号分隔的字符串）。其他键被忽略；一个可改字段都没有时返回 `400 BAD_REQUEST`。→ `{ "book": {...} }`（应用覆盖后的书籍 DTO） 写入的是覆盖层，**扫描永远不会覆盖它**。 ### `DELETE /books/:id/metadata/:field` 撤销单个字段，回落到内嵌值。可用来实现 UI 上的「还原」按钮。→ `{ "book": {...} }` --- ### `PUT /books/:id/reading-status` 把书架上的书标记为想读、在读或已读，或清除标记（`null`），返回 204。不在当前账号书架上的书返回 404。 ```json { "status": "want" } ``` `GET /books` 在书架范围内（默认 `scope`）接受 `status=reading|want|finished` 筛选，并给每本书带上 `readingState`（`"reading" | "want" | "finished" | null`）： - 手动标记的在读、已读优先； - 否则按进度推断：进度 ≥ 99% 为已读，已开始为在读； - 想读只来自标记，开始阅读后让位于在读。 `scope=library` 和单本 `GET /books/:id` 不带这个字段。 ## 朗读（HTTP TTS） 这两条路由只在服务端配置了 HTTP 朗读合成接口 时才有意义，并且分工明确： 一条回答「这里能用什么」，一条真正合成音频。 ### `GET /tts/voices` 能力查询，朗读设置面板打开时调用一次。 → `{ "http": false, "timeoutMs": 20000, "formats": ["audio/mpeg", ...], "maxLength": 800, "voices": [] }` - 未配置 HTTP 朗读合成接口 时返回 `http: false` 而**不是 404**：客户端问的是「这里能用什么引擎」， 不是「这个接口存在吗」。一个 HTTP 朗读合成接口 没配的实例是完全正常的实例。 - `maxLength` 无论开关都返回：客户端会按它切句，这个决定发生在选引擎之前。 - 配置了之后 `voices` 来自 音色列表接口（或约定路径 `<合成接口>/voices`）。 ### `GET /tts?text=<文本>&voice=<可选>&speed=<可选>&format=<可选>` 合成一条语句，返回音频字节流（`audio/*`）。 - **一次一条语句，不是一章**。客户端本来就是逐句朗读（理由见架构文档第 9 节）， 而按请求切分正是让暂停、续读、下一句、改语速在远程引擎上也能工作的前提； 它同时把响应限制在手机可以边走边缓冲的大小，并让缓存以句为单位而不是以书为单位。 - `speed` 夹在 0.25–4；`text` 上限 800 字，超了返回 `TEXT_TOO_LONG`， **不会转发给上游**。 - 上游返回非 `audio/*` 时返回 `TTS_CONTENT` 而不是把 HTML 当音频流出去： 一个配错的 HTTP 朗读合成接口（指到一个网页）会以 200 返回 HTML，塞进 `