docs(phase-01): add planning artifacts

This commit is contained in:
shen
2026-05-21 22:00:41 +08:00
parent 0870996ed0
commit 6d196d64e5
5 changed files with 539 additions and 0 deletions
@@ -0,0 +1,107 @@
---
phase: 01-current-engine-boundaries
plan: 02
type: execute
wave: 2
depends_on:
- "01-01"
files_modified:
- .planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md
autonomous: true
requirements:
- COMP-02
user_setup: []
must_haves:
truths:
- 策略文档给出“旧引擎直接演进”而不是“双引擎并存”的切入方案。
- 策略文档明确 Fixed Layout / 交互式 EPUB 继续走 `WKWebView`。
- 策略文档明确 `RDReaderView` 与现有翻页容器契约保持不变。
- 策略文档指出 Phase 2 与 Phase 3 分别应优先触碰的代码触点。
artifacts:
- .planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md
key_links:
- `Doc/WXRead/analysis/*` 的目标能力被映射到当前 `EPUBTextRendering` 触点。
- `01-reflowable-audit.md` 中确认的边界被转写为后续阶段的实施约束。
---
<objective>
基于当前审计结果和 WXRead 资料,产出一份可执行的旧引擎直接演进策略文档。
Purpose: 把“从哪里动、先动什么、哪些外部契约不能动”固定下来,作为 Phase 2/3 的实现基线。
Output: `.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md`
</objective>
<execution_context>
@$HOME/.codex/get-shit-done/workflows/execute-plan.md
@$HOME/.codex/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-current-engine-boundaries/01-RESEARCH.md
@.planning/phases/01-current-engine-boundaries/01-PATTERNS.md
@.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md
@Doc/WXRead/analysis/01_核心架构与数据流图.md
@Doc/WXRead/analysis/02_符号恢复与核心算法.md
@Doc/WXRead/analysis/EPUB渲染管线详解.md
@Doc/WXRead/analysis/DTCoreText自定义修改分析.md
@Doc/FeatureSolution/ReflowableEPUB_WXReadRenderer_Design.md
@Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift
@Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift
@Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift
@Sources/RDReaderView/RDReaderView.swift
</context>
<tasks>
<task type="auto">
<name>Task 1: 提炼 WXRead 目标能力到当前引擎触点</name>
<files>.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md</files>
<read_first>.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md, Doc/WXRead/analysis/EPUB渲染管线详解.md, Doc/WXRead/analysis/DTCoreText自定义修改分析.md, Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift</read_first>
<action>新建 `01-refactor-entry-strategy.md`,把 WXRead 资料中的五层 CSS、DTCoreText 自定义属性、页面级元数据、块级避免断页、layout frame / layouter 责任拆解为当前仓库可落地的触点映射。至少给出 `RDEPUBDTCoreTextRenderer``RDEPUBTextBookBuilder``RDEPUBTextPaginationSupport``RDEPUBTextPage` / `RDEPUBTextChapter` 这些具体落点,并说明每个落点在 Phase 2 或 Phase 3 中承担什么职责。</action>
<verify>rg -n "RDEPUBDTCoreTextRenderer|RDEPUBTextBookBuilder|RDEPUBTextPaginationSupport|RDEPUBTextPage|RDEPUBTextChapter|CSS|属性|分页" .planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md</verify>
<acceptance_criteria>
- 文档包含明确的“WXRead 能力 -> 当前源码触点”映射
- 文档点名 `RDEPUBDTCoreTextRenderer``RDEPUBTextBookBuilder``RDEPUBTextPaginationSupport`
- 文档区分 Phase 2 与 Phase 3 的切入重心
</acceptance_criteria>
<done>策略文档不再停留在抽象“参考 WXRead”,而是把目标能力落成当前仓库里的具体改造入口。</done>
</task>
<task type="auto">
<name>Task 2: 固化范围边界和兼容性保留链路</name>
<files>.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md</files>
<read_first>.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md, Doc/FeatureSolution/ReflowableEPUB_WXReadRenderer_Design.md, Sources/RDReaderView/EPUBCore/RDEPUBParser+ReadingProfile.swift, Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/RDReaderView.swift</read_first>
<action>在策略文档中追加“非目标与兼容面”章节,明确列出以下内容:`webFixedLayout``webInteractive` 保持 `WKWebView``RDReaderView` 与现有翻页模式不改,阅读位置/高亮/搜索/主题切换后的重分页必须继续通过现有 `RDEPUBReaderController` 契约工作;同时给出后续实施顺序建议,说明为什么必须先增强 renderer/typesetter,再升级分页语义,最后再回接 reader 能力链路。</action>
<verify>rg -n "WKWebView|RDReaderView|阅读位置|高亮|搜索|主题|重分页|实施顺序" .planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md</verify>
<acceptance_criteria>
- 文档明确写出 `WKWebView` 保留边界
- 文档明确写出 `RDReaderView` 不修改
- 文档明确列出阅读位置、高亮、搜索、主题切换等兼容项
- 文档包含一个按阶段排序的切入顺序
</acceptance_criteria>
<done>策略文档既给出切入点,也把必须保留的外层契约固定为后续 phase 的硬约束。</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] `test -f .planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md`
- [ ] `rg -n "WKWebView|RDReaderView|RDEPUBDTCoreTextRenderer|RDEPUBTextBookBuilder" .planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md`
- [ ] 文档结论与 `01-reflowable-audit.md` 不冲突,并明确拒绝双引擎方案
</verification>
<success_criteria>
- All tasks completed
- All verification checks pass
- No errors or warnings introduced
- 策略文档足以直接指导 Phase 2/3 进入实现,不再重复做边界澄清
</success_criteria>
<output>
After completion, create `.planning/phases/01-current-engine-boundaries/01-02-SUMMARY.md`
</output>