diff --git a/.planning/ARCHITECTURE-CONTEXT.md b/.planning/ARCHITECTURE-CONTEXT.md new file mode 100644 index 0000000..291d1ef --- /dev/null +++ b/.planning/ARCHITECTURE-CONTEXT.md @@ -0,0 +1,115 @@ +# 架构分析:WXRead 参考 vs ReadViewSDK 当前 + +**分析日期:** 2026-05-23 +**分析基础:** `Doc/WXRead/decompiled-doc.md`、`Doc/WXRead/resources-doc.md`、`Doc/WXRead/读书EPUB阅读器实现架构.md` +**状态:** Decisions captured + +--- + + +## 分析范围 + +对比读书 (WeRead v10.0.3) 逆向架构与当前 ReadViewSDK 项目的结构性差距,聚焦四大方向:分页引擎集成、CSS 处理、渲染架构、字体系统。 + +读书 EPUB 渲染的核心架构特征: +- Path A (EPUB): 纯 CoreText 渲染 — `WRPageView.drawRect:` → `CTFrameDraw`,不用 UITextView/UILabel +- 4 级语义断页:`WRCoreTextLayouter` + `WRCoreTextLayoutFrame` (语义边界 > 附件边界 > 块边界 > 帧限制) +- 5 层 CSS 级联:`default.css < replace.css < dark.css < EPUB 内嵌 < 用户设置` +- 字符级位置精度:`WREpubPositionConverter` (fileIndex, row, column) ↔ 全局字符偏移 +- 标注直接在 CTFrame 层叠加绘制,搜索高亮同理 + + + + +## 已决事项 + +### Area 1: 分页引擎集成(P0) + +| 决策 | 说明 | +|------|------| +| 将 `RDEPUBTextLayouter` 集成到 `RDEPUBTextBookBuilder` | 内部调用 `rd_paginatedFrames(size:)` 替代旧的 `ss_pageRanges(size:)`,外部 API 不变 | +| 分页元数据暴露到 `RDEPUBTextPage` | 新增 `metadata: RDEPUBTextPageMetadata` 字段(含 breakReason/blockKinds/semanticHints),对外暴露分页质量数据 | +| `RDEPUBTextChapterPaginationDiagnostic` 增强 | 透传 RDEPUBTextLayoutFrame 的诊断信息 | +| 分页缓存 | 按 `bookID + fontSize + lineHeightMultiple + contentInsets` 生成缓存 key,缓存完整 `RDEPUBTextBook` 到磁盘 | + +### Area 2: CSS `` 外部样式表处理(P0) + +| 决策 | 说明 | +|------|------| +| 预处理内联 CSS | 渲染前扫描 HTML 中 `` 标签,从 EPUB 解压目录读取 CSS 内容,注入 `"; - result = result.replace("", insertStyle); - result = result.replace("", insertJs); - return result; -} - -generator.generateHtmlForMPReview = function (content,js, css) { - var result = generator.generateHtml(content,js,css) - var modifiedCopyRight = "