4.1 资料库与导入#

主要代码位于 Qingyue/App/AppStore.swift 和 Sources/QingyueCore/LibraryRepository.swift。

文件导入经过以下步骤：

1. 从系统文件选择器获取文件 URL，申请临时安全作用域访问。
2. 使用 NSFileCoordinator 协调文件提供方，把文件复制到应用拥有的暂存位置。
3. 检查格式、体积与文件内容；压缩包先执行路径和资源限制检查。
4. 解析书名、作者、封面、章节或图片列表，建立文件指纹和资源关联。
5. 文件落地成功后再提交资料库元数据；失败时清理本次暂存内容。

LibraryRepository 使用 actor 串行处理资料库写入，元数据通过原子文件替换保存。当前数据模型为 schema 3，兼容旧版本字段，拒绝未知的未来版本；解码失败不会用空资料库覆盖原文件。

应用沙盒内的目录用途如下，均为通用结构：

1
Library/Application Support/Qingyue/
2
  library.json           图书、设置、阅读资料和会话等元数据
3
  Books/                 原书、TXT 分章文件、EPUB 或漫画资源
4
  Cache/Temporary/       自动产生的临时阅读缓存
5
  Cache/Offline/         用户主动下载的离线内容
6
  Thumbnails/            远端封面缩略图
7
  Covers/                自定义封面
8
  Exports/               导出产物
9
  Temporary/             导入、解析和恢复过程的暂存文件
10
Documents/               用户可见的文件交换目录

清理临时缓存和删除主动离线下载是两个独立操作，使用系统确认界面呈现。原始图书与上述缓存分开存放，避免清理缓存时误删已导入的图书。

4.2 TXT 阅读与稳定位置#

TextParser 处理常见编码、BOM 和换行归一化，再根据章节规则生成目录和分章文件。页面展示由 TextKit 和可选字的 UITextView 完成，分页测量考虑字号、行距、段距和边距。

保存位置采用归一化正文的 UTF-16 偏移、章节位置和上下文锚点。字号变化后重新分页，再根据文本位置恢复；界面页码只用作展示。用户修改 TXT 分章规则时，先预览结果，再重建章节，并映射已有进度、书签和笔记。

4.3 EPUB 渲染与分页#

EPUBParser 读取容器、OPF、spine 和导航信息。渲染前清理不允许的内容，正文交给非持久化数据存储的 WKWebView 展示。出版物脚本被禁用，应用自身的位置逻辑放在隔离的 JavaScript content world 中。

横向阅读通过 CSS 分栏和受控滚动实现；位置保存使用章节相对路径、DOM 锚点、文字偏移及比例回退。字体、图片解码和视图尺寸稳定后才完成分页与位置恢复。

实际修复过的三个问题：

工具栏作为覆盖层显示和隐藏，保持正文视图尺寸稳定，避免打开目录入口时触发一次无意义的重新分页。

4.4 翻页动画与点击响应#

统一翻页入口位于 Qingyue/Readers/PageTurnHost.swift。

文字书支持滑动、覆盖、仿真、无动画和纵向滚动。滑动、覆盖使用视图变换，仿真使用 UIPageViewController 的 page curl；真实可选字正文在过渡后继续作为阅读内容。开启系统“减少动态效果”时关闭过渡动画。

最终的点击规则为：

• 横向阅读时，正文最右侧四分之一区域负责下一页；文字书章节末页继续点击进入下一章。
• 中间区域负责显示或隐藏工具栏；PDF 和漫画可在中间区域双击缩放。
• 右侧独立识别短按松手，不等待双击超时；超过 0.25 秒的按住动作不触发边缘翻页。
• 长按选字、已有选区、链接和原生控件继续优先处理对应操作。PDF、漫画放大后不通过右侧轻点换页。
• 纵向滚动和条漫模式不启用右侧单击分页。

1.4.3 的两项关键优化是拆分右侧与中间识别器，以及让已显示的旧页使用 snapshotView(afterScreenUpdates: false) 获取快照。仿真动画的新页仍在更新后截图，保证内容正确。

响应时间从手指松开开始，测到动画提交后的下一显示帧时间点，目标不超过 200 毫秒。这个指标与用户可调的完整动画播放时长分别计算。诊断探针只在 Debug 显式开启，Release 不包含探针代码。

4.5 PDF 与漫画#

PDF 直接使用 PDFKit，支持缩略图、页码跳转、横向或纵向阅读。有文字层的 PDF 支持搜索、选字、笔记和听书；扫描图像本身不经过 OCR。笔记以应用内数据保存，显示时建立内存注释，不改写原 PDF。

漫画使用可复用的 UICollectionView 单元格和可缩放的滚动视图。图片通过 ImageIO 按目标尺寸解码，配合内存缓存、任务取消和少量相邻页预取，控制长漫画的内存占用。横向左右顺序与纵向条漫分别配置。

4.6 书架、主题与阅读工具#

书架将封面放入统一尺寸区域，固定底边和书名区域，配合木纹、层板与阴影形成分层展示。图书分类、标签、排序和自定义封面由资料库管理，重启后恢复。

阅读设置使用 ReadingPreferences 保存。全局默认设置与单本设置分开；主题可以覆盖文字色和背景色，字号、字距、行段距、边距和部分动画速度可以调整。导入字体先校验再注册，导入背景图片先下采样。

ReaderScreen 统一组织顶部的返回、目录、搜索、书签、设置，以及底部的上一章、进度条和下一章。文字书进度按章节位置计算，PDF 与本地漫画按页计算；不会把文字书百分比当作整本书预先完成的页数统计。

4.7 搜索、高亮与笔记#

BookSearch 在后台逐章搜索 TXT/EPUB，支持取消和结果上限。搜索与阅读使用一致的文字顺序和位置映射，使结果可以跳回原文。

选字后保存摘录、批注、颜色与 locator。TXT 使用 attributed text 高亮，EPUB 使用 CSS Highlight，PDF 使用内存注释。笔记可以按摘录、批注或书名搜索，支持回到原文和导出 Markdown。

简繁显示采用保持位置稳定的逐字转换，不改写原文件；不把它作为具有上下文理解能力的翻译。

4.8 听书与统计#

SpeechReader 使用 AVSpeechSynthesizer 分段朗读，通过 AVAudioSession 管理音频，结合 MediaPlayer 提供媒体信息和控制入口。它保存在应用状态生命周期中，使离开正文页面后仍能显示迷你播放器。

听书实现语速、系统声音、暂停继续、章节切换、定时停止和断点保存。Info.plist 声明后台音频能力。音频中断、耳机断开和锁屏控制已加入处理逻辑，真实设备上的完整场景仍需专门验收。

ReadingActivity 统计正文可见且应用在前台时的阅读时间；打开遮挡正文的设置等页面时暂停计时，两分钟无交互时暂停，自动滚动时继续。听书根据实际语音回调计时，避免与该书阅读时长重复累计。跨午夜的时段拆分到对应日期，重复恢复备份时按会话 ID 去重。

4.9 书源、缓存与网络#

书源使用清阅 JSON v1。SwiftSoup 处理 HTML/CSS 选择器，受限 JSON 路径处理 JSON 响应；支持搜索、详情、目录、正文或漫画图片提取。

网络层检查 HTTPS、标准端口和精确允许域名，重定向再次检查；请求有超时、并发、频率、体积和分页上限。配置文件不能携带敏感认证请求头，认证信息另存 Keychain。

临时阅读缓存与主动离线下载独立管理。章节和图片落地成功后再提交缓存元数据；下载任务记录未完成章节，失败或重启后可以继续剩余任务。这里的恢复是章节级恢复，不承诺任意服务器的字节级断点续传。

4.10 Wi-Fi、压缩包与备份#

Wi-Fi 传书只在用户开启时启动局域网接收服务，每次生成临时访问码。接收后仍由手机确认导入，离开传书页面或进入后台时关闭服务。开启传书可能触发系统本地网络权限提示。

归档读取检查路径穿越、符号链接、重复文件、解压总量、单文件大小和异常压缩比。普通压缩包包含多本书时，先列出候选文件供用户选择。当前不支持加密或分卷压缩包。

.qingyuebackup 包含本地图书、封面、元数据、阅读资料、资源和设置等；在线缓存、主动离线下载和认证凭据不包含在内。恢复先解压校验并展示预览，再按“跳过重复”或“保留两份”合并，已有图书不直接覆盖。单本导出保留或重新打包原出版物，应用内编辑的书名、封面等信息通过资料库备份保存。

5.1 环境要求#

先启动一次 Xcode，按提示完成许可与组件安装，并在设置中的平台或组件管理界面安装 iOS 27 模拟器运行时。

5.2 获取源码并确认工具链#

通过自己的代码仓库或源码压缩包取得项目，保留工程、核心包、锁定文件、测试资源及许可文件。本文不包含原开发环境的仓库地址或登录凭据。

将下面的通用路径替换成实际项目根目录：

1
cd '/path/to/qingyue-reader'
2
export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
3
xcodebuild -version
4
xcodebuild -showsdks
5
xcrun swift --version
6
xcrun simctl list runtimes

如果 Xcode 安装在其他位置，应相应调整 DEVELOPER_DIR。仅安装 Command Line Tools 无法完成 iOS 应用构建；不要通过单改部署版本数字来绕过缺少 SDK 的问题。

5.3 解析依赖#

1
xcodebuild -resolvePackageDependencies \
2
  -project Qingyue.xcodeproj \
3
  -scheme Qingyue

保留现有 Package.resolved。依赖升级应单独验证解析、归档、安全规则和阅读行为，避免排查 UI 问题时同时改变依赖版本。

5.4 打开和运行#

1
open Qingyue.xcodeproj

在 Xcode 中选择 Qingyue scheme 和一个 iOS 27 模拟器，再点击 Run。首次正常启动应显示空书架；通过加号导入 Fixtures/ 中的原创样书，分别检查 TXT、EPUB、PDF 和漫画。

工程已包含生成好的 .xcodeproj，首次运行不需要 XcodeGen。只有修改 project.yml、增加目标或调整工程结构时，才需要安装 XcodeGen 并执行：

1
xcodegen generate

生成后检查新增源码、资源、测试目标和签名设置。project.yml 中开发团队保持为空，由使用者自行配置。

5.5 使用命令行构建模拟器版本#

1
xcodebuild \
2
  -project Qingyue.xcodeproj \
3
  -scheme Qingyue \
4
  -destination 'generic/platform=iOS Simulator' \
5
  -derivedDataPath DerivedData/LocalBuild \
6
  CODE_SIGNING_ALLOWED=NO \
7
  build

看到 BUILD SUCCEEDED 才表示构建成功。这条命令只编译，不会自动安装到模拟器。

5.6 真机签名与安装#

1. 在 Xcode 账号设置中登录自己的开发者账号。
2. 在应用 target 的 Signing & Capabilities 中选择自己的 Team，启用自动签名。
3. 如果创建独立副本，将应用和 UI 测试 target 的 Bundle Identifier 改成自己管理的唯一标识。
4. 连接设备，完成电脑信任和开发者模式设置；系统要求时，在设备中信任对应开发者 App。
5. 选择设备运行。需要签名交互或启动验证时，保持设备解锁。

更新已有安装时，应保持兼容的 Bundle Identifier 和签名归属，先备份，再覆盖安装。修改 Bundle Identifier 会形成另一份应用安装，原有资料库不会自动迁移，应通过备份恢复处理。

个人免费签名受 Apple 当前的有效期和安装配额限制；出现配额不足时，通过 Xcode 查看实际原因。个人在用阅读器的卸载会影响其本地数据，不能把卸载重装当作普通更新步骤。

5.7 可选：生成测试素材#

正常编译和现有测试使用的固定素材已随项目提供。需要调整原创样书或重建图片、PDF 等素材时，可在项目内创建独立 Python 环境：

1
python3 -m venv DerivedData/FixtureTools
2
DerivedData/FixtureTools/bin/python -m pip install Pillow reportlab pypdf
3
DerivedData/FixtureTools/bin/python scripts/generate_fixtures.py

素材生成脚本会更新固定测试文件和部分生成资源，执行后应审阅差异。scripts/generate_reading_fixtures.py 用于额外的归档测试样本，依赖系统归档工具支持对应写入格式；通常无需重新生成已存在的样本。

6.1 核心逻辑和协议#

在完成工具链配置后执行：

1
swift test
2
swift run qingyue-validate docs/example-source.json

核心测试覆盖解析、编码、位置映射、资料库迁移、搜索、归档限制、备份恢复、书源与网络策略，以及阅读统计等。书源校验器检查配置结构与语义，但配置通过不代表某个线上网站当前可访问。

6.2 模拟器 UI 测试#

先查看本机可用模拟器，再把占位符替换为自己创建的测试模拟器标识。UI 测试会重置该模拟器中的测试资料库，不应指向保存个人图书的运行环境。

1
xcrun simctl list devices available
2
export QINGYUE_SIMULATOR_ID='REPLACE_WITH_TEST_SIMULATOR_ID'

对点击翻页和延迟执行定向回归：

1
xcodebuild \
2
  -project Qingyue.xcodeproj \
3
  -scheme Qingyue \
4
  -destination "platform=iOS Simulator,id=$QINGYUE_SIMULATOR_ID" \
5
  -derivedDataPath DerivedData/UITests \
6
  -parallel-testing-enabled NO \
7
  -resultBundlePath DerivedData/UITests/ReaderTap.xcresult \
8
  -only-testing:QingyueUITests/ReaderUITests/testRightEdgeTapResponseTime \
9
  -only-testing:QingyueUITests/ReaderUITests/testRightEdgeTapTextAndEPUB \
10
  -only-testing:QingyueUITests/ReaderUITests/testRightEdgeTapPDFAndComic \
11
  CODE_SIGNING_ALLOWED=NO \
12
  test

再次运行时，为 -resultBundlePath 指定一个新的结果包名称；Xcode 不会覆盖已有的同名结果目录。

现有综合脚本也可以使用：

1
./scripts/verify.sh --build-only
2
SIMULATOR_ID="$QINGYUE_SIMULATOR_ID" ./scripts/verify.sh

--build-only 包含核心测试、书源示例校验和应用编译；完整脚本增加模拟器 UI 回归，排除需要额外素材的两项压力测试。部分历史专项脚本带有原开发环境的模拟器配置，换机器时应先审阅配置，优先使用上面可自行指定目标的命令。

生成的结果包和原始日志可能含设备标识、主机路径、界面截图等信息，应保留在本地。若要分享测试结果，另行导出脱敏摘要。

6.3 建议的人工验收流程#

6.4 已有验证结果与边界#

以下是历史开发记录的脱敏汇总，不表示本文生成时重新运行了这些测试：

26 次计时包含 TXT 和 EPUB 各四种动画、每种三次，以及 PDF、漫画各一次。计时终点是动画提交后的下一显示帧时间点，并非硬件屏幕像素的直接测量；章节加载、其他设备和高系统负载需要另外评估。

前后台自动化不能替代真实手机的锁屏与密码解锁验收。听书的锁屏操作、耳机断开、来电和不同定时时长，以及跨设备 Wi-Fi 传书，应安排真机场景检查。旧版本测试结果也不能直接证明新版本的帧率或长期内存表现。