shen 22bb86959c docs(08): create phase plans for image display fix and pagination cache

3 plans covering QUAL-01 through QUAL-04:
- 08-01: pagination cache key + wiring into rendering pipeline
- 08-02: unified 1080x1920 max-size for all images, footnote width-only fix
- 08-03: pagination timing instrumentation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-23 18:43:41 +08:00

2.1 KiB

Raw Blame History

Phase 8: Validation Plan

Phase: 08-pagination-quality-cache-performance Created: 2026-05-23

Verification Strategy

This phase has no unit test target for EPUBTextRendering. Verification is build-only plus manual visual inspection.

Automated Verification

Check	Command	Frequency
Build succeeds	`xcodebuild build -project ReadViewDemo/ReadViewDemo.xcodeproj -scheme ReadViewDemo -destination 'platform=iOS Simulator,name=iPhone 16'`	Per task commit

Manual Verification (Phase Gate)

Requirement	What to Check	How
QUAL-01	Same chapter does not re-typeset on repeat navigation	Navigate to a chapter, back, then forward again — second visit should be noticeably faster (check `[EPUB][Perf]` log for elapsed time)
QUAL-02	Images don't overflow pages	Open 宝山辽墓材料与释读, navigate to Chapter 5 (qrbodyPic images), verify no height overflow
QUAL-03	Image sizing rules are verifiable	Code review: `DTMaxImageSize` = 1080x1920, unified max-size block in `prepareHTMLElementForReaderRendering`
QUAL-04	No perf degradation	Check `[EPUB][Perf]` log output — pagination times should be comparable to pre-change baseline

Image Display Checklist

Cover image: displays correctly, not cropped, not stretched
qrbodyPic images: display within page bounds, no height overflow
Footnote images: inline with text, same height as text characters, width-only sizing
Dark mode: all image types still display correctly
Page breaks around images: no orphan images at page tops/bottoms

Rationale

Build-only verification is the appropriate approach for this phase because:

No unit test target exists for EPUBTextRendering code
Image sizing correctness is inherently visual — pixel-level assertions would be brittle
The changes are surgical (one new code block, removals of redundant logic) and can be verified by code review + visual inspection
Creating a test infrastructure is out of scope (belongs to Phase 9: 自动化回归与证据标准化)

2.1 KiB Raw Blame History