Reorganize docs and update reader search flows

2026-06-10 08:22:07 +08:00
parent 0e7c0577e3
commit d15187b730
72 changed files with 517 additions and 5214 deletions
@@ -0,0 +1,85 @@
+# 编码规范
+
+**分析日期：** 2026-05-21
+
+> 说明：本仓库以 iOS/Swift 为主，未检测到统一的 lint/format 工具配置；代码风格在不同模块间存在差异。文档按项目规则使用中文描述，但代码标识符保持英文。
+
+## 语言与工程约束
+
+- **主要语言**：Swift（Podspec 声明 `s.swift_versions = ["5.10"]`，见 `RDReaderView.podspec`）
+- **最低系统版本**：Podspec `iOS 15.0`（`RDReaderView.podspec`），示例工程 Podfile/构建设置里常见为 `iOS 15.6`（`Podfile`）
+- **依赖管理**：CocoaPods（`Podfile`、`ReadViewDemo/Podfile`、`Podfile.lock`）
+
+## 命名约定
+
+**文件/类型命名（Swift）：**
+- 以类型名为文件名的单文件组织较常见：`Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`
+- 大量使用前缀区分模块域：
+  - `RD...`：阅读器 UI/控制器相关（如 `Sources/RDReaderView/RDReaderView.swift`、`Sources/RDReaderView/RDURLReaderController.swift`）
+  - `RDEPUB...`：EPUB Core/UI/渲染相关（如 `Sources/RDReaderView/EPUBCore/RDEPUBModels.swift`）
+- Extension 文件使用 `+` 命名：`Sources/RDReaderView/EPUBUI/RDEPUBReaderController+ContentDelegates.swift`
+
+**变量/函数命名：**
+- 基本遵循 Swift lowerCamelCase：`parse(epubURL:)`（`Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`）
+- 常量多用 `static let`：`kRDEPUBHighlightAttributeName`（`Sources/RDReaderView/EPUBCore/Models/RDEPUBAnnotationModels.swift`）
+
+## 代码风格与排版（从现有代码归纳）
+
+**缩进与换行：**
+- 多数文件使用 4 空格缩进（示例：`ReadViewDemo/ReadViewDemo/ViewController.swift`、`Sources/RDReaderView/EPUBCore/RDEPUBModels.swift`）
+- 历史代码中更常见”强制换行/多行括号”风格
+
+**空行与分组：**
+- UI 相关文件常用空行分隔属性/初始化/布局段落
+- `// MARK:` 用于分区组织（示例：`Sources/RDReaderView/RDReaderGestureController.swift`、`Sources/RDReaderView/EPUBTextRendering/RDPlainTextBookBuilder.swift`）
+
+**类型组织：**
+- 偏好用 `extension` 拆分职责/协议实现（示例：`ReadViewDemo/ReadViewDemo/ViewController.swift` 的 `UITableViewDataSource/Delegate`）
+- API 暴露处使用 `public`、`public final class`、`public enum/struct`（示例：`Sources/RDReaderView/EPUBCore/RDEPUBModels.swift`）
+- “对外只读、内部可写”常用 `public internal(set)`（示例：`Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`）
+
+## 导入与依赖使用
+
+**import：**
+- UIKit/UI 文件：`import UIKit`（大量文件）
+- Core/模型文件：`import Foundation`（如 `Sources/RDReaderView/EPUBCore/RDEPUBModels.swift`）
+- 三方依赖按需引入：
+  - `SnapKit`：布局
+  - `SSAlertSwift`：弹窗/提示
+
+**Pods 目录说明：**
+- `ReadViewDemo/Pods/**` 为依赖源码/生成配置，通常不作为本仓库代码风格的“标准样式”参考。
+
+## 错误处理与日志
+
+- Core 解析层倾向用 `throws` + 自定义 `Error`（示例：`Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`、`Sources/RDReaderView/EPUBCore/RDEPUBModels.swift` 的 `RDEPUBParserError`）
+- UI/控制器层常见 `guard` 早返回（示例：`ReadViewDemo/ReadViewDemo/ViewController.swift`）
+- 未检测到统一日志框架（未发现专用 logging package/config）；出现时以系统 API/局部输出为主（需按具体文件核对）。
+
+## 注释与文档
+
+- **项目规则（强约束）**：代码标识符保持英文，但**代码注释/文档/提交信息使用中文**（见 `CONTEXT.md`）。
+- 历史文件常带 Xcode 头部注释块（示例：`Sources/RDReaderView/ReaderView/RDReaderView.swift`）。
+- 公共 API 处存在少量三斜线文档注释（示例：`Sources/RDReaderView/RDReaderView.swift` 的中文说明）。
+
+## Lint / Formatter / 静态检查
+
+**未检测到（仓库根与常见位置）：**
+- SwiftLint 配置：`.swiftlint.yml` / `swiftlint.yml`
+- SwiftFormat 配置：`.swiftformat`
+- 通用格式化配置：`.editorconfig`
+- 其他：ESLint/Prettier/Biome 等（本仓库非 JS/TS 主体）
+
+**可执行的工程级格式化/检查：**
+- 主要依赖 Xcode（或 Swift 编译器）自身检查；如需引入 SwiftLint/SwiftFormat，应先新增对应配置文件并在 CI/构建脚本中接入。
+
+## Evidence（关键证据文件）
+
+- `CONTEXT.md`
+- `Podfile`
+- `RDReaderView.podspec`
+- `ReadViewDemo/ReadViewDemo/ViewController.swift`
+- `Sources/RDReaderView/ReaderView/RDReaderView.swift`
+- `Sources/RDReaderView/EPUBCore/RDEPUBParser.swift`
+- `Sources/RDReaderView/EPUBCore/RDEPUBModels.swift`
+- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`