# Phase 8: 图片显示修复 - Context

**Gathered:** 2026-05-23
**Status:** Ready for planning

<domain>
## Phase Boundary

修复 native text 渲染路径（DTCoreText）中三类图片的尺寸适配问题：
1. `qrbodyPic` 容器中的独立图片 — 当前无特殊处理，高度可能溢出页面
2. 封面图片 (`frontCover`) — 当前用屏幕尺寸基准，需统一到最大尺寸逻辑
3. 脚注图片 (`qqreader-footnote`) — 当前三处不一致的尺寸处理

核心目标：对齐 WXRead 的 `_WRPostProcessElementTree` 逻辑，对所有图片附件统一执行最大尺寸限制。

</domain>

<decisions>
## Implementation Decisions

### 图片最大尺寸
- **D-01:** 对所有图片附件统一执行最大尺寸限制 `CGSizeMake(1080, 1920)`
- **D-02:** 超过最大宽度时等比缩放（与 WXRead `_WRPostProcessElementTree` 一致）
- **D-03:** 实现位置：`prepareHTMLElementForReaderRendering` 中，在现有 footnote/cover 特殊处理之前，添加统一的最大尺寸限制逻辑

### 封面图片
- **D-04:** 保持屏幕尺寸基准（`UIScreen.main.bounds.insetBy(dx: 20, dy: 28)`），但受统一最大尺寸 1080x1920 约束
- **D-05:** 保持 `configureCoverIfNeeded` 的 UIImageView 专用路径不变
- **D-06:** 封面图片仍通过 `prepareHTMLElementForReaderRendering` 中的 cover 分支处理，但需确保不超过统一最大尺寸

### 脚注图片
- **D-07:** 对齐 WXRead：只设 `width:1em`，不设高度，让渲染器按原始宽高比自动计算
- **D-08:** 移除 `prepareHTMLElementForReaderRendering` 中脚注的高度计算逻辑（`pointSize * 0.54`）
- **D-09:** 移除 `normalizeInlineAttachments` 中的高度覆盖逻辑（`pointSize * 0.14`）
- **D-10:** 保留 `normalizeAttachmentHTMLMarkers` 中的 CSS `width:1em`，移除 `height:1em`

### qrbodyPic 图片
- **D-11:** 不单独添加特殊处理逻辑，统一最大尺寸限制会隐式修复高度溢出问题
- **D-12:** 保持现有 CSS 规则不变（`max-width:100%; height:auto; display:block; margin:auto`）

### Claude's Discretion
- 具体实现细节（如是否需要自动添加 `bodyPic` 类、是否需要 `wr-vertical-center-style` 语义标记）由 planner 和 executor 决定
- 图片缓存策略不在本次讨论范围，属于 Phase 8 的 08-01 计划

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### WXRead 参考实现
- `Doc/WXRead/decompiled/WREpubTypesetter.m` §672-701 — `_WRPostProcessElementTree()`：统一图片最大尺寸逻辑（1080x1920）、自动添加 bodyPic 类、设置 wr-vertical-center-style
- `Doc/WXRead/decompiled/WRCoreTextLayoutFrame.m` §615-635 — `drawCoverImage:inContext:rect:`：封面图片等比缩放适配 frame
- `Doc/WXRead/decompiled/WRCoreTextLayouter.m` §639-667 — `targetSizeForPattern:rect:imageSize:`：sizePattern 缩放逻辑
- `Doc/WXRead/resources/css/replace.css` §91-103 — `.bodyPic`、`.qrbodyPic`、`.qqreader-footnote` 的 CSS 规则

### ReadViewSDK 当前实现
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift` §220-262 — `prepareHTMLElementForReaderRendering`：当前图片处理逻辑
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift` §302-343 — `replaceCSS()`：当前图片 CSS 规则
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift` §345-404 — `normalizeAttachmentHTMLMarkers`：HTML 预处理
- `Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift` §217-282 — `configureCoverIfNeeded` 和 `normalizeInlineAttachments`
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift` §90-112 — `dtOptions`：DTMaxImageSize 配置

### Demo 样本
- `ReadViewDemo/ReadViewDemo/book/宝山辽墓材料与释读_副本/OEBPS/Styles/stylesheets.css` — 实际 EPUB 书籍的图片 CSS
- `ReadViewDemo/ReadViewDemo/book/宝山辽墓材料与释读_副本/OEBPS/Text/cover.xhtml` — 封面 HTML 结构
- `ReadViewDemo/ReadViewDemo/book/宝山辽墓材料与释读_副本/OEBPS/Text/Chapter_5.xhtml` — qrbodyPic 图片 HTML 结构

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `prepareHTMLElementForReaderRendering`：已有 footnote 和 cover 的分类处理框架，可在此基础上添加统一最大尺寸逻辑
- `normalizeAttachmentHTMLMarkers`：已有 HTML 正则替换基础设施，可复用于 qrbodyPic 的 HTML 预处理
- `replaceCSS()`：已有图片 CSS 规则，可直接修改

### Established Patterns
- 图片分类检测：通过 CSS class（`qqreader-footnote`、`rd-front-cover-image`）和文件名（`note.png`、`cover.jpg`）识别图片类型
- DTTextAttachment API：`originalSize`（原始尺寸）、`displaySize`（显示尺寸）、`verticalAlignment`（垂直对齐）
- HTML 正则替换：`mergeHTMLAttributes` + `replaceMatches` 模式用于 HTML 预处理

### Integration Points
- `RDEPUBDTCoreTextRenderer.swift` → `willFlushCallback` → `prepareHTMLElementForReaderRendering`：DTCoreText 渲染时的图片处理入口
- `RDEPUBTextContentView.swift` → `configureCoverIfNeeded`：封面图片显示入口
- `RDEPUBTextContentView.swift` → `normalizeInlineAttachments`：显示时的脚注图片处理入口

</code_context>

<specifics>
## Specific Ideas

- 用户明确要求"等比缩放，让图片都能显示全"——图片不能被裁剪，必须完整显示
- 用户明确要求脚注图片"显示的和文本的高度一样，高度不能超过文本的高度"
- WXRead 的实现是参考标准，但不需要 100% 复制——只对齐图片尺寸逻辑

</specifics>

<deferred>
## Deferred Ideas

- 图片缓存机制（属于 08-01 计划）
- `wr-vertical-center-style` 垂直居中语义的完整实现（属于 Phase 7 已完成的工作）
- 图片点击放大/查看大图功能（新能力，不属于当前范围）
- 代码块/表格被粗暴截断（QUAL-02 子需求）— 本次聚焦图片尺寸修复，代码块/表格截断问题留待后续分页质量迭代处理

</deferred>

---

*Phase: 8-图片显示修复*
*Context gathered: 2026-05-23*