diff --git a/.planning/MILESTONES.md b/.planning/MILESTONES.md new file mode 100644 index 0000000..191b46a --- /dev/null +++ b/.planning/MILESTONES.md @@ -0,0 +1,26 @@ +# Milestones + +## v1.0 + +- **Date:** 2026-05-22 +- **Scope:** Phases 1-5, 13 plans +- **Archive:** [v1.0-ROADMAP.md](/Users/shen/Work/Code/ReadViewSDK/.planning/milestones/v1.0-ROADMAP.md) +- **Requirements:** [v1.0-REQUIREMENTS.md](/Users/shen/Work/Code/ReadViewSDK/.planning/milestones/v1.0-REQUIREMENTS.md) +- **Audit:** [v1.0-MILESTONE-AUDIT.md](/Users/shen/Work/Code/ReadViewSDK/.planning/v1.0-MILESTONE-AUDIT.md) + +### Delivered + +- Directly evolved the native reflowable EPUB path toward a WXRead-style renderer instead of introducing a parallel engine. +- Added chapter-level CSS preprocessing, explicit CSS layering, and chapter-scoped renderer inputs. +- Upgraded pagination to use richer page metadata and layouter/layout-frame semantics while preserving offset compatibility. +- Reconnected reader restore, highlight, search, and repagination behavior without modifying `RDReaderView`. +- Built a 5-book validation matrix across native reflowable, fixed/interactive WebKit, and TXT paths. + +### Known Gaps + +- `REND-01`, `REND-02`, `REND-03`, `REND-04` +- `COMP-01`, `COMP-03`, `COMP-04` +- `STAB-01`, `STAB-02` + +Known gaps were accepted at close as requirement bookkeeping debt; see the milestone audit for details. + diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index a03cedf..2726fc4 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -8,6 +8,12 @@ 稳定可用的 EPUB/TXT 阅读体验。 +## Current State + +- 已完成 `v1.0`：现有 reflowable EPUB native path 已完成一轮 WXRead 风格原生化演进。 +- chapter-level CSS 分层、页面元数据、复杂分页、reader restore/search/highlight 回接，以及 demo 样本矩阵都已落地。 +- Fixed Layout / interactive EPUB 仍保持 `WKWebView` 路径，`RDReaderView` 仍保持既有分页容器契约。 + ## 需求 ### 已验证（现有能力） @@ -19,10 +25,11 @@ - ✓ 固定版式（Fixed Layout）与交互式内容存在 `WKWebView` 相关能力与桥接（现有） - ✓ TXT 通过 `RDPlainTextBookBuilder` / `RDEPUBTextBook` 路径进入同一阅读器 UX（现有） - ✓ 默认使用 `UserDefaults` 进行部分阅读器状态/设置持久化（现有） +- ✓ v1.0 已完成 native reflowable 原生化基础：CSS 分层、页面级 metadata、分页器强化、reader 回接与样本矩阵验证（v1.0） ### 进行中（本次范围） -- [ ] 将 **reflowable EPUB** 的现有旧引擎直接重构为参考 `Doc/WXRead/` 的“微信读书（WXRead）原生渲染方案”，覆盖 CSS 分层、自定义 DTCoreText 属性体系、页面级元数据、复杂分页与 reader 集成能力，并在 SDK 内稳定落地且可回归验证 +- [ ] v1.1 继续补齐 WXRead 深化对齐：layout frame 几何能力、自定义分页属性闭环、分页质量/缓存、以及更强的自动化验证 ### 不做（明确排除） @@ -54,10 +61,17 @@ | 决策 | 原因 | 结果 | |---|---|---| -| reflowable EPUB 旧引擎直接重构为 WXRead 风格原生渲染 | 需要页面级排版能力，而不是继续在轻量 renderer 外壳上打补丁 | — Pending | -| Fixed Layout 与交互式 EPUB 继续使用 `WKWebView` | 降低风险与范围，避免破坏既有能力 | — Pending | -| 不保留并行 reflowable 原生引擎 | 避免双引擎长期维护成本，把演进压力集中在现有主路径上 | — Pending | -| 不修改当前翻页代码 | 控制改动半径，避免把阅读容器与翻页交互回归风险卷入本次内核重构 | — Pending | +| reflowable EPUB 旧引擎直接重构为 WXRead 风格原生渲染 | 需要页面级排版能力，而不是继续在轻量 renderer 外壳上打补丁 | ✓ Good | +| Fixed Layout 与交互式 EPUB 继续使用 `WKWebView` | 降低风险与范围，避免破坏既有能力 | ✓ Good | +| 不保留并行 reflowable 原生引擎 | 避免双引擎长期维护成本，把演进压力集中在现有主路径上 | ✓ Good | +| 不修改当前翻页代码 | 控制改动半径，避免把阅读容器与翻页交互回归风险卷入本次内核重构 | ✓ Good | + +## Next Milestone Goals + +- 补齐 native text `layout frame` 几何查询能力，减少 reader 交互对 `UITextView` 黑盒的依赖 +- 建立 WXRead 风格自定义分页属性从 HTML/CSS 到 paginator 的闭环 +- 提升复杂图文章节分页质量，并增加缓存与性能采样 +- 把 native reflowable 主路径的验证从 runtime spot-check 提升到自动化或稳定半自动化 ## 演进 @@ -77,4 +91,4 @@ 4. 更新背景与上下文到当前真实状态 --- -*Last updated: 2026-05-21 after initialization* +*Last updated: 2026-05-22 after v1.0 milestone completion* diff --git a/.planning/REQUIREMENTS-v1.1-WXRead-next.md b/.planning/REQUIREMENTS-v1.1-WXRead-next.md new file mode 100644 index 0000000..b155386 --- /dev/null +++ b/.planning/REQUIREMENTS-v1.1-WXRead-next.md @@ -0,0 +1,110 @@ +# 需求：ReadViewSDK v1.1（WXRead 深化对齐） + +**定义日期：** 2026-05-22 +**核心价值：** 在已完成的 reflowable EPUB 原生化基础上，继续补齐 WXRead 风格的页面级排版能力、阅读交互精度与回归可验证性。 + +## 背景 + +v1 已完成以下主目标： + +- reflowable EPUB 已具备 WXRead 风格的五层 CSS 组织与章节级 render context +- 分页器已具备 block / attachment 边界感知与页面元数据输出 +- reader 主流程、高亮、搜索、位置恢复、主题/字号/行高重分页已接回 +- fixed layout / interactive EPUB 继续保持 `WKWebView` 路径 + +与 `Doc/WXRead/analysis/` 对照后，当前主要差距已不在“是否走原生管线”，而在以下深化能力： + +- 页面级 layout frame 的几何查询与绘制能力不足 +- 自定义 CSS / attributed string 属性到分页器的闭环仍不完整 +- 分页质量、缓存、复杂块元素规则与自动化验证仍弱于 WXRead + +## v1.1 需求（本次范围） + +### 页面级布局与几何能力 + +- [ ] **LAYOUT-01**：为 native text 分页结果补齐页面级 layout frame 几何查询能力，至少包括字符串范围矩形查询、矩形反查文本范围、截断检测、命中定位所需的基础 API +- [ ] **LAYOUT-02**：阅读器侧的高亮、搜索命中、选区、点击定位等行为应优先建立在 layout frame 几何能力之上，而不是继续强依赖 `UITextView` 的黑盒行为 +- [ ] **LAYOUT-03**：页面级模型需要继续保留并兼容 `pageStartOffset`、`pageEndOffset`、`fragmentOffsets`、`RDEPUBTextOffsetRangeInfo` 等既有语义 + +### WXRead 自定义属性闭环 + +- [ ] **ATTR-01**：补齐一条从章节 HTML / CSS 到 `NSAttributedString` 再到分页器的自定义属性闭环，至少覆盖 `avoidPageBreakInside`、`pageBreakBefore`、`pageBreakAfter`、`pageRelate` +- [ ] **ATTR-02**：图片与附件相关排版需要支持类似 `wr-vertical-center-style` 的语义输入，并在分页 / 展示阶段保留可消费的信息 +- [ ] **ATTR-03**：复杂块元素至少要能区分代码块、表格、列表、引用块等类别，以支持更精细的分页边界控制与诊断 + +### 分页质量与性能收敛 + +- [ ] **QUAL-01**：为 layout frame / 分页结果增加缓存机制，避免同一章节在相同视口与排版配置下重复全量排版 +- [ ] **QUAL-02**：复杂图文章节的分页质量要进一步提升，减少不合理断页、孤行/寡行、图片前后留白异常、代码块/表格被粗暴截断等问题 +- [ ] **QUAL-03**：图片与附件的尺寸策略、暗色模式适配、页面背景类信息需要具备可验证的处理规则，而不是依赖默认 DTCoreText 行为 +- [ ] **QUAL-04**：分页深化后不能显著恶化首屏时间、重分页耗时或交互流畅度；若无法立即建立硬性指标，至少要输出稳定的诊断与采样数据 + +### 稳定性与自动化验证 + +- [ ] **AUTO-01**：建立覆盖 native reflowable 主路径的自动化回归能力，至少覆盖打开书籍、分页完成、搜索命中、主题/字号切换、位置恢复 +- [ ] **AUTO-02**：样本矩阵需要持续覆盖复杂图文、代码/表格/列表、附件密集、fixed/interactive WebKit、TXT 五类路径 +- [ ] **AUTO-03**：每项核心能力都应尽量附着到可重复证据：日志、断言、诊断摘要、UI 自动化步骤或稳定的人工检查清单 + +## 成功标准 + +以下结论必须全部为 TRUE： + +1. native reflowable 路径拥有可复用的页面几何查询能力，reader 交互不再主要依赖 `UITextView` 推断页面几何 +2. 至少一组 WXRead 风格自定义分页属性已形成端到端闭环，并对复杂块元素分页产生可见收益 +3. 同一批复杂样本在新一轮分页器深化后，分页质量优于当前 v1 完成态，而不是仅增加结构复杂度 +4. 自动化或半自动化验证覆盖到 native text 的关键交互，不再主要依赖单次手工 spot check +5. fixed layout、interactive EPUB、TXT 和既有 `RDReaderView` 翻页容器不回归 + +## 非目标（本次明确不做） + +| 功能 | 原因 | +|---|---| +| 重写或替换 `RDReaderView` 翻页容器 | 本次继续只深化 native reflowable 内核与页面几何能力 | +| 复刻 WXRead 的完整业务层能力（翻译/双语、免费试读、网络协议、DRM） | 这些属于业务闭环，不是当前 SDK 与 WXRead 的主要技术差距 | +| 将 fixed layout / interactive EPUB 改为原生渲染 | 仍保持 `WKWebView` 路径以控制风险 | +| 直接拷贝微信读书私有 CSS / JS / 私有实现代码 | 仅参考设计思路，不直接搬运私有实现 | +| 一次性完整重写成自绘 `WRPageView` 等价体系 | 风险过大，优先通过 layout frame 几何层与局部 reader 接线演进 | + +## 风险与约束 + +- `RDReaderView`、现有 page curl / horizontal / vertical 交互逻辑继续视为稳定容器契约 +- `RDEPUBReaderController` / `RDURLReaderController` 公开入口必须保持兼容 +- 所有分页深化都必须保留 offset-based 兼容语义，避免破坏现有高亮、搜索、恢复位置数据 +- 若要引入自绘或替换 `UITextView` 页面展示，需要以“先引入几何能力、再最小替换”的顺序推进 +- 若性能采样显示分页深化明显拖慢主流程，应优先做缓存与局部优化，而不是继续扩展特性面 + +## 建议优先级 + +1. `LAYOUT-*`：先补 layout frame 几何能力 +2. `ATTR-*`：再补自定义属性到分页器闭环 +3. `QUAL-*`：随后做分页质量与缓存收敛 +4. `AUTO-*`：最后把运行时验证补成自动化或稳定半自动化 + +## 候选 Phase 映射 + +| 需求 | 建议 Phase | 说明 | +|---|---:|---| +| LAYOUT-01 | Phase 6 | layout frame 几何 API 与截断检测 | +| LAYOUT-02 | Phase 6 | reader 交互从 `UITextView` 推断迁移到几何层 | +| LAYOUT-03 | Phase 6 | 保持 offset / fragment 兼容契约 | +| ATTR-01 | Phase 7 | 自定义分页属性闭环 | +| ATTR-02 | Phase 7 | 图片 / 附件布局语义 | +| ATTR-03 | Phase 7 | block type 分类与分页规则 | +| QUAL-01 | Phase 8 | layout frame / pagination cache | +| QUAL-02 | Phase 8 | 复杂样本分页质量提升 | +| QUAL-03 | Phase 8 | 图片暗色与页面背景类规则 | +| QUAL-04 | Phase 8 | 诊断与性能采样 | +| AUTO-01 | Phase 9 | native reflowable 自动化回归 | +| AUTO-02 | Phase 9 | 样本矩阵扩展 | +| AUTO-03 | Phase 9 | 证据标准化 | + +**覆盖统计：** +- v1.1 需求总数：13 +- 页面级布局：3 +- 属性闭环：3 +- 质量与性能：4 +- 自动化验证：3 + +--- +*Requirements defined: 2026-05-22* +*Last updated: 2026-05-22 after WXRead gap analysis* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md deleted file mode 100644 index 3c621ef..0000000 --- a/.planning/REQUIREMENTS.md +++ /dev/null @@ -1,66 +0,0 @@ -# 需求：ReadViewSDK - -**定义日期：** 2026-05-21 -**核心价值：** 稳定可用的 EPUB/TXT 阅读体验 - -## v1 需求（本次范围） - -### 渲染内核重构（Reflowable EPUB） - -- [ ] **REND-01**：直接重构当前 `.textReflowable` 路径，使 reflowable EPUB 不再依赖当前“简单 `DTCoreText` renderer + `pageRanges` 切页”模式，而是具备 WXRead 风格的页面级原生排版能力 -- [ ] **REND-02**：在旧引擎基础上引入 WXRead 风格的 CSS 分层策略（`default / replace / dark / epub / user`），并让样式作用于章节级 HTML → `NSAttributedString` 转换过程 -- [ ] **REND-03**：在旧引擎基础上引入自定义 DTCoreText 属性体系与页面级 `NSAttributedString` 元数据，能够承载分页、块元素、图片、页面语义等布局信息 -- [ ] **REND-04**：将当前简单的 CoreText 切页逻辑升级为具备页面语义的复杂分页器，具备与 `WRCoreTextLayouter / WRCoreTextLayoutFrame` 核心能力等价的分页与页面布局控制能力 - -### 兼容性与主流程 - -- [ ] **COMP-01**：`RDURLReaderController` / `RDEPUBReaderController` 作为公开入口继续可用，`.epub` / `.txt` 打开主流程不回归 -- [x] **COMP-02**：Fixed Layout EPUB 与交互式 EPUB 继续使用 `WKWebView`，行为不因本次改造产生回归 -- [ ] **COMP-03**：reflowable EPUB 的阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页在新内核下继续可用 -- [ ] **COMP-04**：当前翻页代码（`RDReaderView` 及现有 page curl / horizontal scroll / vertical scroll 交互逻辑）不做修改，新内核必须适配既有翻页容器 - -### 稳定性与验证 - -- [ ] **STAB-01**：至少 3 类样本书验证通过：纯文本/小说类、含图片与复杂段落样式的章节、含外链与多个 CSS 文件引用的章节 -- [ ] **STAB-02**：以上样本在新内核下不出现崩溃、白屏、无限加载、严重错页或关键交互链路失效 - -## v2 需求（延期） - -### 后续增强（不进入当前路线图） - -- **PERF-01**：定义并达成明确性能指标（首屏、翻页耗时、内存峰值）与持续监控方案 -- **INTL-01**：更完整的国际化排版增强（如更细粒度 RTL / 连字符断字 / 多语种高级回退） - -## 不做（防止范围漂移） - -| 功能 | 原因 | -|---|---| -| Fixed Layout EPUB 改为原生渲染 | 本次明确保留 `WKWebView` 路径以控制风险 | -| 交互式 EPUB 改为原生渲染 | 交互能力（JS/音视频/表单/iframe/外链/bridge）更适配 `WKWebView`，本次不改 | -| 修改当前翻页代码（`RDReaderView` / 现有翻页模式与交互逻辑） | 本次只重构 reflowable 渲染内核，不把翻页容器一起纳入改造 | -| 直接拷贝使用微信读书私有 JS/CSS/私有实现代码 | 只能参考设计与行为，不直接搬运私有实现 | -| 同时保留两套 reflowable 原生引擎 | 本次要求直接演进旧引擎，不维护双轨 | - -## 可追溯性（需求 ↔ Phase） - -| 需求 | Phase | 状态 | -|---|---:|---| -| REND-01 | Phase 2 | Pending | -| REND-02 | Phase 2 | Pending | -| REND-03 | Phase 3 | Pending | -| REND-04 | Phase 3 | Pending | -| COMP-01 | Phase 4 | Pending | -| COMP-02 | Phase 1 | Complete | -| COMP-03 | Phase 4 | Pending | -| COMP-04 | Phase 4 | Pending | -| STAB-01 | Phase 5 | Pending | -| STAB-02 | Phase 5 | Pending | - -**覆盖统计：** -- v1 需求总数：10 -- 已映射到 phases：10 -- 未映射：0 ✓ - ---- -*Requirements defined: 2026-05-21* -*Last updated: 2026-05-21 after scope update* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index d24cc77..2c593f3 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -1,119 +1,3 @@ # 路线图：ReadViewSDK -## 概述 - -本次路线图围绕“**直接重构现有 reflowable EPUB 旧引擎**”展开，而不是继续在轻量 renderer 外壳上做增量增强，也不是维护并行的第二套原生引擎。Fixed Layout 与交互式 EPUB 保持 `WKWebView` 路径不变；reflowable EPUB 则在现有 `.textReflowable` 主路径上逐步引入 WXRead 风格的 CSS 分层、自定义 DTCoreText 属性体系、页面级元数据与复杂分页能力，最终完成对旧内核的直接演进。**当前翻页代码（`RDReaderView` 及现有翻页模式/交互逻辑）不在本次改动范围内，新内核必须适配现有翻页容器。** - -## Phases - -- [x] **Phase 1: 对齐现状、边界与重构切入点** - 明确当前旧引擎的真实调用链、分流边界与必须保留的兼容能力 (completed 2026-05-21) -- [x] **Phase 2: 重构 typesetter 与 CSS 分层** - 在旧引擎基础上引入 WXRead 风格样式组织与章节级 HTML → attributed string 转换增强 (completed 2026-05-22) -- [x] **Phase 3: 重构属性体系与复杂分页器** - 引入页面级 attributed string 元数据与更强的分页/布局能力 (completed 2026-05-22) -- [x] **Phase 4: 接回现有 reader 能力链路** - 让新内核与阅读位置、高亮、搜索、主题切换等现有功能继续协作 (completed 2026-05-22) -- [x] **Phase 5: 回归验证与稳定性收敛** - 以样本书和主流程为核心完成回归、修复与验收 (completed 2026-05-22) - -## Phase Details - -### Phase 1: 对齐现状、边界与重构切入点 -**Goal**: 把“当前旧引擎是什么、哪些能力必须保留、哪些路径绝对不能动”说清楚，形成直接重构旧引擎的实施基线。 -**Depends on**: Nothing (first phase) -**Requirements**: COMP-02 -**Success Criteria** (必须为 TRUE): - 1. 能准确描述当前 `.textReflowable` 的真实调用链与数据流 - 2. Fixed Layout / 交互式 EPUB 的 `WKWebView` 边界不含糊，且不被纳入本次重构 - 3. 当前翻页代码（`RDReaderView`）被明确排除在本次改造范围外 - 4. 输出一份针对“旧引擎直接演进”的重构切入策略，而不是双引擎方案 -**Plans**: 2 plans - -Plans: -- [x] 01-01：审计当前 `.textReflowable` 路径（`RDEPUBDTCoreTextRenderer` / `RDEPUBTextBookBuilder` / `RDEPUBTextPaginationSupport` / `RDEPUBTextContentView`） -- [x] 01-02：结合 `Doc/WXRead/analysis/*` 提炼旧引擎可直接演进的切入点与必须保留的兼容链路 - -### Phase 2: 重构 typesetter 与 CSS 分层 -**Goal**: 在现有旧引擎基础上引入 WXRead 风格的 CSS 分层与章节级 HTML → attributed string 增强，让 renderer 输入具备更完整的排版语义。 -**Depends on**: Phase 1 -**Requirements**: REND-01, REND-02 -**Success Criteria** (必须为 TRUE): - 1. reflowable EPUB 的章节渲染输入不再只是“简单 DTCoreText 默认 builder + 少量 options” - 2. CSS 五层策略（`default / replace / dark / epub / user`）能够在旧引擎路径中落地 - 3. 章节级 baseURL、资源解析与样式注入策略清晰、可验证 -**Plans**: 3 plans - -Plans: -- [x] 02-01：设计并实现旧引擎中的 WXRead 风格 stylesheet builder / HTML 预处理增强 -- [x] 02-02：改造 `RDEPUBDTCoreTextRenderer` 与相邻渲染链路，使其承接新的样式分层与章节上下文 -- [x] 02-03：验证章节级图片/CSS/基础资源在新渲染输入下可正常解析 - -### Phase 3: 重构属性体系与复杂分页器 -**Goal**: 在旧引擎路径中引入页面级 attributed string 元数据与更复杂的分页/页面布局能力，替代当前简单 `pageRanges` 切页模式。 -**Depends on**: Phase 2 -**Requirements**: REND-03, REND-04 -**Success Criteria** (必须为 TRUE): - 1. 自定义 DTCoreText 属性体系可承载分页、块元素、图片、页面语义等布局信息 - 2. 新分页器具备明显强于当前 `CTFrameGetVisibleStringRange` 切页的页面布局能力 - 3. 分页结果可为后续 reader 集成提供稳定的页面范围与页面语义 -**Plans**: 3 plans - -Plans: -**Wave 1** -- [x] 03-01：定义并实现页面级 attributed string 元数据与自定义属性键 - -**Wave 2** *(blocked on Wave 1 completion)* -- [x] 03-02：在旧引擎基础上重构分页器，使其具备接近 `WRCoreTextLayouter / WRCoreTextLayoutFrame` 的核心能力 - -**Wave 3** *(blocked on Wave 2 completion)* -- [x] 03-03：验证复杂块元素、图片与分页边界控制在新分页器下可工作 - -Cross-cutting constraints: -- `pageStartOffset`、`pageEndOffset`、chapter text continuity、`fragmentOffsets` 必须保持为稳定兼容字段 -- 不修改 `RDReaderView`，不碰 fixed / interactive `WKWebView` 路径 - -### Phase 4: 接回现有 reader 能力链路 -**Goal**: 让新内核在不新增并行原生引擎、且不修改当前翻页代码的前提下，继续服务现有 reader UI、阅读位置、高亮、搜索与主题切换能力。 -**Depends on**: Phase 3 -**Requirements**: COMP-01, COMP-03, COMP-04 -**Success Criteria** (必须为 TRUE): - 1. `RDURLReaderController` / `RDEPUBReaderController` 主流程在新内核下继续可用 - 2. 阅读位置映射、高亮/选区、搜索结果定位可继续工作 - 3. 字号/行高/主题切换可驱动正确的重新分页，而不是破坏状态链路 - 4. `RDReaderView` 及现有翻页模式/交互逻辑无需修改即可承接新内核输出 -**Plans**: 3 plans - -Plans: -- [x] 04-01：将新内核接回 `RDEPUBTextBookBuilder` / `RDEPUBTextContentView` / `RDEPUBReaderController`，不修改 `RDReaderView` -- [x] 04-02：修复并验证阅读位置映射、高亮、搜索等兼容能力 -- [x] 04-03：验证字体、行高、主题切换后的重新分页与状态恢复 - -Cross-cutting constraints: -- `RDReaderView` 继续只作为现有翻页容器使用，不承接新的 native page metadata 责任 -- native text 兼容能力必须继续围绕 `RDEPUBLocation`、`pageStartOffset` / `pageEndOffset`、`RDEPUBTextOffsetRangeInfo` 工作 -- 主题 / 字号 / 行高 / viewport 变化后的恢复应以 semantic location 为主，而不是 page number - -### Phase 5: 回归验证与稳定性收敛 -**Goal**: 围绕样本书和主流程做回归，收敛分页正确性、位置映射稳定性与关键阅读交互问题。 -**Depends on**: Phase 4 -**Requirements**: STAB-01, STAB-02 -**Success Criteria** (必须为 TRUE): - 1. 至少 3 类样本书验证通过：纯文本/小说类、含图片与复杂段落样式、含外链与多个 CSS 文件引用 - 2. `.epub` / `.txt` 打开主流程、Fixed Layout、交互式 EPUB 不回归 - 3. 新内核下不出现崩溃、白屏、无限加载、严重错页或关键交互链路失效 -**Plans**: 2 plans - -Plans: -- [x] 05-01：构建样本书验证矩阵与诊断手段（日志/断言/复现清单） -- [x] 05-02：收敛分页、位置映射、图片/块元素分页与主题切换后的稳定性问题 - -Cross-cutting constraints: -- Phase 5 以验证和收敛修复为主，不重新打开更大范围的架构改造 -- 样本矩阵必须覆盖 native reflowable、fixed/interactive WebKit 路径，以及 TXT 兼容路径 -- 每项回归结论都应尽量附着到可重复证据：runtime summary、日志、断言或清单 - -## Progress - -| Phase | Plans Complete | Status | Completed | -|---|---:|---|---| -| 1. 对齐现状、边界与重构切入点 | 2/2 | Complete | 2026-05-21 | -| 2. 重构 typesetter 与 CSS 分层 | 3/3 | Complete | 2026-05-22 | -| 3. 重构属性体系与复杂分页器 | 3/3 | Complete | 2026-05-22 | -| 4. 接回现有 reader 能力链路 | 3/3 | Complete | 2026-05-22 | -| 5. 回归验证与稳定性收敛 | 2/2 | Complete | 2026-05-22 | +- `v1.0` 已归档：见 [v1.0-ROADMAP.md](/Users/shen/Work/Code/ReadViewSDK/.planning/milestones/v1.0-ROADMAP.md)；下一步请启动新 milestone 并生成新的 requirements / roadmap。 diff --git a/.planning/STATE.md b/.planning/STATE.md index b6eb997..67d5950 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,15 +2,15 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone -status: ready_to_complete_milestone -last_updated: 2026-05-22T05:22:00.000Z +status: ready_for_new_milestone +last_updated: 2026-05-22T05:40:00.000Z progress: - total_phases: 5 - completed_phases: 5 - total_plans: 13 - completed_plans: 13 + total_phases: 0 + completed_phases: 0 + total_plans: 0 + completed_plans: 0 percent: 100 -stopped_at: Phase 05 executed and verified — ready for milestone completion +stopped_at: v1.0 archived with accepted audit gaps — ready to start next milestone --- # STATE @@ -20,23 +20,22 @@ stopped_at: Phase 05 executed and verified — ready for milestone completion ## Project Reference -参见：`.planning/PROJECT.md`（更新于 2026-05-21） +参见：`.planning/PROJECT.md`（更新于 2026-05-22） **核心价值：** 稳定可用的 EPUB/TXT 阅读体验 -**当前关注：** Phase 5（回归验证与稳定性收敛）已执行完成，下一步可进入 milestone 收尾 +**当前关注：** `v1.0` 已归档，下一步启动 `v1.1` 里程碑定义 ## 当前结论（摘要） -- 全部 5 个 phase 已完成，native reflowable、fixed/interactive WebKit、TXT 三条主路径均有 Phase 5 运行时证据。 -- Demo 启动摘要现在输出 5/5 样本矩阵结果，并保留 Phase 3-4 的 pagination / restore diagnostics。 -- TXT 样本已内置到 `ReadViewDemo/ReadViewDemo/book/回归验证样本.txt`，不再依赖执行期临时文件。 -- `RDReaderView` 仍保持不修改；本轮里程碑以验证收敛结束，没有重新打开更大架构改造。 +- `v1.0` 已完成归档，详细路线图与需求快照见 `.planning/milestones/`。 +- 当前项目已拥有可运行的 native reflowable EPUB 主路径，并保留 fixed/interactive `WKWebView` 与 TXT 兼容能力。 +- `v1.1` 候选需求已草拟在 `.planning/REQUIREMENTS-v1.1-WXRead-next.md`。 ## 当前风险焦点 -- 仍缺少“每本样本都全自动点读一遍”的 UI 自动化；当前证据以启动矩阵、日志和一次 reader UI 快照为主 +- 里程碑归档接受了 requirement bookkeeping gaps；详见 `.planning/v1.0-MILESTONE-AUDIT.md` +- native text 几何查询、自定义分页属性闭环、分页质量与自动化验证仍是下一里程碑主要风险 - simulator 仍会输出既有 `.SFUI-Semibold` CoreText 替代提示，但未造成功能性失败 -- 若后续进入发布前验收，建议补一轮更细的交互式手动清单或 UI 自动化 ## 现有代码库地图 @@ -51,10 +50,11 @@ stopped_at: Phase 05 executed and verified — ready for milestone completion ## 下一步 -- 建议下一步：`$gsd-complete-milestone` +- 建议下一步：`$gsd-new-milestone` - 已完成的产物目录： - `.planning/phases/01-current-engine-boundaries/` - `.planning/phases/02-typesetter-css/` - `.planning/phases/03-page-metadata-pagination/` - `.planning/phases/04-reader-capabilities/` - `.planning/phases/05-regression-stability/` + - `.planning/milestones/` diff --git a/.planning/milestones/v1.0-REQUIREMENTS.md b/.planning/milestones/v1.0-REQUIREMENTS.md new file mode 100644 index 0000000..558448a --- /dev/null +++ b/.planning/milestones/v1.0-REQUIREMENTS.md @@ -0,0 +1,83 @@ +# 需求归档：ReadViewSDK v1.0 + +**归档日期：** 2026-05-22 +**核心价值：** 稳定可用的 EPUB/TXT 阅读体验 + +## 结果说明 + +本归档按 milestone close 生成。v1.0 的实现与运行时证据整体达成，但由于 close-out 前未完全回写 requirement bookkeeping，以下需求状态分为： + +- `Validated`：实现、phase verification、summary metadata 三者一致 +- `Delivered with accepted gaps`：实现和运行时证据存在，但 requirement bookkeeping 未完全对齐，作为已接受的归档缺口保留 + +## v1 Requirements + +### 渲染内核重构（Reflowable EPUB） + +- [x] **REND-01**：直接重构当前 `.textReflowable` 路径，使 reflowable EPUB 不再依赖当前“简单 `DTCoreText` renderer + `pageRanges` 切页”模式，而是具备 WXRead 风格的页面级原生排版能力 +- [x] **REND-02**：在旧引擎基础上引入 WXRead 风格的 CSS 分层策略（`default / replace / dark / epub / user`），并让样式作用于章节级 HTML → `NSAttributedString` 转换过程 +- [x] **REND-03**：在旧引擎基础上引入自定义 DTCoreText 属性体系与页面级 `NSAttributedString` 元数据，能够承载分页、块元素、图片、页面语义等布局信息 +- [x] **REND-04**：将当前简单的 CoreText 切页逻辑升级为具备页面语义的复杂分页器，具备与 `WRCoreTextLayouter / WRCoreTextLayoutFrame` 核心能力等价的分页与页面布局控制能力 + +### 兼容性与主流程 + +- [x] **COMP-01**：`RDURLReaderController` / `RDEPUBReaderController` 作为公开入口继续可用，`.epub` / `.txt` 打开主流程不回归 +- [x] **COMP-02**：Fixed Layout EPUB 与交互式 EPUB 继续使用 `WKWebView`，行为不因本次改造产生回归 +- [x] **COMP-03**：reflowable EPUB 的阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页在新内核下继续可用 +- [x] **COMP-04**：当前翻页代码（`RDReaderView` 及现有 page curl / horizontal scroll / vertical scroll 交互逻辑）不做修改，新内核必须适配既有翻页容器 + +### 稳定性与验证 + +- [x] **STAB-01**：至少 3 类样本书验证通过：纯文本/小说类、含图片与复杂段落样式的章节、含外链与多个 CSS 文件引用的章节 +- [x] **STAB-02**：以上样本在新内核下不出现崩溃、白屏、无限加载、严重错页或关键交互链路失效 + +## Requirement Outcomes + +| Requirement | Archived Outcome | Notes | +|-------------|------------------|-------| +| REND-01 | Delivered with accepted gaps | Phase 2 established renderer/context path; audit still flagged bookkeeping incompleteness. | +| REND-02 | Delivered with accepted gaps | Phase 2 verification marked it satisfied; archive accepts missing checkbox sync. | +| REND-03 | Delivered with accepted gaps | Phase 3 implemented page metadata; requirement-level verification mapping was missing. | +| REND-04 | Delivered with accepted gaps | Phase 3 delivered stronger pagination semantics; requirement bookkeeping remained orphaned. | +| COMP-01 | Delivered with accepted gaps | Phase 4 restored reader main flow, but requirement mapping was not backfilled. | +| COMP-02 | Validated | Phase 1 fully documented and verified the `WKWebView` retention boundary. | +| COMP-03 | Delivered with accepted gaps | Phase 4 runtime evidence supports compatibility, though close-out evidence chain was incomplete. | +| COMP-04 | Delivered with accepted gaps | `RDReaderView` remained untouched across the milestone, but requirement metadata was not reconciled. | +| STAB-01 | Delivered with accepted gaps | Phase 5 5-book matrix covers required categories. | +| STAB-02 | Delivered with accepted gaps | Phase 5 runtime/UI evidence shows no sampled crash/blank-page regression. | + +## Out of Scope + +| 功能 | 原因 | +|---|---| +| Fixed Layout EPUB 改为原生渲染 | 本次明确保留 `WKWebView` 路径以控制风险 | +| 交互式 EPUB 改为原生渲染 | 交互能力（JS/音视频/表单/iframe/外链/bridge）更适配 `WKWebView`，本次不改 | +| 修改当前翻页代码（`RDReaderView` / 现有翻页模式与交互逻辑） | 本次只重构 reflowable 渲染内核，不把翻页容器一起纳入改造 | +| 直接拷贝使用微信读书私有 JS/CSS/私有实现代码 | 只能参考设计与行为，不直接搬运私有实现 | +| 同时保留两套 reflowable 原生引擎 | 本次要求直接演进旧引擎，不维护双轨 | + +## Traceability + +| Requirement | Phase | Final Status | +|-------------|-------|--------------| +| REND-01 | Phase 2 | Delivered with accepted gaps | +| REND-02 | Phase 2 | Delivered with accepted gaps | +| REND-03 | Phase 3 | Delivered with accepted gaps | +| REND-04 | Phase 3 | Delivered with accepted gaps | +| COMP-01 | Phase 4 | Delivered with accepted gaps | +| COMP-02 | Phase 1 | Validated | +| COMP-03 | Phase 4 | Delivered with accepted gaps | +| COMP-04 | Phase 4 | Delivered with accepted gaps | +| STAB-01 | Phase 5 | Delivered with accepted gaps | +| STAB-02 | Phase 5 | Delivered with accepted gaps | + +**Coverage:** +- v1 requirements: 10 total +- Archived as shipped: 10 +- Strict audit passed without gaps: 1 +- Archived with accepted evidence gaps: 9 + +--- +*Requirements defined: 2026-05-21* +*Archived: 2026-05-22 after milestone close with accepted audit gaps* + diff --git a/.planning/milestones/v1.0-ROADMAP.md b/.planning/milestones/v1.0-ROADMAP.md new file mode 100644 index 0000000..6025b78 --- /dev/null +++ b/.planning/milestones/v1.0-ROADMAP.md @@ -0,0 +1,139 @@ +# Milestone v1.0: WXRead Native Reflowable Foundation + +**Status:** ✅ SHIPPED 2026-05-22 +**Phases:** 1-5 +**Total Plans:** 13 + +## Overview + +v1.0 completed the direct evolution of the existing reflowable EPUB native path instead of introducing a parallel engine. The milestone established chapter-level CSS preprocessing, richer page metadata, a stronger paginator, reader-shell reintegration, and sample-corpus regression evidence across native reflowable, fixed/interactive WebKit, and TXT flows. + +The milestone was archived with accepted audit gaps: the runtime and source evidence indicate the implementation is broadly complete, but requirement bookkeeping in `REQUIREMENTS.md`, `VERIFICATION.md`, and `SUMMARY.md` was not fully reconciled before close-out. + +## Phases + +### Phase 1: 对齐现状、边界与重构切入点 + +**Goal**: 把“当前旧引擎是什么、哪些能力必须保留、哪些路径绝对不能动”说清楚，形成直接重构旧引擎的实施基线。 +**Depends on**: Nothing (first phase) +**Plans**: 2 plans + +Plans: + +- [x] 01-01：审计当前 `.textReflowable` 路径（`RDEPUBDTCoreTextRenderer` / `RDEPUBTextBookBuilder` / `RDEPUBTextPaginationSupport` / `RDEPUBTextContentView`） +- [x] 01-02：结合 `Doc/WXRead/analysis/*` 提炼旧引擎可直接演进的切入点与必须保留的兼容链路 + +**Details:** + +- 固定了 native `.textReflowable` 的真实调用链和 `WKWebView` 分流边界。 +- 把 `RDReaderView` 明确记录为稳定容器，不纳入这轮重构。 +- 产出了后续 Phase 2-4 的实施顺序和硬边界。 + +### Phase 2: 重构 typesetter 与 CSS 分层 + +**Goal**: 在现有旧引擎基础上引入 WXRead 风格的 CSS 分层与章节级 HTML → attributed string 增强，让 renderer 输入具备更完整的排版语义。 +**Depends on**: Phase 1 +**Plans**: 3 plans + +Plans: + +- [x] 02-01：设计并实现旧引擎中的 WXRead 风格 stylesheet builder / HTML 预处理增强 +- [x] 02-02：改造 `RDEPUBDTCoreTextRenderer` 与相邻渲染链路，使其承接新的样式分层与章节上下文 +- [x] 02-03：验证章节级图片/CSS/基础资源在新渲染输入下可正常解析 + +**Details:** + +- 建立了 `default / replace / dark / epub / user` 五层 CSS 顺序。 +- 把 chapter preprocessing、baseURL、linked CSS 内联、资源标准化接入 native renderer。 +- 用 demo 样本书验证了 reflowable 章节资源解析。 + +### Phase 3: 重构属性体系与复杂分页器 + +**Goal**: 在旧引擎路径中引入页面级 attributed string 元数据与更复杂的分页/页面布局能力，替代当前简单 `pageRanges` 切页模式。 +**Depends on**: Phase 2 +**Plans**: 3 plans + +Plans: + +- [x] 03-01：定义并实现页面级 attributed string 元数据与自定义属性键 +- [x] 03-02：在旧引擎基础上重构分页器，使其具备接近 `WRCoreTextLayouter / WRCoreTextLayoutFrame` 的核心能力 +- [x] 03-03：验证复杂块元素、图片与分页边界控制在新分页器下可工作 + +**Details:** + +- 引入了页面元数据、attachment/block break reasons、layout frame 语义。 +- 保持 `pageStartOffset`、`pageEndOffset`、`fragmentOffsets`、`RDEPUBTextOffsetRangeInfo` 兼容不变。 +- 在真实 EPUB 上输出分页诊断，证明新分页语义已生效。 + +### Phase 4: 接回现有 reader 能力链路 + +**Goal**: 让新内核在不新增并行原生引擎、且不修改当前翻页代码的前提下，继续服务现有 reader UI、阅读位置、高亮、搜索与主题切换能力。 +**Depends on**: Phase 3 +**Plans**: 3 plans + +Plans: + +- [x] 04-01：将新内核接回 `RDEPUBTextBookBuilder` / `RDEPUBTextContentView` / `RDEPUBReaderController`，不修改 `RDReaderView` +- [x] 04-02：修复并验证阅读位置映射、高亮、搜索等兼容能力 +- [x] 04-03：验证字体、行高、主题切换后的重新分页与状态恢复 + +**Details:** + +- native text backend 被接回现有 reader shell，`RDReaderView` 保持不变。 +- 位置恢复、高亮、搜索、TOC、重分页行为围绕 absolute offset 契约继续工作。 +- demo 输出恢复诊断，证明 semantic location 在主题/字号变化后仍可恢复。 + +### Phase 5: 回归验证与稳定性收敛 + +**Goal**: 围绕样本书和主流程做回归，收敛分页正确性、位置映射稳定性与关键阅读交互问题。 +**Depends on**: Phase 4 +**Plans**: 2 plans + +Plans: + +- [x] 05-01：构建样本书验证矩阵与诊断手段（日志/断言/复现清单） +- [x] 05-02：收敛分页、位置映射、图片/块元素分页与主题切换后的稳定性问题 + +**Details:** + +- demo 启动摘要扩展为 5 本样本书的矩阵验证。 +- 覆盖 native reflowable、fixed/interactive WebKit、TXT 三条主路径。 +- 运行时证据确认 `样本验证：5/5 通过`，并保留分页/恢复诊断。 + +--- + +## Milestone Summary + +**Decimal Phases:** + +- None + +**Key Decisions:** + +- 选择直接演进现有 `.textReflowable` 原生引擎，而不是引入并行原生引擎。 +- Fixed Layout 与交互式 EPUB 继续保留 `WKWebView` 路径。 +- `RDReaderView` 作为稳定分页容器不纳入本轮改造范围。 +- 兼容链路继续围绕 offset-based location/highlight/search/restore 语义维持。 + +**Issues Resolved:** + +- chapter-level CSS 分层、preprocessing 和资源标准化接入 native renderer。 +- 分页器从纯 visible-range slicing 升级为带 block/attachment-aware 语义的 layouter path。 +- native reader shell 与位置恢复、高亮、搜索、主题/字号切换重新打通。 +- demo 建立了覆盖 reflowable / WebKit / TXT 的统一样本矩阵。 + +**Issues Deferred:** + +- requirement bookkeeping 未在 milestone close 前完全回写，详见 `v1.0-MILESTONE-AUDIT.md`。 +- 尚无完整 UI 自动化覆盖所有样本和关键交互。 +- Nyquist validation 文档仍存在 draft / partial 状态。 + +**Technical Debt Incurred:** + +- `REQUIREMENTS.md`、`VERIFICATION.md`、`SUMMARY.md` 的 requirement evidence chain 需要后续补齐。 +- simulator 运行仍会出现既有 `.SFUI-Semibold` CoreText substitution note。 + +--- + +_For current project status, see `.planning/ROADMAP.md`_ + diff --git a/.planning/v1.0-MILESTONE-AUDIT.md b/.planning/v1.0-MILESTONE-AUDIT.md new file mode 100644 index 0000000..51e9f64 --- /dev/null +++ b/.planning/v1.0-MILESTONE-AUDIT.md @@ -0,0 +1,207 @@ +--- +milestone: v1.0 +audited: 2026-05-22T05:32:00Z +status: gaps_found +scores: + requirements: 1/10 + phases: 5/5 + integration: 3/3 + flows: 4/4 +nyquist: + compliant_phases: [] + partial_phases: [1, 2, 3, 4, 5] + missing_phases: [] + overall: partial +gaps: + requirements: + - id: "REND-01" + status: "unsatisfied" + phase: "Phase 2" + claimed_by_plans: ["02-02-PLAN.md", "02-03-PLAN.md"] + completed_by_plans: [] + verification_status: "partial" + evidence: "02-VERIFICATION.md only marks REND-01 as partial; REQUIREMENTS.md remains unchecked; no SUMMARY frontmatter claims completion." + - id: "REND-02" + status: "partial" + phase: "Phase 2" + claimed_by_plans: ["02-01-PLAN.md", "02-02-PLAN.md", "02-03-PLAN.md"] + completed_by_plans: [] + verification_status: "passed" + evidence: "02-VERIFICATION.md marks REND-02 satisfied, but REQUIREMENTS.md remains unchecked and no SUMMARY frontmatter records completion." + - id: "REND-03" + status: "orphaned" + phase: "Phase 3" + claimed_by_plans: ["03-01-PLAN.md", "03-02-PLAN.md", "03-03-PLAN.md"] + completed_by_plans: [] + verification_status: "orphaned" + evidence: "Phase 3 summary/verifications describe page metadata and paginator work, but no Phase 3 VERIFICATION requirements table maps back to REND-03 and REQUIREMENTS.md remains pending." + - id: "REND-04" + status: "orphaned" + phase: "Phase 3" + claimed_by_plans: ["03-02-PLAN.md", "03-03-PLAN.md"] + completed_by_plans: [] + verification_status: "orphaned" + evidence: "Phase 3 runtime evidence proves stronger pagination, but no requirement-level verification entry or checked-off requirement exists for REND-04." + - id: "COMP-01" + status: "orphaned" + phase: "Phase 4" + claimed_by_plans: ["04-01-PLAN.md"] + completed_by_plans: [] + verification_status: "orphaned" + evidence: "Phase 4 verification describes restored reader entry flow, but no explicit requirement table or summary frontmatter marks COMP-01 complete." + - id: "COMP-03" + status: "orphaned" + phase: "Phase 4" + claimed_by_plans: ["04-02-PLAN.md"] + completed_by_plans: [] + verification_status: "orphaned" + evidence: "Search/highlight/restore behavior is evidenced in Phase 4, but not reconciled into REQUIREMENTS.md or requirement-level verification records." + - id: "COMP-04" + status: "orphaned" + phase: "Phase 4" + claimed_by_plans: ["04-03-PLAN.md"] + completed_by_plans: [] + verification_status: "orphaned" + evidence: "ROADMAP and summaries say RDReaderView stayed untouched, but milestone requirement tracking never marks COMP-04 complete." + - id: "STAB-01" + status: "orphaned" + phase: "Phase 5" + claimed_by_plans: ["05-01-PLAN.md"] + completed_by_plans: [] + verification_status: "orphaned" + evidence: "05-VERIFICATION.md shows a 5-book matrix across required categories, but no requirement table or checked requirement ties that evidence to STAB-01." + - id: "STAB-02" + status: "orphaned" + phase: "Phase 5" + claimed_by_plans: ["05-02-PLAN.md"] + completed_by_plans: [] + verification_status: "orphaned" + evidence: "05-VERIFICATION.md shows no crash/blank-page regressions in sampled flows, but milestone requirement tracking never records STAB-02 as satisfied." + integration: [] + flows: [] +tech_debt: + - phase: "01-current-engine-boundaries" + items: + - "01-VALIDATION.md remains draft with pending Wave 0 sign-off and nyquist_compliant false." + - phase: "02-typesetter-css" + items: + - "02-VALIDATION.md remains draft with pending Wave 0 sign-off and nyquist_compliant false." + - "02-VERIFICATION.md leaves REND-01 only partial even though later phases likely complete the milestone intent." + - phase: "03-page-metadata-pagination" + items: + - "03-VALIDATION.md has nyquist_compliant true but all task rows and sign-off remain pending." + - "03-VERIFICATION.md lacks a requirement coverage section for REND-03 / REND-04." + - phase: "04-reader-capabilities" + items: + - "04-VALIDATION.md has no frontmatter compliance markers." + - "04-VERIFICATION.md lacks requirement-level mapping for COMP-01 / COMP-03 / COMP-04." + - "Residual risk notes admit no full interactive UI automation for TOC/highlight/search." + - phase: "05-regression-stability" + items: + - "05-VALIDATION.md documents the matrix but not Nyquist frontmatter compliance." + - "05-VERIFICATION.md lacks requirement-level mapping for STAB-01 / STAB-02." + - "Residual risk notes admit no fully automated UI walkthrough of every sample/interaction." +--- + +# Milestone v1.0 Audit + +## Result + +Status: `gaps_found` + +The implementation milestone appears substantively complete at the phase and runtime-evidence level, but the milestone does **not** pass the strict close-out gate because requirement bookkeeping was never reconciled after execution. Under the required 3-source cross-reference, only `COMP-02` is fully satisfied. + +## Scope + +- Milestone: `v1.0` +- Phases in scope: `01` through `05` +- Completed phases: `5/5` +- Verification files present: `5/5` +- Summary files present: `13/13` + +## Phase Audit + +| Phase | Verification | Summary Coverage | Audit Result | +|-------|--------------|------------------|--------------| +| 1 | present, `passed` | 2/2 | pass | +| 2 | present, `passed` | 3/3 | pass with requirement bookkeeping gap | +| 3 | present, runtime evidence strong | 3/3 | pass with orphaned requirement gap | +| 4 | present, runtime evidence strong | 3/3 | pass with orphaned requirement gap | +| 5 | present, runtime evidence strong | 2/2 | pass with orphaned requirement gap | + +## Requirements Cross-Reference + +| Requirement | Traceability | Verification | Summary Frontmatter | Final | +|-------------|--------------|--------------|---------------------|-------| +| COMP-02 | Complete | satisfied in Phase 1 | listed in 01 summaries | satisfied | +| REND-02 | Pending | satisfied in Phase 2 | not listed | partial | +| REND-01 | Pending | partial in Phase 2 | not listed | unsatisfied | +| REND-03 | Pending | no requirement table entry | not listed | orphaned | +| REND-04 | Pending | no requirement table entry | not listed | orphaned | +| COMP-01 | Pending | no requirement table entry | not listed | orphaned | +| COMP-03 | Pending | no requirement table entry | not listed | orphaned | +| COMP-04 | Pending | no requirement table entry | not listed | orphaned | +| STAB-01 | Pending | no requirement table entry | not listed | orphaned | +| STAB-02 | Pending | no requirement table entry | not listed | orphaned | + +Interpretation: + +- The code and runtime evidence strongly suggest several orphaned requirements were actually delivered. +- The milestone audit still fails because `REQUIREMENTS.md`, `*-VERIFICATION.md`, and `requirements-completed` summary metadata do not agree. +- This is a close-out gap, not necessarily an implementation gap. + +## Integration Check + +Cross-phase integration appears healthy from the shipped evidence: + +- Phase 2 chapter preprocessing and CSS layering feed the Phase 3 paginator path. +- Phase 3 offset-compatible pagination semantics feed Phase 4 reader restore/search/highlight behavior. +- Phase 5 validates native reflowable, fixed/interactive WebKit, and TXT from the same demo/runtime surface. + +No cross-phase wiring break or broken end-to-end flow was evidenced in the verification artifacts. + +## Runtime / E2E Evidence + +Observed milestone-level evidence from Phase 3-5 verification: + +- `EPUB 资源验证：2/2 通过` +- `分页诊断：宝山辽墓材料与释读 ...` +- `恢复诊断：宝山辽墓材料与释读 ...` +- `样本验证：5/5 通过` +- `矩阵[Fixed/互动] 2/2` +- `矩阵[TXT] 1/1` + +These support the claim that the milestone behavior is broadly working, but they do not by themselves satisfy the workflow's requirement-traceability gate. + +## Nyquist Coverage + +| Phase | VALIDATION.md | Compliance | Notes | +|-------|---------------|------------|-------| +| 1 | present | partial | draft, `nyquist_compliant: false` | +| 2 | present | partial | draft, `nyquist_compliant: false` | +| 3 | present | partial | `nyquist_compliant: true`, but task/sign-off rows remain pending | +| 4 | present | partial | validation doc exists, but no frontmatter compliance markers | +| 5 | present | partial | validation doc exists, but no frontmatter compliance markers | + +## Why This Fails Close-Out + +The milestone close workflow requires all of the following to align: + +1. `REQUIREMENTS.md` checkboxes and traceability statuses +2. phase `VERIFICATION.md` requirement coverage +3. phase `SUMMARY.md` `requirements-completed` frontmatter + +That alignment is missing for 9 of 10 requirements. + +## Recommended Closure Path + +1. Reconcile the requirement evidence into the existing phase artifacts: + - add requirement coverage sections where missing in Phases 3-5 + - update `requirements-completed` frontmatter in relevant summaries + - update `.planning/REQUIREMENTS.md` checkboxes and traceability statuses +2. Run `$gsd-validate-phase 1`, `$gsd-validate-phase 2`, `$gsd-validate-phase 3`, `$gsd-validate-phase 4`, `$gsd-validate-phase 5` if you want Nyquist compliance brought up to date before close-out. +3. Re-run `$gsd-audit-milestone`. + +## Bottom Line + +The milestone looks operationally complete, but it is **not archive-ready** under the workflow’s audit rules because the requirement evidence chain is incomplete.