chore: checkpoint current milestone work
This commit is contained in:
shen
@@ -0,0 +1,84 @@
|
||||
---
|
||||
phase: 05-regression-stability
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- ReadViewDemo/ReadViewDemo/ViewController.swift
|
||||
- .planning/phases/05-regression-stability/05-VALIDATION.md
|
||||
- .planning/phases/05-regression-stability/05-RESEARCH.md
|
||||
autonomous: true
|
||||
requirements:
|
||||
- STAB-01
|
||||
user_setup: []
|
||||
must_haves:
|
||||
truths:
|
||||
- Phase 5 needs an explicit sample matrix, not only ad hoc simulator runs.
|
||||
- demo/runtime diagnostics are the primary validation entry point.
|
||||
- the matrix must account for native reflowable, fixed/interactive, and TXT-compatible paths.
|
||||
artifacts:
|
||||
- .planning/phases/05-regression-stability/05-01-SUMMARY.md
|
||||
key_links:
|
||||
- `ReadViewDemo/ReadViewDemo/book/`
|
||||
- `ReadViewDemo/ReadViewDemo/ViewController.swift`
|
||||
---
|
||||
|
||||
<objective>
|
||||
构建样本书验证矩阵、诊断输出和复现清单，让 Phase 5 的回归验证有明确覆盖面和可重复证据。
|
||||
|
||||
Purpose: 先把“验证什么、用什么样本、看什么证据”固定下来，再进入稳定性收敛。
|
||||
Output: documented sample matrix plus demo-visible or log-visible validation summary covering the required book categories.
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/05-regression-stability/05-RESEARCH.md
|
||||
@.planning/phases/05-regression-stability/05-PATTERNS.md
|
||||
@.planning/phases/04-reader-capabilities/04-VERIFICATION.md
|
||||
@ReadViewDemo/ReadViewDemo/ViewController.swift
|
||||
@ReadViewDemo/ReadViewDemo/book/
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: 定义样本矩阵与风险映射</name>
|
||||
<files>.planning/phases/05-regression-stability/05-RESEARCH.md, .planning/phases/05-regression-stability/05-VALIDATION.md, ReadViewDemo/ReadViewDemo/ViewController.swift</files>
|
||||
<read_first>.planning/phases/05-regression-stability/05-RESEARCH.md, ReadViewDemo/ReadViewDemo/ViewController.swift, ReadViewDemo/ReadViewDemo/book/</read_first>
|
||||
<action>明确每本样本书对应的验证类别与风险映射，并在需要时把这份矩阵体现在 demo 诊断输出或 phase 文档中。矩阵至少覆盖：小说/长文本 reflowable、复杂块元素/图片 reflowable、fixed 或 interactive WebKit 路径，以及 TXT 路径（如当前缺样本，则需在执行期明确补充策略）。</action>
|
||||
<acceptance_criteria>
|
||||
- sample corpus is mapped to explicit regression categories
|
||||
- Phase 5 artifacts state what evidence each sample is expected to provide
|
||||
- demo remains the primary visible validation entry point
|
||||
</acceptance_criteria>
|
||||
<verify>find ReadViewDemo/ReadViewDemo/book -maxdepth 1 -type f | sort && rg -n "validation|diagnostic|sample|matrix|restore|fixed|reflowable|txt" ReadViewDemo/ReadViewDemo .planning/phases/05-regression-stability -S</verify>
|
||||
<done>Phase 5 has an explicit validation matrix instead of an implicit sample list.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: 增强可重复诊断输出与复现清单</name>
|
||||
<files>ReadViewDemo/ReadViewDemo/ViewController.swift, .planning/phases/05-regression-stability/05-VALIDATION.md</files>
|
||||
<read_first>ReadViewDemo/ReadViewDemo/ViewController.swift, .planning/phases/04-reader-capabilities/04-VERIFICATION.md</read_first>
|
||||
<action>在现有 demo summary 基础上补充最小但可重复的诊断输出或验证说明，使后续 Phase 5 回归结果能被再次运行并比对。不要引入新的测试壳；应复用当前 demo 和已有日志体系。</action>
|
||||
<acceptance_criteria>
|
||||
- runtime validation evidence is clearer than a generic success/failure line
|
||||
- there is a written checklist or summary path for rerunning the same validations
|
||||
- diagnostics remain lightweight and tied to existing sample books
|
||||
</acceptance_criteria>
|
||||
<verify>rg -n "validation|diagnostic|restore|pagination|search|highlight|fixed|resource" ReadViewDemo/ReadViewDemo/ViewController.swift .planning/phases/05-regression-stability/05-VALIDATION.md</verify>
|
||||
<done>Phase 5 starts with a repeatable evidence-producing validation layer.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
Before declaring plan complete:
|
||||
- [ ] `find ReadViewDemo/ReadViewDemo/book -maxdepth 1 -type f | sort`
|
||||
- [ ] `rg -n "validation|diagnostic|sample|matrix|restore|fixed|reflowable|txt" ReadViewDemo/ReadViewDemo .planning/phases/05-regression-stability -S`
|
||||
</verification>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/05-regression-stability/05-01-SUMMARY.md`
|
||||
</output>
|
||||
@@ -0,0 +1,21 @@
|
||||
# 05-01 Summary
|
||||
|
||||
## Outcome
|
||||
|
||||
Wave 1 turned the sample corpus into an explicit regression matrix and made the demo startup log the primary repeatable proof surface.
|
||||
|
||||
- `ViewController` now validates every local `.epub` and `.txt` sample instead of only native reflowable EPUBs
|
||||
- startup summary now groups books into `TXT/小说`、`复杂图文`、`Fixed/互动`、`TXT` categories
|
||||
- a built-in TXT sample, `ReadViewDemo/ReadViewDemo/book/回归验证样本.txt`, now keeps the TXT path inside the repo instead of relying on an external file
|
||||
|
||||
## Evidence
|
||||
|
||||
Runtime log after simulator launch:
|
||||
|
||||
- `样本验证：5/5 通过`
|
||||
- `矩阵[复杂图文] 2/2 · 宝山辽墓材料与释读(textReflowable)、张学良传(textReflowable)`
|
||||
- `矩阵[Fixed/互动] 2/2 · 《凡人修仙传》精校版全本(webInteractive)、爱忘事的熊爷爷(webFixedLayout)`
|
||||
- `矩阵[TXT] 1/1 · 回归验证样本(txt)`
|
||||
|
||||
The demo remains the only validation surface; no extra test shell was introduced.
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
phase: 05-regression-stability
|
||||
plan: 02
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on:
|
||||
- "05-01"
|
||||
files_modified:
|
||||
- Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift
|
||||
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift
|
||||
- Sources/RDReaderView/EPUBCore/RDEPUBWebView.swift
|
||||
- Sources/RDReaderView/EPUBCore/RDEPUBWebView+FixedLayout.swift
|
||||
- Sources/RDReaderView/EPUBCore/RDEPUBResourceURLSchemeHandler.swift
|
||||
- Sources/RDReaderView/RDURLReaderController.swift
|
||||
- ReadViewDemo/ReadViewDemo/ViewController.swift
|
||||
autonomous: true
|
||||
requirements:
|
||||
- STAB-02
|
||||
user_setup: []
|
||||
must_haves:
|
||||
truths:
|
||||
- Phase 5 is allowed to fix concrete regressions discovered by the validation matrix.
|
||||
- fixes should be evidence-driven and narrow in scope.
|
||||
- no new architecture should be introduced in a convergence phase.
|
||||
artifacts:
|
||||
- .planning/phases/05-regression-stability/05-02-SUMMARY.md
|
||||
- .planning/phases/05-regression-stability/05-VERIFICATION.md
|
||||
key_links:
|
||||
- `RDEPUBReaderController`
|
||||
- `RDEPUBTextBookBuilder`
|
||||
- `RDEPUBWebView*`
|
||||
- `RDURLReaderController`
|
||||
---
|
||||
|
||||
<objective>
|
||||
依据样本矩阵执行回归，定位并收敛分页、位置映射、图片/块元素分页、fixed/interactive 资源加载，以及主题切换后的稳定性问题。
|
||||
|
||||
Purpose: 用真实样本和 reader 主流程把 Phase 1-4 的改动压测到可交付稳定水平。
|
||||
Output: regression fixes where needed, plus a verification artifact showing which main flows and sample categories passed.
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/05-regression-stability/05-RESEARCH.md
|
||||
@.planning/phases/05-regression-stability/05-PATTERNS.md
|
||||
@.planning/phases/05-regression-stability/05-VALIDATION.md
|
||||
@.planning/phases/03-page-metadata-pagination/03-VERIFICATION.md
|
||||
@.planning/phases/04-reader-capabilities/04-VERIFICATION.md
|
||||
@Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift
|
||||
@Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift
|
||||
@Sources/RDReaderView/EPUBCore/RDEPUBWebView.swift
|
||||
@Sources/RDReaderView/EPUBCore/RDEPUBWebView+FixedLayout.swift
|
||||
@Sources/RDReaderView/EPUBCore/RDEPUBResourceURLSchemeHandler.swift
|
||||
@Sources/RDReaderView/RDURLReaderController.swift
|
||||
@ReadViewDemo/ReadViewDemo/ViewController.swift
|
||||
@ReadViewDemo/ReadViewDemo/book/
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: 按矩阵执行 reader 主流程回归并修复具体问题</name>
|
||||
<files>Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/RDURLReaderController.swift, ReadViewDemo/ReadViewDemo/ViewController.swift</files>
|
||||
<read_first>.planning/phases/05-regression-stability/05-VALIDATION.md, Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/RDURLReaderController.swift, ReadViewDemo/ReadViewDemo/ViewController.swift</read_first>
|
||||
<action>基于样本矩阵执行 native reflowable 与 TXT 相关 reader 主流程验证，包括打开、位置恢复、搜索、highlight、TOC、theme/font repagination，并对发现的具体问题做最小修复。重点是收敛错误页、状态丢失、刷新后高亮/搜索不一致、TXT 入口回退等问题。</action>
|
||||
<acceptance_criteria>
|
||||
- key native/TXT reader flows have explicit pass evidence
|
||||
- any fixes are traceable to a concrete regression found during validation
|
||||
- no broad architectural refactor is introduced
|
||||
</acceptance_criteria>
|
||||
<verify>rg -n "search|highlight|location|restore|theme|font|bookmark|tableOfContents" Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift Sources/RDReaderView/RDURLReaderController.swift ReadViewDemo/ReadViewDemo/ViewController.swift</verify>
|
||||
<done>native and TXT reader flows are regression-checked and stabilized.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: 回归 fixed / interactive WebKit 路径并收敛资源加载与展示问题</name>
|
||||
<files>Sources/RDReaderView/EPUBCore/RDEPUBWebView.swift, Sources/RDReaderView/EPUBCore/RDEPUBWebView+FixedLayout.swift, Sources/RDReaderView/EPUBCore/RDEPUBResourceURLSchemeHandler.swift, ReadViewDemo/ReadViewDemo/ViewController.swift</files>
|
||||
<read_first>Sources/RDReaderView/EPUBCore/RDEPUBWebView.swift, Sources/RDReaderView/EPUBCore/RDEPUBWebView+FixedLayout.swift, Sources/RDReaderView/EPUBCore/RDEPUBResourceURLSchemeHandler.swift, ReadViewDemo/ReadViewDemo/ViewController.swift</read_first>
|
||||
<action>对 fixed / interactive EPUB 路径做回归验证，利用现有 `RDEPUBWebViewDebug` 与 demo/runtime evidence 检查资源加载、页面渲染、外链/内部链接与 search decoration 相关行为。若发现明显回归（白屏、加载失败、关键资源缺失、渲染未完成），做最小修复并把结果写入 verification artifact。</action>
|
||||
<acceptance_criteria>
|
||||
- fixed or interactive sample path has explicit runtime evidence
|
||||
- resource loading and rendering regressions are either fixed or clearly surfaced in verification
|
||||
- demo/runtime logs remain sufficient to inspect failures without adding a second validation shell
|
||||
</acceptance_criteria>
|
||||
<verify>rg -n "RDEPUBWebViewDebug|load fixed|ResourceScheme|rendered|didFail|didFinish|searchPresentation" Sources/RDReaderView/EPUBCore ReadViewDemo/ReadViewDemo -S</verify>
|
||||
<done>WebKit-backed reader paths are included in the final regression closure, not treated as out-of-band.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
Before declaring plan complete:
|
||||
- [ ] `find ReadViewDemo/ReadViewDemo/book -maxdepth 1 -type f | sort`
|
||||
- [ ] `rg -n "search|highlight|location|restore|theme|font|bookmark|tableOfContents" Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift Sources/RDReaderView/RDURLReaderController.swift ReadViewDemo/ReadViewDemo/ViewController.swift`
|
||||
- [ ] `rg -n "RDEPUBWebViewDebug|load fixed|ResourceScheme|rendered|didFail|didFinish|searchPresentation" Sources/RDReaderView/EPUBCore ReadViewDemo/ReadViewDemo -S`
|
||||
</verification>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/05-regression-stability/05-02-SUMMARY.md` and `.planning/phases/05-regression-stability/05-VERIFICATION.md`
|
||||
</output>
|
||||
@@ -0,0 +1,16 @@
|
||||
# 05-02 Summary
|
||||
|
||||
## Outcome
|
||||
|
||||
Wave 2 closed the remaining regression gap by exercising the new matrix and tightening the demo validator where it initially drifted from public APIs.
|
||||
|
||||
- fixed/interactive validation now resolves spine resources through public `RDEPUBResourceResolver` APIs and verifies fixed spreads with explicit `RDEPUBPreferences`
|
||||
- TXT validation now builds a real `RDPlainTextBook` and records chapter/page evidence
|
||||
- the existing native pagination and restore diagnostics remain active for reflowable books, so Phase 3-4 guarantees stay visible during Phase 5 runs
|
||||
|
||||
## Fixes
|
||||
|
||||
- removed demo-only calls to internal reader helpers (`makePreferences`, theme CSS accessors)
|
||||
- removed the nonisolated `UIScreen.main` warning by passing the existing viewport size into fixed-layout validation
|
||||
- kept the changes local to `ReadViewDemo/ReadViewDemo/ViewController.swift`; no new runtime architecture was introduced
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# Phase 5: 回归验证与稳定性收敛 - Pattern Map
|
||||
|
||||
## Goal
|
||||
|
||||
把 Phase 5 约束成“样本矩阵 + reader 流程 + 收敛修复”的闭环，而不是泛泛地补测试。
|
||||
|
||||
## Planned Outputs
|
||||
|
||||
| Planned file | Role | Primary evidence | Why this is the right analog |
|
||||
|--------------|------|------------------|------------------------------|
|
||||
| `05-01-PLAN.md` | 构建样本矩阵、诊断手段和复现清单 | `ReadViewDemo/ViewController.swift`, `ReadViewDemo/book/`, `RDEPUBWebViewDebug`, prior verification artifacts | 这些是现有验证入口和日志基础。 |
|
||||
| `05-02-PLAN.md` | 依据矩阵执行回归并收敛稳定性问题 | `RDEPUBReaderController`, `RDEPUBTextBookBuilder`, `RDEPUBWebView*`, `RDURLReaderController` | 这里汇聚了 Phase 1-4 改动后的主要风险表面。 |
|
||||
|
||||
## Code Evidence Map
|
||||
|
||||
| Concern | Closest source of truth | Evidence to extract |
|
||||
|---------|-------------------------|---------------------|
|
||||
| 样本入口与启动验证 | `ReadViewDemo/ReadViewDemo/ViewController.swift` | 已有 startup validation，可扩展成矩阵摘要。 |
|
||||
| native reflowable 风险 | `RDEPUBReaderController`, `RDEPUBTextBookBuilder`, `RDEPUBTextContentView` | 搜索、高亮、repagination、位置恢复都集中在这里。 |
|
||||
| fixed / interactive 风险 | `RDEPUBWebView`, `RDEPUBWebView+FixedLayout`, `RDEPUBResourceURLSchemeHandler` | 这些路径依赖 WebKit/resource loading，不同于 native text。 |
|
||||
| TXT 支持风险 | `RDURLReaderController`, `RDPlainTextBookBuilder` | roadmap 要求 `.txt` 主流程不回归，但当前样本覆盖不足。 |
|
||||
|
||||
## Writing Guidance
|
||||
|
||||
- Phase 5 的计划必须明确区分“验证基础设施/矩阵”与“发现问题后的收敛修复”。
|
||||
- 任何修复都应以回归证据驱动，不应重新打开更大范围的架构重构。
|
||||
- 计划里要写清楚哪些样本书承担哪些验证职责。
|
||||
@@ -0,0 +1,122 @@
|
||||
# Phase 5: 回归验证与稳定性收敛 - Research
|
||||
|
||||
**Researched:** 2026-05-22
|
||||
**Domain:** iOS EPUB/TXT regression validation / sample-corpus coverage / stability convergence
|
||||
**Confidence:** HIGH
|
||||
|
||||
<user_constraints>
|
||||
## User Constraints
|
||||
|
||||
No `CONTEXT.md` exists for this phase. Planning is based on roadmap requirements, the current codebase, and completed artifacts from Phases 1-4 only.
|
||||
</user_constraints>
|
||||
|
||||
<research_summary>
|
||||
## Summary
|
||||
|
||||
By the end of Phase 4, the codebase has meaningful diagnostics for both native text pagination and reader-state restore, but the validation surface is still uneven. Most current proof is either:
|
||||
|
||||
- source inspection (`rg`, architecture invariants)
|
||||
- simulator build/run success
|
||||
- demo startup logs from a small subset of sample books
|
||||
|
||||
That was enough to unblock development, but not enough to claim stability closure. Phase 5 therefore shifted from “implement capability” to “prove breadth and harden failures.”
|
||||
|
||||
The sample corpus used for execution now covers five local books:
|
||||
|
||||
- `《凡人修仙传》精校版全本.epub`
|
||||
- `回归验证样本.txt`
|
||||
- `宝山辽墓材料与释读.epub`
|
||||
- `张学良传.epub`
|
||||
- `爱忘事的熊爷爷.epub`
|
||||
|
||||
Observed behavior from Phases 3-4 shows these books are not equivalent:
|
||||
|
||||
- `宝山辽墓材料与释读.epub` exercises native reflowable pagination semantics and repagination restore checks
|
||||
- `爱忘事的熊爷爷.epub` clearly drives fixed-layout / interactive-style WebKit resource flows in runtime logs
|
||||
- `回归验证样本.txt` was added during execution so the TXT path is now part of the built-in demo corpus
|
||||
|
||||
The main Phase 5 planning implication is that validation has to be organized as a matrix, not a single “open the app and see it works” loop. At minimum the matrix must cover:
|
||||
|
||||
1. Native reflowable text with richer page metadata and repagination
|
||||
2. Fixed layout / WebKit-based rendering and resource loading
|
||||
3. TXT/native text book path through `RDURLReaderController`
|
||||
4. Reader interaction flows: open, TOC jump, search navigation, highlight persistence, theme/font changes, and repeated repagination
|
||||
|
||||
The repo already has enough hooks to support this:
|
||||
|
||||
- `ReadViewDemo/ViewController.swift` reports sample validation summaries at startup
|
||||
- `RDEPUBTextBookBuilder` records pagination/resource diagnostics
|
||||
- `RDEPUBWebViewDebug` and resource-scheme logs expose WebKit/fixed-layout loading behavior
|
||||
- `RDEPUBReaderController` centralizes repagination, restore, search, highlight, and viewport handling
|
||||
|
||||
What is missing is orchestration and closure:
|
||||
|
||||
- explicit mapping from sample book → risk category
|
||||
- runtime assertions or summary output for reader flows beyond startup validation
|
||||
- a disciplined path to take discovered regressions and either fix them or record them as resolved in the same phase
|
||||
|
||||
**Primary recommendation:** Plan Phase 5 as a validation-and-fix loop centered on a documented sample matrix and runtime evidence. The goal is not new architecture; it is repeatable proof that the main supported book categories and reader flows stay intact after the Phase 1-4 refactor.
|
||||
|
||||
Execution outcome:
|
||||
|
||||
- `ReadViewDemo` startup validation now emits matrix lines for complex reflowable, fixed/interactive WebKit, and TXT samples
|
||||
- runtime evidence showed `样本验证：5/5 通过`
|
||||
- the demo remains the single validation entry point; no secondary harness was introduced
|
||||
</research_summary>
|
||||
|
||||
<code_evidence>
|
||||
## Code Evidence
|
||||
|
||||
| Concern | Source | Why it matters |
|
||||
|--------|--------|----------------|
|
||||
| Demo validation entry point | `ReadViewDemo/ReadViewDemo/ViewController.swift` | Already emits startup resource/pagination/restore summaries; best place to extend verification. |
|
||||
| Native text diagnostics | `RDEPUBTextBookBuilder`, `RDEPUBTextLayouter`, `RDEPUBTextRendererSupport` | Existing metadata can drive stronger regression assertions. |
|
||||
| Reader flow behavior | `RDEPUBReaderController` | Open, search, selection, highlight, TOC, repagination, and state restore all converge here. |
|
||||
| Web/fixed runtime logs | `RDEPUBWebViewDebug`, `RDEPUBWebView`, `RDEPUBWebView+FixedLayout`, `RDEPUBResourceURLSchemeHandler` | Needed to prove non-native paths did not regress. |
|
||||
| TXT path | `RDURLReaderController`, `RDPlainTextBookBuilder` | Supported but currently underrepresented in the sample corpus. |
|
||||
|
||||
</code_evidence>
|
||||
|
||||
<sample_corpus>
|
||||
## Current Sample Corpus
|
||||
|
||||
| Sample | Likely category | Current evidence |
|
||||
|--------|------------------|------------------|
|
||||
| `宝山辽墓材料与释读.epub` | Native reflowable, complex blocks/images | Used in Phase 3/4 pagination and restore diagnostics. |
|
||||
| `《凡人修仙传》精校版全本.epub` | Interactive/WebKit path | Runtime summary now classifies it as `webInteractive` and verifies `spine 2470 · missing 0`. |
|
||||
| `回归验证样本.txt` | TXT/native text path | Added in Phase 5 and validated through `RDPlainTextBookBuilder` with startup summary output. |
|
||||
| `张学良传.epub` | Reflowable nonfiction / alternate structure | Runtime summary classifies it under complex reflowable. |
|
||||
| `爱忘事的熊爷爷.epub` | Fixed-layout / interactive-style WebKit path | Runtime log shows extensive fixed/resource loading. |
|
||||
|
||||
</sample_corpus>
|
||||
|
||||
<architecture_patterns>
|
||||
## Architecture Patterns
|
||||
|
||||
### Pattern 1: Validate by book category, not by implementation layer
|
||||
**What:** Organize checks around sample types and user flows.
|
||||
**Why:** Stability issues are user-visible regressions, not just module-level failures.
|
||||
|
||||
### Pattern 2: Prefer evidence-producing diagnostics over ad hoc manual notes
|
||||
**What:** Runtime summaries, assertions, and structured logs should back regression claims.
|
||||
**Why:** Repeatability matters more than one-off successful runs.
|
||||
|
||||
### Pattern 3: Couple regression detection with fix closure
|
||||
**What:** The phase should allow targeted source fixes where diagnostics surface concrete failures.
|
||||
**Why:** A pure audit phase without remediation would leave the roadmap unfinished.
|
||||
|
||||
### Anti-Patterns to Avoid
|
||||
- Treating build success as sufficient evidence of reader stability.
|
||||
- Adding broad new architecture during a convergence phase.
|
||||
- Expanding validation without documenting which sample proves which risk category.
|
||||
|
||||
</architecture_patterns>
|
||||
|
||||
<open_questions>
|
||||
## Open Questions
|
||||
|
||||
- Should Phase 5 add a dedicated TXT sample into the demo corpus, or rely on an external local text file during execution?
|
||||
- How much of the reader interaction validation should be automated in code/logs versus performed manually on simulator?
|
||||
- If a regression is found in fixed/interactive WebKit flows, should it be fixed within Phase 5 or only documented if the root cause is outside the current scope?
|
||||
|
||||
</open_questions>
|
||||
@@ -0,0 +1,46 @@
|
||||
# Phase 5: 回归验证与稳定性收敛 - Validation
|
||||
|
||||
## Required Checks
|
||||
|
||||
- 至少覆盖三类样本：纯文本/TXT 或小说型 reflowable、复杂块元素/图片 reflowable、fixed/interactive WebKit 路径
|
||||
- `.epub` 与 `.txt` 的 reader 主流程都必须有明确验证路径
|
||||
- 每个重要 reader 流程至少有一种可重复证据：日志、断言、摘要、或稳定的手动检查清单
|
||||
|
||||
## Executed Matrix
|
||||
|
||||
| Sample | Category | Evidence |
|
||||
|--------|----------|----------|
|
||||
| `宝山辽墓材料与释读.epub` | 复杂图文 / native reflowable | 启动摘要 + pagination/restore diagnostics |
|
||||
| `张学良传.epub` | 复杂图文 / native reflowable | 启动摘要 + active native reader UI evidence |
|
||||
| `《凡人修仙传》精校版全本.epub` | interactive / WebKit | 启动摘要 `webInteractive` + `missing 0` |
|
||||
| `爱忘事的熊爷爷.epub` | fixed layout / WebKit | 启动摘要 `webFixedLayout` + `spread` validation |
|
||||
| `回归验证样本.txt` | TXT | 启动摘要 `TXT 验证` + page/chapter counts |
|
||||
|
||||
## Verification Anchors
|
||||
|
||||
### Source-level
|
||||
- `find ReadViewDemo/ReadViewDemo/book -maxdepth 1 -type f | sort`
|
||||
- `rg -n "validation|diagnostic|restore|search|highlight|location|theme|font|fixed|resource" ReadViewDemo/ReadViewDemo Sources/RDReaderView -S`
|
||||
- `rg -n "RDEPUBWebViewDebug|logSchemeTask|rendered|page break|restore" Sources/RDReaderView -S`
|
||||
|
||||
### Runtime / demo
|
||||
- run `ReadViewDemo` on simulator
|
||||
- capture startup validation summaries for every relevant sample category
|
||||
- exercise at least one native reflowable flow with search/highlight/repagination
|
||||
- exercise at least one fixed/interactive EPUB flow and confirm no loading/resource regression
|
||||
- exercise a TXT reading flow if a sample exists or is added during execution
|
||||
|
||||
## Current Rerun Path
|
||||
|
||||
1. Launch `ReadViewDemo` on the configured simulator.
|
||||
2. Read the startup summary from the on-screen status area or runtime log.
|
||||
3. Confirm the matrix lines for `复杂图文`、`Fixed/互动`、`TXT`.
|
||||
4. Open any listed sample and use the existing reader controls to recheck TOC, bookmark/highlight, and theme/font adjustments as needed.
|
||||
|
||||
## Completion Standard
|
||||
|
||||
Phase 5 planning is only good enough if each plan names:
|
||||
|
||||
1. which sample categories it covers
|
||||
2. what evidence proves success
|
||||
3. how discovered regressions are routed into concrete fixes
|
||||
@@ -0,0 +1,47 @@
|
||||
# Phase 5 Verification
|
||||
|
||||
## Commands
|
||||
|
||||
- `build_sim` for scheme `ReadViewDemo`
|
||||
- `build_run_sim` for scheme `ReadViewDemo`
|
||||
- `find ReadViewDemo/ReadViewDemo/book -maxdepth 1 -type f | sort`
|
||||
- `rg -n "validation|diagnostic|sample|matrix|restore|fixed|reflowable|txt" ReadViewDemo/ReadViewDemo .planning/phases/05-regression-stability -S`
|
||||
- `rg -n "search|highlight|location|restore|theme|font|bookmark|tableOfContents" Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift Sources/RDReaderView/RDURLReaderController.swift ReadViewDemo/ReadViewDemo/ViewController.swift`
|
||||
- `rg -n "RDEPUBWebViewDebug|load fixed|ResourceScheme|rendered|didFail|didFinish|searchPresentation" Sources/RDReaderView/EPUBCore ReadViewDemo/ReadViewDemo -S`
|
||||
- `snapshot_ui` on the running simulator
|
||||
|
||||
## Results
|
||||
|
||||
- Simulator build succeeded with no warnings
|
||||
- Simulator launch succeeded
|
||||
- Demo corpus now includes 5 verifiable books:
|
||||
- `《凡人修仙传》精校版全本.epub`
|
||||
- `回归验证样本.txt`
|
||||
- `宝山辽墓材料与释读.epub`
|
||||
- `张学良传.epub`
|
||||
- `爱忘事的熊爷爷.epub`
|
||||
- Source verification confirms:
|
||||
- `ViewController` now validates `.txt`, native reflowable EPUB, and fixed/interactive EPUB in one pass
|
||||
- native reader flows for search, highlight, location restore, bookmarks, TOC, and theme/font repagination remain centered in `RDEPUBReaderController`
|
||||
- WebKit-backed flows still expose resource/render lifecycle evidence through `RDEPUBWebViewDebug` and `RDEPUBResourceURLSchemeHandler`
|
||||
|
||||
## Runtime Evidence
|
||||
|
||||
From the app runtime log:
|
||||
|
||||
- `样本验证：5/5 通过`
|
||||
- `矩阵[复杂图文] 2/2 · 宝山辽墓材料与释读(textReflowable)、张学良传(textReflowable)`
|
||||
- `矩阵[Fixed/互动] 2/2 · 《凡人修仙传》精校版全本(webInteractive)、爱忘事的熊爷爷(webFixedLayout)`
|
||||
- `矩阵[TXT] 1/1 · 回归验证样本(txt)`
|
||||
- `Web 路径验证：《凡人修仙传》精校版全本 · profile webInteractive · spine 2470 · missing 0`
|
||||
- `Web 路径验证：爱忘事的熊爷爷 · profile webFixedLayout · spine 22 · missing 0`
|
||||
|
||||
From simulator UI inspection:
|
||||
|
||||
- the app was running inside `RDEPUBReaderController` with visible reader controls (`epub.reader.back`, `epub.reader.toc`, `epub.reader.bookmarks`, `epub.reader.highlights`, `epub.reader.settings`)
|
||||
- the current native reflowable sample exposed page state (`2 / 691`) and standard reader chrome without a blank page or stalled render
|
||||
|
||||
## Residual Risk
|
||||
|
||||
- The phase now has corpus-level runtime evidence for TXT and WebKit paths, but not a fully automated UI walkthrough for opening every sample and driving every interaction on simulator
|
||||
- Simulator runtime still emits pre-existing CoreText font substitution notes for `.SFUI-Semibold`; Phase 5 did not change font selection code and the app remained functional despite the warning
|
||||
Reference in New Issue
Block a user