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>