2026-09-15 20:22:11 +08:00
30 changed files with 2339 additions and 54 deletions
@@ -287,6 +287,7 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才
 - #4 独立阅读选择小样位于 `spikes/selection/`，`python spikes/selection/serve.py` 默认仅本机 5184。桌面鼠标/键盘与 11 项测试已验证，#4 已获用户验收并关闭；真实手机长按/手柄/滚动详细证据仍未提供；禁止把窄屏桌面当作真机验收。Intl.Segmenter 只用于 UI 范围验证，不替代 #3 NLP；释义保存只在内存。固定 LinguaCafe 源码对照和与 v1 的差异记录见架构 Wiki。
 - 2026-09-11 用户确认正式 NLP/词典采用全 Go。#5 已验收并合入 main；#6 使用 Go WordNet 解析和词形候选、Go Unicode 原文分片、schema v4 共享词典资源表，不调用 Python NLP。WordNet 3.0 ZIP 来源与摘要见 `server/wordnet-resource.json`，许可保留在 `server/WORDNET-LICENSE.txt`。词形候选不等于上下文消歧，不自动合并个人学习状态；#3 Python 小样只保留历史验证。当前词典仅英语释义，个人释义输入为临时草稿，持久化归 #7。
 - 2026-09-11 用户确认 #7 个人词条口径（三项由 Agent 定案）：身份为「学习者＋语言＋规范化词形」，大小写合并但**不按 lemma/候选合并**（`dog` 与 `dogs` 是两条记录）；首次保存默认「新词」；状态为 新词/学习中/已知/忽略，只有「学习中」带 1～7 级，对应原版 stage 2/1/0/-1～-7；例句只保存手输内容，不自动关联原文句子。schema v5 新增 `lexgo_terms`（唯一键加状态/等级检查约束），个人释义与共享词典分离且不进入审计日志；等级编辑 UI 归 #8/#12。
+- 2026-09-15 用户确认 #21 附件口径：每本书可选**一张封面**（JPG/PNG/WebP，≤2 MiB，≤4096×4096）与**一段 MP3**（≤20 MiB），**按文件内容 magic bytes 判定类型、不看扩展名**；附件与播放位置**存 MySQL**（dump 即完整备份、属主校验一致、删书无孤儿文件）；读取需会话并支持 **HTTP Range（206）**与 ETag/304，界面用带凭据的 fetch + 对象 URL（**令牌不进 URL**，代价是无渐进式流式播放）；不自动播放、**不与文本同步**、不解析时长；播放位置按账号＋书籍保存（播放中每 5 秒与暂停/离开上报），**替换或移除音频时重置**；跨账号一律 404；schema v8 新增两张表（可重放 DDL，回退写回版本号 7）。范围外：多音轨/分章音轨、字幕同步、逐句跟读、转写、TTS、转码、自动搜图、在线音频地址、公开分享。**浏览器是否真实解码播放尚未验证**（测试中媒体元素被桩替换），真机听感待人工确认。
 - 2026-09-15 用户确认 #15 交付口径：只交付本机可复现的安装/备份/恢复材料并在本机演练，**不对外部署、不创建 release/tag、不邀请用户**；生产入口与 HTTPS 只写入文档；前端由反向代理托管 dist（不改后端代码）；试用实例从**空库**开始、管理员由显式 bootstrap 建立、不带默认密码；备份＝MySQL 全库 dump ＋ 环境配置（凭据只存运维密码库，不进仓库/日志），不新增定时备份；性能用人造数据集实测并写明环境，只作观察不给承诺。备份/恢复规则：`restore` 必须 `--confirm`、默认只写空库、覆盖需 `--force`、库名必须含 lexgo 且不能是系统库、拒绝带 CREATE DATABASE/USE 的 dump，恢复前后比对源库逐表内容校验和。**附件（#21）尚未实施，恢复契约目前只覆盖数据库**；真实回滚、HTTPS、多机与定时备份仍未验证。部署与运维规则见 Wiki 页 `Deployment-and-Operations`（镜像 `docs/11-deployment-and-operations.md`）。
 - 2026-09-15 用户确认 #14 显示与键盘口径：`theme ∈ {浅色,深色,跟随系统}`（默认跟随系统）与正文字号 `{标准,大,特大}`（1.0/1.15/1.3）**按账号保存在本机** `lexgo-learner-display:<账号 id>`，切换账号即换成该账号偏好或默认，退出回到默认，**不跨设备同步**；字号经 `--reader-font-scale` 只作用于阅读面（正文、释义内容、复习卡），不做全局缩放；深色用 `html[data-theme]` ＋ Element Plus 的 `html.dark`，`style.css` 的 `:root` 是文件内仅有的颜色字面量；阅读位置按账号＋章节保存滚动比例与该章 `content_sha256`，**正文换新版本后不恢复**；复习页 `空格`/`Enter` 显示答案、`1/2/3` 评分，输入类控件与聚焦按钮的按键不被劫持，带修饰键不拦截；移动验证用 390×844＋`hasTouch` 的 Playwright `mobile` 项目（桌面项目 `testIgnore: mobile-*`），**真机长按选择与手感仍需人工确认**，不得用模拟设备结果冒充真机。本单无 schema 与接口变化。
 - 2026-09-15 用户确认 #13 完成阅读与进度口径：`POST /api/v1/chapters/:id/complete` 只记已读、**不批量改变词语状态或等级**，只有 `ready` 章节可标记（其他 409），重复调用返回同一行且带 `duplicate`（不移动时间、不重复计数）；完成记录保存标记时的 `content_sha256`，**正文新版本后该章回到未读**（记录保留，重读后更新同一行），只改标题不影响，章节删除随外键级联；`GET /api/v1/progress` 统计只含本人与当前语言，已读与分母都只算可阅读（`ready`）章节，已知/学习中/新词/忽略分开计数，`dueNow` 与到期复习队列共用 `dueTermsQuery` 与同一服务端时钟；schema 升到 v7（新表 `lexgo_chapter_progress`，不用 ALTER TABLE），需显式 migrate。不做每日目标、日历、难度评分、统计导出与取消已读，也不做 X10 批量标已知。
@@ -8,7 +8,7 @@
 - [英语分词与离线词典验证小样](spikes/english/README.md)（#3 已验收，独立本机入口）
 - [阅读选择验证小样](spikes/selection/README.md)（#4 已验收，真机详细测试证据缺口保留）
 - [项目档案](docs/00-project-profile.md) · [需求总览](docs/09-product-requirements-overview.md)
- [工作量估算](docs/10-workload-estimate.md)：#2、#3、#4、#5、#6、#7、#8、#9、#10、#11、#12、#13、#14、#18 已验收，原规划中的 #5 已完成；#15 已实现待验收；新增 #21、#24 待排期；缺陷 #32 待确认修复方案；后续结合集成结果重估，旧全量研究仅供参考。
+- [工作量估算](docs/10-workload-estimate.md)：#2、#3、#4、#5、#6、#7、#8、#9、#10、#11、#12、#13、#14、#18 已验收，原规划中的 #5 已完成；#15 与 #21 已实现待验收；#24 待排期；缺陷 #32 待确认修复方案；后续结合集成结果重估，旧全量研究仅供参考。
 - [四阶段实施总览 #16](https://git.ilapage.cn/OPC/lexgo/issues/16)：14 张单元工单，工程基础 → 技术验证 → 首条学习闭环 → 补齐 MVP；原型 v1 已获用户验收。两端使用账号（用户名）＋密码登录，不要求邮箱。
 - [原型工单 #1](https://git.ilapage.cn/OPC/lexgo/issues/1)：Quant-UX 桌面/手机原型 v1，预览入口与审核记录见工单及需求总览。
 - 运维命令：`./lexgo migrate|bootstrap|serve|backup|restore|verify`（纯二进制），开发便利与交叉验证走 `python scripts/server.py …` / `python scripts/ops.py …`
@@ -16,7 +16,7 @@

 ## 本地工程基础

-运行前在 MySQL 8 中准备项目专用空库，复制 `.env.example` 为忽略的 `.env.local` 并填写本机连接及初始管理员密码。首次执行 `python scripts/server.py migrate`、`python scripts/server.py bootstrap`；随后执行 `python scripts/server.py serve`。两端分别通过 `npx --yes pnpm@9.15.1 --dir admin dev`、`npx --yes pnpm@9.15.1 --dir learner dev` 启动，首次需安装锁定依赖。
+运行前在 MySQL 8 中准备项目专用空库，复制 `.env.example` 为忽略的 `.env.local` 并填写本机连接及初始管理员密码。首次执行 `python scripts/server.py migrate`、`python scripts/server.py bootstrap`（等价纯二进制路径：`./server/lexgo migrate` / `bootstrap`）；随后执行 `python scripts/server.py serve`。两端分别通过 `npx --yes pnpm@9.15.1 --dir admin dev`、`npx --yes pnpm@9.15.1 --dir learner dev` 启动，首次需安装锁定依赖。书籍封面与音频附件（#21）存于数据库，包含在 `scripts/ops.py backup` 与 `./server/lexgo backup` 的备份范围内。

 本地入口：学习端 http://127.0.0.1:5173，管理端 http://127.0.0.1:5174。完整安装与测试命令见[开发与验证](docs/04-local-development-and-verification.md)。账号使用用户名，无需邮箱；没有随代码交付的默认密码。

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Architecture-and-Code-Map
 wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Architecture-and-Code-Map.-
-wiki_revision: fabdaf13861b4cae9ad6cd66a5bd904c08361f73
-synchronized_at: 2026-09-15T09:08:48Z
+wiki_revision: 3b785a11352776e36656da59ef9928a2cbb42694
+synchronized_at: 2026-09-15T10:33:06Z
 <!-- gitea-wiki-mirror:end -->

 # 架构与代码地图
@@ -410,3 +410,27 @@ schema v7 新增 `lexgo_chapter_progress`：一章一行（`chapter_id` 主键
 **两条通道**：Go 二进制提供数据库层的备份、恢复与校验（`lexgo backup|restore|verify`），Python 工具提供依赖检查、建库与 HTTP 接口级的两账号闭环（`ops.py smoke` / `verify --api`）。两者共用同一份 `LEXGO_*` 配置、同一套 manifest 与安全规则；2026-09-15 交叉验证两条通道可互相恢复对方的备份。

 **视图与进程**：后端单二进制监听 `127.0.0.1:8000`；两份 SPA 由反向代理托管 `dist`，反代把 `/api/` 转发到后端并把未知路径回落到 `index.html`；本机开发用 supervisor 托管 `lexgo-api`/`lexgo-learner`/`lexgo-admin` 三个 program。
+
+## #21 书籍音频与封面附件（2026-09-15）
+
+schema v8 新增两张表，都只用可重放的 `CREATE TABLE IF NOT EXISTS`：
+
+| 表 | 结构 |
+|---|---|
+| `lexgo_book_attachments` | 主键 `(book_id, kind)`，`kind ∈ {audio, cover}`；`owner_id`、`mime`、`byte_size`、`sha256`、`bytes MEDIUMBLOB`、时间戳；外键级联到书籍与账号。一本书最多一段音频、一张封面，替换即覆盖同一行 |
+| `lexgo_playback_positions` | 主键 `(owner_id, book_id)`，`position_seconds`、`updated_at`；外键级联到账号与书籍 |
+
+**文件为什么存进 MySQL**：这样一份 dump 仍然是完整备份、附件与其它私有行走同一套属主校验、删除书籍不可能留下孤儿文件；代价是音频会增大数据库体积（单文件上限 20 MiB 已在文档写明）。
+
+`server/app/lexgo/attachment.go` 集中实现：`sniffAttachment`（按文件头 magic bytes 判定类型，MP3 接受 ID3 或帧同步，图片接受 JPG/PNG/WebP 签名）、`coverDimensions`（JPEG/PNG 用标准库解码，WebP 读 VP8X/VP8/VP8L 头）、`validateAttachment`（音频 ≤ 20 MiB、封面 ≤ 2 MiB 且 ≤ 4096×4096）、`SaveAttachment`（先校验后 upsert，替换音频同时清空进度）、`DeleteAttachment`、`BookAttachmentFile`、`BookAttachmentsFor`、`SavePlaybackPosition`。
+
+| 接口 | 行为 |
+|---|---|
+| `POST /api/v1/books/:id/audio`、`.../cover` | multipart 单文件；成功返回附件元数据；替换即覆盖；`413` 超限、`400` 类型或内容非法、他人 `404` |
+| `DELETE /api/v1/books/:id/audio`、`.../cover` | 移除附件；移除音频同时删除该账号的进度行 |
+| `GET /api/v1/books/:id/audio`、`.../cover` | 二进制响应，需会话；`respond` 支持 `binaryResponse`，交给 `http.ServeContent` 处理 **Range（206）**、`416`、`If-Modified-Since`，并按内容摘要给出 `ETag` 与 `304` |
+| `PUT /api/v1/books/:id/playback` | `{positionSeconds}`，upsert，只写本人；音频不存在时 `404` |
+| `GET /api/v1/books` | 增加 `coverVersion`（封面内容摘要，用于缓存与刷新判定）与 `hasAudio` |
+| `GET /api/v1/books/:id`、`GET /api/v1/chapters/:id` | 书籍对象带 `attachments`：封面/音频元数据与该账号的 `playbackSeconds` |
+
+学习端：`stores/library.ts` 用带鉴权的 `session.requestBlob` 取回字节并转成对象 URL（**不把令牌放进 URL**），库列表批量预取封面，阅读器按需取音频；`components/AudioPlayer.vue` 是播放器（播放/暂停、进度、0.75–1.5 倍速、错误重试，播放中每 5 秒与暂停/离开时上报位置）；`views/LibraryView.vue` 显示封面（`aria-hidden` 的重复链接，标题链接仍是唯一可访问入口）、`views/BookView.vue` 新增「音频与封面」区块（上传/替换/移除、像素与体积提示、失败保留旧附件）、`views/ReaderView.vue` 在正文上方放常驻播放器条。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Business-Rules-and-Glossary.-
-wiki_revision: 5f2912edd09256cf5fc52059145d65918e99f9cb
-synchronized_at: 2026-09-15T08:27:38Z
+wiki_revision: 34a1994dae20957a68f2bd60e3a7dd97530cffac
+synchronized_at: 2026-09-15T10:33:08Z
 <!-- gitea-wiki-mirror:end -->

 # 业务规则与术语
@@ -304,3 +304,19 @@ exact优先；未命中再按WordNet异常表/词尾规则查候选，词性顺
 **安装规则**：空库不含默认密码与任何演示数据；管理员只能由显式 `bootstrap` 建立，库中已有账号时拒绝再次执行、不覆盖既有管理员；应用账号只对该库拥有最小权限，不使用管理员账号运行应用；服务默认只监听 `127.0.0.1`，对外由反向代理转发。

 **验收账号规则**：试用验证使用虚构的演练账号，密码由演练进程生成、只经环境变量传入，不写入磁盘、日志、工单或截图。
+
+## #21 附件与播放规则（2026-09-15）
+
+**归属与可见性**：附件属于书籍所有者。任何跨账号的读取、替换、移除或位置上报都返回 `404`；未登录返回 `401`。附件与播放进度都按账号隔离，同一本书的播放位置不共享。
+
+**格式与上限**：音频只接受 **MP3**（ID3 标记或 MPEG 帧同步），单文件 ≤ **20 MiB**；封面只接受 **JPG、PNG、WebP**，单文件 ≤ **2 MiB**，像素 ≤ **4096×4096**。类型**按文件内容判定，不看扩展名或客户端声明的 MIME**：把 SVG 改名成 `.png`、把文本改名成 `.mp3` 都会被拒绝。超限返回 `413`，类型或内容非法返回 `400` 并给出可读原因。首版只收 MP3，其它格式待桌面与手机浏览器实测后再谈，不承诺任意格式。
+
+**替换与失败**：替换即覆盖同一行，一本书每个类型只有一条记录。**校验通过后才写入**，因此被拒绝的上传不会损坏已存在的附件。替换音频会**清空播放位置**——旧位置对新文件没有意义；移除音频同样删除位置记录。
+
+**播放行为**：不自动播放，必须由用户点击；提供播放/暂停、拖动进度与 0.75/1.0/1.25/1.5 倍速。**音频不与文本同步**：没有时间戳、字幕或逐句对齐，也不做转写。播放中每 5 秒、暂停时与离开页面时上报位置；服务端只做上界校验（0 ≤ 秒 ≤ 24 小时）与 upsert，并发以最后一次写入为准，不解析音频时长（时长来自浏览器）。
+
+**传输与缓存**：附件读取需要会话，支持 HTTP Range（拖动进度只需取所需片段），并在响应里带内容摘要作为 `ETag`，命中即返回 `304`。前端用带凭据的 fetch 取字节再交给 `<img>`/`<audio>`，因此**令牌不会出现在 URL、历史记录或访问日志里**；代价是浏览器会整份取回后再播放，暂不支持渐进式流式播放。
+
+**删除与备份**：删除书籍级联删除附件与所有账号的该书进度。附件存于数据库，所以 #15 的备份与恢复契约自动覆盖附件与进度；恢复后附件可继续读取与播放，这一点已由 2026-09-15 的恢复演练验证（逐表内容校验和一致、恢复实例按字节相同地返回音频与封面）。
+
+**范围外**：多音轨、分章音轨、字幕与时间戳同步、逐句跟读、转写、TTS、音频转码、自动搜索封面、在线音频地址抓取、公开分享与跨用户共享。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Local-Development-and-Verification
 wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Local-Development-and-Verification.-
-wiki_revision: fa4c663fabf5db418104fc53b7ce00f41f5ba910
-synchronized_at: 2026-09-15T09:11:27Z
+wiki_revision: ba5e3acc746432e55c186fd3a1fdf3c158fd121b
+synchronized_at: 2026-09-15T10:33:08Z
 <!-- gitea-wiki-mirror:end -->

 # 本地开发与验证
@@ -746,3 +746,36 @@ Go 二进制与 Python 工具各做一次备份，并**互相恢复对方的备
 - 未做定时备份、监控与告警；备份与恢复均为人工触发。
 - 大库恢复耗时与磁盘空间上限未测；演练库与生产库规模不同。
 - 附件（封面/音频，#21）尚未实现，恢复范围目前只覆盖数据库。
+
+## #21 附件功能验证（2026-09-15）
+
+### 迁移
+
+schema v7 → v8：新增 `lexgo_book_attachments` 与 `lexgo_playback_positions` 两张表，**不修改既有表**。开发库迁移前后逐表业务计数一致，schema 记到 8，两张新表为空（快照 `.local/issue13-before21.json`、`.local/issue13-after21.json`）；回退时把 `lexgo_schema.version` 写回 7 并恢复上一版二进制（备份 `.local/lexgo-pre-issue21.exe`）。
+
+| 命令 | 结果 |
+|---|---|
+| `go vet ./...` | 通过，`gofmt -l` 无输出 |
+| `LEXGO_TEST_DB_NAME=lexgo_test_issue13 python scripts/server.py test-integration` | **86 项顶层用例全部通过、0 跳过**（本单新增 7 项：类型嗅探、上限与像素、WebP 维度、位置边界、上传/读取/Range/替换/移除/级联的集成用例、v7→v8 迁移） |
+| `cd learner`：`npx vitest --run` / `npx vue-tsc --build` / `npx pnpm run build` / `npx playwright test` | 157 项单测、类型检查、构建、**25 项 E2E**（桌面 21 ＋ 移动 4）全部通过；本单新增 10 单测与 3 项 E2E |
+| `cd admin`：`npx pnpm test` / `npx pnpm lint` | 31 项与 lint 通过（管理端无改动） |
+| `python -m unittest discover -s tests` / `harness.py check --strict` / `sync --check` | 65 项、严格检查、镜像一致 |
+
+### 真实链路（41 项检查全部通过）
+
+真实 API＋真实 MySQL：上传**真实 PNG**（461 字节）与**真实三秒 MP3**（ffmpeg 生成，18407 字节）→ 数据库中的 `byte_size` 与 `OCTET_LENGTH(bytes)` 一致、音频 sha256 与上传文件一致 → 书籍详情与书库列表报告 `attachments`、`coverVersion`、`hasAudio` → 封面按字节返回且带 `ETag`（`If-None-Match` 得 `304`）→ 音频按字节返回、`Accept-Ranges` 存在、`Range: bytes=100-999` 得 `206` 且切片正确、不可满足的 Range 得 `416` → 越权读取/替换/上报位置全部 `404`、匿名 `401` → SVG 改名封面、文本改名音频均 `400`，21 MiB 音频 `413`，且**被拒绝后原文件仍在** → 位置写入与回读、负值 `400`、无音频的书 `404` → 替换音频后位置归零且仍只有一行 → 移除音频、删除书籍后附件与位置级联清空。证据 `.local/issue21-api-evidence.json`。
+
+### 恢复演练（含附件，22 项检查全部通过）
+
+在 #15 的恢复契约上扩展：建一本带真实封面与音频的 fixture 书籍 → 用 **Go 二进制** `lexgo backup`（manifest 已包含两张新表）→ 恢复到空库 `lexgo_test_restore_attach` → `lexgo verify --manifest` 通过且新增的「附件都指向存在的书」「播放位置都指向存在的书」检查在内 → **15 张表的逐表内容校验和与源库一致** → 用恢复库起第二个实例：同一账号可登录、书籍仍报告两个附件、位置仍是恢复前的值、**音频与封面按字节相同地返回**、恢复实例上 Range 仍得 `206`、越权仍 `404` → 删除演练库与 fixture 书籍，开发库仍是 schema 8。证据 `.local/issue21-restore-evidence.json`。
+
+### 顺带修掉的既有问题
+
+`e2e/phrase.spec.ts` 的连续选词用例在并行全量跑时约 6 次失败 2 次（合成鼠标拖拽偶尔少选一个词）。修法：每次重试都重新读取词的位置（面板打开会改变布局，缓存的坐标会一直拖错）、松开前留 80ms 让浏览器扩展选区、把重试条件改成**断言期望的词数**而不是「面板出现了」、重试前关掉部分选中的面板。修完连续 6 次全量跑全部通过；若选择逻辑真的退化，4 次重试仍会失败，不会掩盖真实问题。
+
+### 未验证
+
+- **浏览器是否真的解码并播放音频：本机验证用桩替换了媒体元素**（合成的 MP3 帧不足以证明解码）。真实 MP3 的听感、手机扬声器/蓝牙、后台播放与锁屏控制需要人工确认。
+- 未验证 Safari/Firefox（项目既有测试只在 Chromium 上跑）；WebP 只验证了容器维度解析，未在各浏览器实测显示。
+- 20 MiB 上限下的播放启动延迟未测；附件进库对 dump 体积与恢复耗时的影响只在小数据量下观察。
+- 未做音频转码与格式探测，非 MP3 一律拒绝。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Product-Requirements-Overview
 wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Product-Requirements-Overview.-
-wiki_revision: a1847957e287c7eb1a54905e13632aeca4cd75f7
-synchronized_at: 2026-09-15T08:27:38Z
+wiki_revision: 437d154868c23dd5b39e525d6c45e9ff13364d47
+synchronized_at: 2026-09-15T10:33:08Z
 <!-- gitea-wiki-mirror:end -->

 # 产品需求总览
@@ -293,3 +293,9 @@ F12 的电脑与手机基础体验已于 2026-09-15 通过用户验收：新增
 B04 与 F01–F12 的集成交付已实现，待用户验收：新部署与运维 Wiki 页（首次部署、配置与凭据来源、日常运维、健康检查、升级回滚、备份恢复、已知限制），运维工具 `scripts/ops.py`（`install-check` / `init-database` / `backup` / `restore` / `verify` / `smoke`）与 `scripts/bench.py`。本机完成完整演练：空库安装并由管理员建立两个虚构演练账号走通学习闭环；备份开发库后恢复到空实例，逐表行数与内容校验和一致、源库未被改动，两账号闭环与越权校验全通过。性能在 20 章／2000 词条／8000 条作答的人造数据集上实测（p50 6–23 ms，登录 82 ms，均无错误），只作观察不给承诺。

 用户已确认的范围边界：本次只交付本机可复现的安装/备份/恢复材料并在本机演练，**不对外部署、不创建发布标签、不邀请用户**；生产入口与 HTTPS 只写入文档。**真实回滚、定时备份、监控告警、多机部署与 HTTPS 仍未验证**；附件（音频/封面，#21）尚未实现，因此恢复契约目前只覆盖数据库，待 #21 落地后由本单的恢复验收纳入附件。遗留缺陷 #32（编辑正文回到曾用版本返回 500）仍待确认修复方案。
+
+## #21 交付状态更新（2026-09-15）
+
+F 范围之外的 MVP 增补项「书籍音频与封面附件」已实现，待用户验收：每本书可选一张封面与一段 MP3，书库显示封面，书籍页可上传/替换/移除，阅读页播放器支持播放、拖动与倍速，不自动播放也不与文本同步；播放位置按账号与书籍保存，替换或移除音频时重置；附件按文件内容校验类型（不看扩展名），音频 ≤20 MiB、封面 ≤2 MiB 且 ≤4096×4096；附件读取需会话并支持 HTTP Range。schema 升到 v8（两张新表，需显式迁移）。附件存于数据库，因此包含在 #15 的备份与完整恢复范围内，恢复演练已验证附件按字节恢复且仍可读取与拖动。
+
+非目标保持不变：多音轨、分章音轨、字幕与时间戳同步、逐句跟读、转写、TTS、转码、自动搜索封面、在线音频地址抓取、公开分享与跨用户共享。**浏览器真实解码播放（测试中媒体元素被桩替换）与真机听感仍需人工确认**；Safari/Firefox 未验证。其余待办：书籍音频与封面已在 #21 落地，剩余 #24 书库列表优化与缺陷 #32。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Deployment-and-Operations
 wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Deployment-and-Operations.-
-wiki_revision: 3791ef4adc5c5cc8d6e5006c719cd0ddccb15fc0
-synchronized_at: 2026-09-15T09:08:49Z
+wiki_revision: dacdad8a9385b2fde153a0dd1fe2579b57a810fd
+synchronized_at: 2026-09-15T10:33:09Z
 <!-- gitea-wiki-mirror:end -->

 # 部署与运维
@@ -32,7 +32,7 @@ synchronized_at: 2026-09-15T09:08:49Z
 | 运行时 | 后端为单个静态二进制，无需运行时依赖；构建需要 Go 1.26.5、Node 22、pnpm 9 |
 | 进程托管 | supervisor（本项目开发机即为 `lexgo-api` / `lexgo-learner` / `lexgo-admin` 三个 program） |
 | 日志 | supervisor 的 `stdout`/`stderr` 日志文件；应用自身不写文件日志 |
-| 备份对象 | MySQL 全库（用户数据、原文、词典归档、审计）+ `.env.local`（单独从密码库取） |
+| 备份对象 | MySQL 全库（用户数据、原文、词典归档、审计、**书籍封面与音频附件及播放位置**）+ `.env.local`（单独从密码库取） |

 ## 环境要求

@@ -212,7 +212,8 @@ python scripts/ops.py smoke --api http://127.0.0.1:<端口> --admin-user <管理
 - **真实回滚演练未做**：本文档给出规则，但没有在真实实例上执行过「升级 → 回滚」全过程。
 - 未验证 HTTPS、域名、多机与灰度部署；本机演练只用 `127.0.0.1` 与模拟触摸视口。
 - 未启用定时备份、监控与告警；备份由人工触发。
- **附件（封面/音频）尚未实现（工单 #21）**：本页的备份恢复范围目前只覆盖数据库；#21 落地后必须把附件存储纳入备份与恢复验收。
+- **封面与音频附件（#21）已存进数据库**，因此 dump 自动包含附件与播放位置，恢复后仍可按字节读取并拖动；**附件会让 dump 变大**（单音频上限 20 MiB，封面上限 2 MiB），容量与备份体积要按试用量估算。
+- 附件读取需要会话并支持 HTTP Range；客户端用带凭据的 fetch 取字节后交给媒体元素，令牌不出现在 URL 里，但浏览器会整份取回后再播放（未做渐进式流式播放）。
 - 恢复演练是单机顺序执行，未验证大库恢复耗时与磁盘空间上限。
 - 接口级的两账号闭环与越权验证需要 HTTP 客户端，目前只在 Python 工具通道提供；Go 二进制提供数据库层的备份、恢复与校验。
 - 备份仍调用 `mysqldump`：自己实现一致性导出风险更高，因此部署机需要 MySQL 客户端而不只是服务端。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Home
 wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Home
-wiki_revision: 8c563c979bdfcacf1dda8743621b0ea00b3805f8
-synchronized_at: 2026-09-15T09:08:48Z
+wiki_revision: e1e363e39ea02c26fab7f96c696ee20e60dcec60
+synchronized_at: 2026-09-15T10:33:06Z
 <!-- gitea-wiki-mirror:end -->

 # LexGo 文档入口
@@ -90,3 +90,5 @@ Quant-UX 原型 v1 已通过用户验收。[桌面预览](https://qux.ilapage.cn
 #15 自托管试用交付已实现，待用户验收：新增运维工具（`scripts/ops.py`：依赖检查、建空库、备份、恢复、校验、两账号闭环演练；`scripts/bench.py`：写明规模的人造数据集性能测量）、新的 Wiki 部署与运维页，以及一次完整的本机演练——空库安装（建库 → 迁移 → 首次 bootstrap 建管理员 → 管理员建两个虚构演练账号 → 走通粘贴/阅读/查词/保存/复习/完成章节/进度）、备份 lexgo_dev、恢复到空实例并用第二个 API 实例完成两账号闭环与越权校验，恢复后逐表行数与内容校验和都和源库一致、源库未被改动。备份含全部用户数据（数据库）与环境配置（单独保管凭据），恢复默认只写空库、覆盖需要显式确认与 `--force`、拒绝写入系统库。性能在 20 章/2000 词条/8000 条作答的人造数据集上实测并记录环境，只作观察不给承诺。真实回滚、HTTPS、多机与定时备份仍未验证；附件（#21）尚未实施，恢复范围目前只覆盖数据库。

 #15 自托管试用交付已实现，待用户验收：备份、恢复与校验同时提供**纯二进制子命令**（`lexgo backup|restore|verify`，部署机只需要二进制与 MySQL 客户端）与 Python 工具通道（交叉验证与开发便利），两条通道的 dump 与 manifest 格式一致、可互相恢复；新增运维工具（`scripts/ops.py`：依赖检查、建空库、备份、恢复、校验、两账号闭环演练；`scripts/bench.py`：写明规模的人造数据集性能测量）、新的 Wiki 部署与运维页，以及一次完整的本机演练——空库安装（建库 → 迁移 → 首次 bootstrap 建管理员 → 管理员建两个虚构演练账号 → 走通粘贴/阅读/查词/保存/复习/完成章节/进度）、备份 lexgo_dev、恢复到空实例并用第二个 API 实例完成两账号闭环与越权校验，恢复后逐表行数与内容校验和都和源库一致、源库未被改动。备份含全部用户数据（数据库）与环境配置（单独保管凭据），恢复默认只写空库、覆盖需要显式确认与 `--force`、拒绝写入系统库。性能在 20 章/2000 词条/8000 条作答的人造数据集上实测并记录环境，只作观察不给承诺。两条通道已在本机交叉验证（19 项）。真实回滚、HTTPS、多机与定时备份仍未验证；附件（#21）尚未实施，恢复范围目前只覆盖数据库。
+
+#21 书籍音频与封面附件已于 2026-09-15 实施完成，待用户验收：每本书可以上传一张封面（JPG/PNG/WebP，≤2 MiB，≤4096×4096）和一段 MP3（≤20 MiB）；书库卡片显示封面，书籍页新增「音频与封面」区块可上传、替换、移除，阅读页在正文上方显示常驻播放器（播放/暂停、拖动进度、0.75–1.5 倍速），不自动播放、不与文本同步。播放位置按账号与书籍保存，替换或移除音频会重置位置；附件与进度按账号隔离，读取需要会话并支持 HTTP Range。附件存于 MySQL，因此 #15 的备份恢复天然覆盖：2026-09-15 的恢复演练验证了恢复后附件按字节相同地返回且 Range 仍可用。真实浏览器是否解码播放（媒体元素在测试中被桩替换）以及真机听感仍需人工确认。
@@ -0,0 +1,194 @@
+import { expect, test, type Page } from '@playwright/test'
+
+// Book audio and covers against a mocked API: upload, replace, remove, and the reader's player.
+const user = { id: 42, username: 'fictional-attachment', role: 'learner' }
+const book = { id: 7, title: 'Fictional reader', language: 'en' }
+const chapterText = 'Curiosity opens the first door.\nThe second door stays closed.\n'
+const chapter = {
+  id: 3, bookId: 7, ordinal: 1, title: 'Fictional chapter', status: 'ready', charCount: chapterText.length,
+  errorReason: '', errorMessage: '', jobId: 9, readAt: null, createdAt: '', updatedAt: '',
+}
+const pngBytes = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex')
+
+interface Attachment { kind: 'audio' | 'cover'; mime: string; byteSize: number; version: string; updatedAt: string }
+
+async function mockApi(page: Page, options: { audio?: boolean; cover?: boolean } = {}): Promise<{ posted: string[]; deleted: string[]; positions: number[] }> {
+  let audio: Attachment | null = options.audio === false ? null : { kind: 'audio', mime: 'audio/mpeg', byteSize: 4096, version: 'audio-sha', updatedAt: '2026-09-15T00:00:00Z' }
+  let cover: Attachment | null = options.cover === false ? null : { kind: 'cover', mime: 'image/png', byteSize: pngBytes.length, version: 'cover-sha', updatedAt: '2026-09-15T00:00:00Z' }
+  let playbackSeconds = 0
+  const posted: string[] = []
+  const deleted: string[] = []
+  const positions: number[] = []
+
+  await page.route('**/api/v1/**', async route => {
+    const url = new URL(route.request().url())
+    const path = url.pathname
+    const method = route.request().method()
+    const json = (data: unknown, status = 200) => route.fulfill({ status, json: { code: 200, data } })
+    const attachments = () => ({ cover, audio, playbackSeconds })
+
+    if (path === '/api/v1/login') return json({ token: 'fictional-session', user })
+    if (path === '/api/v1/me') return json(user)
+    if (path === '/api/v1/space') return json({ ownerId: user.id, language: 'en' })
+    if (path === '/api/v1/books' && method === 'GET') {
+      return json({ items: [{ ...book, chapterCount: 1, pendingCount: 0, processingCount: 0, readyCount: 1, failedCount: 0, coverVersion: cover?.version ?? '', hasAudio: audio !== null, createdAt: '', updatedAt: '' }] })
+    }
+    if (path === '/api/v1/books/7' && method === 'GET') return json({ book: { ...book, attachments: attachments() }, chapters: [chapter] })
+    if (path === '/api/v1/books/7/cover' || path === '/api/v1/books/7/audio') {
+      const kind = path.endsWith('cover') ? 'cover' : 'audio'
+      if (method === 'GET') {
+        const body = kind === 'cover' ? pngBytes : Buffer.concat([Buffer.from('ID3'), Buffer.alloc(4096)])
+        return route.fulfill({ status: 200, headers: { 'Content-Type': kind === 'cover' ? 'image/png' : 'audio/mpeg' }, body })
+      }
+      if (method === 'POST') {
+        posted.push(kind)
+        // The mock answers exactly like the backend: the new version replaces the old one.
+        const next: Attachment = { kind: kind as 'cover' | 'audio', mime: kind === 'cover' ? 'image/png' : 'audio/mpeg', byteSize: 2048, version: `${kind}-new`, updatedAt: '2026-09-15T01:00:00Z' }
+        if (kind === 'cover') cover = next
+        else { audio = next; playbackSeconds = 0 }
+        return json({ attachment: next })
+      }
+      if (method === 'DELETE') {
+        deleted.push(kind)
+        if (kind === 'cover') cover = null
+        else audio = null
+        return json({ deleted: true })
+      }
+    }
+    if (path === '/api/v1/books/7/playback' && method === 'PUT') {
+      const body = route.request().postDataJSON() as { positionSeconds: number }
+      positions.push(body.positionSeconds)
+      playbackSeconds = body.positionSeconds
+      return json({ playbackSeconds })
+    }
+    if (path === '/api/v1/chapters/3/tokens') {
+      let offset = 0
+      const tokens = (chapterText.match(/[A-Za-z]+|\s+|[^A-Za-z\s]+/g) ?? []).map(piece => {
+        const start = offset
+        offset += piece.length
+        return { text: piece, start, end: offset, startUtf16: start, endUtf16: offset, kind: /^[A-Za-z]+$/.test(piece) ? 'word' : 'space' }
+      })
+      return json({ textSha256: 'sha', tokens })
+    }
+    if (path === '/api/v1/chapters/3') return json({ book: { ...book, attachments: attachments() }, chapter: { ...chapter, contentSha256: 'sha', originalText: chapterText }, navigation: { previousChapterId: null, nextChapterId: null } })
+    return json({})
+  })
+  return { posted, deleted, positions }
+}
+
+async function login(page: Page): Promise<void> {
+  await page.addInitScript(() => sessionStorage.setItem('lexgo-learner-token', 'fictional-session'))
+  await page.goto('/')
+  await expect(page.getByRole('heading', { name: '我的书库' })).toBeVisible()
+}
+
+test('the library shows the stored cover and the book page manages attachments', async ({ page }) => {
+  const calls = await mockApi(page)
+  await login(page)
+  await expect(page.getByTestId('book-cover')).toBeVisible()
+  await page.screenshot({ path: '../.local/evidence/issue21-library-cover.png' })
+
+  await page.getByRole('link', { name: 'Fictional reader', exact: true }).click()
+  await expect(page.getByTestId('attachments')).toBeVisible()
+  await expect(page.getByTestId('cover-state')).toContainText('PNG')
+  await expect(page.getByTestId('audio-state')).toContainText('MP3')
+  await page.screenshot({ path: '../.local/evidence/issue21-attachments.png' })
+
+  // Replacing the cover uploads the picked file and reports the new state.
+  await page.setInputFiles('[data-testid="cover-input"]', { name: 'cover.png', mimeType: 'image/png', buffer: pngBytes })
+  await expect(page.getByTestId('book-notice')).toContainText('封面已更新')
+  expect(calls.posted).toEqual(['cover'])
+
+  // A file of the wrong type is refused in the page, before any request.
+  await page.setInputFiles('[data-testid="audio-input"]', { name: 'song.wav', mimeType: 'audio/wav', buffer: Buffer.from('RIFF....') })
+  await expect(page.locator('.field-error')).toContainText('音频只支持 MP3')
+  expect(calls.posted).toEqual(['cover'])
+
+  // Uploading audio clears the stored position, which the state line shows.
+  await page.setInputFiles('[data-testid="audio-input"]', { name: 'track.mp3', mimeType: 'audio/mpeg', buffer: Buffer.concat([Buffer.from('ID3'), Buffer.alloc(2048)]) })
+  await expect(page.getByTestId('audio-state')).toContainText('MP3')
+  expect(calls.posted).toEqual(['cover', 'audio'])
+
+  // Removing asks first and then reports the empty state.
+  await page.getByTestId('audio-remove').click()
+  await page.getByRole('button', { name: '确认移除' }).click()
+  await expect(page.getByTestId('audio-state')).toContainText('未设置')
+  expect(calls.deleted).toEqual(['audio'])
+})
+
+test('the reader plays the audio without starting it and remembers the position', async ({ page }) => {
+  // The fixture bytes are not a decodable MP3, so the media element itself is stubbed: the test is
+  // about the player's behaviour, not about Chromium decoding a synthetic file.
+  await page.addInitScript(() => {
+    const media = HTMLMediaElement.prototype as unknown as Record<string, unknown>
+    Object.defineProperty(media, 'duration', { configurable: true, get: () => 180 })
+    // paused has to follow the stub, otherwise the player would try to play again instead of pausing.
+    Object.defineProperty(media, 'paused', {
+      configurable: true,
+      get(this: HTMLMediaElement & { __playing?: boolean }) { return !this.__playing },
+    })
+    Object.defineProperty(media, 'play', {
+      configurable: true,
+      value(this: HTMLMediaElement & { __playing?: boolean }) {
+        this.__playing = true
+        this.dispatchEvent(new Event('play'))
+        return Promise.resolve()
+      },
+    })
+    Object.defineProperty(media, 'pause', {
+      configurable: true,
+      value(this: HTMLMediaElement & { __playing?: boolean }) {
+        this.__playing = false
+        this.dispatchEvent(new Event('pause'))
+      },
+    })
+    Object.defineProperty(media, 'load', {
+      configurable: true,
+      value(this: HTMLMediaElement) { this.dispatchEvent(new Event('loadedmetadata')) },
+    })
+  })
+  const calls = await mockApi(page)
+  await login(page)
+  await page.goto('/chapters/3')
+  await expect(page.locator('.reader-text')).toBeVisible()
+  const player = page.getByTestId('audio-player')
+  await expect(player).toBeVisible()
+  // The player is sticky above the text so the controls stay reachable while reading.
+  await expect(player).toHaveCSS('position', 'sticky')
+  await expect(player).toContainText('0:00')
+  await page.screenshot({ path: '../.local/evidence/issue21-reader-player.png' })
+
+  // Nothing plays until the button is pressed.
+  await expect(page.getByTestId('audio-toggle')).toHaveAttribute('aria-label', '播放音频')
+  await page.getByTestId('audio-toggle').click()
+  await expect(page.getByTestId('audio-toggle')).toHaveAttribute('aria-label', '暂停音频')
+  await page.screenshot({ path: '../.local/evidence/issue21-reader-playing.png' })
+
+  // Seeking moves the position and pausing reports it to the book.
+  // A range input cannot be filled, so the value is set the way dragging the handle would.
+  await page.getByTestId('audio-seek').evaluate((element, value) => {
+    const input = element as HTMLInputElement
+    input.value = String(value)
+    input.dispatchEvent(new Event('input', { bubbles: true }))
+  }, 12)
+  await page.getByTestId('audio-toggle').click()
+  await expect.poll(() => calls.positions.length).toBeGreaterThan(0)
+
+  // The speed control states which rate is active.
+  await page.getByTestId('audio-rate-1.5').click()
+  await expect(page.getByTestId('audio-rate-1.5')).toHaveAttribute('aria-pressed', 'true')
+})
+
+test('a book without audio shows no player at all', async ({ page }) => {
+  await mockApi(page, { audio: false, cover: false })
+  await login(page)
+  await expect(page.getByTestId('book-cover')).toHaveCount(0)
+  // The management section stays: adding an attachment must be possible before one exists.
+  await page.getByRole('link', { name: 'Fictional reader', exact: true }).click()
+  await expect(page.getByTestId('attachments')).toBeVisible()
+  await expect(page.getByTestId('cover-state')).toContainText('未设置')
+  await expect(page.getByTestId('audio-state')).toContainText('未设置')
+  await page.goto('/chapters/3')
+  await expect(page.locator('.reader-text')).toBeVisible()
+  await expect(page.getByTestId('audio-player')).toHaveCount(0)
+})
@@ -63,7 +63,9 @@ test('rename the book, edit a chapter into a new version and delete both', async
  await page.getByRole('button', { name: '登录', exact: true }).click()
  await page.getByRole('link', { name: 'A small step' }).click()
  await expect(page.getByRole('heading', { name: 'A small step' })).toBeVisible()
-  await expect(page.getByText('封面使用系统默认样式')).toBeVisible()
+  // The subtitle no longer claims a system cover: covers are attachments now (#21).
+  await expect(page.getByText('语言 英语')).toBeVisible()
+  await expect(page.getByTestId('attachments')).toBeVisible()

  // Rename the book through the dialog.
  await page.getByTestId('edit-book').click()
@@ -29,11 +29,13 @@ test('a touch swipe scrolls the chapter and does not open the word panel', async
  const padding = await page.evaluate(() => getComputedStyle(document.querySelector('.reader-page') as Element).paddingBottom)
  expect(parseFloat(padding)).toBeGreaterThan(100)

-  // Closing the panel keeps the reading position instead of jumping away.
-  const before = await page.evaluate(() => window.scrollY)
+  // Closing the panel keeps the reader where they were: the tapped word stays on screen. The page
+  // releases the space it reserved for the sheet, so the browser may clamp the scroll by a little
+  // when the chapter end is already in view; what must not happen is losing sight of the word.
+  const word = page.locator('.reader-word').nth(1)
  await page.getByRole('button', { name: '关闭释义' }).tap()
  await expect(panel).toHaveCount(0)
-  expect(Math.abs((await page.evaluate(() => window.scrollY)) - before)).toBeLessThan(40)
+  await expect(word).toBeInViewport()
 })

 test('the display choice survives a reload and belongs to the account', async ({ page }) => {
@@ -22,6 +22,13 @@ export async function mockLearnerApi(page: Page): Promise<void> {
    errorReason: '', errorMessage: '', jobId: 9, readAt: null, createdAt: '', updatedAt: '',
  }
  const term = { id: 11, term: 'curiosity', originalForm: 'curiosity', definition: '好奇心；求知欲', examples: ['Curious minds ask.'], status: 'new', level: 0, kind: 'word', wordCount: 1, updatedAt: '2026-01-02T00:00:00Z' }
+  // The phone audit also covers the attachment surfaces, so the fixture book carries both.
+  const pngBytes = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex')
+  const attachments = {
+    cover: { kind: 'cover', mime: 'image/png', byteSize: pngBytes.length, version: 'cover-sha', updatedAt: '2026-09-15T00:00:00Z' },
+    audio: { kind: 'audio', mime: 'audio/mpeg', byteSize: 4096, version: 'audio-sha', updatedAt: '2026-09-15T00:00:00Z' },
+    playbackSeconds: 65,
+  }

  await page.route('**/api/v1/**', async route => {
    const url = new URL(route.request().url())
@@ -30,8 +37,13 @@ export async function mockLearnerApi(page: Page): Promise<void> {
    if (path === '/api/v1/login') data = { token: 'fictional-session', user: mobileUser }
    else if (path === '/api/v1/me') data = mobileUser
    else if (path === '/api/v1/space') data = { ownerId: mobileUser.id, language: 'en' }
-    else if (path === '/api/v1/books') data = { items: [book] }
-    else if (path === '/api/v1/books/7') data = { book, chapters: [chapter] }
+    else if (path === '/api/v1/books') data = { items: [{ ...book, coverVersion: attachments.cover.version, hasAudio: true }] }
+    else if (path === '/api/v1/books/7/cover' || path === '/api/v1/books/7/audio') {
+      const body = path.endsWith('cover') ? pngBytes : Buffer.concat([Buffer.from('ID3'), Buffer.alloc(4096)])
+      await route.fulfill({ status: 200, headers: { 'Content-Type': path.endsWith('cover') ? 'image/png' : 'audio/mpeg' }, body })
+      return
+    } else if (path === '/api/v1/books/7/playback') data = { playbackSeconds: 65 }
+    else if (path === '/api/v1/books/7') data = { book: { ...book, attachments }, chapters: [chapter] }
    else if (path === '/api/v1/chapters/3/tokens') {
      const tokens: unknown[] = []
      let offset = 0
@@ -46,7 +58,7 @@ export async function mockLearnerApi(page: Page): Promise<void> {
      // The reader follows the tokens only while they describe the chapter's content version.
      data = { textSha256: 'e'.repeat(64), tokens }
    } else if (path === '/api/v1/chapters/3') {
-      data = { book, chapter: { ...chapter, contentSha256: 'e'.repeat(64), originalText: chapterText }, navigation: { previousChapterId: null, nextChapterId: null } }
+      data = { book: { ...book, attachments }, chapter: { ...chapter, contentSha256: 'e'.repeat(64), originalText: chapterText }, navigation: { previousChapterId: null, nextChapterId: null } }
    } else if (path === '/api/v1/terms/lookup') {
      data = { query: 'curiosity', terms: [{ term: 'curiosity', entries: [{ partOfSpeech: 'noun', definition: '好奇心' }] }], candidates: [] }
    } else if (path === '/api/v1/terms' && route.request().method() === 'GET') {
@@ -47,24 +47,53 @@ async function openChapter(page: Page, options: { phrases?: unknown[]; onPhrase?
  await expect(page.locator('.reader-text')).toBeVisible()
 }

-/** Drags from the centre of one word to the centre of another, like a person selecting text. */
-async function dragWords(page: Page, from: string, to: string) {
-  const words = page.locator('.reader-word')
-  const start = words.filter({ hasText: new RegExp(`^${from}$`) }).first()
-  const end = words.filter({ hasText: new RegExp(`^${to}$`) }).first()
-  const startBox = (await start.boundingBox())!
-  const endBox = (await end.boundingBox())!
-  await page.mouse.move(startBox.x + startBox.width / 2, startBox.y + startBox.height / 2)
-  await page.mouse.down()
-  await page.mouse.move(endBox.x + endBox.width / 2, endBox.y + endBox.height / 2, { steps: 8 })
-  await page.mouse.up()
+/**
+ * Drags from the centre of one word to the centre of another, like a person selecting text.
+ *
+ * A synthetic drag sometimes stops one word short or collapses entirely in Chromium, especially
+ * while other tests load the same dev server, so the drag is repeated until the highlighted run
+ * has the expected number of words. The retry condition is the property the test is about, not
+ * just "a panel appeared": a real regression in selection handling still fails all attempts.
+ */
+async function dragWords(page: Page, from: string, to: string, words: number) {
+  const word = page.locator('.reader-word')
+  const start = word.filter({ hasText: new RegExp(`^${from}$`) }).first()
+  const end = word.filter({ hasText: new RegExp(`^${to}$`) }).first()
+  const range = page.getByTestId('phrase-range')
+  for (let attempt = 1; attempt <= 4; attempt += 1) {
+    // The boxes are read again on every attempt: an open panel reflows the page, so a cached
+    // coordinate would drag to the wrong place and keep the retry failing for the same reason.
+    const startBox = (await start.boundingBox())!
+    const endBox = (await end.boundingBox())!
+    const startX = startBox.x + startBox.width / 2
+    const startY = startBox.y + startBox.height / 2
+    await page.mouse.move(startX, startY)
+    await page.mouse.down()
+    // A couple of pixels first: the browser only starts extending the selection once the pointer
+    // has actually moved, and a single jump can be treated as a click.
+    await page.mouse.move(startX + 3, startY, { steps: 2 })
+    await page.mouse.move(endBox.x + endBox.width / 2, endBox.y + endBox.height / 2, { steps: 12 })
+    // Under load the browser may not have extended the selection by the time the button is
+    // released, which is what produces a run that stops one word short.
+    await page.waitForTimeout(80)
+    await page.mouse.up()
+    try {
+      await expect(range).toContainText(`短语 · ${words} 个单词`, { timeout: 2500 })
+      return
+    } catch (reason) {
+      if (attempt === 4) throw reason
+      // Close whatever panel the partial selection opened, so the next attempt starts clean.
+      await page.keyboard.press('Escape')
+      await expect(page.locator('.lookup-panel')).toHaveCount(0)
+    }
+  }
 }

 test('drag a continuous phrase, save it and highlight it', async ({ page }) => {
  let body: Record<string, unknown> | undefined
  await openChapter(page, { onPhrase: value => { body = value } })

-  await dragWords(page, 'Take', 'small')
+  await dragWords(page, 'Take', 'small', 3)
  const range = page.getByTestId('phrase-range')
  await expect(range).toContainText('短语 · 3 个单词')
  // A phrase that is not stored yet is labelled as a new entry.
@@ -81,7 +110,7 @@ test('drag a continuous phrase, save it and highlight it', async ({ page }) => {

 test('adjust the endpoints by whole words from the panel', async ({ page }) => {
  await openChapter(page)
-  await dragWords(page, 'Take', 'small')
+  await dragWords(page, 'Take', 'small', 3)
  await expect(page.getByTestId('phrase-range')).toContainText('3 个单词')
  await page.getByTestId('range-end-right').click()
  await expect(page.getByTestId('phrase-range')).toContainText('4 个单词')
@@ -0,0 +1,249 @@
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from 'vitest'
+import { flushPromises, mount, type VueWrapper } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createMemoryHistory, type Router } from 'vue-router'
+import { ElMessageBox } from 'element-plus'
+import AudioPlayer from '../components/AudioPlayer.vue'
+import BookView from '../views/BookView.vue'
+import LibraryView from '../views/LibraryView.vue'
+import ReaderView from '../views/ReaderView.vue'
+import { useLibraryStore } from '../stores/library'
+import { useSessionStore } from '../stores/session'
+
+const user = { id: 42, username: 'fictional-attachment', role: 'learner' as const }
+const cover = { kind: 'cover' as const, mime: 'image/png', byteSize: 1234, version: 'cover-sha', updatedAt: '2026-09-15T00:00:00Z' }
+const audio = { kind: 'audio' as const, mime: 'audio/mpeg', byteSize: 4096, version: 'audio-sha', updatedAt: '2026-09-15T00:00:00Z' }
+const book = { id: 7, title: 'Fictional reader', language: 'en' }
+const chapter = {
+  id: 3, bookId: 7, ordinal: 1, title: 'Fictional chapter', status: 'ready', charCount: 31, errorReason: '', errorMessage: '',
+  jobId: 9, readAt: null, createdAt: '', updatedAt: '', contentSha256: 'sha', originalText: 'Curiosity opens the first door.\n',
+}
+let wrapper: VueWrapper | undefined
+let createdUrls: string[]
+
+/** jsdom has no object URLs, so the two functions are added to the existing URL object. */
+function stubObjectUrls(): void {
+  createdUrls = []
+  let counter = 0
+  ;(URL as unknown as Record<string, unknown>).createObjectURL = vi.fn(() => {
+    const url = `blob:fictional-${++counter}`
+    createdUrls.push(url)
+    return url
+  })
+  ;(URL as unknown as Record<string, unknown>).revokeObjectURL = vi.fn()
+}
+
+function putBackObjectUrls(): void {
+  delete (URL as unknown as Record<string, unknown>).createObjectURL
+  delete (URL as unknown as Record<string, unknown>).revokeObjectURL
+}
+
+/** Sets the files of a hidden input the way a file picker would, then fires the change event. */
+async function pickFile(view: VueWrapper, testid: string, file: File): Promise<void> {
+  const input = view.get(`[data-testid="${testid}"]`).element as HTMLInputElement
+  Object.defineProperty(input, 'files', { value: [file], configurable: true })
+  await view.get(`[data-testid="${testid}"]`).trigger('change')
+  await flushPromises()
+}
+
+function stubMedia(): { play: MockInstance; pause: MockInstance } {
+  const play = vi.spyOn(HTMLMediaElement.prototype, 'play').mockImplementation(async () => undefined)
+  const pause = vi.spyOn(HTMLMediaElement.prototype, 'pause').mockImplementation(() => undefined)
+  return { play, pause }
+}
+
+/** An API mock whose book and chapter carry attachments. */
+function mockApi(options: { attachments?: { cover: unknown; audio: unknown; playbackSeconds: number } } = {}): MockInstance {
+  const attachments = options.attachments ?? { cover, audio, playbackSeconds: 90 }
+  return vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => {
+    const url = String(input)
+    const method = String(init?.method ?? 'GET')
+    const ok = (data: unknown) => new Response(JSON.stringify({ code: 200, data }))
+    if (url.endsWith('/me')) return ok(user)
+    if (url.endsWith('/space')) return ok({ ownerId: user.id, language: 'en' })
+    if (url.endsWith('/books') && method === 'GET') {
+      return ok({ items: [{ ...book, chapterCount: 1, pendingCount: 0, processingCount: 0, readyCount: 1, failedCount: 0, coverVersion: attachments.cover ? 'cover-sha' : '', hasAudio: Boolean(attachments.audio), createdAt: '', updatedAt: '' }] })
+    }
+    if (url.includes('/books/7/cover') || url.includes('/books/7/audio')) {
+      // A body of bytes rather than a jsdom Blob: the Response constructor cannot stream that one.
+      if (method === 'GET') return new Response(new Uint8Array([1, 2, 3, 4]), { status: 200, headers: { 'Content-Type': 'application/octet-stream' } })
+      return ok({ attachment: url.includes('cover') ? cover : audio })
+    }
+    if (url.includes('/books/7/playback')) {
+      const body = typeof init?.body === 'string' ? JSON.parse(init.body) : { positionSeconds: 0 }
+      return ok({ playbackSeconds: Number(body.positionSeconds) })
+    }
+    if (url.includes('/books/7')) return ok({ book: { ...book, attachments }, chapters: [chapter] })
+    if (url.includes('/chapters/3/tokens')) return ok({ textSha256: 'sha', tokens: [] })
+    if (url.includes('/chapters/3')) return ok({ book: { ...book, attachments }, chapter, navigation: { previousChapterId: null, nextChapterId: null } })
+    if (url.includes('/terms')) return ok({ items: [], total: 0, page: 1, limit: 20 })
+    if (url.includes('/progress')) return ok({})
+    return ok({})
+  })
+}
+
+async function mountWith(component: unknown, path: string): Promise<{ view: VueWrapper; router: Router }> {
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/', component: LibraryView },
+      { path: '/books/:id', component: BookView },
+      { path: '/chapters/:id', component: ReaderView },
+      { path: '/vocab', component: { template: '<div />' } },
+      { path: '/review', component: { template: '<div />' } },
+      { path: '/progress', component: { template: '<div />' } },
+      { path: '/import', component: { template: '<div />' } },
+    ],
+  })
+  await router.push(path)
+  await router.isReady()
+  wrapper = mount(component as never, { attachTo: document.body, global: { plugins: [router] } })
+  await flushPromises()
+  await flushPromises()
+  return { view: wrapper, router }
+}
+
+describe('book covers in the library', () => {
+  beforeEach(() => { localStorage.clear(); setActivePinia(createPinia()); stubObjectUrls(); useSessionStore().user = { ...user } })
+  afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); putBackObjectUrls(); wrapper?.unmount() })
+
+  it('shows the stored cover and falls back to a default block', async () => {
+    mockApi()
+    const { view } = await mountWith(LibraryView, '/')
+    // The cover is fetched after the list answers, so the test waits for the blob instead of
+    // assuming that two microtask flushes are enough.
+    await vi.waitFor(() => expect(useLibraryStore().coverUrls[7]).toBeTruthy())
+    await flushPromises()
+    const image = view.get('[data-testid="book-cover"]')
+    expect(image.attributes('src')).toMatch(/^blob:fictional-/)
+    // The cover repeats the title link, so it is decorative and hidden from the accessibility tree.
+    expect(image.attributes('alt')).toBe('')
+    expect(view.get('.book-cover').attributes('aria-hidden')).toBe('true')
+    expect(useLibraryStore().coverUrls[7]).toMatch(/^blob:fictional-/)
+  })
+
+  it('keeps the default cover when the book has none', async () => {
+    mockApi({ attachments: { cover: null, audio: null, playbackSeconds: 0 } })
+    const { view } = await mountWith(LibraryView, '/')
+    expect(view.find('[data-testid="book-cover"]').exists()).toBe(false)
+    expect(view.get('.book-cover-default').text()).toBe('F')
+  })
+})
+
+describe('attachments on the book page', () => {
+  beforeEach(() => { localStorage.clear(); setActivePinia(createPinia()); stubObjectUrls(); useSessionStore().user = { ...user } })
+  afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); putBackObjectUrls(); wrapper?.unmount() })
+
+  it('describes what is stored and where the audio stopped', async () => {
+    mockApi()
+    const { view } = await mountWith(BookView, '/books/7')
+    expect(view.get('[data-testid="cover-state"]').text()).toContain('PNG')
+    expect(view.get('[data-testid="audio-state"]').text()).toContain('MP3')
+    expect(view.get('[data-testid="audio-state"]').text()).toContain('1:30')
+    expect(view.find('[data-testid="cover-remove"]').exists()).toBe(true)
+    expect(view.find('[data-testid="audio-remove"]').exists()).toBe(true)
+  })
+
+  it('refuses an oversized or wrong-typed file before uploading', async () => {
+    const fetchMock = mockApi()
+    const { view } = await mountWith(BookView, '/books/7')
+    const big = new File([new Uint8Array(3 << 20)], 'big.png', { type: 'image/png' })
+    await pickFile(view, 'cover-input', big)
+    expect(view.get('.field-error').text()).toContain('2 MiB')
+    expect(fetchMock.mock.calls.some(([url]) => String(url).includes('/cover') && String(url).includes('books/7'))).toBe(true) // only the initial read
+    expect(fetchMock.mock.calls.filter(([, init]) => String(init?.method) === 'POST')).toHaveLength(0)
+
+    const wrong = new File([new Uint8Array(16)], 'song.wav', { type: 'audio/wav' })
+    await pickFile(view, 'audio-input', wrong)
+    expect(view.text()).toContain('音频只支持 MP3')
+  })
+
+  it('uploads a replacement and reports the new state', async () => {
+    const fetchMock = mockApi()
+    const { view } = await mountWith(BookView, '/books/7')
+    const file = new File([new Uint8Array(2048)], 'cover.png', { type: 'image/png' })
+    await pickFile(view, 'cover-input', file)
+    const posted = fetchMock.mock.calls.find(([, init]) => String(init?.method) === 'POST')
+    expect(String(posted?.[0])).toContain('/api/v1/books/7/cover')
+    expect(posted?.[1]?.body).toBeInstanceOf(FormData)
+    expect(view.get('[data-testid="book-notice"]').text()).toContain('封面已更新')
+  })
+
+  it('removes an attachment after confirmation', async () => {
+    const fetchMock = mockApi()
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue('confirm' as never)
+    const { view } = await mountWith(BookView, '/books/7')
+    await view.get('[data-testid="audio-remove"]').trigger('click')
+    await flushPromises()
+    const deleted = fetchMock.mock.calls.find(([, init]) => String(init?.method) === 'DELETE')
+    expect(String(deleted?.[0])).toContain('/api/v1/books/7/audio')
+    expect(view.get('[data-testid="book-notice"]').text()).toContain('音频已移除')
+    // The audio state falls back to "not set" once the file is gone.
+    expect(view.get('[data-testid="audio-state"]').text()).toContain('未设置')
+  })
+})
+
+describe('audio player', () => {
+  beforeEach(() => { localStorage.clear(); setActivePinia(createPinia()) })
+  afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); putBackObjectUrls(); wrapper?.unmount() })
+
+  it('formats the clock, changes the rate and reports an error', async () => {
+    stubMedia()
+    const positions: number[] = []
+    wrapper = mount(AudioPlayer, { props: { src: 'blob:fictional', initialPosition: 65, onPosition: (value: number) => positions.push(value) } })
+    await flushPromises()
+    expect(wrapper.get('[data-testid="audio-clock"]').text()).toContain('1:05')
+    await wrapper.get('[data-testid="audio-rate-1.5"]').trigger('click')
+    expect(wrapper.get('[data-testid="audio-rate-1.5"]').attributes('aria-pressed')).toBe('true')
+    const element = wrapper.get('[data-testid="audio-element"]').element as HTMLAudioElement
+    expect(element.playbackRate).toBe(1.5)
+    element.currentTime = 42
+    await wrapper.get('[data-testid="audio-element"]').trigger('pause')
+    expect(positions).toEqual([42])
+    await wrapper.get('[data-testid="audio-element"]').trigger('error')
+    expect(wrapper.get('[data-testid="audio-error"]').text()).toContain('音频加载失败')
+  })
+
+  it('never starts on its own and tolerates a rejected play', async () => {
+    const { play } = stubMedia()
+    play.mockRejectedValueOnce(new Error('blocked'))
+    wrapper = mount(AudioPlayer, { props: { src: 'blob:fictional', initialPosition: 0, onPosition: () => undefined } })
+    await flushPromises()
+    expect(play).not.toHaveBeenCalled()
+    await wrapper.get('[data-testid="audio-toggle"]').trigger('click')
+    await flushPromises()
+    expect(play).toHaveBeenCalledTimes(1)
+    expect(wrapper.get('[data-testid="audio-error"]').text()).toContain('无法播放')
+  })
+})
+
+describe('player inside the reader', () => {
+  beforeEach(() => { localStorage.clear(); setActivePinia(createPinia()); stubObjectUrls(); stubMedia(); useSessionStore().user = { ...user } })
+  afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); putBackObjectUrls(); wrapper?.unmount() })
+
+  it('appears for a book with audio and stays away otherwise', async () => {
+    mockApi()
+    const { view } = await mountWith(ReaderView, '/chapters/3')
+    expect(view.find('.reader-text').exists()).toBe(true)
+    await vi.waitFor(() => expect(useLibraryStore().audioUrl).not.toBe(''))
+    await flushPromises()
+    expect(view.find('[data-testid="audio-player"]').exists()).toBe(true)
+    wrapper?.unmount()
+
+    mockApi({ attachments: { cover, audio: null, playbackSeconds: 0 } })
+    const second = await mountWith(ReaderView, '/chapters/3')
+    expect(second.view.find('[data-testid="audio-player"]').exists()).toBe(false)
+  })
+
+  it('sends the position to the book instead of only keeping it locally', async () => {
+    const fetchMock = mockApi()
+    const { view } = await mountWith(ReaderView, '/chapters/3')
+    const element = view.get('[data-testid="audio-element"]').element as HTMLAudioElement
+    element.currentTime = 77
+    await view.get('[data-testid="audio-element"]').trigger('pause')
+    await flushPromises()
+    const reported = fetchMock.mock.calls.find(([, init]) => String(init?.method) === 'PUT')
+    expect(String(reported?.[0])).toContain('/api/v1/books/7/playback')
+    expect(JSON.parse(String(reported?.[1]?.body))).toEqual({ positionSeconds: 77 })
+  })
+})
@@ -0,0 +1,184 @@
+<script setup lang="ts">
+import { computed, onScopeDispose, ref, watch } from 'vue'
+import { ElButton } from 'element-plus'
+
+/**
+ * The audio player for one book. It only appears when the book has audio, never starts on its own,
+ * and remembers the position per account so reading can continue where it stopped. Nothing here
+ * aligns the audio with the text: the two are independent, as the ticket requires.
+ */
+const props = defineProps<{
+  src: string
+  /** Where this account stopped last time, in seconds. */
+  initialPosition: number
+  /** Called with the position while playing, when pausing and when leaving. */
+  onPosition: (seconds: number) => void
+}>()
+
+const audio = ref<HTMLAudioElement | null>(null)
+const playing = ref(false)
+const position = ref(props.initialPosition)
+const duration = ref(0)
+const rate = ref(1)
+const error = ref('')
+const rates = [0.75, 1, 1.25, 1.5]
+
+const positionLabel = computed(() => formatClock(position.value))
+const durationLabel = computed(() => (duration.value > 0 ? formatClock(duration.value) : '--:--'))
+
+function formatClock(seconds: number): string {
+  const total = Math.max(0, Math.floor(seconds))
+  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`
+}
+
+async function toggle(): Promise<void> {
+  const element = audio.value
+  if (!element) return
+  error.value = ''
+  if (element.paused) {
+    try {
+      await element.play()
+    } catch {
+      // A rejected play() is usually a blocked autoplay attempt or a missing file.
+      error.value = '音频无法播放，请重试。'
+      playing.value = false
+    }
+    return
+  }
+  element.pause()
+}
+
+function onLoaded(): void {
+  const element = audio.value
+  if (!element) return
+  duration.value = Number.isFinite(element.duration) ? element.duration : 0
+  // The stored position is applied once the metadata is known, so seeking actually lands.
+  if (props.initialPosition > 0 && props.initialPosition < duration.value) {
+    element.currentTime = props.initialPosition
+  }
+}
+
+function onSeek(event: Event): void {
+  const element = audio.value
+  if (!element) return
+  element.currentTime = Number((event.target as HTMLInputElement).value)
+  position.value = element.currentTime
+}
+
+function setRate(value: number): void {
+  rate.value = value
+  if (audio.value) audio.value.playbackRate = value
+}
+
+/** Reports the position on a fixed cadence while playing, so a long listen is not lost. */
+let reportTimer: number | undefined
+function onTimeUpdate(): void {
+  const element = audio.value
+  if (!element) return
+  position.value = element.currentTime
+  if (reportTimer !== undefined) return
+  reportTimer = window.setInterval(() => {
+    reportTimer = undefined
+    if (audio.value && !audio.value.paused) props.onPosition(audio.value.currentTime)
+    startReporting()
+  }, 5000)
+}
+
+function startReporting(): void {
+  if (reportTimer !== undefined) return
+  reportTimer = window.setInterval(() => {
+    if (audio.value && !audio.value.paused) props.onPosition(audio.value.currentTime)
+  }, 5000)
+}
+
+function stopReporting(): void {
+  if (reportTimer !== undefined) {
+    window.clearInterval(reportTimer)
+    reportTimer = undefined
+  }
+}
+
+function onPause(): void {
+  playing.value = false
+  stopReporting()
+  if (audio.value) props.onPosition(audio.value.currentTime)
+}
+
+function onPlay(): void {
+  playing.value = true
+  startReporting()
+}
+
+function retry(): void {
+  error.value = ''
+  const element = audio.value
+  if (element) {
+    element.load()
+    void toggle()
+  }
+}
+
+watch(() => props.src, () => {
+  error.value = ''
+  position.value = props.initialPosition
+  playing.value = false
+})
+
+// Leaving the page stores the last position, so the same book continues where it stopped.
+onScopeDispose(() => {
+  stopReporting()
+  if (audio.value) props.onPosition(audio.value.currentTime)
+})
+</script>
+
+<template>
+  <section class="audio-player" aria-label="音频播放" data-testid="audio-player">
+    <ElButton
+      circle
+      type="primary"
+      data-testid="audio-toggle"
+      :aria-label="playing ? '暂停音频' : '播放音频'"
+      @click="toggle"
+    >{{ playing ? '❚❚' : '▶' }}</ElButton>
+    <span class="audio-clock" data-testid="audio-clock">{{ positionLabel }} / {{ durationLabel }}</span>
+    <input
+      class="audio-range"
+      type="range"
+      min="0"
+      :max="duration > 0 ? duration : 0"
+      step="1"
+      :value="position"
+      aria-label="播放进度"
+      data-testid="audio-seek"
+      :disabled="duration === 0"
+      @input="onSeek"
+    />
+    <div class="audio-rates" role="group" aria-label="播放速度">
+      <button
+        v-for="value in rates"
+        :key="value"
+        type="button"
+        class="audio-rate"
+        :class="{ 'is-active': rate === value }"
+        :aria-pressed="rate === value"
+        :data-testid="`audio-rate-${value}`"
+        @click="setRate(value)"
+      >{{ value }}×</button>
+    </div>
+    <span v-if="error" role="alert" class="audio-error" data-testid="audio-error">{{ error }}
+      <ElButton text size="small" data-testid="audio-retry" @click="retry">重试</ElButton>
+    </span>
+    <audio
+      ref="audio"
+      :src="src"
+      preload="metadata"
+      data-testid="audio-element"
+      @loadedmetadata="onLoaded"
+      @timeupdate="onTimeUpdate"
+      @play="onPlay"
+      @pause="onPause"
+      @ended="onPause"
+      @error="error = '音频加载失败。'"
+    />
+  </section>
+</template>
@@ -4,9 +4,35 @@ import { ApiError, useSessionStore } from './session'

 export type ChapterStatus = 'pending' | 'processing' | 'ready' | 'failed'

-export interface BookRef { id: number; title: string; language: string }
+export type AttachmentKind = 'audio' | 'cover'
+
+/** One stored attachment: metadata only, the bytes are fetched from the attachment endpoint. */
+export interface BookAttachment {
+  kind: AttachmentKind
+  mime: string
+  byteSize: number
+  /** Content digest, used as the cache key so a replaced file is fetched again. */
+  version: string
+  updatedAt: string
+}
+
+export interface BookAttachments {
+  cover: BookAttachment | null
+  audio: BookAttachment | null
+  /** Where this account stopped in this book, in seconds. */
+  playbackSeconds: number
+}
+
+export interface BookRef {
+  id: number
+  title: string
+  language: string
+  attachments?: BookAttachments | null
+}

 export interface BookSummary extends BookRef {
+  coverVersion?: string
+  hasAudio?: boolean
  chapterCount: number
  pendingCount: number
  processingCount: number
@@ -188,6 +214,7 @@ export const useLibraryStore = defineStore('library', () => {
  const submitError = ref('')
  const retryingChapterId = ref<number | null>(null)
  const completingChapterId = ref<number | null>(null)
+  const uploadingKind = ref<AttachmentKind | null>(null)

  /** Reader text exists only for ready chapters and is never taken from a cache. */
  const readerText = computed(() => (chapter.value?.status === 'ready' ? chapter.value.originalText ?? '' : ''))
@@ -278,6 +305,9 @@ export const useLibraryStore = defineStore('library', () => {
      if (seq !== booksSeq || isStale(version, owner)) return
      const items = result?.items
      books.value = Array.isArray(items) ? items : []
+      for (const book of books.value) {
+        if (book.coverVersion) void loadCover(book.id, book.coverVersion)
+      }
    } catch (reason) {
      if (seq !== booksSeq || isStale(version, owner)) return
      booksError.value = failureMessage(reason, '书库暂时无法加载，请稍后重试。')
@@ -300,6 +330,9 @@ export const useLibraryStore = defineStore('library', () => {
      book.value = result.book
      chapters.value = Array.isArray(result.chapters) ? result.chapters : []
      bookError.value = ''
+      // The book is always present in this response; the guard also covers a stale server reply.
+      const cover = result.book?.attachments?.cover
+      if (cover) void loadCover(result.book.id, cover.version)
      schedulePolling()
    } catch (reason) {
      if (seq !== bookSeq || isStale(version, owner)) return
@@ -341,6 +374,13 @@ export const useLibraryStore = defineStore('library', () => {
      chapter.value = result.chapter
      navigation.value = result.navigation ?? emptyNavigation()
      chapterError.value = ''
+      const audio = result.book?.attachments?.audio
+      if (audio) {
+        // A failure here is shown by the player itself; the chapter stays readable without audio.
+        void loadAudio(result.book.id, audio.version).catch(() => undefined)
+      } else {
+        audioUrl.value = ''
+      }
      schedulePolling()
    } catch (reason) {
      if (seq !== chapterSeq || isStale(version, owner)) return
@@ -575,6 +615,140 @@ export const useLibraryStore = defineStore('library', () => {
    }
  }

+  /**
+   * Uploads or replaces one attachment of an owned book. The reply is the stored metadata, which is
+   * written back into the open book and into the library list so a cover appears without a reload.
+   */
+  async function uploadAttachment(bookId: number, kind: AttachmentKind, file: File): Promise<BookAttachment> {
+    const version = generation
+    const owner = ownerId()
+    uploadingKind.value = kind
+    try {
+      const form = new FormData()
+      form.append('file', file, file.name)
+      const result = await session.request<{ attachment: BookAttachment }>(`books/${bookId}/${kind}`, 'POST', form)
+      if (!isStale(version, owner)) applyAttachment(bookId, kind, result.attachment)
+      return result.attachment
+    } catch (reason) {
+      if (isStale(version, owner)) throw reason instanceof Error ? reason : new Error('上传失败，请稍后重试。')
+      throw reason instanceof Error ? reason : new Error('上传失败，请稍后重试。')
+    } finally {
+      if (!isStale(version, owner)) uploadingKind.value = null
+    }
+  }
+
+  /** Removes one attachment of an owned book; removing the audio also clears the position. */
+  async function deleteAttachment(bookId: number, kind: AttachmentKind): Promise<void> {
+    const version = generation
+    const owner = ownerId()
+    uploadingKind.value = kind
+    try {
+      await session.request<{ deleted: boolean }>(`books/${bookId}/${kind}`, 'DELETE')
+      if (!isStale(version, owner)) applyAttachment(bookId, kind, null)
+    } catch (reason) {
+      if (isStale(version, owner)) throw reason instanceof Error ? reason : new Error('删除失败，请稍后重试。')
+      throw reason instanceof Error ? reason : new Error('删除失败，请稍后重试。')
+    } finally {
+      if (!isStale(version, owner)) uploadingKind.value = null
+    }
+  }
+
+  /** Writes the attachment change into every view that shows this book. */
+  function applyAttachment(bookId: number, kind: AttachmentKind, attachment: BookAttachment | null): void {
+    const current = book.value?.id === bookId
+      ? book.value.attachments ?? { cover: null, audio: null, playbackSeconds: 0 }
+      : null
+    if (current) {
+      const next: BookAttachments = { ...current, [kind]: attachment }
+      // A new audio file has nothing to do with the old position.
+      if (kind === 'audio') next.playbackSeconds = 0
+      book.value = { ...book.value!, attachments: next }
+    }
+    const listed = books.value.find(item => item.id === bookId)
+    if (listed) {
+      if (kind === 'cover') listed.coverVersion = attachment?.version ?? ''
+      else listed.hasAudio = attachment !== null
+    }
+    if (kind === 'cover') {
+      // The cached image belongs to the previous file, so it is dropped and loaded again.
+      forgetCover(bookId)
+      if (attachment) void loadCover(bookId, attachment.version)
+    }
+    if (kind === 'audio') {
+      loadedVersions.delete(`audio:${bookId}`)
+      audioUrl.value = ''
+    }
+  }
+
+  /** Remembers where this account stopped in one book, so reading can continue later. */
+  async function savePlaybackPosition(bookId: number, seconds: number): Promise<void> {
+    const version = generation
+    const owner = ownerId()
+    const result = await session.request<{ playbackSeconds: number }>(`books/${bookId}/playback`, 'PUT', { positionSeconds: Math.max(0, Math.floor(seconds)) })
+    if (!isStale(version, owner) && book.value?.id === bookId && book.value.attachments) {
+      book.value = { ...book.value, attachments: { ...book.value.attachments, playbackSeconds: result.playbackSeconds } }
+    }
+  }
+
+  /** Object URLs handed to <img>/<audio>; the token never appears in a URL the browser sees. */
+  const coverUrls = ref<Record<number, string>>({})
+  const audioUrl = ref('')
+  const liveBlobUrls = new Set<string>()
+  const loadedVersions = new Map<string, string>()
+
+  function rememberBlob(blob: Blob): string {
+    const url = URL.createObjectURL(blob)
+    liveBlobUrls.add(url)
+    return url
+  }
+
+  function releaseBlobs(): void {
+    for (const url of liveBlobUrls) URL.revokeObjectURL(url)
+    liveBlobUrls.clear()
+    loadedVersions.clear()
+    coverUrls.value = {}
+    audioUrl.value = ''
+  }
+
+  /** Loads a cover for the library list, once per version. */
+  async function loadCover(bookId: number, version: string): Promise<void> {
+    if (!version || loadedVersions.get(`cover:${bookId}`) === version) return
+    try {
+      const blob = await session.requestBlob(`books/${bookId}/cover`)
+      if (!session.user) return
+      loadedVersions.set(`cover:${bookId}`, version)
+      coverUrls.value = { ...coverUrls.value, [bookId]: rememberBlob(blob) }
+    } catch {
+      // A cover that cannot be read simply keeps the default styling.
+    }
+  }
+
+  /** Loads the audio of the open book, once per version, for the player in the reader. */
+  async function loadAudio(bookId: number, version: string): Promise<void> {
+    if (!version || loadedVersions.get(`audio:${bookId}`) === version) return
+    try {
+      const blob = await session.requestBlob(`books/${bookId}/audio`)
+      if (!session.user) return
+      loadedVersions.set(`audio:${bookId}`, version)
+      audioUrl.value = rememberBlob(blob)
+    } catch (reason) {
+      throw reason instanceof Error ? reason : new Error('音频暂时无法加载。')
+    }
+  }
+
+  /** Drops one cached cover so a replaced file is fetched again. */
+  function forgetCover(bookId: number): void {
+    loadedVersions.delete(`cover:${bookId}`)
+    const url = coverUrls.value[bookId]
+    if (url) {
+      URL.revokeObjectURL(url)
+      liveBlobUrls.delete(url)
+      const next = { ...coverUrls.value }
+      delete next[bookId]
+      coverUrls.value = next
+    }
+  }
+
  /**
   * Marks one owned chapter as read. Completing only records the reading fact: word statuses and
   * levels are left alone. A repeated request answers with the same mark instead of counting
@@ -646,6 +820,8 @@ export const useLibraryStore = defineStore('library', () => {
    submitError.value = ''
    retryingChapterId.value = null
    completingChapterId.value = null
+    uploadingKind.value = null
+    releaseBlobs()
    submissionKey = ''
    submissionRequestId = ''
  }
@@ -656,6 +832,8 @@ export const useLibraryStore = defineStore('library', () => {
    chapter, chapterBook, navigation, chapterLoading, chapterError,
    submitting, submitError, retryingChapterId, completingChapterId, readerText,
    loadBooks, loadBook, loadChapter, submit, upload, retryChapter, markChapterRead,
+    uploadAttachment, deleteAttachment, savePlaybackPosition, uploadingKind,
+    coverUrls, audioUrl, loadCover, loadAudio,
    renameBook, updateChapter, loadChapterSource, deleteBook, deleteChapter,
    stopPolling, closeBook, closeChapter, reset,
  }
@@ -53,6 +53,29 @@ export const useSessionStore = defineStore('session', () => {
    return result.data as T
  }

+  /**
+   * Fetches binary content with the same session as every other request. A media element cannot
+   * carry an Authorization header, so the bytes are fetched here and handed to the page as a blob
+   * URL instead of putting the token into a URL where it could be logged or shared.
+   */
+  async function requestBlob(path: string): Promise<Blob> {
+    const response = await fetch(`/api/v1/${path}`, {
+      headers: token ? { Authorization: `Bearer ${token}` } : {},
+      cache: 'no-store',
+    })
+    if (!response.ok) {
+      let message = '附件暂时无法加载。'
+      try {
+        const result = await response.json()
+        if (result?.msg) message = result.msg
+      } catch {
+        // A non-JSON error body keeps the default message.
+      }
+      throw new ApiError(message, response.status)
+    }
+    return response.blob()
+  }
+
  async function login(username: string, password: string) {
    clear()
    initialized = true
@@ -104,5 +127,5 @@ export const useSessionStore = defineStore('session', () => {
    if (previousToken) await request<null>('logout', 'POST', undefined, previousToken, -1)
  }

-  return { user, space, notice, login, restore, logout, loadSpace, request }
+  return { user, space, notice, login, restore, logout, loadSpace, request, requestBlob }
 })
@@ -345,3 +345,31 @@ button:focus-visible, a:focus-visible, [role='button']:focus-visible,

 /* Discoverable keyboard operations on the review page. */
 .shortcut-hint { margin: 22px 0 0; color: var(--text-muted); font-size: 13px; }
+
+/* Book covers: the card shows the stored image or a default block built from the title. */
+.book-cover { display: block; aspect-ratio: 16 / 9; border-radius: 10px; overflow: hidden; background: var(--accent-soft); text-decoration: none; }
+.book-cover img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.book-cover-default { display: grid; place-items: center; width: 100%; height: 100%; font-family: Georgia, serif; font-size: 40px; color: var(--accent); }
+/* Book attachments: metadata, preview and the upload controls. */
+.attachments { margin-top: 26px; padding: 22px; border: 1px solid var(--border); border-radius: 12px; background: var(--surface); }
+.attachments h2 { margin: 0 0 16px; font-size: 19px; }
+.attachment-row { display: flex; gap: 18px; align-items: flex-start; padding: 14px 0; border-top: 1px solid var(--border); }
+.attachment-row:first-of-type { border-top: 0; padding-top: 0; }
+.attachment-preview { flex: 0 0 160px; aspect-ratio: 16 / 9; border-radius: 8px; overflow: hidden; background: var(--accent-soft); }
+.attachment-preview img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.attachment-info { min-width: 0; flex: 1; }
+.attachment-label { margin: 0 0 4px; font-weight: 600; }
+.attachment-info .subtle { margin: 4px 0 0; }
+.attachment-actions { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; margin: 10px 0 0; }
+.attachment-actions input[type='file'] { position: absolute; width: 1px; height: 1px; opacity: 0; overflow: hidden; }
+.attachment-actions label { position: relative; cursor: pointer; border: 1px solid var(--border-strong); border-radius: 20px; padding: 0 14px; background: var(--surface-raised); }
+.attachment-actions label.is-busy { opacity: 0.6; cursor: progress; }
+/* Audio player: sticky so the controls stay reachable while the chapter is read. */
+.audio-player { position: sticky; top: 0; z-index: 5; display: flex; align-items: center; gap: 14px; flex-wrap: wrap; margin-bottom: 18px; padding: 12px 16px; border: 1px solid var(--border); border-radius: 12px; background: var(--surface); box-shadow: 0 2px 10px #233d3114; }
+.audio-clock { font-size: 13px; color: var(--text-muted); font-variant-numeric: tabular-nums; }
+.audio-range { flex: 1 1 160px; min-width: 120px; accent-color: var(--accent); }
+.audio-rates { display: flex; gap: 4px; }
+.audio-rate { min-width: 44px; min-height: 32px; border: 1px solid var(--border-strong); border-radius: 16px; background: var(--surface-raised); color: var(--text); font-size: 12px; cursor: pointer; }
+.audio-rate.is-active { border-color: var(--accent); color: var(--accent); font-weight: 600; }
+.audio-error { display: inline-flex; align-items: center; gap: 6px; color: var(--notice-text); font-size: 13px; }
+.audio-player audio { display: none; }
@@ -2,7 +2,7 @@
 import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
 import { RouterLink, useRoute, useRouter } from 'vue-router'
 import { ElButton, ElDialog, ElInput, ElMessageBox } from 'element-plus'
-import { canRetry, statusLabel, TEXT_MAX_CODE_POINTS, textProblem, titleProblem, useLibraryStore, type ChapterSource } from '../stores/library'
+import { canRetry, fileSizeLabel, statusLabel, TEXT_MAX_CODE_POINTS, textProblem, titleProblem, useLibraryStore, type ChapterSource } from '../stores/library'
 import { useSessionStore } from '../stores/session'
 import DisplaySettings from '../components/DisplaySettings.vue'

@@ -12,6 +12,85 @@ const route = useRoute()
 const router = useRouter()
 const retryError = ref('')
 const notice = ref('')
+const attachmentError = ref<{ cover: string; audio: string }>({ cover: '', audio: '' })
+
+const ATTACHMENT_RULES = {
+  cover: { types: ['image/jpeg', 'image/png', 'image/webp'], maxBytes: 2 << 20, label: '封面只支持 JPG、PNG 或 WebP 图片，且不超过 2 MiB。' },
+  audio: { types: ['audio/mpeg'], maxBytes: 20 << 20, label: '音频只支持 MP3，且不超过 20 MiB。' },
+} as const
+
+const coverState = computed(() => {
+  const cover = library.book?.attachments?.cover
+  if (!cover) return '未设置（显示默认封面）'
+  return `${cover.mime === 'image/png' ? 'PNG' : cover.mime === 'image/webp' ? 'WebP' : 'JPG'} · ${fileSizeLabel(cover.byteSize)}`
+})
+
+const audioState = computed(() => {
+  const audio = library.book?.attachments?.audio
+  if (!audio) return '未设置（阅读时可正常使用）'
+  const position = library.book?.attachments?.playbackSeconds ?? 0
+  const detail = `${fileSizeLabel(audio.byteSize)}${position > 0 ? ` · 上次播放位置 ${Math.floor(position / 60)}:${String(position % 60).padStart(2, '0')}` : ''}`
+  return `MP3 · ${detail}`
+})
+
+/** The browser reports a type, but the server checks the bytes: this only avoids an obvious mistake. */
+function reject(kind: 'cover' | 'audio', file: File): string {
+  const rules = ATTACHMENT_RULES[kind]
+  if (file.size === 0) return '文件为空，请重新选择。'
+  if (file.size > rules.maxBytes) return rules.label
+  if (file.type && !(rules.types as readonly string[]).includes(file.type)) return rules.label
+  return ''
+}
+
+async function upload(kind: 'cover' | 'audio', file: File): Promise<void> {
+  if (library.book === null) return
+  attachmentError.value = { ...attachmentError.value, [kind]: '' }
+  const problem = reject(kind, file)
+  if (problem) {
+    attachmentError.value = { ...attachmentError.value, [kind]: problem }
+    return
+  }
+  try {
+    await library.uploadAttachment(library.book.id, kind, file)
+    notice.value = kind === 'cover' ? '封面已更新。' : '音频已更新，播放位置已重置。'
+  } catch (reason) {
+    attachmentError.value = { ...attachmentError.value, [kind]: reason instanceof Error ? reason.message : '上传失败，请稍后重试。' }
+  }
+}
+
+function onCoverPicked(event: Event): void {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (file) void upload('cover', file)
+}
+
+function onAudioPicked(event: Event): void {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (file) void upload('audio', file)
+}
+
+async function removeAttachment(kind: 'cover' | 'audio'): Promise<void> {
+  if (library.book === null) return
+  const question = kind === 'cover' ? '移除这本书的封面？' : '移除这本书的音频？播放位置会一起清除。'
+  try {
+    await ElMessageBox.confirm(question, kind === 'cover' ? '移除封面' : '移除音频', {
+      confirmButtonText: '确认移除', cancelButtonText: '取消', type: 'warning',
+    })
+  } catch { return }
+  attachmentError.value = { ...attachmentError.value, [kind]: '' }
+  try {
+    await library.deleteAttachment(library.book.id, kind)
+    notice.value = kind === 'cover' ? '封面已移除。' : '音频已移除。'
+  } catch (reason) {
+    attachmentError.value = { ...attachmentError.value, [kind]: reason instanceof Error ? reason.message : '移除失败，请稍后重试。' }
+  }
+}
+
+function removeCover(): void { void removeAttachment('cover') }
+function removeAudio(): void { void removeAttachment('audio') }

 // Renaming the book.
 const bookDialog = ref(false)
@@ -163,7 +242,7 @@ onUnmounted(() => library.closeBook())
        <div class="page-title">
          <div>
            <h1>{{ library.book.title }}</h1>
-            <p class="subtle">{{ library.chapters.length }} 个章节 · 语言 英语 · 封面使用系统默认样式</p>
+            <p class="subtle">{{ library.chapters.length }} 个章节 · 语言 英语</p>
          </div>
          <div class="page-actions">
            <ElButton data-testid="edit-book" @click="openBookDialog">编辑书名</ElButton>
@@ -172,6 +251,43 @@ onUnmounted(() => library.closeBook())
          </div>
        </div>
        <p v-if="notice" role="status" class="chapter-notice" data-testid="book-notice">{{ notice }}</p>
+        <section class="attachments" aria-label="音频与封面" data-testid="attachments">
+          <h2>音频与封面</h2>
+          <div class="attachment-row">
+            <div class="attachment-preview">
+              <img v-if="library.coverUrls[library.book.id]" :src="library.coverUrls[library.book.id]" alt="当前封面" data-testid="cover-preview" />
+              <span v-else class="book-cover-default" aria-hidden="true">{{ library.book.title.slice(0, 1) }}</span>
+            </div>
+            <div class="attachment-info">
+              <p class="attachment-label">封面</p>
+              <p class="subtle" data-testid="cover-state">{{ coverState }}</p>
+              <p v-if="attachmentError.cover" role="alert" class="field-error">{{ attachmentError.cover }}</p>
+              <div class="attachment-actions">
+                <label class="link-button" :class="{ 'is-busy': library.uploadingKind === 'cover' }">
+                  {{ library.coverUrls[library.book.id] ? '替换封面' : '上传封面' }}
+                  <input type="file" accept="image/jpeg,image/png,image/webp" data-testid="cover-input" :disabled="library.uploadingKind !== null" @change="onCoverPicked" />
+                </label>
+                <ElButton v-if="library.coverUrls[library.book.id] || library.book.attachments?.cover" size="small" :disabled="library.uploadingKind !== null" data-testid="cover-remove" @click="removeCover">移除</ElButton>
+              </div>
+              <p class="subtle">JPG、PNG 或 WebP，最大 2 MiB，像素不超过 4096×4096。</p>
+            </div>
+          </div>
+          <div class="attachment-row">
+            <div class="attachment-info">
+              <p class="attachment-label">音频</p>
+              <p class="subtle" data-testid="audio-state">{{ audioState }}</p>
+              <p v-if="attachmentError.audio" role="alert" class="field-error">{{ attachmentError.audio }}</p>
+              <div class="attachment-actions">
+                <label class="link-button" :class="{ 'is-busy': library.uploadingKind === 'audio' }">
+                  {{ library.book.attachments?.audio ? '替换音频' : '上传音频' }}
+                  <input type="file" accept="audio/mpeg,.mp3" data-testid="audio-input" :disabled="library.uploadingKind !== null" @change="onAudioPicked" />
+                </label>
+                <ElButton v-if="library.book.attachments?.audio" size="small" :disabled="library.uploadingKind !== null" data-testid="audio-remove" @click="removeAudio">移除</ElButton>
+              </div>
+              <p class="subtle">MP3，最大 20 MiB；播放不与文本同步。替换或移除后播放位置会重置。</p>
+            </div>
+          </div>
+        </section>
        <p v-if="retryError" role="alert" class="notice">{{ retryError }}</p>
        <ul v-if="library.chapters.length" class="chapter-list" aria-label="章节列表">
          <li v-for="item in library.chapters" :key="item.id" class="chapter-row">
@@ -62,6 +62,17 @@ onMounted(load)
      </div>
      <ul v-else-if="library.books.length" class="book-grid" aria-label="书籍列表">
        <li v-for="item in library.books" :key="item.id" class="book-card">
+          <!-- The cover repeats the title link, so it is hidden from assistive technology and from
+               keyboard order: the title link next to it is the accessible way into the book. -->
+          <RouterLink
+            :to="`/books/${item.id}`"
+            class="book-cover"
+            aria-hidden="true"
+            tabindex="-1"
+          >
+            <img v-if="library.coverUrls[item.id]" :src="library.coverUrls[item.id]" alt="" data-testid="book-cover" />
+            <span v-else class="book-cover-default">{{ item.title.slice(0, 1) }}</span>
+          </RouterLink>
          <RouterLink :to="`/books/${item.id}`" class="book-title">{{ item.title }}</RouterLink>
          <p class="subtle">{{ item.chapterCount }} 个章节</p>
          <p v-if="statusSummary(item)" class="status-summary">{{ statusSummary(item) }}</p>
@@ -9,6 +9,7 @@ import { adjustTokenRange, MAX_PHRASE_WORDS, normalizeTokenRange, phrasesAt, ran
 import { currentRatio, readPosition, writePosition } from '../composables/readingPosition'
 import { useTextSelection } from '../composables/useTextSelection'
 import ReaderTokens from '../components/ReaderTokens.vue'
+import AudioPlayer from '../components/AudioPlayer.vue'
 import DisplaySettings from '../components/DisplaySettings.vue'
 import LookupPanel from '../components/LookupPanel.vue'

@@ -93,6 +94,17 @@ async function load() {
  restorePosition()
 }

+// The player only exists for a book that has audio, and it reports the position for this account.
+const audioSource = computed(() => library.audioUrl)
+const audioStart = computed(() => library.chapterBook?.attachments?.playbackSeconds ?? library.book?.attachments?.playbackSeconds ?? 0)
+
+function rememberPlayback(seconds: number): void {
+  const bookId = library.chapterBook?.id
+  if (bookId === undefined) return
+  // The reported value is not awaited: leaving the page must not wait for the network.
+  void library.savePlaybackPosition(bookId, seconds).catch(() => undefined)
+}
+
 // Reading position: remembered per account and chapter, and only while the text is the version
 // the position was taken from. The restore waits for the chapter to be on screen and for the
 // browser to lay the paragraph out, otherwise the saved ratio would land in the wrong place.
@@ -223,6 +235,12 @@ onUnmounted(() => {
          <RouterLink v-if="library.chapterBook" :to="`/books/${library.chapterBook.id}`">{{ library.chapterBook.title }}</RouterLink>
          <span v-else>章节</span>
        </p>
+        <AudioPlayer
+          v-if="audioSource"
+          :src="audioSource"
+          :initial-position="audioStart"
+          :on-position="rememberPlayback"
+        />
        <div class="page-title">
          <h1>{{ chapter.title }}</h1>
          <span class="status-chip" :class="`status-${chapter.status}`">{{ statusLabel(chapter.status) }}</span>
@@ -42,6 +42,7 @@ TABLES = [
    "sys_user", "lexgo_spaces", "lexgo_sessions", "lexgo_login_logs", "lexgo_operation_logs",
    "lexgo_books", "lexgo_chapters", "lexgo_ingest_jobs", "lexgo_dictionaries",
    "lexgo_terms", "lexgo_term_reviews", "lexgo_review_answers", "lexgo_chapter_progress",
+    "lexgo_book_attachments", "lexgo_playback_positions",
 ]
 SCHEMA_VERSION = 7

@@ -470,6 +471,9 @@ def integrity_checks(database):
    add("等级只出现在学习中词条", int(scalar(database, "SELECT COUNT(*) FROM lexgo_terms WHERE (status='learning' AND (level<1 OR level>7)) OR (status<>'learning' AND level<>0)", "0") or 0) == 0)
    add("完成记录都指向存在的章节", int(scalar(database, "SELECT COUNT(*) FROM lexgo_chapter_progress p LEFT JOIN lexgo_chapters c ON c.id=p.chapter_id WHERE c.id IS NULL", "0") or 0) == 0)
    add("词条语言与所属空间一致", int(scalar(database, "SELECT COUNT(*) FROM lexgo_terms t JOIN lexgo_spaces s ON s.owner_id=t.owner_id WHERE t.language<>s.language", "0") or 0) == 0)
+    add("附件都指向存在的书", int(scalar(database, "SELECT COUNT(*) FROM lexgo_book_attachments a LEFT JOIN lexgo_books b ON b.id=a.book_id WHERE b.id IS NULL", "0") or 0) == 0)
+    add("附件归属与书归属一致", int(scalar(database, "SELECT COUNT(*) FROM lexgo_book_attachments a JOIN lexgo_books b ON b.id=a.book_id WHERE a.owner_id<>b.owner_id", "0") or 0) == 0)
+    add("播放位置都指向存在的书", int(scalar(database, "SELECT COUNT(*) FROM lexgo_playback_positions p LEFT JOIN lexgo_books b ON b.id=p.book_id WHERE b.id IS NULL", "0") or 0) == 0)

    # The audit tables must not gain a column that could hold a credential or private content.
    for table in ("lexgo_login_logs", "lexgo_operation_logs"):
@@ -0,0 +1,495 @@
+package lexgo
+
+import (
+	"bytes"
+	"encoding/binary"
+	"errors"
+	"image"
+	_ "image/jpeg" // dimension checks for covers
+	_ "image/png"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	admin "go-admin/app/admin/models"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// A book may carry one audio track and one cover image. Both live in MySQL next to everything else,
+// so a dump is still a complete backup, the owner check is the same as for any other private data,
+// and deleting a book removes its attachments with it. Nothing is written to disk: an uploaded file
+// never becomes a path, and the client file name is only used for display.
+const (
+	attachmentAudio = "audio"
+	attachmentCover = "cover"
+
+	maxAudioBytes = 20 << 20
+	maxCoverBytes = 2 << 20
+	// Covers are downscaled by the browser, so an upload larger than this is refused instead of
+	// being stored at a size nothing will ever display.
+	maxCoverPixels = 4096
+	// A playback position beyond this is treated as a client mistake rather than a real position.
+	maxPlaybackSeconds = 24 * 60 * 60
+)
+
+// BookAttachment is one binary file belonging to a book. book_id plus kind are unique, so replacing
+// a file updates one row instead of accumulating versions.
+type BookAttachment struct {
+	BookID    int64     `gorm:"primaryKey"`
+	Kind      string    `gorm:"primaryKey"`
+	OwnerID   int       `json:"-"`
+	Mime      string    `json:"mime"`
+	ByteSize  int       `json:"byteSize"`
+	SHA256    string    `json:"sha256"`
+	Bytes     []byte    `json:"-"`
+	CreatedAt time.Time `json:"createdAt"`
+	UpdatedAt time.Time `json:"updatedAt"`
+}
+
+func (BookAttachment) TableName() string { return "lexgo_book_attachments" }
+
+// PlaybackPosition remembers where one learner stopped in one book. It is separate from the
+// attachment row: the file belongs to the book, the position belongs to the reader.
+type PlaybackPosition struct {
+	OwnerID         int       `gorm:"primaryKey"`
+	BookID          int64     `gorm:"primaryKey"`
+	PositionSeconds int       `json:"positionSeconds"`
+	UpdatedAt       time.Time `json:"updatedAt"`
+}
+
+func (PlaybackPosition) TableName() string { return "lexgo_playback_positions" }
+
+// BookAttachmentView is what the client sees: metadata and a version for cache invalidation, never
+// the bytes.
+type BookAttachmentView struct {
+	Kind      string    `json:"kind"`
+	Mime      string    `json:"mime"`
+	ByteSize  int       `json:"byteSize"`
+	Version   string    `json:"version"`
+	UpdatedAt time.Time `json:"updatedAt"`
+}
+
+type BookAttachmentsView struct {
+	Cover           *BookAttachmentView `json:"cover"`
+	Audio           *BookAttachmentView `json:"audio"`
+	PlaybackSeconds int                 `json:"playbackSeconds"`
+}
+
+// sniffAttachment checks the actual bytes instead of trusting a file name or a declared type.
+func sniffAttachment(kind string, data []byte) (string, error) {
+	switch kind {
+	case attachmentAudio:
+		if isMP3(data) {
+			return "audio/mpeg", nil
+		}
+		return "", failure(400, "只支持 MP3 音频，请转换为 MP3 后重试")
+	case attachmentCover:
+		mime := sniffImage(data)
+		if mime == "" {
+			return "", failure(400, "封面只支持 JPG、PNG 或 WebP 图片")
+		}
+		return mime, nil
+	}
+	return "", failure(400, "附件类型无效")
+}
+
+// isMP3 accepts both an ID3-tagged file and a bare frame: "ID3" or a frame sync of 11 bits.
+func isMP3(data []byte) bool {
+	if len(data) < 4 {
+		return false
+	}
+	if bytes.HasPrefix(data, []byte("ID3")) {
+		return true
+	}
+	return data[0] == 0xFF && data[1]&0xE0 == 0xE0
+}
+
+func sniffImage(data []byte) string {
+	switch {
+	case bytes.HasPrefix(data, []byte{0xFF, 0xD8, 0xFF}):
+		return "image/jpeg"
+	case bytes.HasPrefix(data, []byte{0x89, 'P', 'N', 'G', 0x0D, 0x0A, 0x1A, 0x0A}):
+		return "image/png"
+	case len(data) >= 12 && bytes.HasPrefix(data, []byte("RIFF")) && bytes.Equal(data[8:12], []byte("WEBP")):
+		return "image/webp"
+	}
+	return ""
+}
+
+// coverDimensions returns the pixel size of a supported image. JPEG and PNG are decoded by the
+// standard library; WebP is read from its own header because no decoder is imported for it.
+func coverDimensions(mime string, data []byte) (int, int, bool) {
+	if mime == "image/webp" {
+		return webpDimensions(data)
+	}
+	config, _, err := image.DecodeConfig(bytes.NewReader(data))
+	if err != nil {
+		return 0, 0, false
+	}
+	return config.Width, config.Height, true
+}
+
+func webpDimensions(data []byte) (int, int, bool) {
+	if len(data) < 30 {
+		return 0, 0, false
+	}
+	chunk := string(data[12:16])
+	switch chunk {
+	case "VP8X":
+		width := int(data[24]) | int(data[25])<<8 | int(data[26])<<16
+		height := int(data[27]) | int(data[28])<<8 | int(data[29])<<16
+		return width + 1, height + 1, true
+	case "VP8 ":
+		// The frame header starts after the 10-byte chunk header; the 14-bit dimensions sit 6 bytes in.
+		if len(data) < 30 {
+			return 0, 0, false
+		}
+		width := int(binary.LittleEndian.Uint16(data[26:28]) & 0x3FFF)
+		height := int(binary.LittleEndian.Uint16(data[28:30]) & 0x3FFF)
+		return width, height, width > 0 && height > 0
+	case "VP8L":
+		if len(data) < 25 {
+			return 0, 0, false
+		}
+		bits := binary.LittleEndian.Uint32(data[21:25])
+		width := int(bits&0x3FFF) + 1
+		height := int((bits>>14)&0x3FFF) + 1
+		return width, height, true
+	}
+	return 0, 0, false
+}
+
+// validateAttachment enforces the size, type and pixel limits before anything is stored.
+func validateAttachment(kind string, data []byte) (string, error) {
+	switch kind {
+	case attachmentAudio:
+		if len(data) == 0 {
+			return "", failure(400, "音频文件为空")
+		}
+		if len(data) > maxAudioBytes {
+			return "", failure(400, "音频文件不能超过 20 MiB")
+		}
+	case attachmentCover:
+		if len(data) == 0 {
+			return "", failure(400, "封面图片为空")
+		}
+		if len(data) > maxCoverBytes {
+			return "", failure(400, "封面图片不能超过 2 MiB")
+		}
+	default:
+		return "", failure(400, "附件类型无效")
+	}
+	mime, err := sniffAttachment(kind, data)
+	if err != nil {
+		return "", err
+	}
+	if kind == attachmentCover {
+		width, height, ok := coverDimensions(mime, data)
+		if !ok {
+			return "", failure(400, "无法识别该图片，请换一张 JPG、PNG 或 WebP")
+		}
+		if width > maxCoverPixels || height > maxCoverPixels {
+			return "", failure(400, "封面图片不能超过 4096×4096 像素")
+		}
+	}
+	return mime, nil
+}
+
+// readAttachmentUpload reads a single "file" part plus no other fields, with the byte limit applied
+// to the request body itself so an oversized upload is rejected while it is still arriving.
+func readAttachmentUpload(c *gin.Context, limit int64) ([]byte, error) {
+	bad := failure(400, "请选择一个文件后重试")
+	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, limit+(64<<10))
+	reader, err := c.Request.MultipartReader()
+	if err != nil {
+		return nil, bad
+	}
+	var content []byte
+	for {
+		part, err := reader.NextPart()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			if tooLarge(err) {
+				return nil, failure(413, "文件超过允许的大小")
+			}
+			return nil, bad
+		}
+		if part.FormName() != "file" {
+			part.Close()
+			return nil, bad
+		}
+		if content != nil {
+			part.Close()
+			return nil, bad
+		}
+		content, err = readPart(part, limit)
+		part.Close()
+		if err != nil {
+			return nil, err
+		}
+	}
+	if content == nil {
+		return nil, bad
+	}
+	return content, nil
+}
+
+func readPart(part *multipart.Part, limit int64) ([]byte, error) {
+	content, err := io.ReadAll(io.LimitReader(part, limit+1))
+	if err != nil {
+		if tooLarge(err) {
+			return nil, failure(413, "文件超过允许的大小")
+		}
+		return nil, failure(400, "文件读取失败，请重试")
+	}
+	if len(content) == 0 {
+		return nil, failure(400, "文件为空")
+	}
+	if int64(len(content)) > limit {
+		return nil, failure(413, "文件超过允许的大小")
+	}
+	return content, nil
+}
+
+func tooLarge(err error) bool {
+	var maxErr *http.MaxBytesError
+	return errors.As(err, &maxErr) || strings.Contains(err.Error(), "http: request body too large")
+}
+
+// SaveAttachment validates and stores one file for a book the caller owns. A replacement updates the
+// same row only after the new file passed every check, so a rejected upload leaves the old one in
+// place.
+func SaveAttachment(tx *gorm.DB, owner int, bookID int64, kind string, data []byte, now time.Time) (BookAttachmentView, error) {
+	if kind != attachmentAudio && kind != attachmentCover {
+		return BookAttachmentView{}, failure(404, "附件不存在")
+	}
+	if err := lockOwnedBook(tx, owner, bookID, &Book{}); err != nil {
+		return BookAttachmentView{}, err
+	}
+	mime, err := validateAttachment(kind, data)
+	if err != nil {
+		return BookAttachmentView{}, err
+	}
+	ts := stamp(now)
+	row := BookAttachment{BookID: bookID, Kind: kind, OwnerID: owner, Mime: mime,
+		ByteSize: len(data), SHA256: contentSHA(string(data)), Bytes: data, CreatedAt: ts, UpdatedAt: ts}
+	// The identity stays (book_id, kind); the file and its metadata move forward together.
+	if err = tx.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "book_id"}, {Name: "kind"}},
+		DoUpdates: clause.AssignmentColumns([]string{"owner_id", "mime", "byte_size", "sha256", "bytes", "updated_at"}),
+	}).Create(&row).Error; err != nil {
+		return BookAttachmentView{}, err
+	}
+	if kind == attachmentAudio {
+		// A new file has nothing to do with the old position, so any stored position is dropped.
+		if err = tx.Where("owner_id = ? AND book_id = ?", owner, bookID).Delete(&PlaybackPosition{}).Error; err != nil {
+			return BookAttachmentView{}, err
+		}
+	}
+	return attachmentView(row), nil
+}
+
+func attachmentView(row BookAttachment) BookAttachmentView {
+	return BookAttachmentView{Kind: row.Kind, Mime: row.Mime, ByteSize: row.ByteSize,
+		Version: row.SHA256, UpdatedAt: row.UpdatedAt}
+}
+
+// DeleteAttachment removes one file, and an audio removal also drops the stored position.
+func DeleteAttachment(tx *gorm.DB, owner int, bookID int64, kind string, now time.Time) error {
+	if kind != attachmentAudio && kind != attachmentCover {
+		return failure(404, "附件不存在")
+	}
+	if err := lockOwnedBook(tx, owner, bookID, &Book{}); err != nil {
+		return err
+	}
+	result := tx.Where("book_id = ? AND owner_id = ? AND kind = ?", bookID, owner, kind).Delete(&BookAttachment{})
+	if result.Error != nil {
+		return result.Error
+	}
+	if result.RowsAffected == 0 {
+		return failure(404, "附件不存在")
+	}
+	if kind == attachmentAudio {
+		return tx.Where("owner_id = ? AND book_id = ?", owner, bookID).Delete(&PlaybackPosition{}).Error
+	}
+	return nil
+}
+
+// BookAttachmentFile returns one stored file for the caller's own book.
+func BookAttachmentFile(tx *gorm.DB, owner int, bookID int64, kind string) (BookAttachment, error) {
+	var row BookAttachment
+	err := tx.Where("book_id = ? AND owner_id = ? AND kind = ?", bookID, owner, kind).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return BookAttachment{}, failure(404, "附件不存在")
+	}
+	return row, err
+}
+
+// attachmentsByBook loads the attachment metadata for a list of books, so a book list can show
+// covers without a query per row.
+func attachmentsByBook(tx *gorm.DB, owner int, bookIDs []int64) (map[int64]map[string]BookAttachmentView, error) {
+	found := map[int64]map[string]BookAttachmentView{}
+	if len(bookIDs) == 0 {
+		return found, nil
+	}
+	var rows []BookAttachment
+	if err := tx.Select("book_id", "kind", "mime", "byte_size", "sha256", "updated_at").
+		Where("owner_id = ? AND book_id IN ?", owner, bookIDs).Find(&rows).Error; err != nil {
+		return found, err
+	}
+	for _, row := range rows {
+		if found[row.BookID] == nil {
+			found[row.BookID] = map[string]BookAttachmentView{}
+		}
+		found[row.BookID][row.Kind] = attachmentView(row)
+	}
+	return found, nil
+}
+
+func playbackSeconds(tx *gorm.DB, owner int, bookIDs []int64) (map[int64]int, error) {
+	positions := map[int64]int{}
+	if len(bookIDs) == 0 {
+		return positions, nil
+	}
+	var rows []PlaybackPosition
+	if err := tx.Where("owner_id = ? AND book_id IN ?", owner, bookIDs).Find(&rows).Error; err != nil {
+		return positions, err
+	}
+	for _, row := range rows {
+		positions[row.BookID] = row.PositionSeconds
+	}
+	return positions, nil
+}
+
+// BookAttachmentsFor is the view the book page uses.
+func BookAttachmentsFor(tx *gorm.DB, owner int, bookID int64) (BookAttachmentsView, error) {
+	view := BookAttachmentsView{}
+	found, err := attachmentsByBook(tx, owner, []int64{bookID})
+	if err != nil {
+		return view, err
+	}
+	if cover, ok := found[bookID][attachmentCover]; ok {
+		view.Cover = &cover
+	}
+	if audio, ok := found[bookID][attachmentAudio]; ok {
+		view.Audio = &audio
+	}
+	positions, err := playbackSeconds(tx, owner, []int64{bookID})
+	if err != nil {
+		return view, err
+	}
+	view.PlaybackSeconds = positions[bookID]
+	return view, nil
+}
+
+// SavePlaybackPosition remembers where the learner stopped. Only the caller's own position moves.
+func SavePlaybackPosition(tx *gorm.DB, owner int, bookID int64, seconds int, now time.Time) (int, error) {
+	if seconds < 0 || seconds > maxPlaybackSeconds {
+		return 0, failure(400, "播放位置无效")
+	}
+	if err := lockOwnedBook(tx, owner, bookID, &Book{}); err != nil {
+		return 0, err
+	}
+	var audio int64
+	if err := tx.Model(&BookAttachment{}).Where("book_id = ? AND kind = ?", bookID, attachmentAudio).Count(&audio).Error; err != nil {
+		return 0, err
+	}
+	if audio == 0 {
+		return 0, failure(404, "这本书没有音频")
+	}
+	ts := stamp(now)
+	row := PlaybackPosition{OwnerID: owner, BookID: bookID, PositionSeconds: seconds, UpdatedAt: ts}
+	if err := tx.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "owner_id"}, {Name: "book_id"}},
+		DoUpdates: clause.AssignmentColumns([]string{"position_seconds", "updated_at"}),
+	}).Create(&row).Error; err != nil {
+		return 0, err
+	}
+	return seconds, nil
+}
+
+func registerAttachmentRoutes(v *gin.RouterGroup, protect func(bool, func(*gin.Context, *gorm.DB, admin.SysUser) (any, error)) gin.HandlerFunc, now func() time.Time) {
+	upload := func(kind string, limit int64) gin.HandlerFunc {
+		return protect(false, func(c *gin.Context, tx *gorm.DB, u admin.SysUser) (any, error) {
+			if len(c.Request.URL.Query()) > 0 {
+				return nil, failure(400, "附件上传不接受查询参数")
+			}
+			id, err := pathID(c, "书籍不存在")
+			if err != nil {
+				return nil, err
+			}
+			data, err := readAttachmentUpload(c, limit)
+			if err != nil {
+				return nil, err
+			}
+			view, err := SaveAttachment(tx, u.UserId, id, kind, data, now())
+			if err != nil {
+				return nil, err
+			}
+			return gin.H{"attachment": view}, nil
+		})
+	}
+	v.POST("/books/:id/audio", upload(attachmentAudio, maxAudioBytes))
+	v.POST("/books/:id/cover", upload(attachmentCover, maxCoverBytes))
+	v.DELETE("/books/:id/audio", protect(false, func(c *gin.Context, tx *gorm.DB, u admin.SysUser) (any, error) {
+		id, err := pathID(c, "书籍不存在")
+		if err != nil {
+			return nil, err
+		}
+		if err = DeleteAttachment(tx, u.UserId, id, attachmentAudio, now()); err != nil {
+			return nil, err
+		}
+		return gin.H{"deleted": true}, nil
+	}))
+	v.DELETE("/books/:id/cover", protect(false, func(c *gin.Context, tx *gorm.DB, u admin.SysUser) (any, error) {
+		id, err := pathID(c, "书籍不存在")
+		if err != nil {
+			return nil, err
+		}
+		if err = DeleteAttachment(tx, u.UserId, id, attachmentCover, now()); err != nil {
+			return nil, err
+		}
+		return gin.H{"deleted": true}, nil
+	}))
+	for kind, name := range map[string]string{attachmentAudio: "audio", attachmentCover: "cover"} {
+		attachmentKind, fileName := kind, name
+		v.GET("/books/:id/"+fileName, protect(false, func(c *gin.Context, tx *gorm.DB, u admin.SysUser) (any, error) {
+			id, err := pathID(c, "书籍不存在")
+			if err != nil {
+				return nil, err
+			}
+			row, err := BookAttachmentFile(tx, u.UserId, id, attachmentKind)
+			if err != nil {
+				return nil, err
+			}
+			return binaryResponse{ContentType: row.Mime, Bytes: row.Bytes, FileName: fileName,
+				ModifiedAt: row.UpdatedAt, ETag: `"` + row.SHA256 + `"`}, nil
+		}))
+	}
+	v.PUT("/books/:id/playback", protect(false, func(c *gin.Context, tx *gorm.DB, u admin.SysUser) (any, error) {
+		id, err := pathID(c, "书籍不存在")
+		if err != nil {
+			return nil, err
+		}
+		var input struct {
+			PositionSeconds *int `json:"positionSeconds"`
+		}
+		if err = decode(c, &input); err != nil {
+			return nil, err
+		}
+		if input.PositionSeconds == nil {
+			return nil, failure(400, "请提供播放位置")
+		}
+		seconds, err := SavePlaybackPosition(tx, u.UserId, id, *input.PositionSeconds, now())
+		if err != nil {
+			return nil, err
+		}
+		return gin.H{"playbackSeconds": seconds}, nil
+	}))
+}
@@ -0,0 +1,459 @@
+package lexgo
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"image/png"
+	"mime/multipart"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ---------------------------------------------------------------- unit rules
+
+func testPNG(t *testing.T, width, height int) []byte {
+	t.Helper()
+	canvas := image.NewRGBA(image.Rect(0, 0, width, height))
+	canvas.Set(0, 0, color.RGBA{R: 10, G: 20, B: 30, A: 255})
+	var buffer bytes.Buffer
+	if err := png.Encode(&buffer, canvas); err != nil {
+		t.Fatal(err)
+	}
+	return buffer.Bytes()
+}
+
+func testJPEG(t *testing.T, width, height int) []byte {
+	t.Helper()
+	canvas := image.NewRGBA(image.Rect(0, 0, width, height))
+	canvas.Set(0, 0, color.RGBA{R: 200, G: 100, B: 50, A: 255})
+	var buffer bytes.Buffer
+	if err := jpeg.Encode(&buffer, canvas, nil); err != nil {
+		t.Fatal(err)
+	}
+	return buffer.Bytes()
+}
+
+// testWebP builds the smallest possible VP8X header: the sniffing and dimension code reads the
+// container header, and no decoder is needed for that.
+func testWebP(width, height int) []byte {
+	data := make([]byte, 30)
+	copy(data[0:4], "RIFF")
+	copy(data[8:12], "WEBP")
+	copy(data[12:16], "VP8X")
+	// The stored value is size-1, little endian, three bytes each.
+	w, h := width-1, height-1
+	data[24], data[25], data[26] = byte(w), byte(w>>8), byte(w>>16)
+	data[27], data[28], data[29] = byte(h), byte(h>>8), byte(h>>16)
+	return data
+}
+
+func testMP3(payload int) []byte {
+	data := make([]byte, 4+payload)
+	copy(data, "ID3")
+	for i := 4; i < len(data); i++ {
+		data[i] = byte(i % 251)
+	}
+	return data
+}
+
+func TestAttachmentTypeSniffing(t *testing.T) {
+	cases := []struct {
+		name string
+		kind string
+		data []byte
+		mime string
+		ok   bool
+	}{
+		{"id3 audio", attachmentAudio, testMP3(64), "audio/mpeg", true},
+		{"bare frame", attachmentAudio, []byte{0xFF, 0xFB, 0x90, 0x00}, "audio/mpeg", true},
+		{"wav is not mp3", attachmentAudio, append([]byte("RIFF"), make([]byte, 40)...), "", false},
+		{"text renamed", attachmentAudio, []byte("this is not audio at all.........."), "", false},
+		{"png cover", attachmentCover, testPNG(t, 8, 8), "image/png", true},
+		{"jpeg cover", attachmentCover, testJPEG(t, 8, 8), "image/jpeg", true},
+		{"webp cover", attachmentCover, testWebP(8, 8), "image/webp", true},
+		{"gif is not accepted", attachmentCover, []byte("GIF89a"), "", false},
+		{"svg is not accepted", attachmentCover, []byte(`<svg xmlns="http://www.w3.org/2000/svg"></svg>`), "", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			mime, err := sniffAttachment(tc.kind, tc.data)
+			if tc.ok && (err != nil || mime != tc.mime) {
+				t.Fatalf("got %q %v, want %q", mime, err, tc.mime)
+			}
+			if !tc.ok && err == nil {
+				t.Fatalf("expected a rejection, got %q", mime)
+			}
+		})
+	}
+}
+
+func TestAttachmentLimits(t *testing.T) {
+	if _, err := validateAttachment(attachmentAudio, make([]byte, maxAudioBytes+1)); err == nil {
+		t.Fatal("an oversized audio file must be refused")
+	}
+	if _, err := validateAttachment(attachmentCover, make([]byte, maxCoverBytes+1)); err == nil {
+		t.Fatal("an oversized cover must be refused")
+	}
+	if _, err := validateAttachment(attachmentAudio, nil); err == nil {
+		t.Fatal("an empty file must be refused")
+	}
+	// A cover wider than the pixel limit is refused even though its bytes are small.
+	wide := testPNG(t, maxCoverPixels+1, 4)
+	if len(wide) > maxCoverBytes {
+		t.Skip("the generated image is larger than the byte limit; the pixel rule is covered below")
+	}
+	if _, err := validateAttachment(attachmentCover, wide); err == nil {
+		t.Fatal("a cover above the pixel limit must be refused")
+	}
+	// A JPEG inside the limit is accepted, one above it is refused.
+	inside := testJPEG(t, 4000, 20)
+	if len(inside) > maxCoverBytes {
+		t.Skip("the generated JPEG is larger than the byte limit")
+	}
+	if _, err := validateAttachment(attachmentCover, inside); err != nil {
+		t.Fatalf("a 4000 pixel wide cover is inside the limit: %v", err)
+	}
+	tooWide := testJPEG(t, maxCoverPixels+1, 8)
+	if len(tooWide) <= maxCoverBytes {
+		if _, err := validateAttachment(attachmentCover, tooWide); err == nil {
+			t.Fatal("a cover wider than the pixel limit must be refused")
+		}
+	}
+	if _, err := validateAttachment("other", testPNG(t, 8, 8)); err == nil {
+		t.Fatal("an unknown kind must be refused")
+	}
+}
+
+func TestWebPDimensions(t *testing.T) {
+	width, height, ok := webpDimensions(testWebP(320, 200))
+	if !ok || width != 320 || height != 200 {
+		t.Fatalf("VP8X parsed as %dx%d (%v)", width, height, ok)
+	}
+	if _, _, ok = webpDimensions([]byte("RIFF____WEBP nothing here")); ok {
+		t.Fatal("an unknown chunk must not parse")
+	}
+	if _, _, ok = webpDimensions(testPNG(t, 8, 8)); ok {
+		t.Fatal("a PNG must not be read as WebP")
+	}
+}
+
+func TestPlaybackPositionBounds(t *testing.T) {
+	// The bound is checked before any database work, so a nil transaction is fine here.
+	if _, err := SavePlaybackPosition(nil, 1, 1, -1, time.Now()); err == nil {
+		t.Fatal("a negative position must be refused")
+	}
+	if _, err := SavePlaybackPosition(nil, 1, 1, maxPlaybackSeconds+1, time.Now()); err == nil {
+		t.Fatal("an absurd position must be refused")
+	}
+}
+
+// ---------------------------------------------------------------- integration
+
+// uploadAttachment posts one multipart file to an attachment endpoint.
+func uploadAttachment(t *testing.T, r *gin.Engine, token string, path string, data []byte) (int, string, BookAttachmentView) {
+	t.Helper()
+	var body bytes.Buffer
+	writer := multipart.NewWriter(&body)
+	part, err := writer.CreateFormFile("file", "fictional-upload.bin")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err = part.Write(data); err != nil {
+		t.Fatal(err)
+	}
+	if err = writer.Close(); err != nil {
+		t.Fatal(err)
+	}
+	request := httptest.NewRequest("POST", path, bytes.NewReader(body.Bytes()))
+	request.Header.Set("Content-Type", writer.FormDataContentType())
+	if token != "" {
+		request.Header.Set("Authorization", "Bearer "+token)
+	}
+	recorder := httptest.NewRecorder()
+	r.ServeHTTP(recorder, request)
+	var envelope struct {
+		Code int `json:"code"`
+		Msg  string
+		Data struct {
+			Attachment BookAttachmentView
+		}
+	}
+	if err := json.Unmarshal(recorder.Body.Bytes(), &envelope); err != nil {
+		t.Fatalf("invalid JSON from %s (status %d): %s", path, recorder.Code, recorder.Body.String()[:min(120, recorder.Body.Len())])
+	}
+	return recorder.Code, envelope.Msg, envelope.Data.Attachment
+}
+
+// fetchRaw reads a binary endpoint without decoding the JSON envelope.
+func fetchRaw(t *testing.T, r *gin.Engine, token, path string, headers map[string]string) *httptest.ResponseRecorder {
+	t.Helper()
+	request := httptest.NewRequest("GET", path, nil)
+	if token != "" {
+		request.Header.Set("Authorization", "Bearer "+token)
+	}
+	for key, value := range headers {
+		request.Header.Set(key, value)
+	}
+	recorder := httptest.NewRecorder()
+	r.ServeHTTP(recorder, request)
+	return recorder
+}
+
+func min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+func bookDetailOf(t *testing.T, r *gin.Engine, token string, bookID int64) (BookRef, []ChapterSummary) {
+	t.Helper()
+	code, _, data := callRaw(t, r, "GET", fmt.Sprintf("/api/v1/books/%d", bookID), token, nil)
+	if code != 200 {
+		t.Fatalf("book detail status %d", code)
+	}
+	var payload struct {
+		Book     BookRef
+		Chapters []ChapterSummary
+	}
+	if err := json.Unmarshal(data, &payload); err != nil {
+		t.Fatal(err)
+	}
+	return payload.Book, payload.Chapters
+}
+
+// TestMySQLBookAttachmentsAndPlayback covers upload, authenticated Range reads, replacement,
+// position handling, ownership and cascade deletion.
+func TestMySQLBookAttachmentsAndPlayback(t *testing.T) {
+	db, r, owner := libraryFixture(t)
+	learner := newLearner(t, r, owner.Token)
+	other := newLearner(t, r, owner.Token)
+	code, pasted := pasteBook(t, r, learner.Token, map[string]string{
+		"requestId": "attach-0001", "title": "Fictional attachments", "text": "Curiosity opens the first door.\n", "language": "en"})
+	if code != 201 {
+		t.Fatalf("paste %d", code)
+	}
+	drainIngest(t, db)
+	bookID := pasted.Chapter.BookID
+
+	// A book without attachments reports neither a cover nor audio.
+	book, _ := bookDetailOf(t, r, learner.Token, bookID)
+	if book.Attachments == nil || book.Attachments.Cover != nil || book.Attachments.Audio != nil || book.Attachments.PlaybackSeconds != 0 {
+		t.Fatalf("a new book must have no attachments: %+v", book.Attachments)
+	}
+	if recorder := fetchRaw(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/audio", bookID), nil); recorder.Code != 404 {
+		t.Fatalf("reading a missing audio must be 404, got %d", recorder.Code)
+	}
+
+	// A cover upload stores the bytes and is visible in the list as a version.
+	cover := testPNG(t, 40, 25)
+	code, msg, coverView := uploadAttachment(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/cover", bookID), cover)
+	if code != 200 || coverView.Kind != attachmentCover || coverView.Mime != "image/png" || coverView.ByteSize != len(cover) {
+		t.Fatalf("cover upload: %d %s %+v", code, msg, coverView)
+	}
+	if coverView.Version != contentSHA(string(cover)) {
+		t.Fatal("the cover version must be the content digest")
+	}
+	code, _, listed := callRaw(t, r, "GET", "/api/v1/books", learner.Token, nil)
+	if code != 200 {
+		t.Fatalf("book list %d", code)
+	}
+	var page struct {
+		Items []BookSummary
+	}
+	if err := json.Unmarshal(listed, &page); err != nil {
+		t.Fatal(err)
+	}
+	if len(page.Items) != 1 || page.Items[0].CoverVersion != coverView.Version || page.Items[0].HasAudio {
+		t.Fatalf("book list attachments: %+v", page.Items)
+	}
+
+	// The cover is served with its own content type and can be cached by version.
+	recorder := fetchRaw(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/cover", bookID), nil)
+	if recorder.Code != 200 || recorder.Header().Get("Content-Type") != "image/png" || !bytes.Equal(recorder.Body.Bytes(), cover) {
+		t.Fatalf("cover read: %d %s", recorder.Code, recorder.Header().Get("Content-Type"))
+	}
+	etag := recorder.Header().Get("ETag")
+	if etag == "" {
+		t.Fatal("the cover must carry an ETag")
+	}
+	if recorder = fetchRaw(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/cover", bookID), map[string]string{"If-None-Match": etag}); recorder.Code != 304 {
+		t.Fatalf("a matching ETag must answer 304, got %d", recorder.Code)
+	}
+
+	// An audio upload is readable in full and by Range, which is what the player needs.
+	audio := testMP3(4096)
+	code, msg, audioView := uploadAttachment(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/audio", bookID), audio)
+	if code != 200 || audioView.Kind != attachmentAudio || audioView.Mime != "audio/mpeg" {
+		t.Fatalf("audio upload: %d %s %+v", code, msg, audioView)
+	}
+	book, _ = bookDetailOf(t, r, learner.Token, bookID)
+	if book.Attachments.Audio == nil || book.Attachments.Audio.ByteSize != len(audio) {
+		t.Fatalf("book detail audio: %+v", book.Attachments)
+	}
+	recorder = fetchRaw(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/audio", bookID), nil)
+	if recorder.Code != 200 || !bytes.Equal(recorder.Body.Bytes(), audio) || recorder.Header().Get("Accept-Ranges") == "" {
+		t.Fatalf("audio read: %d ranges=%q bytes=%d", recorder.Code, recorder.Header().Get("Accept-Ranges"), recorder.Body.Len())
+	}
+	recorder = fetchRaw(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/audio", bookID), map[string]string{"Range": "bytes=100-199"})
+	if recorder.Code != 206 || recorder.Body.Len() != 100 {
+		t.Fatalf("a range request must answer 206 with 100 bytes, got %d with %d", recorder.Code, recorder.Body.Len())
+	}
+	if contentRange := recorder.Header().Get("Content-Range"); contentRange == "" {
+		t.Fatal("a range answer must carry Content-Range")
+	}
+	if !bytes.Equal(recorder.Body.Bytes(), audio[100:200]) {
+		t.Fatal("the range must return the requested bytes")
+	}
+	recorder = fetchRaw(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/audio", bookID), map[string]string{"Range": "bytes=999999-"})
+	if recorder.Code != 416 {
+		t.Fatalf("an unsatisfiable range must answer 416, got %d", recorder.Code)
+	}
+
+	// Playback position: only the caller's own position moves, and it is reported with the book.
+	code, msg, _ = callRaw(t, r, "PUT", fmt.Sprintf("/api/v1/books/%d/playback", bookID), learner.Token, map[string]any{"positionSeconds": 125})
+	if code != 200 {
+		t.Fatalf("position update: %d %s", code, msg)
+	}
+	book, _ = bookDetailOf(t, r, learner.Token, bookID)
+	if book.Attachments.PlaybackSeconds != 125 {
+		t.Fatalf("playback position %d", book.Attachments.PlaybackSeconds)
+	}
+	// Another account cannot even see the book, so its position is unreachable.
+	if code, _, _ = callRaw(t, r, "GET", fmt.Sprintf("/api/v1/books/%d", bookID), other.Token, nil); code != 404 {
+		t.Fatalf("another account reading the book must be 404, got %d", code)
+	}
+	code, _, _ = callRaw(t, r, "PUT", fmt.Sprintf("/api/v1/books/%d/playback", bookID), learner.Token, map[string]any{"positionSeconds": 300})
+	if code != 200 {
+		t.Fatalf("second position update %d", code)
+	}
+	book, _ = bookDetailOf(t, r, learner.Token, bookID)
+	if book.Attachments.PlaybackSeconds != 300 {
+		t.Fatalf("the position must be replaced, got %d", book.Attachments.PlaybackSeconds)
+	}
+	if code, _, _ := callRaw(t, r, "PUT", fmt.Sprintf("/api/v1/books/%d/playback", bookID), learner.Token, map[string]any{"positionSeconds": -5}); code != 400 {
+		t.Fatal("a negative position must be refused")
+	}
+	if code, _, _ := callRaw(t, r, "PUT", fmt.Sprintf("/api/v1/books/%d/playback", bookID), learner.Token, map[string]any{}); code != 400 {
+		t.Fatal("a position request without a value must be refused")
+	}
+
+	// Replacing the audio drops the old position: the new file has nothing to do with it.
+	smaller := testMP3(2048)
+	code, msg, replaced := uploadAttachment(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/audio", bookID), smaller)
+	if code != 200 || replaced.ByteSize != len(smaller) || replaced.Version == audioView.Version {
+		t.Fatalf("audio replacement: %d %s %+v", code, msg, replaced)
+	}
+	book, _ = bookDetailOf(t, r, learner.Token, bookID)
+	if book.Attachments.PlaybackSeconds != 0 {
+		t.Fatalf("a replacement must reset the position, got %d", book.Attachments.PlaybackSeconds)
+	}
+	var rows int64
+	if err := db.Model(&BookAttachment{}).Where("book_id = ? AND kind = ?", bookID, attachmentAudio).Count(&rows).Error; err != nil || rows != 1 {
+		t.Fatalf("a replacement must keep one row: %d %v", rows, err)
+	}
+
+	// A rejected upload leaves the stored file untouched.
+	code, _, _ = uploadAttachment(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/audio", bookID), []byte("not audio at all, just text"))
+	if code != 400 {
+		t.Fatalf("a text file must be refused, got %d", code)
+	}
+	recorder = fetchRaw(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/audio", bookID), nil)
+	if !bytes.Equal(recorder.Body.Bytes(), smaller) {
+		t.Fatal("a refused upload must keep the previous file")
+	}
+	big := make([]byte, maxAudioBytes+1024)
+	copy(big, "ID3")
+	if code, _, _ = uploadAttachment(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/audio", bookID), big); code != 413 {
+		t.Fatalf("an oversized audio must be refused with 413, got %d", code)
+	}
+	if code, _, _ = uploadAttachment(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/cover", bookID), testPNG(t, maxCoverPixels+1, 4)); code != 400 {
+		t.Fatalf("an oversized image must be refused, got %d", code)
+	}
+
+	// Ownership: another account cannot read, replace, remove or report on this book.
+	if recorder = fetchRaw(t, r, other.Token, fmt.Sprintf("/api/v1/books/%d/audio", bookID), nil); recorder.Code != 404 {
+		t.Fatalf("another account reading audio must be 404, got %d", recorder.Code)
+	}
+	if recorder = fetchRaw(t, r, "", fmt.Sprintf("/api/v1/books/%d/audio", bookID), nil); recorder.Code != 401 {
+		t.Fatalf("an anonymous read must be 401, got %d", recorder.Code)
+	}
+	if code, _, _ = uploadAttachment(t, r, other.Token, fmt.Sprintf("/api/v1/books/%d/cover", bookID), testPNG(t, 8, 8)); code != 404 {
+		t.Fatalf("another account uploading a cover must be 404, got %d", code)
+	}
+	if code, _, _ = callRaw(t, r, "DELETE", fmt.Sprintf("/api/v1/books/%d/audio", bookID), other.Token, nil); code != 404 {
+		t.Fatalf("another account deleting audio must be 404, got %d", code)
+	}
+	if code, _, _ = callRaw(t, r, "PUT", fmt.Sprintf("/api/v1/books/%d/playback", bookID), other.Token, map[string]any{"positionSeconds": 10}); code != 404 {
+		t.Fatalf("another account reporting a position must be 404, got %d", code)
+	}
+	if code, _, _ = callRaw(t, r, "PUT", fmt.Sprintf("/api/v1/books/%d/playback", bookID), "", map[string]any{"positionSeconds": 10}); code != 401 {
+		t.Fatal("reporting a position needs a session")
+	}
+
+	// Removing the audio removes the position with it.
+	code, _, _ = callRaw(t, r, "PUT", fmt.Sprintf("/api/v1/books/%d/playback", bookID), learner.Token, map[string]any{"positionSeconds": 42})
+	if code != 200 {
+		t.Fatalf("position before removal %d", code)
+	}
+	if code, _, _ = callRaw(t, r, "DELETE", fmt.Sprintf("/api/v1/books/%d/audio", bookID), learner.Token, nil); code != 200 {
+		t.Fatalf("audio removal %d", code)
+	}
+	if err := db.Model(&PlaybackPosition{}).Where("book_id = ?", bookID).Count(&rows).Error; err != nil || rows != 0 {
+		t.Fatalf("removing the audio must remove the position: %d %v", rows, err)
+	}
+	if code, _, _ = callRaw(t, r, "DELETE", fmt.Sprintf("/api/v1/books/%d/audio", bookID), learner.Token, nil); code != 404 {
+		t.Fatal("removing a missing attachment must be 404")
+	}
+
+	// Deleting the book takes its remaining attachments with it.
+	code, msg, _ = callRaw(t, r, "DELETE", fmt.Sprintf("/api/v1/books/%d", bookID), learner.Token, nil)
+	if code != 200 {
+		t.Fatalf("book delete: %d %s", code, msg)
+	}
+	var attachments int64
+	if err := db.Model(&BookAttachment{}).Where("book_id = ?", bookID).Count(&attachments).Error; err != nil || attachments != 0 {
+		t.Fatalf("deleting a book must remove its attachments: %d %v", attachments, err)
+	}
+}
+
+// TestMySQLAttachmentUploadRejectsBadRequests covers the request shapes that must not be stored.
+func TestMySQLAttachmentUploadRejectsBadRequests(t *testing.T) {
+	db, r, owner := libraryFixture(t)
+	learner := newLearner(t, r, owner.Token)
+	code, pasted := pasteBook(t, r, learner.Token, map[string]string{
+		"requestId": "attach-0002", "title": "Fictional attachment rules", "text": "Curiosity opens the first door.\n", "language": "en"})
+	if code != 201 {
+		t.Fatalf("paste %d", code)
+	}
+	drainIngest(t, db)
+	bookID := pasted.Chapter.BookID
+
+	if code, _, _ = uploadAttachment(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/cover", bookID), nil); code != 400 {
+		t.Fatalf("an empty upload must be refused, got %d", code)
+	}
+	if code, _, _ = uploadAttachment(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/audio", bookID), []byte{}); code != 400 {
+		t.Fatalf("an empty audio must be refused, got %d", code)
+	}
+	if code, _, _ = uploadAttachment(t, r, learner.Token, fmt.Sprintf("/api/v1/books/%d/cover?extra=1", bookID), testPNG(t, 8, 8)); code != 400 {
+		t.Fatal("an upload with query parameters must be refused")
+	}
+	if code, _, _ = uploadAttachment(t, r, learner.Token, "/api/v1/books/999999/cover", testPNG(t, 8, 8)); code != 404 {
+		t.Fatal("an unknown book must be 404")
+	}
+	if code, _, _ = uploadAttachment(t, r, "", fmt.Sprintf("/api/v1/books/%d/cover", bookID), testPNG(t, 8, 8)); code != 401 {
+		t.Fatal("uploading needs a session")
+	}
+	// The rejections must not have stored anything for this book.
+	var attachments int64
+	if err := db.Model(&BookAttachment{}).Where("book_id = ?", bookID).Count(&attachments).Error; err != nil || attachments != 0 {
+		t.Fatalf("nothing may be stored for this book: %d %v", attachments, err)
+	}
+}
@@ -84,6 +84,9 @@ func Migrate(db *gorm.DB) error {
 	if current < 7 {
 		statements = append(statements, schemaV7Statements...)
 	}
+	if current < 8 {
+		statements = append(statements, schemaV8Statements...)
+	}
 	for i, s := range statements {
 		if _, err = conn.ExecContext(ctx, s); err != nil {
 			var sqlErr *driver.MySQLError
@@ -99,7 +102,35 @@ func Migrate(db *gorm.DB) error {

 // SchemaVersion is the version an explicit migration leaves behind, and the
 // version the server requires before it starts.
-const SchemaVersion = 7
+const SchemaVersion = 8
+
+// v8 adds the optional book attachments and the per-learner playback position. Both are additive
+// tables, so an older binary can still be rolled back to by writing the version marker back.
+// The file bytes live in the database on purpose: a dump stays a complete backup, the ownership
+// check is the same as for every other private row, and deleting a book cannot leave a file behind.
+var schemaV8Statements = []string{
+	`CREATE TABLE IF NOT EXISTS lexgo_book_attachments (
+		book_id BIGINT UNSIGNED NOT NULL,
+		kind VARCHAR(8) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
+		owner_id BIGINT NOT NULL,
+		mime VARCHAR(64) NOT NULL, byte_size INT NOT NULL,
+		sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
+		bytes MEDIUMBLOB NOT NULL,
+		created_at DATETIME(3) NOT NULL, updated_at DATETIME(3) NOT NULL,
+		PRIMARY KEY (book_id, kind),
+		CHECK (kind IN ('audio','cover')),
+		FOREIGN KEY (book_id) REFERENCES lexgo_books(id) ON DELETE CASCADE,
+		FOREIGN KEY (owner_id) REFERENCES sys_user(user_id) ON DELETE CASCADE
+		) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`,
+	`CREATE TABLE IF NOT EXISTS lexgo_playback_positions (
+		owner_id BIGINT NOT NULL, book_id BIGINT UNSIGNED NOT NULL,
+		position_seconds INT NOT NULL DEFAULT 0, updated_at DATETIME(3) NOT NULL,
+		PRIMARY KEY (owner_id, book_id),
+		CHECK (position_seconds >= 0),
+		FOREIGN KEY (owner_id) REFERENCES sys_user(user_id) ON DELETE CASCADE,
+		FOREIGN KEY (book_id) REFERENCES lexgo_books(id) ON DELETE CASCADE
+		) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`,
+}

 // v7 records one learner's own reading completion per chapter. A chapter belongs to exactly
 // one owner, so the chapter id alone identifies the row and repeating the completion cannot
@@ -112,25 +112,33 @@ type IngestJob struct {
 func (IngestJob) TableName() string { return "lexgo_ingest_jobs" }

 type BookSummary struct {
-	ID              int64     `json:"id"`
-	Title           string    `json:"title"`
-	Language        string    `json:"language"`
-	ChapterCount    int       `json:"chapterCount"`
-	PendingCount    int       `json:"pendingCount"`
-	ProcessingCount int       `json:"processingCount"`
-	ReadyCount      int       `json:"readyCount"`
-	FailedCount     int       `json:"failedCount"`
-	CreatedAt       time.Time `json:"createdAt"`
-	UpdatedAt       time.Time `json:"updatedAt"`
+	ID              int64  `json:"id"`
+	Title           string `json:"title"`
+	Language        string `json:"language"`
+	ChapterCount    int    `json:"chapterCount"`
+	PendingCount    int    `json:"pendingCount"`
+	ProcessingCount int    `json:"processingCount"`
+	ReadyCount      int    `json:"readyCount"`
+	FailedCount     int    `json:"failedCount"`
+	// CoverVersion lets the library show a cover and refresh it exactly when the file changes.
+	CoverVersion string    `json:"coverVersion,omitempty"`
+	HasAudio     bool      `json:"hasAudio"`
+	CreatedAt    time.Time `json:"createdAt"`
+	UpdatedAt    time.Time `json:"updatedAt"`
 }

 type BookRef struct {
 	ID       int64  `json:"id"`
 	Title    string `json:"title"`
 	Language string `json:"language"`
+	// Attachments is filled by the endpoints that show a book, so a cover can be rendered from the
+	// list without a request per row.
+	Attachments *BookAttachmentsView `json:"attachments,omitempty"`
 }

-func bookRef(book Book) BookRef { return BookRef{book.ID, book.Title, book.Language} }
+func bookRef(book Book) BookRef {
+	return BookRef{ID: book.ID, Title: book.Title, Language: book.Language}
+}

 type ChapterSummary struct {
 	ID        int64  `json:"id"`
@@ -491,6 +499,20 @@ func ListBooks(db *gorm.DB, owner int) ([]BookSummary, error) {
 	if len(ids) == 0 {
 		return items, nil
 	}
+	// Attachment metadata is loaded for the whole page at once, so a cover in the list costs one
+	// extra query instead of one per book.
+	found, err := attachmentsByBook(db, owner, ids)
+	if err != nil {
+		return nil, err
+	}
+	for i, item := range items {
+		if cover, ok := found[item.ID][attachmentCover]; ok {
+			items[i].CoverVersion = cover.Version
+		}
+		if _, ok := found[item.ID][attachmentAudio]; ok {
+			items[i].HasAudio = true
+		}
+	}
 	type row struct {
 		BookID int64
 		Status string
@@ -525,6 +547,16 @@ func ListBooks(db *gorm.DB, owner int) ([]BookSummary, error) {
 	return items, nil
 }

+// attachToBookRef fills the attachment metadata for one book the caller owns.
+func attachToBookRef(db *gorm.DB, owner int, ref *BookRef) error {
+	view, err := BookAttachmentsFor(db, owner, ref.ID)
+	if err != nil {
+		return err
+	}
+	ref.Attachments = &view
+	return nil
+}
+
 func BookDetail(db *gorm.DB, owner int, bookID int64) (BookRef, []ChapterSummary, error) {
 	var book Book
 	if err := db.Where("id = ? AND owner_id = ?", bookID, owner).First(&book).Error; err != nil {
@@ -561,7 +593,11 @@ func BookDetail(db *gorm.DB, owner int, bookID int64) (BookRef, []ChapterSummary
 		}
 		items = append(items, summary)
 	}
-	return bookRef(book), items, nil
+	ref := bookRef(book)
+	if err = attachToBookRef(db, owner, &ref); err != nil {
+		return BookRef{}, nil, err
+	}
+	return ref, items, nil
 }

 // jobIDsByChapter maps chapters to their ingestion job so a client can retry a failed chapter
@@ -627,7 +663,13 @@ func ChapterDetail(db *gorm.DB, owner int, chapterID int64) (ReaderResponse, err
 	if at, ok := marks[chapter.ID]; ok {
 		view.ReadAt = &at
 	}
-	return ReaderResponse{Book: bookRef(book), Chapter: view, Navigation: navigation}, nil
+	// The reader shows the book's audio player and the stored position, so the response carries the
+	// attachment metadata for the book, not only for the book page.
+	ref := bookRef(book)
+	if err = attachToBookRef(db, owner, &ref); err != nil {
+		return ReaderResponse{}, err
+	}
+	return ReaderResponse{Book: ref, Chapter: view, Navigation: navigation}, nil
 }

 func JobDetail(db *gorm.DB, owner int, jobID int64) (JobView, error) {
@@ -447,3 +447,86 @@ func TestMigrationFromV3PreservesLibraryAndJobs(t *testing.T) {
 		t.Fatal("migration must create empty resource table", resources, err)
 	}
 }
+
+func TestMigrationFromV7AddsBookAttachments(t *testing.T) {
+	db := emptyMigrationDB(t)
+	statements := []string{"CREATE TABLE lexgo_schema (id INT PRIMARY KEY,version INT,product VARCHAR(32))", "INSERT INTO lexgo_schema VALUES (1,7,'lexgo')"}
+	statements = append(statements, schemaV2Statements...)
+	statements = append(statements, schemaV3Statements...)
+	statements = append(statements, schemaV4Statements...)
+	statements = append(statements, schemaV5Statements...)
+	statements = append(statements, schemaV6Statements...)
+	statements = append(statements, schemaV7Statements...)
+	for _, statement := range statements {
+		if err := db.Exec(statement).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := db.Exec("INSERT INTO sys_user (user_id,username,password,role_id) VALUES (31,'fixture_v7','fictional-not-a-real-hash',2)").Error; err != nil {
+		t.Fatal(err)
+	}
+	saved := stamp(time.Now())
+	book := Book{OwnerID: 31, Title: "Fictional v7 book", Language: "en", CreatedAt: saved, UpdatedAt: saved}
+	if err := db.Create(&book).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := CheckSchema(db); err == nil {
+		t.Fatal("old schema accepted before explicit migration")
+	}
+	if err := Migrate(db); err != nil {
+		t.Fatal(err)
+	}
+	if err := CheckSchema(db); err != nil {
+		t.Fatal(err)
+	}
+	// The upgrade starts with no attachments: nothing is invented for existing books.
+	var attachments int64
+	if err := db.Model(&BookAttachment{}).Count(&attachments).Error; err != nil || attachments != 0 {
+		t.Fatalf("an upgrade must not create attachments: %d %v", attachments, err)
+	}
+	// One audio and one cover per book, and a second row of the same kind is rejected.
+	entry := BookAttachment{BookID: book.ID, Kind: attachmentAudio, OwnerID: 31, Mime: "audio/mpeg",
+		ByteSize: 4, SHA256: contentSHA("ID3"), Bytes: []byte("ID3x"), CreatedAt: saved, UpdatedAt: saved}
+	if err := db.Create(&entry).Error; err != nil {
+		t.Fatal(err)
+	}
+	duplicate := entry
+	duplicate.Mime = "audio/mpeg"
+	if err := db.Create(&duplicate).Error; err == nil {
+		t.Fatal("a book must hold only one attachment per kind")
+	}
+	// A closed set of kinds is enforced by the table itself.
+	unknown := entry
+	unknown.Kind = "video"
+	if err := db.Create(&unknown).Error; err == nil {
+		t.Fatal("an unknown attachment kind must be rejected")
+	}
+	position := PlaybackPosition{OwnerID: 31, BookID: book.ID, PositionSeconds: 12, UpdatedAt: saved}
+	if err := db.Create(&position).Error; err != nil {
+		t.Fatal(err)
+	}
+	// Rolling the marker back for a binary rollback and upgrading again keeps the rows.
+	if err := db.Exec("UPDATE lexgo_schema SET version=7 WHERE id=1").Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := Migrate(db); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Model(&BookAttachment{}).Count(&attachments).Error; err != nil || attachments != 1 {
+		t.Fatalf("re-upgrade must keep the attachment: %d %v", attachments, err)
+	}
+	var positions int64
+	if err := db.Model(&PlaybackPosition{}).Count(&positions).Error; err != nil || positions != 1 {
+		t.Fatalf("re-upgrade must keep the position: %d %v", positions, err)
+	}
+	// Deleting the book removes both, so no attachment or position can outlive its book.
+	if err := db.Where("id = ?", book.ID).Delete(&Book{}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Model(&BookAttachment{}).Count(&attachments).Error; err != nil || attachments != 0 {
+		t.Fatalf("deleting a book must remove its attachments: %d %v", attachments, err)
+	}
+	if err := db.Model(&PlaybackPosition{}).Count(&positions).Error; err != nil || positions != 0 {
+		t.Fatalf("deleting a book must remove its positions: %d %v", positions, err)
+	}
+}
@@ -34,6 +34,7 @@ var OpsTables = []string{
 	"sys_user", "lexgo_spaces", "lexgo_sessions", "lexgo_login_logs", "lexgo_operation_logs",
 	"lexgo_books", "lexgo_chapters", "lexgo_ingest_jobs", "lexgo_dictionaries",
 	"lexgo_terms", "lexgo_term_reviews", "lexgo_review_answers", "lexgo_chapter_progress",
+	"lexgo_book_attachments", "lexgo_playback_positions",
 }

 var opsSystemSchemas = map[string]bool{
@@ -544,6 +545,17 @@ func OpsVerify(client *gorm.DB, database string, manifestPath string) ([]OpsChec
 	if err := linked("SELECT COUNT(*) FROM "+term+" t JOIN "+space+" s ON s.owner_id = t.owner_id WHERE t.language <> s.language", "词条语言与所属空间一致"); err != nil {
 		return checks, err
 	}
+	// Attachments and playback positions must belong to a book that still exists.
+	attachments, positions := table("lexgo_book_attachments"), table("lexgo_playback_positions")
+	if err := linked("SELECT COUNT(*) FROM "+attachments+" a LEFT JOIN "+book+" b ON b.id = a.book_id WHERE b.id IS NULL", "附件都指向存在的书"); err != nil {
+		return checks, err
+	}
+	if err := linked("SELECT COUNT(*) FROM "+attachments+" a JOIN "+book+" b ON b.id = a.book_id WHERE a.owner_id <> b.owner_id", "附件归属与书归属一致"); err != nil {
+		return checks, err
+	}
+	if err := linked("SELECT COUNT(*) FROM "+positions+" p LEFT JOIN "+book+" b ON b.id = p.book_id WHERE b.id IS NULL", "播放位置都指向存在的书"); err != nil {
+		return checks, err
+	}

 	// The audit tables must not gain a column that could hold a credential or private content.
 	for _, name := range []string{"lexgo_login_logs", "lexgo_operation_logs"} {
@@ -1,6 +1,7 @@
 package lexgo

 import (
+	"bytes"
 	"encoding/json"
 	"errors"
 	"github.com/gin-gonic/gin"
@@ -341,6 +342,18 @@ func decodeLimit(c *gin.Context, value any, limit int64) error {
 	}
 	return nil
 }
+
+// binaryResponse lets a handler answer with bytes instead of the JSON envelope: an attachment is
+// served with its own content type, and ServeContent needs the raw response writer so it can apply
+// Range requests, conditional requests and the correct status codes itself.
+type binaryResponse struct {
+	ContentType string
+	Bytes       []byte
+	FileName    string
+	ModifiedAt  time.Time
+	ETag        string
+}
+
 func respond(c *gin.Context, status int, data any, err error) {
 	if err != nil {
 		var e *apiError
@@ -351,6 +364,22 @@ func respond(c *gin.Context, status int, data any, err error) {
 		c.JSON(500, gin.H{"code": 500, "msg": "服务暂不可用，请稍后再试"})
 		return
 	}
+	if binary, ok := data.(binaryResponse); ok {
+		c.Header("Content-Type", binary.ContentType)
+		if binary.ETag != "" {
+			c.Header("ETag", binary.ETag)
+			// A versioned attachment is private and may be cached until its version changes.
+			c.Header("Cache-Control", "private, max-age=0, must-revalidate")
+			if c.GetHeader("If-None-Match") == binary.ETag {
+				c.Status(http.StatusNotModified)
+				return
+			}
+		}
+		// ServeContent answers Range requests with 206, a bad range with 416, and honours
+		// If-Modified-Since through the modification time.
+		http.ServeContent(c.Writer, c.Request, binary.FileName, binary.ModifiedAt, bytes.NewReader(binary.Bytes))
+		return
+	}
 	c.JSON(status, gin.H{"code": 200, "data": data})
 }

@@ -407,4 +407,5 @@ func registerTermRoutes(v *gin.RouterGroup, protect func(bool, func(*gin.Context
 	registerPhraseRoutes(v, protect, now)
 	registerVocabularyRoutes(v, protect, now)
 	registerProgressRoutes(v, protect, now)
+	registerAttachmentRoutes(v, protect, now)
 }