feat(wxread): align pagination, rendering, and docs
This commit is contained in:
shen
@@ -1,39 +1,77 @@
|
||||
# Phase 8: Validation Plan
|
||||
---
|
||||
phase: 8
|
||||
slug: pagination-quality-cache-performance
|
||||
status: draft
|
||||
nyquist_compliant: true
|
||||
wave_0_complete: true
|
||||
created: 2026-05-23
|
||||
---
|
||||
|
||||
**Phase:** 08-pagination-quality-cache-performance
|
||||
**Created:** 2026-05-23
|
||||
# Phase 8 — Validation Strategy
|
||||
|
||||
## Verification Strategy
|
||||
> Per-phase validation contract for feedback sampling during execution.
|
||||
|
||||
This phase has no unit test target for EPUBTextRendering. Verification is build-only plus manual visual inspection.
|
||||
---
|
||||
|
||||
### Automated Verification
|
||||
## Test Infrastructure
|
||||
|
||||
| Check | Command | Frequency |
|
||||
|-------|---------|-----------|
|
||||
| Build succeeds | `xcodebuild build -project ReadViewDemo/ReadViewDemo.xcodeproj -scheme ReadViewDemo -destination 'platform=iOS Simulator,name=iPhone 16'` | Per task commit |
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Framework** | XCTest (ReadViewSDKDemoTests / ReadViewSDKDemoUITests) |
|
||||
| **Config file** | ReadViewDemo/ReadViewDemo.xcodeproj |
|
||||
| **Quick run command** | `xcodebuild test -scheme ReadViewDemo -destination 'platform=iOS Simulator,name=iPhone 17' -only-testing:ReadViewSDKDemoTests` |
|
||||
| **Full suite command** | `xcodebuild test -scheme ReadViewDemo -destination 'platform=iOS Simulator,name=iPhone 17'` |
|
||||
| **Estimated runtime** | ~60 seconds |
|
||||
|
||||
### 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 |
|
||||
## Sampling Rate
|
||||
|
||||
### Image Display Checklist
|
||||
- **After every task commit:** Build succeeds (`xcodebuild build -scheme ReadViewDemo`)
|
||||
- **After every plan wave:** Run quick test suite + runtime diagnostic log check
|
||||
- **Before `/gsd:verify-work`:** Full suite green + runtime diagnostic evidence
|
||||
- **Max feedback latency:** 120 seconds
|
||||
|
||||
- [ ] 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
|
||||
## Per-Task Verification Map
|
||||
|
||||
Build-only verification is the appropriate approach for this phase because:
|
||||
1. No unit test target exists for EPUBTextRendering code
|
||||
2. Image sizing correctness is inherently visual — pixel-level assertions would be brittle
|
||||
3. The changes are surgical (one new code block, removals of redundant logic) and can be verified by code review + visual inspection
|
||||
4. Creating a test infrastructure is out of scope (belongs to Phase 9: 自动化回归与证据标准化)
|
||||
| Task ID | Plan | Wave | Requirement | Automated Command | Status |
|
||||
|---------|------|------|-------------|-------------------|--------|
|
||||
| 08-01-01 | 01 | 1 | QUAL-01 | build succeeds + cache hit/miss log | ✅ green |
|
||||
| 08-01-02 | 01 | 1 | QUAL-01 | build succeeds + cache invalidation log | ✅ green |
|
||||
| 08-02-01 | 02 | 1 | QUAL-02 | build succeeds + pagination diagnostic log | ✅ green |
|
||||
| 08-02-02 | 02 | 1 | QUAL-03 | build succeeds + attachment diagnostic log | ✅ green |
|
||||
| 08-03-01 | 03 | 2 | QUAL-04 | build succeeds + timing diagnostic log | ✅ green |
|
||||
|
||||
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
|
||||
|
||||
---
|
||||
|
||||
## Wave 0 Requirements
|
||||
|
||||
- Existing `ReadViewSDKDemoTests` covers parser / resolver / persistence
|
||||
- No new test infrastructure needed — runtime diagnostic logs serve as evidence
|
||||
|
||||
---
|
||||
|
||||
## Manual-Only Verifications
|
||||
|
||||
| Behavior | Requirement | Why Manual | Test Instructions |
|
||||
|----------|-------------|------------|-------------------|
|
||||
| 缓存命中后不再重复排版 | QUAL-01 | 需要对比前后分页结果一致性 | 打开同一本书两次，检查第二次的日志无渲染耗时 |
|
||||
| 复杂图文章节分页改善 | QUAL-02 | 需要视觉对比 | 用宝山辽墓样书，对比改善前后分页结果 |
|
||||
| 图片不跨页、居中显示 | QUAL-03 | 需要视觉验证 | 检查含大图章节，确认图片在单页内居中 |
|
||||
| 首屏时间不退化 | QUAL-04 | 需要实际设备计时 | 对比改善前后打开书籍的首屏时间 |
|
||||
|
||||
---
|
||||
|
||||
## Validation Sign-Off
|
||||
|
||||
- [x] All tasks have build-success verification
|
||||
- [x] Runtime diagnostic logs captured for cache, pagination quality, and timing
|
||||
- [ ] Manual verification completed for visual/behavioral checks
|
||||
- [x] Wave 0: existing test infrastructure sufficient
|
||||
- [x] Feedback latency < 120s
|
||||
|
||||
**Approval:** code-complete, manual verification pending
|
||||
|
||||
Reference in New Issue
Block a user