# 代码库结构

**分析日期：** 2026-05-21

## 目录布局

```text
ReadViewSDK/
├── Sources/
│   └── RDReaderView/                # SDK 实现（Swift）
│       ├── EPUBCore/                # EPUB 解压/解析/模型/分页/状态（Foundation/WebKit）
│       ├── EPUBTextRendering/       # TXT/TextBook 构建 + 文本渲染/搜索
│       ├── EPUBUI/                  # 阅读器控制器 UX、设置、持久化、工具视图
│       ├── LegacyRDReaderController/# 旧版阅读器控制器 + 工具视图
│       ├── Resources/               # 资源（pod resource bundle）
│       ├── RDReaderView.swift        # 核心分页视图 + DS/delegate 协议
│       ├── RDReaderFlowLayout.swift  # 滚动模式的 CollectionView 分页布局
│       └── RDURLReaderController.swift # 基于 URL 的入口控制器
├── ReadViewDemo/
│   ├── ReadViewDemo/                # Demo App 源码/资源（UIKit）
│   ├── ReadViewDemo.xcodeproj/      # Demo target 的 Xcode project
│   ├── ReadViewDemo.xcworkspace/    # 集成 Pods 工程的 workspace
│   ├── Podfile                      # Demo 的 Pods 集成（本地 path）
│   └── Podfile.lock                 # Demo 的锁定依赖版本
├── Pods/                            # 仓库根目录的 CocoaPods 产物（本地开发）
├── Podfile                          # 仓库级 Pods 集成脚本（见说明）
├── RDReaderView.podspec             # SDK 的 Podspec（分发与依赖声明）
├── Doc/                             # 参考资料/分析产物
└── .planning/codebase/              # 生成的代码库地图（本目录）
```

## 目录职责

**`Sources/RDReaderView/EPUBCore`：**
- 目的：EPUB 解压 + 解析 + 核心模型 + 分页 + 导航状态。
- 关键文件：
  - `Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`
  - `Sources/RDReaderView/EPUBCore/RDEPUBPaginator.swift`
  - `Sources/RDReaderView/EPUBCore/RDEPUBPublication.swift`
  - `Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift`

**`Sources/RDReaderView/EPUBUI`：**
- 目的：阅读器 UX 协调与对外 reader controller API。
- 关键文件：
  - `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`
  - `Sources/RDReaderView/EPUBUI/RDEPUBReaderConfiguration.swift`
  - `Sources/RDReaderView/EPUBUI/RDEPUBReaderPersistence.swift`

**`Sources/RDReaderView/EPUBTextRendering`：**
- 目的：从 `.txt` 构建 `RDEPUBTextBook`，并提供渲染/搜索等能力。
- 关键文件：
  - `Sources/RDReaderView/EPUBTextRendering/RDPlainTextBookBuilder.swift`
  - `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift`
  - `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift`

**`Sources/RDReaderView`（顶层文件）：**
- 目的：SDK 的对外入口与核心分页视图/布局基础设施。
- 关键文件：
  - `Sources/RDReaderView/RDURLReaderController.swift`
  - `Sources/RDReaderView/RDReaderView.swift`
  - `Sources/RDReaderView/RDReaderFlowLayout.swift`

**`ReadViewDemo/ReadViewDemo`：**
- 目的：Demo App，用于发现内置书籍并打开 SDK。
- 关键文件：
  - `ReadViewDemo/ReadViewDemo/ViewController.swift`
  - `ReadViewDemo/ReadViewDemo/AppDelegate.swift`
  - `ReadViewDemo/ReadViewDemo/SceneDelegate.swift`

## 关键文件位置

**SDK 入口点：**
- `Sources/RDReaderView/RDURLReaderController.swift`：URL 入口（epub/txt 路由）。
- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`：主阅读器控制器（EPUB + external TextBook）。
- `Sources/RDReaderView/RDReaderView.swift`：分页视图与 data source/delegate 协议。

**Demo 入口点：**
- `ReadViewDemo/ReadViewDemo/AppDelegate.swift`：App 生命周期入口（`@main`）。
- `ReadViewDemo/ReadViewDemo/SceneDelegate.swift`：Window 与 root navigation controller 配置。
- `ReadViewDemo/ReadViewDemo/ViewController.swift`：书籍列表 → 打开 reader。

**配置/打包：**
- `RDReaderView.podspec`：SDK 打包（源码 + 资源 + 依赖）。
- `ReadViewDemo/Podfile`：Demo 的 Pods 集成（`pod 'RDReaderView', :path => '..'`）。
- `ReadViewDemo/ReadViewDemo.xcworkspace/contents.xcworkspacedata`：workspace 结构。

## 命名约定

**模块（目录）划分：**
- `EPUBCore`、`EPUBUI`、`EPUBTextRendering`：按职责分层拆分于 `Sources/RDReaderView/` 下。

**类型前缀：**
- `RD*`：阅读器容器视图与 legacy controller/tooling（例如 `RDReaderView`、`RDURLReaderController`）。
- `RDEPUB*`：EPUB 解析/分页/阅读器 UI 域（例如 `RDEPUBParser`、`RDEPUBPaginator`、`RDEPUBReaderController` 及相关模型）。

## 组件关系（从入口到渲染）

- `RDURLReaderController` 根据文件类型选择实现：
  - `.epub` → `RDEPUBReaderController(epubURL:configuration:persistence:)`
  - `.txt` → `RDPlainTextBookBuilder` → `RDEPUBReaderController(textBook:...)`
  - 回退路径：分页失败时使用 `UITextView` 展示原始文本
  - 入口文件：`Sources/RDReaderView/RDURLReaderController.swift`
- `RDEPUBReaderController` 负责阅读器生命周期：
  - parse（`RDEPUBParser`）→ publication（`RDEPUBPublication`）→ paginate（`RDEPUBPaginator`）→ display（`RDReaderView`）
  - 通过 `RDEPUBReaderPersistence` 持久化设置/位置/书签/高亮等
  - 入口文件：`Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`

## 新代码应放在哪里

**新增面向读者的 UI 功能（工具视图/菜单/手势）：**
- 主要：`Sources/RDReaderView/EPUBUI/`
- 若影响分页呈现：`Sources/RDReaderView/RDReaderView.swift` 或 `Sources/RDReaderView/RDReaderFlowLayout.swift`

**新增 EPUB 解析/模型支持：**
- 主要：`Sources/RDReaderView/EPUBCore/`（parser/models/resolver）

**新增纯文本导入/渲染行为：**
- 主要：`Sources/RDReaderView/EPUBTextRendering/`

**更新 Demo / 复现步骤：**
- 主要：`ReadViewDemo/ReadViewDemo/`

## 特殊目录说明

**`Pods/` 与 `ReadViewDemo/Pods/`：**
- 用途：CocoaPods 生成产物，服务本地开发/示例工程。
- 是否生成：是。
- 是否提交：当前工作区中存在（通常按生成目录对待）。

**`Doc/`：**
- 用途：文档/分析资料（不属于 SDK 运行时的一部分）。

## Evidence（关键证据）

检查过的关键文件：
- `RDReaderView.podspec`
- `Podfile`
- `ReadViewDemo/Podfile`
- `ReadViewDemo/ReadViewDemo.xcodeproj/project.pbxproj`
- `ReadViewDemo/ReadViewDemo.xcworkspace/contents.xcworkspacedata`
- `ReadViewDemo/ReadViewDemo/ViewController.swift`
- `Sources/RDReaderView/RDURLReaderController.swift`
- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`
- `Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`
- `Sources/RDReaderView/EPUBCore/RDEPUBPaginator.swift`

---

*结构分析：2026-05-21*