150 lines
6.8 KiB
Markdown
150 lines
6.8 KiB
Markdown
# 代码库结构
|
||
|
||
**分析日期：** 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*
|