ReadViewSDK/.planning/phases/05-regression-stability/05-RESEARCH.md

# 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>