docs: add codebase map

2026-05-21 20:36:12 +08:00
parent faa069ec99
commit 4daa3a6ed4
7 changed files with 764 additions and 0 deletions
@@ -0,0 +1,149 @@
+# 代码库结构
+
+**分析日期：** 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*