# EPUBUI 功能实现逻辑

## 1. 范围与目标

- 代码范围：`Sources/RDReaderView/EPUBUI/`（16 个 Swift 文件）
- 目标：说明 EPUBUI 如何作为开箱即用的阅读器 UI 层，协调 EPUBCore 解析、EPUBTextRendering 文本渲染、RDReaderView 分页容器，提供完整的阅读体验（工具栏、目录、高亮批注、设置面板、阅读位置持久化、搜索）。
- 主链路关键词：`RDEPUBReaderController.init -> 解析 EPUB -> 分页 -> 渲染 -> 用户交互（翻页/工具栏/设置/高亮/搜索）-> 持久化`。

## 2. 关键对象职责

### 2.1 主控制器 `RDEPUBReaderController`

- 文件：`EPUBUI/RDEPUBReaderController.swift`（~1255 行）
- 入口方法：`init(epubURL:configuration:persistence:)`
- 职责：
  - 加载 EPUB：后台解析 → 应用分页 → 恢复阅读位置
  - 实现 `RDReaderDataSource` / `RDReaderDelegate` 为容器提供数据
  - 实现 `RDEPUBWebContentViewDelegate` 接收 WebView 事件
  - 管理工具栏显隐、目录面板、高亮管理、设置面板、搜索
  - 持久化阅读位置、高亮、用户设置
  - 对外暴露 `RDEPUBReaderDelegate` 回调宿主 App

### 2.2 配置 `RDEPUBReaderConfiguration`

- 文件：`EPUBUI/RDEPUBReaderConfiguration.swift`
- 13 个配置项：
  - `fontSize`（默认 15）、`lineHeightMultiple`（默认 1.6）
  - `displayType`（默认 .pageCurl）、`landscapeDualPageEnabled`（默认 true）
  - `showsTableOfContents`（默认 true）、`allowsHighlights`（默认 true）、`showsSettingsPanel`（默认 true）
  - `reflowableContentInsets`（默认 40/16/40/16）、`fixedContentInset`（默认 .zero）
  - `theme`（默认 .light）
  - `fixedLayoutFit`（默认 .page）、`fixedLayoutSpreadMode`（默认 .automatic）
  - `textRenderingEngine`（默认 .dtCoreText）
- 变更检测：
  - `requiresRepagination`：fontSize / lineHeightMultiple / contentInsets / fixedLayoutFit / fixedLayoutSpreadMode / textRenderingEngine 变化 → 完整重新分页
  - `requiresVisibleRefresh`：theme 变化 → 刷新可见内容（不重新分页）

### 2.3 委托协议 `RDEPUBReaderDelegate`

- 文件：`EPUBUI/RDEPUBReaderDelegate.swift`
- 10 个可选方法（全部有默认空实现）：
  - `didOpen`：成功打开出版物
  - `didUpdateLocation`：翻页或滚动时位置更新
  - `didReachEnd`：到达最后一页
  - `didChangeSelection`：文本选择变化或清除
  - `didUpdateHighlights`：高亮增删改
  - `didUpdateSearchResult`：搜索状态变化
  - `didChangeCurrentSearchMatch`：当前搜索匹配项变化
  - `didUpdateCurrentTableOfContentsItem`：翻页时匹配的目录项
  - `didActivateExternalLink`：外部链接点击
  - `didFailWithError`：解析或分页错误

### 2.4 持久化 `RDEPUBReaderPersistence`

- 文件：`EPUBUI/RDEPUBReaderPersistence.swift`
- 协议定义 6 个方法：loadLocation / saveLocation / loadHighlights / saveHighlights / loadReaderSettings / saveReaderSettings
- 默认实现 `RDEPUBUserDefaultsPersistence`：
  - 位置：`ssreader.epub.location.<bookIdentifier>`（JSON 编码）
  - 高亮：`ssreader.epub.highlights.<bookIdentifier>`（JSON 编码）
  - 设置：`ssreader.epub.settings`（全局，非按书）

### 2.5 主题 `RDEPUBReaderTheme`

- 文件：`EPUBUI/RDEPUBReaderTheme.swift`
- 6 个颜色属性：contentBackgroundColor、contentTextColor、toolBackgroundColor、toolControlTextColor、toolControlBorderUnselectColor、toolLineColor
- 6 个内置预设：`.light`、`.dark`、`.yellow`、`.green`、`.pink`、`.blue`
- 计算属性 `themeBackgroundColorCSS` / `themeTextColorCSS` 用于 Web 渲染路径

### 2.6 设置面板 `RDEPUBReaderSettingsViewController`

- 文件：`EPUBUI/RDEPUBReaderSettingsViewController.swift`
- 5 个控制项：
  - 亮度滑块（0-1）
  - 字号 A-/A+（范围 12-36，步长 1）
  - 行高分段（紧凑 1.3 / 标准 1.6 / 宽松 1.9）
  - 显示模式分段（仿真 / 横滑 / 竖滑 / 覆盖）
  - 主题选择（6 个圆形色块按钮）
- 所有变更通过闭包实时回调

### 2.7 内容视图

- `RDEPUBTextContentView`（`EPUBUI/RDEPUBTextContentView.swift`）：textReflowable 路径，UITextView 展示富文本，支持系统选区、标注菜单、用户标注叠加和搜索高亮叠加
- `RDEPUBWebContentView`（`EPUBUI/RDEPUBWebContentView.swift`）：web 路径，包装 `RDEPUBWebView`，转发位置、选区、标注菜单、链接和 JS 错误事件

### 2.8 其他 UI 组件

- `RDEPUBReaderTopToolView`：顶部导航栏（返回按钮 + 标题）
- `RDEPUBReaderBottomToolView`：底部工具栏（目录 / 批注 / 标注 / 设置 4 个按钮）
- `RDEPUBReaderChapterListController`：目录列表（modal UITableViewController，当前项高亮 systemBlue）
- `RDEPUBReaderHighlightsViewController`：标注管理（全部 / 批注 / 划线过滤，列表 + 编辑备注 + 删除 + 跳转，空态按过滤条件提示）

## 3. 主流程（代码级）

### 3.1 初始化与加载

1. `init(epubURL:configuration:persistence:)`：
   - 加载持久化的阅读设置，叠加到 configuration
   - 恢复屏幕亮度
2. `viewDidLoad`：
   - 设置背景色
   - `setupReaderView()`：添加 RDReaderView 全屏约束，注册 `RDEPUBTextContentView` 和 `RDEPUBWebContentView`
   - `setupLoadingIndicator()`、`setupErrorLabel()`
3. `viewDidAppear`：调用 `startInitialLoadIfNeeded()`
4. 加载序列：
   - `loadPublication()` → 读取持久化位置
   - 后台 `RDEPUBParser.parse(epubURL:)` 解析
   - 主线程 `applyParsedPublication()` → `paginatePublication()`

### 3.2 分页流程

`paginatePublication(restoreLocation:)` 根据 readingProfile 分三条路径：

**textReflowable 路径**：
1. 后台队列：`RDEPUBTextBookBuilder.build(parser:publication:pageSize:style:)`
2. 主线程 `applyTextBook(textBook:)`：保存 textBook，reloadData

**fixed layout 路径**：
1. 创建快照：`pageCounts: Array(repeating: 1, count: publication.spine.count)`
2. `applyPaginationSnapshot(snapshot:restoreLocation:)`

**web interactive 路径**：
1. `RDEPUBPaginator.calculate(parser:hostingView:presentation:completion:)`
2. 回调收到页数数组后 `applyPaginationSnapshot(snapshot:restoreLocation:)`

三条路径汇合 `finishPagination(restoreLocation:)`：
- `readerView.reloadData()`
- `restoreReadingLocation(restoreLocation)`

### 3.3 页面内容工厂

`pageContentView(readerView:pageNum:containerView:)`：
- 有 textBook → 出队/创建 `RDEPUBTextContentView`，调用 `configure(page:pageNumber:totalPages:configuration:searchState:)`
- 无 textBook → 出队/创建 `RDEPUBWebContentView`，调用 `configure(publication:request:pageNumber:totalPages:theme:)`

`pageIdentifier(readerView:pageNum:)`：返回对应类名字符串用于 cell 出队

### 3.4 工具栏交互

- RDReaderView 内部处理点击手势，中心 1/3 区域切换工具栏
- 顶部工具栏：返回按钮 pop/dismiss，标题设为 metadata.title
- 底部工具栏：4 个按钮按配置 flags 控制可见性
  - 目录按钮 → present `RDEPUBReaderChapterListController`（.pageSheet）
  - 批注按钮 → present `RDEPUBReaderHighlightsViewController`（.pageSheet）
  - 标注按钮 → `presentAnnotationActionSheet(for:)`（需有 currentSelection，否则 disabled），可创建高亮、划线或带 note 的批注
  - 设置按钮 → present `RDEPUBReaderSettingsViewController`（.pageSheet）

### 3.5 设置变更处理

- 字号变化：`configuration.fontSize = newValue` → `requiresRepagination` → `repaginatePreservingCurrentLocation()`
- 行高变化：同上
- 显示模式变化：`readerView.switchReaderDisplayType()` 重建容器
- 主题变化：`configuration.theme = newValue` → `requiresVisibleRefresh` → `refreshVisibleContentPreservingLocation()`
- 亮度变化：`UIScreen.main.brightness = value` + 持久化

### 3.6 标注管理

- 创建：`addAnnotation(from:style:color:note:)` → 从 currentSelection 构建 → 去重 → 追加到 activeHighlights → 持久化 → 刷新可见内容
- 兼容入口：`addHighlight(from:color:note:)` 仍保留，内部按 `.highlight` 创建
- 样式：`RDEPUBHighlightStyle.highlight` 使用背景色，`RDEPUBHighlightStyle.underline` 使用下划线；旧数据缺少 style 时默认按普通高亮解码
- 批注：note 非空时同一条 `RDEPUBHighlight` 同时承担批注语义
- 删除：`removeHighlight(id:)` → 移除 → 持久化 → 刷新
- 编辑备注：`updateHighlightNote(id:note:)` → 更新 → 持久化 → 刷新
- 跳转：`go(toHighlightID:animated:)` → 从高亮 location 解析页码 → `transitionToPage`
- WebView 选区：`epub-bridge.js` 生成 `dom-range` rangeInfo，Web 内容通过 payload 的 `style` 字段恢复高亮或划线
- DT 选区：`RDEPUBTextContentView` 把页内 selectedRange 映射为章节全局 text-offset rangeInfo，并在当前页与标注范围重叠时叠加背景或下划线
- 选区菜单：WebView 与 DT 路径都通过自定义菜单动作收口到 `拷贝 / 高亮 / 批注`，动作最终复用同一套创建与批注输入流程

### 3.7 书签管理

- 创建/切换：`toggleBookmark(note:)` 基于 `currentVisibleLocation()` 生成当前位置书签；若同一语义位置已存在书签则执行取消
- 位置范围：书签使用 `RDEPUBLocation`，持久化字段包含 `href / fragment / progression`，不依赖正文选区
- 当前位置命中：优先比较标准化后的 `href`，若双方都有 `fragment` 则直接比较；否则按 `navigationProgression` 容差判断（fixed-layout 0.01，reflowable 0.05）
- 标题补全：优先复用当前 TOC 项标题，否则根据扁平目录用 href 反查章节标题
- 列表管理：底部工具栏 `书签` 入口弹出 `RDEPUBReaderBookmarksViewController`，支持按创建时间倒序展示、跳转与删除
- 顶部状态：TopToolView 右上角书签按钮显示当前页是否已加书签，点击可直接添加/取消
- 持久化：每次新增/删除都会通过 `RDEPUBReaderPersistence.saveBookmarks(_:for:)` 按书保存，并回调 `didUpdateBookmarks`

### 3.8 搜索流程

1. `search(keyword:)`：标准化输入
2. textBook 路径：`RDEPUBTextSearchEngine.search(keyword:)`
3. web 路径：`RDEPUBHTMLSearchEngine.search(keyword:)`
4. 存储结果到 `searchState`，导航到第一个匹配
5. `searchNext()` / `searchPrevious()`：循环推进 currentMatchIndex 并导航
6. `clearSearch()`：清除状态，刷新可见内容

### 3.9 阅读位置持久化

**保存时机**：
- 每次翻页：`pageNum(readerView:pageNum:)` → `persist(location:)`
- WebView 滚动：`epubWebContentView(_:didUpdateLocation:)` → `persist(location:)`

**恢复时机**：
- 初始加载：`loadPublication()` 读取 → 传递到 `finishPagination()` → `restoreReadingLocation()`
- 显式导航：`go(to:)` / `go(toTableOfContentsHref:)` / `go(toHighlightID:)` / 搜索导航

**恢复逻辑**：
- textBook 路径：`textBook.pageNumber(for:resolver:bookIdentifier:)` → `readerView.transitionToPage`
- readingSession 路径：`readingSession.queueNavigation(to:)` → `transitionToPage`

### 3.9 横竖屏适配

- `viewWillTransition(to:with:)`：等待旋转过渡完成后，统一触发 viewport 变化处理
- `viewDidLayoutSubviews`：用于补齐分屏、多窗口、safe area 变化等非旋转型视口变化
- 控制器内部使用 viewport signature 做去重，避免一次旋转触发多次正文重分页
- RDReaderView 的 `readerViewOrientationWillChange` 仅保留容器级双页布局和 pageCurl 重建职责，不再直接驱动 EPUBUI 重新分页

## 4. 异常与边界处理

- EPUB 解析失败：显示 errorLabel，delegate 收到 `didFailWithError`
- 分页失败：主线程 `handle(error:)` 处理
- `paginationToken` 防竞态：每次加载/分页生成新 UUID，后台完成时校验 token 一致才应用结果
- 标注去重：`addAnnotation` 检查相同 location、text、rangeInfo 和 style 是否已存在标注
- 自定义主题不可持久化：仅 6 个内置 preset 可序列化，自定义主题仅当前会话有效
- 目录页码缺失：`flattenedTableOfContents` 中 pageNumber 可能为 nil（无法定位到对应页面的 TOC 项）

## 5. 数据结构与字段映射

### 5.1 持久化键值

| 数据 | UserDefaults Key | 编码 |
|------|-----------------|------|
| 阅读位置 | `ssreader.epub.location.<bookIdentifier>` | JSON → `RDEPUBLocation` |
| 高亮列表 | `ssreader.epub.highlights.<bookIdentifier>` | JSON → `[RDEPUBHighlight]` |
| 书签列表 | `ssreader.epub.bookmarks.<bookIdentifier>` | JSON → `[RDEPUBBookmark]` |
| 阅读设置 | `ssreader.epub.settings` | JSON → `RDEPUBReaderSettings` |

### 5.2 Book Identifier

- 优先使用 `parser.metadata.identifier`
- 回退使用 `epubURL.lastPathComponent`

### 5.3 设置快照

```swift
RDEPUBReaderSettings (Codable)
  ├── brightness: CGFloat
  ├── fontSize: CGFloat
  ├── lineHeightMultiple: CGFloat
  ├── displayMode: RDEPUBReaderDisplayMode
  └── themePreset: RDEPUBReaderThemePreset?
```

### 5.4 目录扁平化项

```swift
RDEPUBReaderTableOfContentsItem
  ├── title: String
  ├── href: String
  ├── depth: Int          // 缩进层级
  └── pageNumber: Int?    // 可能为 nil
```

## 6. 视图绑定规则

- 规则 1：内容视图通过 class name 注册到 RDReaderView，出队时根据 textBook 是否存在选择类型
- 规则 2：RDEPUBTextContentView 展示 attributedText + 搜索高亮叠加 + 页码标签（"N / M"）
- 规则 3：RDEPUBWebContentView 包装 RDEPUBWebView + 页码标签
- 规则 4：顶部工具栏固定提供返回与书签切换入口；底部工具栏提供目录、书签、标注、设置等管理入口
- 规则 5：设置面板所有变更实时生效（闭包回调），无需确认按钮

## 7. 通知协作与回调机制

### 外部通信（Delegate）

- `RDEPUBReaderDelegate`：11 个可选方法，覆盖打开、位置更新、到达末尾、选择变化、高亮更新、书签更新、搜索更新、目录项更新、外部链接、错误

### 内部通信（闭包）

- `RDEPUBReaderTopToolView.onBack / onToggleBookmark`
- `RDEPUBReaderBottomToolView.onShowTableOfContents / onShowBookmarks / onShowHighlights / onAddHighlight / onShowSettings`
- `RDEPUBReaderChapterListController.onSelectItem`
- `RDEPUBReaderHighlightsViewController.onSelectHighlight / onUpdateHighlight / onDeleteHighlight`
- `RDEPUBReaderSettingsViewController.onBrightnessChange / onFontSizeChange / onLineHeightChange / onDisplayTypeChange / onThemeChange`

### 容器通信（协议）

- `RDReaderDataSource` / `RDReaderDelegate`：RDEPUBReaderController 实现，为 RDReaderView 提供页面数据和接收页面变化事件
- `RDEPUBWebContentViewDelegate`：RDEPUBReaderController 实现，接收 WebView 的位置更新、选择变化、链接激活、JS 错误

## 8. 联调与排查建议

- 排查 1：阅读器打开后空白
  - 检查 `RDEPUBParser.parse(epubURL:)` 是否成功
  - 检查 `startInitialLoadIfNeeded()` 是否被调用（需要 viewDidAppear）
  - 检查 errorLabel 是否显示
- 排查 2：翻页后位置不恢复
  - 检查 `persistence.loadLocation(for:)` 是否返回非 nil
  - 检查 `restoreReadingLocation` 是否在 `finishPagination` 中被调用
  - textBook 路径检查 `textBook.pageNumber(for:)` 返回值
- 排查 3：设置变更后无效果
  - 字号/行高变化需触发 `repaginatePreservingCurrentLocation()`
  - 主题变化只需 `refreshVisibleContentPreservingLocation()`
  - 检查 `requiresRepagination` / `requiresVisibleRefresh` 的判断逻辑
- 排查 4：高亮不显示
  - 确认 `currentSelection` 非 nil
  - 确认 `addHighlight` 成功返回
  - 确认 `refreshVisibleContentPreservingLocation()` 被调用
  - textBook 路径检查 `RDEPUBTextContentView.configure` 中的搜索高亮逻辑
- 排查 5：搜索无结果
  - textBook 路径确认 `RDEPUBTextSearchEngine.search` 被调用
  - web 路径确认 `RDEPUBHTMLSearchEngine.search` 被调用
  - 检查搜索关键词是否为空
- 排查 6：横屏布局异常
  - 确认 `landscapeDualPageEnabled` 是否为 true
  - 检查 `viewDidLayoutSubviews` 是否触发了重新分页
  - 检查 RDReaderView 的 orientation change 处理