---
phase: 7
plan: 07-01
type: execute
wave: 1
depends_on: []
files_modified:
  - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift
  - Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift
  - Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift
  - Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift
autonomous: true
requirements:
  - ATTR-01
  - ATTR-03
---

# Phase 7-01: 自定义分页语义映射

<objective>
定义一套显式的 WXRead 分页语义模型，并把章节 HTML/CSS 中的分页相关语义稳定映射到 attributed string，作为后续分页器消费的唯一事实来源。
</objective>

<must_haves>
- `avoidPageBreakInside`、`pageBreakBefore`、`pageBreakAfter`、`pageRelate` 至少在 attributed string 层形成统一属性键闭环。
- 块元素分类需要在 attributed string 或配套语义模型中可读，而不是只存在于 HTML 标签解析时的瞬时判断。
- 现有 `fragmentOffsets`、`pageStartOffset`、`pageEndOffset` 兼容语义不被破坏。
</must_haves>

<tasks>
<task id="07-01-01">
<type>execute</type>
<action>在 `RDEPUBTextRenderer.swift` 与 `RDEPUBReadingModels.swift` 中定义 Phase 7 需要的原生分页语义类型和属性键，例如块类型、分页 hint、附件垂直居中值、页面关联标记等。保持命名收敛，避免把语义散落成多个匿名字符串常量。</action>
<read_first>
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift
- Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift
- .planning/phases/07-wxread/07-RESEARCH.md
- Doc/WXRead/analysis/DTCoreText自定义修改分析.md
</read_first>
<acceptance_criteria>
- 新语义有明确的 Swift 类型或受控 raw-value 定义，不依赖匿名 magic string。
- 至少覆盖 `avoidPageBreakInside`、`pageBreakBefore`、`pageBreakAfter`、`pageRelate`、块类型、附件垂直居中语义。
- 现有 `rdPageBlockRange`、`rdPageBlockIndex`、`rdPageAttachmentKind` 语义保持兼容，不被重命名或删除。
</acceptance_criteria>
</task>

<task id="07-01-02">
<type>execute</type>
<action>扩展 `RDEPUBTextRendererSupport` 与 `RDEPUBDTCoreTextRenderer` 的 preprocessing / post-processing 流程，从章节 HTML/CSS 中提取上述语义并写入 attributed string。优先复用现有 chapter preprocessing 与 attribute normalization 流程，必要时通过可诊断的桥接标记或受控 HTML 注入把 DTCoreText 默认不会保留的语义带过来。</action>
<read_first>
- Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift
- Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift
- ReadViewDemo/Pods/DTCoreText/Core/Source/DTHTMLElement.h
- ReadViewDemo/Pods/DTCoreText/Core/Source/DTHTMLAttributedStringBuilder.m
</read_first>
<acceptance_criteria>
- 渲染后的 attributed string 至少能在对应 range 上读到分页 hint、页面关联标记与块类型中的一部分或全部。
- 无法直接保真的语义必须有明确桥接策略和诊断回退，而不是默默丢失。
- 现有章节渲染流程仍可构建 native text 样本，不引入 fixed/interactive 分支依赖。
</acceptance_criteria>
</task>
</tasks>

<verification>
- Build the `ReadViewDemo` workspace with the `ReadViewDemo` scheme.
- 对一个包含图片和复杂块元素的 native text 样本打印 attributed string 语义摘要，确认关键属性可见。
- 确认 fragment marker 提取和现有章节分页入口仍然工作。
</verification>

<success_criteria>
- Phase 7 的核心语义在 attributed string 层稳定存在。
- 语义提取路径集中在 renderer support，而不是散落在 UI 层。
- 后续分页器与诊断路径可以消费统一的语义模型。
</success_criteria>