chore: archive v1.0 milestone
This commit is contained in:
shen
@@ -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*
|
||||
|
||||
@@ -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`_
|
||||
|
||||
Reference in New Issue
Block a user