# EPUBCore 功能实现逻辑

## 1. 范围与目标

- 代码范围：`Sources/RDReaderView/EPUBCore/`（30 个 Swift 文件 + 2 个资源文件）
- 目标：说明 EPUBCore 如何完成 EPUB 解析、资源定位、阅读会话管理、离屏分页、JS 桥接渲染和全文搜索。
- 主链路关键词：`epubURL -> RDEPUBParser.parse -> container.xml -> OPF -> spine/TOC -> RDEPUBPublication -> RDEPUBReadingSession -> RDEPUBWebView/Paginator -> 分页/渲染`。

## 2. 关键对象职责

### 2.1 解析器 `RDEPUBParser`

- 文件：`EPUBCore/RDEPUBParser.swift` + 5 个扩展文件
- 入口方法：`parse(epubURL:)`
- 职责：
  - ZIP 解压到缓存目录（`RDEPUBParser+Archive.swift`）
  - 解析 `META-INF/container.xml` 定位 OPF 根文件
  - 解析 OPF 文档提取 metadata / manifest / spine（`RDEPUBParser+Package.swift`）
  - 解析目录支持 NCX（EPUB 2）和 Nav Document（EPUB 3）（`RDEPUBParser+TOC.swift`）
  - 判断阅读配置文件类型（`RDEPUBParser+ReadingProfile.swift`）
  - 资源路径转换：相对路径 ↔ 文件 URL ↔ `ss-reader://` 自定义 scheme URL（`RDEPUBParser+Resources.swift`）

### 2.2 Publication 门面 `RDEPUBPublication`

- 文件：`EPUBCore/RDEPUBPublication.swift`
- 职责：
  - 包装 `RDEPUBParser` + `RDEPUBResourceResolver`，对外暴露只读接口
  - 提供 metadata、manifest、spine、TOC、layout、readingProfile、readingProgression
  - 计算 fixed layout 的 spread 组合：`makeFixedSpreads(preferences:viewportSize:)`

### 2.3 阅读会话 `RDEPUBReadingSession`

- 文件：`EPUBCore/RDEPUBReadingSession.swift` + `RDEPUBNavigatorState.swift`
- 职责：
  - 管理导航状态机：`initializing -> loading -> idle <-> jumping/moving/repaginating`
  - 维护活跃/暂存分页快照（`activePages` / `activeChapters` / `stagedPages` / `stagedChapters`）
  - 管理待定导航目标（`pendingNavigationLocation` / `pendingNavigationPageNum`）
  - 更新阅读上下文（`currentReadingContext`：location + viewport + pageNumber + chapterIndex）
  - 构建分页快照：`makePaginationSnapshot(pageCounts:preferences:layoutContext:)`

### 2.4 WebView 渲染层 `RDEPUBWebView`

- 文件：`EPUBCore/RDEPUBWebView.swift` + 5 个扩展文件
- 职责：
  - 内部持有 WKWebView，配置自定义 scheme handler 和 JS 桥接
  - 可重排内容加载：`loadPage(parser:spineIndex:pageIndex:...)`（`+Reflowable.swift`）
  - 固定版式内容加载：`loadFixedSpread(parser:spread:...)`（`+FixedLayout.swift`）
  - 处理 JS 桥接消息和链接导航拦截（`+JavaScriptBridge.swift`）
  - 搜索高亮装饰（`+Search.swift`）
  - 定义 `RDEPUBWebViewDelegate` 协议（6 个回调方法）

### 2.5 离屏分页器 `RDEPUBPaginator`

- 文件：`EPUBCore/RDEPUBPaginator.swift`
- 职责：
  - 创建隐藏的 WKWebView 加载每个 spine 项的 HTML
  - 注入分页 CSS，运行 JS 测量 `scrollWidth`
  - 计算 `ceil(scrollWidth / viewportWidth)` 作为页数
  - 多次测量取最大值（延迟 0ms / 80ms / 180ms）确保布局稳定

### 2.6 资源解析 `RDEPUBResourceResolver` + `RDEPUBResourceURLSchemeHandler`

- 文件：`EPUBCore/RDEPUBResourceResolver.swift`、`EPUBCore/RDEPUBResourceURLSchemeHandler.swift`
- 职责：
  - `RDEPUBResourceResolver`：对外门面，提供 href 标准化、spine 索引查找、Location 构建
  - `RDEPUBResourceURLSchemeHandler`：实现 `WKURLSchemeHandler`，将 `ss-reader://book/<path>` 映射到解压后的文件系统路径，缺失的可选资源（字体/图片/CSS/JS）返回空 200

### 2.7 JS 桥接

- 文件：`EPUBCore/RDEPUBJavaScriptBridge.swift`、`Resources/epub-bridge.js`
- 6 种消息类型（JS → Swift）：
  - `ssReaderProgressionChanged`：阅读进度变化
  - `ssReaderSelectionChanged`：文本选择变化
  - `ssReaderInternalLink`：内部链接点击
  - `ssReaderExternalLink`：外部链接点击
  - `ssReaderJSError`：JS 错误
  - `ssReaderFixedLayoutReady`：固定版式渲染完成
- JS 端 `window.RDReaderBridge` 暴露：`applyPagination`、`setPageMetrics`、`scrollToPage`、`scrollToLocation`、`setHighlights`、`clearHighlights`、`reportProgression`、`selectionPayload`

### 2.8 搜索引擎 `RDEPUBHTMLSearchEngine`

- 文件：`EPUBCore/RDEPUBSearchEngine.swift`、`EPUBCore/RDEPUBSearchModels.swift`
- 职责：
  - 将 HTML 转为纯文本（NSAttributedString 或正则兜底）
  - 执行大小写不敏感的全文搜索
  - 返回 `RDEPUBSearchMatch` 数组（含 progression 偏移和预览文本）

### 2.9 配置与样式

- `RDEPUBPreferences`（`EPUBCore/RDEPUBPreferences.swift`）：用户阅读偏好（字号、行高、内容边距、主题色、固定版式适配模式），构建 `RDEPUBPresentationStyle` 和 `RDEPUBRenderRequest`
- `RDEPUBNavigatorLayoutContext`（`EPUBCore/RDEPUBNavigatorLayoutContext.swift`）：容器布局上下文（容器尺寸、每屏页数、安全区域、设备类型）
- `RDEPUBStyleSheetBuilder`（`EPUBCore/RDEPUBStyleSheetBuilder.swift`）：生成分页 CSS、渲染 CSS 和测量 JS 脚本
- `RDEPUBFixedLayoutTemplate`（`EPUBCore/RDEPUBFixedLayoutTemplate.swift`）：生成固定版式 HTML 模板

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

### 3.1 EPUB 解析全流程

1. 入口：`RDEPUBParser.parse(epubURL:)`。
2. 调用 `extractArchiveIfNeeded(epubURL:)`：
   - 缓存路径：`~/Library/Caches/ssreaderview-epub/<slug>-<fileSize>-<timestamp>/`
   - 若目录已存在则跳过解压
   - 否则用 ZIPFoundation 解压 ZIP 到缓存目录
3. 解析 `META-INF/container.xml`：
   - `ContainerXMLParserDelegate`（SAX）找到第一个 `<rootfile>` 的 `full-path` 属性
4. 解析 OPF 文档：
   - `OPFPackageParserDelegate`（SAX）分段解析 metadata / manifest / spine
   - 提取 `<package>` 版本和 unique-identifier
   - 提取 `<dc:identifier>` / `<dc:title>` / `<dc:creator>` / `<dc:language>`
   - 提取 `<meta property="rendition:layout">` 判断 fixed/reflowable
   - 提取 manifest 每个 `<item>` 为 `RDEPUBManifestItem`
   - 提取 spine 每个 `<itemref>` 为 `OPFSpineReference`
5. 构建 spine：`buildSpine(from:opfURL:)`
   - 将 spine reference 匹配到 manifest item
   - 标准化 href（相对于 OPF 目录）
   - 确定每项的有效 layout（显式属性覆盖出版级设置）
   - 返回 `[RDEPUBSpineItem]`，空 spine 抛 `emptySpine` 错误
6. 解析目录：`parseTOC(from:opfURL:)`
   - 优先 NCX（`NCXParserDelegate`），其次 Nav Document（`NavDocumentParserDelegate`）
   - 兜底使用 spine 标题
   - href 标准化保留 fragment 标识符
7. 创建 Publication：`makePublication()` → `RDEPUBPublication(parser: self)`

### 3.2 阅读配置文件判断

- 入口：`RDEPUBParser+ReadingProfile.swift`
- 判断逻辑：
  - 扫描 manifest 检查是否有 `scripted` 属性的项
  - 扫描 HTML body 检查是否有 `script`、`iframe`、`video` 等交互元素
  - 结果：
    - `.webFixedLayout`：固定版式 EPUB（漫画、绘本）— WKWebView 渲染
    - `.webInteractive`：可重排 + 交互脚本 EPUB — WKWebView 渲染
    - `.textReflowable`：纯文本可重排 EPUB — DTCoreText 渲染

### 3.3 离屏分页测量

1. 入口：`RDEPUBPaginator.calculate(parser:hostingView:presentation:completion:)`
2. 初始化所有 spine 项页数为 `[1, 1, ..., 1]`
3. 固定版式直接返回（每 spread = 1 页）
4. 顺序遍历可渲染的 HTML/XHTML spine 项
5. 对每项：
   - `webView.loadFileURL(...)` 加载文件
   - `didFinish` 后启动多次测量（`scheduleMeasurementPass`）
   - 3 次测量延迟 [0ms, 80ms, 180ms]
   - 每次执行 `measurementScript`：注入分页 CSS → 测量 `scrollWidth` → 返回 `Math.max(1, Math.ceil(totalWidth / viewportWidth))`
   - 取多次测量的最大值
6. 全部完成后回调 `completion([Int])` 页数数组
7. `activeSessionID`（UUID）防止过期回调污染结果

### 3.4 WebView 可重排内容加载

1. 入口：`RDEPUBWebView.loadPage(parser:spineIndex:pageIndex:...)`
2. 计算 `loadSignature`（包含 publication key、spine index、href、viewport、字号、行高、主题色、目标位置、高亮等）
3. 若签名与 `currentLoadSignature` 相同且已渲染/正在加载，跳过重复请求
4. 若签名匹配但文档 URL 已加载，仅调用 `applyPresentation()` 重新应用样式
5. 否则 `handleReflowableLoad(...)` 执行完整加载：
   - 读取 HTML 内容
   - 调用 `applyPresentationScript(for:)` 生成 JS
   - JS 执行：`RDReaderBridge.applyPagination(css)` → `setPageMetrics` → 清除并重新应用高亮 → 滚动到目标位置 → 报告进度 → 应用搜索装饰

### 3.5 固定版式内容加载

1. 入口：`RDEPUBWebView.loadFixedSpread(parser:spread:...)`
2. `RDEPUBFixedLayoutTemplate.html(for:publication:)` 从模板生成 HTML，包含 spread 中每个资源的 `<iframe>`
3. `webView.loadHTMLString(html, baseURL: "ss-reader://book/")` 加载
4. 模板 JS 加载每个 iframe，检测页面尺寸，计算缩放（auto/page/width 适配模式），定位 iframe
5. 所有 iframe 加载完成后 JS 发送 `ssReaderFixedLayoutReady`
6. Swift 收到消息后应用搜索装饰并调用 `rendered()`
7. 1 秒兜底定时器确保即使 JS 消息丢失也能调用 `rendered()`

### 3.6 JS 桥接消息处理

- 入口：`RDEPUBWebView+JavaScriptBridge.swift` 的 `userContentController(_:didReceive:)`
- 分发逻辑：
  - `progressionChanged` → 提取 progression/lastProgression/fragment → `delegate?.epubWebView(_:didUpdateLocation:spineIndex:)`
  - `selectionChanged` → 提取 text/rangeInfo → 创建 `RDEPUBSelection` → `delegate?.epubWebView(_:didChangeSelection:spineIndex:)`
  - `internalLink` → 创建 `RDEPUBLocation` → `delegate?.epubWebView(_:didActivateInternalLink:fromSpineIndex:)`
  - `externalLink` → 提取 URL → `delegate?.epubWebView(_:didActivateExternalLink:)`
  - `javaScriptError` → `delegate?.epubWebView(_:didLogJavaScriptError:)`
  - `fixedLayoutReady` → 应用搜索装饰 → `rendered()`

### 3.7 链接导航拦截

- 入口：`decidePolicyFor navigationAction`
- 逻辑：
  - `ss-reader://` URL + `.linkActivated` → 内部链接代理回调，取消导航
  - `http/https/mailto/tel` → 外部链接代理回调，取消导航
  - 其他 → 允许导航

## 4. 异常与边界处理

- `RDEPUBParserError`（7 种，全部 `LocalizedError`，中文描述）：
  - `archiveOpenFailed(URL)`：ZIPFoundation 无法打开 EPUB 文件
  - `missingContainerXML`：`META-INF/container.xml` 不存在
  - `missingRootFile`：container.xml 中无 `<rootfile>`
  - `invalidRootFilePath(String)`：rootfile 路径对应的 OPF 文件不存在
  - `invalidXML(URL)`：XMLParser 无法创建或解析失败
  - `missingManifestItem(idref:)`：spine 引用了不存在的 manifest 项
  - `emptySpine`：构建后 spine 为空
- 目录解析：NCX 和 Nav Document 解析器失败时返回空数组，不抛异常，兜底使用 spine 标题
- 资源缺失：`RDEPUBResourceURLSchemeHandler` 对缺失的可选资源（字体/图片/CSS/JS）返回空 200，避免 WKWebView 控制台噪音
- 分页失败：`RDEPUBPaginator` 导航失败（`didFail` / `didFailProvisional`）时将页数设为 1 并继续下一项
- HTML 转纯文本兜底：`RDEPUBHTMLSearchEngine` 在 NSAttributedString 失败时回退到正则去标签
- 固定版式 1 秒兜底：`scheduleFixedLayoutReadyFallback()` 确保即使 JS ready 消息丢失也能调用 `rendered()`
- 重复请求跳过：`handleReflowableLoad` 在 loadSignature 匹配且已渲染/正在加载时跳过

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

### 5.1 EPUB 元数据

```
RDEPUBParser
  ├── metadata: RDEPUBMetadata
  │     ├── identifier, title, author, language, version
  │     ├── layout: RDEPUBLayout (.reflowable | .fixed)
  │     ├── readingProgression: RDEPUBReadingProgression (.ltr | .rtl | .auto)
  │     └── spread: String?
  ├── manifest: [String: RDEPUBManifestItem]
  │     ├── id, href, mediaType
  │     ├── properties: [String]  (nav, scripted, cover-image, rendition:layout-*)
  │     └── title: String?
  ├── spine: [RDEPUBSpineItem]
  │     ├── idref -> manifest[id]
  │     ├── href (normalized), mediaType, title, linear
  │     ├── pageSpread: RDEPUBPageSpread? (.left | .right | .center)
  │     └── layout: RDEPUBLayout? (per-item override)
  └── tableOfContents: [EPUBTableOfContentsItem]
        ├── title, href
        └── children: [EPUBTableOfContentsItem] (recursive)
```

### 5.2 阅读位置模型

```
RDEPUBLocation
  ├── bookIdentifier, href
  ├── progression: Double?       (0..1，章节内起始位置)
  ├── lastProgression: Double?   (0..1，章节内结束位置)
  ├── fragment: String?          (#anchor)
  └── navigationProgression      (computed: midpoint of progression and lastProgression)
```

### 5.3 视口模型

```
RDEPUBViewport
  ├── resources: [RDEPUBViewportResource]
  │     ├── href, spineIndex
  │     ├── progression, lastProgression, fragment
  ├── visiblePageNumber, chapterIndex
  └── isFixedLayout: Bool
```

### 5.4 渲染请求

```
RDEPUBRenderRequest (enum)
  ├── .reflowable(RDEPUBReflowableRenderRequest)
  │     ├── spineIndex, href, pageIndex, totalPagesInChapter
  │     ├── presentation: RDEPUBPresentationStyle
  │     │     ├── viewportSize, contentInsets
  │     │     ├── fontSize, lineHeightMultiple
  │     │     └── themeBackgroundColor, themeTextColor
  │     ├── targetLocation: RDEPUBLocation?
  │     ├── highlights: [RDEPUBHighlight]
  │     └── searchPresentation: RDEPUBSearchPresentation?
  └── .fixed(RDEPUBFixedRenderRequest)
        ├── spread: EPUBFixedSpread
        │     └── resources: [EPUBFixedSpreadResource]
        ├── viewportSize, contentInset
        ├── backgroundColorCSS
        ├── fit: RDEPUBFixedLayoutFit (.auto | .page | .width)
        └── searchPresentation: RDEPUBSearchPresentation?
```

### 5.5 高亮与选择

```
RDEPUBHighlight
  ├── id, bookIdentifier
  ├── location: RDEPUBLocation
  ├── text, rangeInfo (JSON-serialized DOM range)
  ├── color: String, note: String
  └── createdAt: Date

RDEPUBSelection
  ├── bookIdentifier
  ├── location: RDEPUBLocation
  ├── text, rangeInfo
  └── createdAt: Date
```

### 5.6 搜索模型

```
RDEPUBSearchState
  ├── keyword: String
  ├── matches: [RDEPUBSearchMatch]
  │     ├── href, progression
  │     ├── previewText, localMatchIndex
  │     ├── rangeLocation, rangeLength
  └── currentMatchIndex: Int
```

## 6. 分页与渲染机制

### 6.1 CSS 多栏分页原理

- HTML 内容被包裹为 `body > div#ss-reader-viewport > div#ss-reader-content`
- `#ss-reader-content` 应用 `-webkit-column-width: <viewportWidth>px`
- `html` / `body` 设置 `overflow: hidden`
- 页间导航通过 `transform: translate3d(-N*stride, 0, 0)` 实现

### 6.2 重新布局触发条件

- `scheduleRelayout()`（60ms 防抖）在以下事件触发：
  - `window.load`、`window.resize`
  - `document.fonts.ready`
  - 每个 `<img>` / `<iframe>` / `<video>` 的 load/error 事件

### 6.3 选择变化处理

- `selectionchange` 监听器（120ms 防抖）发送 `ssReaderSelectionChanged` 消息，携带 text、rangeInfo、progression

## 7. 缓存策略

- **EPUB 解压缓存**：解压目录按 `文件大小 + 修改时间` 生成缓存 key，已存在则跳过解压
- **Load Signature 去重**：每次渲染请求计算签名（含 publication key、layout、spine index、viewport、字号、行高、主题色、目标位置、高亮），相同签名跳过重复加载
- **WKWebView 复用**：同一 publication 配置下复用已有 WKWebView 实例，仅切换 publication 时才 teardown
- **非持久化数据存储**：`WKWebViewConfiguration().websiteDataStore = .nonPersistent()`，不缓存 Web 内容到磁盘

## 8. 联调与排查建议

- 排查 1：EPUB 解析失败
  - 检查 `parse(epubURL:)` 抛出的 `RDEPUBParserError` 具体类型
  - 检查 EPUB 文件是否损坏（ZIP 能否正常打开）
  - 检查 `META-INF/container.xml` 是否存在且格式正确
- 排查 2：目录为空
  - 检查 OPF 中是否有 NCX 或 Nav Document 引用
  - 检查 NCX 文件路径是否正确（相对于 OPF 目录）
  - 目录解析失败时会兜底使用 spine 标题
- 排查 3：页面内容空白
  - 检查 `ss-reader://` scheme handler 是否正确映射资源路径
  - 检查 `RDEPUBResourceURLSchemeHandler` 日志（`RDEPUBWebViewDebug`）
  - 确认 HTML 文件在解压目录中实际存在
- 排查 4：分页页数不正确
  - 检查 `RDEPUBPaginator` 多次测量结果是否一致
  - 检查 viewport 尺寸计算是否正确（容器宽度 / pagesPerScreen）
  - 检查 CSS 分页样式是否正确注入
- 排查 5：JS 桥接消息未收到
  - 确认 `epub-bridge.js` 已正确注入（检查 `WKUserContentController`）
  - 检查 JS 控制台是否有错误
  - 固定版式检查是否收到 `ssReaderFixedLayoutReady`，否则看 1 秒兜底定时器
- 排查 6：内部链接不跳转
  - 检查链接 href 是否以 `ss-reader://` 开头
  - 检查 `decidePolicyFor navigationAction` 中的链接类型判断
  - 确认 `RDEPUBLocation` 构建是否正确（href + fragment）