# 书签能力方案讨论

## 需求背景

`Doc/EPUB_MAINTENANCE.md` 已将“书签能力”列为 EPUB 阅读器下一阶段的高优先级能力之一。

当前阅读器已经具备：

1. EPUB 打开与解析
2. WebView / DTCoreText / fixed-layout 三条正文渲染路径
3. 目录跳转、阅读位置恢复、主题与字号调整
4. 高亮、划线、批注、搜索等阅读交互能力

但现阶段“位置记录”仍主要依赖：

1. 自动保存的上次阅读位置
2. 需要选中文本的高亮 / 批注能力

这会遗漏一种非常常见、也非常轻量的阅读诉求：

1. 只想标记当前位置
2. 稍后回来继续读
3. 不需要摘录正文
4. 不需要输入批注

因此，“书签能力”这项需求的目标，不是扩展现有标注功能，而是补上一条面向“位置收藏”的轻量链路，用来覆盖“只记录位置、不做摘录”的常见阅读需求。

## 代码事实

### 已有基础

当前仓库其实已经具备不少可直接复用的基础设施：

1. `RDEPUBLocation` 已能稳定表达 `href + progression + fragment`
2. `RDEPUBReaderController` 已具备“当前位置读取”和“跳转到位置”的主链路
3. `RDEPUBReaderPersistence` 已形成按 `bookIdentifier` 分书持久化的模式
4. 高亮管理页已经具备“列表展示 -> 点击跳转 -> 删除”的成熟交互范式

结论：

1. 书签不需要重新设计位置模型
2. 书签可以复用现有定位和跳转能力
3. 更需要新增的是独立模型、持久化存储位和 UI 入口

### 当前实现存在的问题

#### 问题 1：当前只有单一阅读位置，没有“多书签”能力

`RDEPUBReaderPersistence` 当前只提供：

1. `loadLocation / saveLocation`
2. `loadHighlights / saveHighlights`
3. `loadReaderSettings / saveReaderSettings`

这意味着：

1. 系统只能保存“上次读到哪”
2. 不能保存“用户主动收藏的多个位置”

而这两者的语义并不相同：

1. 阅读位置是自动覆盖的
2. 书签是主动创建、可长期保留多个的

#### 问题 2：当前标注模型不适合直接承载书签

虽然看起来可以用 `RDEPUBHighlight` 勉强模拟书签，但这会带来明显问题：

1. 书签不一定有选中文本
2. 书签不应依赖 `rangeInfo`
3. 书签列表应以“位置”为中心，而不是以“摘录内容”为中心
4. 书签与高亮、划线、批注的展示和管理语义不同

因此，不建议把书签硬塞进现有高亮模型。

#### 问题 3：当前 UI 没有书签入口与状态反馈

从 `RDEPUBReaderBottomToolView` 当前结构来看，只有：

1. 目录
2. 批注列表
3. 添加标注
4. 设置

当前并没有：

1. 当前页添加 / 取消书签入口
2. 书签列表入口
3. 当前阅读位置是否已加书签的状态反馈

这意味着即便补了数据层，用户仍然无法自然感知和使用这项能力。

## 需求拆解

建议把“书签能力”拆成四部分推进。

### 1. 独立书签模型

需要新增一个面向“位置记录”的独立模型，而不是复用高亮模型。

### 2. 独立书签持久化

需要新增书签读写接口，支持每本书存储多个书签。

### 3. 书签入口与状态反馈

需要让用户在当前页能轻量创建 / 取消书签，并能看到当前位置的书签状态。

### 4. 书签管理与跳转

需要补齐书签列表、点击跳转、删除等基本管理闭环。

## 技术路线对比

### 路线 A：把书签并入 `RDEPUBHighlight`

思路：

1. 给 `RDEPUBHighlight` 增加一个新的 style 或特殊标识
2. 将书签存入 highlights
3. 复用现有标注列表页

优点：

1. 表面上改动范围较小
2. 可以快速借用现有列表管理代码

风险：

1. 模型语义不清晰
2. 书签没有文本选区时会很别扭
3. 后续展示、筛选、持久化逻辑会越来越绕
4. 容易让“书签”和“标注”边界变得混乱

### 路线 B：完全独立一条书签链路

思路：

1. 新建 `RDEPUBBookmark`
2. 新增 `loadBookmarks / saveBookmarks`
3. 新增书签列表页
4. 独立接入添加、删除、跳转、状态更新

优点：

1. 模型语义清晰
2. 更符合产品能力边界
3. 后续扩展空间更好

风险：

1. 会新增一部分 UI 与管理代码
2. 与高亮列表在形态上会有一定重复

### 路线 C：模型独立，交互模式局部复用

思路：

1. 数据模型与持久化独立
2. 定位、跳转和列表交互模式尽量复用现有高亮链路
3. 第一阶段先做轻量闭环，再考虑更复杂管理能力

优点：

1. 语义清晰，同时控制改动范围
2. 能复用现有阅读位置链路和管理交互经验
3. 更适合当前仓库的演进方式

风险：

1. 仍需补一组新的数据与列表代码
2. 需要明确书签状态判定规则，避免重排后误判

### 推荐结论

建议采用：

**主路线：路线 C，模型独立，位置链路复用，UI 先做轻量闭环**

原因：

1. 书签和标注的语义不同，模型应保持独立
2. 当前仓库已有成熟的位置和跳转主链路，可以直接复用
3. 第一阶段先满足“记录位置”的核心需求，不需要把书签做得过重

## 推荐方案

### 方案总览

书签能力第一阶段建议形成如下结构：

1. 新增 `RDEPUBBookmark` 独立模型
2. 扩展 `RDEPUBReaderPersistence`，新增 bookmarks 读写
3. 在 `RDEPUBReaderController` 中接入书签状态、添加、删除、跳转能力
4. 增加轻量级书签入口和书签列表页
5. 支持退出重进后的书签持久化恢复

### 推荐数据模型

建议书签模型至少包含以下字段：

1. `id`
2. `bookIdentifier`
3. `location`
4. `chapterTitle`
5. `displayText` 或摘要信息（可选）
6. `note`（可选）
7. `createdAt`

其中第一阶段真正必要的最小集合是：

1. `id`
2. `bookIdentifier`
3. `location`
4. `createdAt`

建议同时补上 `chapterTitle`，这样书签列表在展示时会更友好，也更接近真实阅读器使用习惯。

### 推荐持久化结构

建议在 `RDEPUBReaderPersistence` 中新增：

1. `loadBookmarks(for:)`
2. `saveBookmarks(_:for:)`

`RDEPUBUserDefaultsPersistence` 中新增：

1. `bookmarksPrefix`

第一阶段继续沿用当前：

1. `UserDefaults`
2. `JSONEncoder / JSONDecoder`
3. `bookIdentifier` 作用域隔离

这样能在最小改动下形成可用闭环。

### 推荐 UI 入口

第一阶段建议至少补两类入口：

1. 当前页添加 / 取消书签入口
2. 书签列表入口

比较自然的放置方式是：

1. 顶部工具栏增加“当前页书签”切换按钮
2. 底部工具栏增加“书签列表”入口

这样可以把两种动作区分开：

1. “加书签”是当前上下文动作
2. “看书签列表”是全局管理动作

### 推荐交互闭环

第一阶段建议用户路径收敛成下面这条主链路：

1. 用户在当前阅读位置点击书签按钮
2. 如果当前语义位置未加书签，则创建书签
3. 如果当前语义位置已加书签，则取消该书签
4. 用户可从书签列表查看当前书籍的全部书签
5. 点击任意书签后跳转到对应位置
6. 支持从列表中删除书签

## 关键实现建议

### Task K1：新增书签模型

文件：

1. `Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift`

改动：

1. 新增 `RDEPUBBookmark: Codable, Equatable`
2. 字段以 `location` 为核心，不依赖选区文本

完成定义：

1. 可以表达一本书中的一个可持久化书签位置

### Task K2：扩展书签持久化协议

文件：

1. `Sources/RDReaderView/EPUBUI/RDEPUBReaderPersistence.swift`

改动：

1. 协议增加 `loadBookmarks / saveBookmarks`
2. `RDEPUBUserDefaultsPersistence` 增加 `bookmarksPrefix`

完成定义：

1. 每本书可以稳定读取和保存多个书签

### Task K3：控制器接入书签状态与操作

文件：

1. `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`

改动：

1. 增加 `activeBookmarks`
2. 打开图书时加载 bookmarks
3. 增加 `addBookmark`
4. 增加 `removeBookmark`
5. 增加 `toggleBookmark`
6. 增加 `go(to: bookmark)`
7. 增加当前阅读位置是否已书签的状态计算

完成定义：

1. 书签与阅读主链路、跳转链路、持久化链路打通

### Task K4：补书签 UI 与列表管理

文件：

1. `Sources/RDReaderView/EPUBUI/RDEPUBReaderBottomToolView.swift`
2. 新增 `Sources/RDReaderView/EPUBUI/RDEPUBReaderBookmarksViewController.swift`
3. 视情况补充顶部工具栏按钮

改动：

1. 添加书签入口
2. 添加书签列表入口
3. 点击书签跳转
4. 支持删除
5. 提供当前位置书签状态反馈

完成定义：

1. 用户能看到、添加、取消、查看和管理书签

## 当前页书签判定建议

“当前位置是否已加书签”不建议简单按“完全相同的 `progression`”判断，因为：

1. 字号变化会触发重分页
2. 视口尺寸变化会导致 progression 细微漂移
3. WebView 和文本分页的进度精度并不完全一致

更合理的判定策略是：

1. 优先比较标准化后的 `href`
2. 如果存在 `fragment`，优先使用 `fragment` 作为更强锚点
3. reflowable 路径允许一定 progression 容差
4. fixed-layout 路径优先按页级位置判断

这样可以减少用户在重排、重进或轻微位置变化时的书签状态抖动。

## 验收矩阵建议

第一阶段至少要覆盖以下验证维度：

1. 当前页可添加书签
2. 同一位置可取消书签
3. 书签列表展示正常
4. 点击书签可以跳转
5. 删除书签后列表更新正确
6. 退出重进后书签仍存在
7. 字号变化后书签仍能回到同章节或邻近语义位置
8. `webInteractive` 路径正常
9. `textReflowable` 路径正常
10. `webFixedLayout` 路径至少能按页恢复

## 风险与注意点

### 风险 1：把书签与高亮强行合并

这样短期看似省事，长期会让模型、持久化和 UI 语义都变重。

### 风险 2：过度依赖精确 progression 匹配

如果书签命中规则太严格，重分页后会显得“不稳定”，用户体验会很差。

### 风险 3：第一阶段把书签做得过重

书签能力的首要目标是“轻量记录位置”，不是一开始就做成复杂的收藏管理系统。

## 推荐实施顺序

如果目标是“最小投入换最大需求闭环”，建议按下面顺序推进：

1. 先补独立 `RDEPUBBookmark` 模型
2. 先扩展 `RDEPUBReaderPersistence` 的书签读写能力
3. 再在 `RDEPUBReaderController` 接入书签主链路
4. 最后补 UI 入口和书签列表页
5. 待第一阶段稳定后，再考虑备注、排序、筛选等增强能力

## 推荐结论

“书签能力”这项需求，建议最终收敛为下面这句话：

**为 EPUB 阅读器补齐一条独立的轻量书签链路，以 `RDEPUBLocation` 为核心记录位置，支持添加、取消、列表管理、跳转与持久化恢复，用来覆盖“只记录位置、不做摘录”的常见阅读需求。**