chore: archive v1.0 milestone
This commit is contained in:
shen
parent
5698aeaead
commit
1498e83ace
26
.planning/MILESTONES.md
Normal file
26
.planning/MILESTONES.md
Normal file
@ -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.
|
||||
|
||||
@ -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*
|
||||
|
||||
110
.planning/REQUIREMENTS-v1.1-WXRead-next.md
Normal file
110
.planning/REQUIREMENTS-v1.1-WXRead-next.md
Normal file
@ -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*
|
||||
@ -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*
|
||||
@ -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。
|
||||
|
||||
@ -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/`
|
||||
|
||||
83
.planning/milestones/v1.0-REQUIREMENTS.md
Normal file
83
.planning/milestones/v1.0-REQUIREMENTS.md
Normal file
@ -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*
|
||||
|
||||
139
.planning/milestones/v1.0-ROADMAP.md
Normal file
139
.planning/milestones/v1.0-ROADMAP.md
Normal file
@ -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`_
|
||||
|
||||
207
.planning/v1.0-MILESTONE-AUDIT.md
Normal file
207
.planning/v1.0-MILESTONE-AUDIT.md
Normal file
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user