# Phase 7: WXRead 自定义属性闭环 - Research

**Date:** 2026-05-22
**Phase:** 7

## Research Question

What do we need to know to plan the WXRead custom pagination-attribute closure well for the native text pipeline?

## Current State

- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift` 已经负责章节 HTML 预处理、CSS 分层注入、fragment marker 注入，以及 `normalizeReadingAttributes` 的统一属性收口。
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift` 当前只把 DTCoreText 产出的 attributed string 交给通用后处理，没有显式保留 WXRead 风格的分页语义。
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift` 目前只定义了 `rdPageBlockRange`、`rdPageBlockIndex`、`rdPageFragmentID`、`rdPageAttachmentKind` 四个原生属性键，缺少分页控制语义模型。
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift` 已经会消费 block/attachment 元数据，并在分页时输出 `breakReason`、`blockRange`、`attachmentKinds`、`diagnostics`，但还不会消费 `avoidPageBreakInside`、`pageBreakBefore`、`pageBreakAfter`、`pageRelate` 这类显式语义。
- `Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift` 的 `RDEPUBTextPageMetadata` 已经是页级元数据汇总点，适合继续承载块类型、附件语义、强制分页、分页诊断摘要。
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` 会把分页结果提升为 chapter/page 模型，并生成诊断摘要，是把新语义暴露给 Demo、回归、后续 Phase 8 的最佳出口。
- `Doc/WXRead/analysis/EPUB渲染管线详解.md` 与 `Doc/WXRead/analysis/DTCoreText自定义修改分析.md` 明确给出了目标语义集合：`wr-vertical-center-style`、`weread-page-relate`、`avoidPageBreakInside`、`pageBreakBefore`、`pageBreakAfter`，以及 `table / code / list / blockquote` 这类块分类。
- `ReadViewDemo/Pods/DTCoreText/Core/Source/DTHTMLElement.*` 与 `DTHTMLAttributedStringBuilder.*` 是当前可复用的底层行为边界：现阶段更现实的是在现有 chapter preprocessing 和 attributed-string 后处理层增量接线，而不是直接重写 DTCoreText 私有实现。

## What This Means

1. Phase 7 的缺口不是“再造一个 renderer”，而是给现有 renderer 增加一套显式、可诊断、可分页消费的语义模型。
2. 最稳妥的切入点是 `RDEPUBTextRendererSupport`，因为它已经同时掌握 HTML、CSS、attributed string、fragment marker 和统一后处理。
3. 块分类和分页语义必须先在 attributed string 上变成稳定属性键，后面的 layouter / page metadata / demo 诊断才能复用同一份事实。
4. 附件语义不能只保留“是不是图片”，还需要保留像 `wr-vertical-center-style` 这样的消费值，否则 Phase 8 无法继续细化图片/附件规则。
5. `avoidPageBreakInside`、`pageBreakBefore`、`pageBreakAfter` 不能停留在“记录下来”，它们至少要影响分页边界选择或诊断结果，否则闭环是不完整的。

## Recommended Planning Shape

- **Plan 07-01:** 定义语义模型与属性键，把 HTML/CSS 中的分页相关语义稳定映射到 attributed string。
- **Plan 07-02:** 让分页器和页级元数据真正消费这些语义，尤其是块分类、强制分页、附件垂直居中与 avoid-break 规则。
- **Plan 07-03:** 把语义闭环暴露到 demo / 诊断 / 回归路径，确保复杂样本上可观察、可比对、可复现。

## Technical Risks

- 如果语义提取分散在 renderer、layouter、UI 多处，Phase 8 会继续面对“同一规则多处解释”的漂移问题。
- DTCoreText 默认产物对自定义 CSS 属性并不天然保真，Phase 7 需要在 preprocessing 或 post-processing 层建立明确桥接策略。
- `avoidPageBreakInside` 与强制分页一旦直接改写分页边界，最容易引入 page offset 回归，因此必须把兼容契约和诊断一起规划进去。
- 块分类如果只靠标签名静态猜测，遇到 EPUB 自带 class/style 变体时可能不稳定；计划里需要明确保守策略和可诊断回退。

## Validation Implications

- 现有仓库没有独立测试靶，Phase 7 仍需依赖 simulator build/run 与 demo 日志证据。
- 验证重点必须覆盖三类证据：属性是否进入 attributed string、分页器是否消费、demo 是否能看见块类型/附件语义/分页原因。
- 复杂样本至少要覆盖代码块/表格/列表/引用块以及含图片附件章节，否则 ATTR-02 / ATTR-03 的闭环无法证明。