ReadViewSDK/.planning/codebase/STRUCTURE.md

代码库结构

分析日期： 2026-05-21

目录布局

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