1
0

refactor: modularize yaml2pptx into layered architecture

Refactor yaml2pptx.py from a 1,245-line monolithic script into a modular
architecture with clear separation of concerns. The entry point is now
127 lines, with business logic distributed across focused modules.

Architecture:
- core/: Domain models (elements, template, presentation)
- loaders/: YAML loading and validation
- renderers/: PPTX and HTML rendering
- preview/: Flask preview server
- utils.py: Shared utilities

Key improvements:
- Element abstraction layer using dataclass with validation
- Renderer logic built into generator classes
- Single-direction dependencies (no circular imports)
- Each module 150-300 lines for better readability
- Backward compatible CLI interface

Documentation:
- README.md: User-facing usage guide
- README_DEV.md: Developer documentation

OpenSpec:
- Archive refactor-yaml2pptx-modular change (63/70 tasks complete)
- Sync 5 delta specs to main specs (2 new + 3 updated)
This commit is contained in:
2026-03-02 16:43:45 +08:00
parent b2132dc06b
commit ed940f0690
31 changed files with 3142 additions and 1307 deletions

View File

@@ -197,6 +197,92 @@ HTML Rendering 系统负责将 YAML 中定义的各类元素(文本、图片
- **WHEN** 渲染多个幻灯片
- **THEN** 每个幻灯片之间有 20px 的垂直间距
### Requirement: HTML 渲染必须使用独立的 HtmlRenderer 类
系统 SHALL 将 HTML 渲染逻辑重构为独立的 HtmlRenderer 类,而不是内联函数。
#### Scenario: HtmlRenderer 类定义在独立模块
- **WHEN** 开发者查看项目结构
- **THEN** HtmlRenderer 类应定义在 `renderers/html_renderer.py` 文件中
#### Scenario: HtmlRenderer 包含渲染方法
- **WHEN** 开发者查看 HtmlRenderer 类
- **THEN** 应包含 `render_slide()`, `render_text()`, `render_image()`, `render_shape()`, `render_table()` 等方法
#### Scenario: 预览服务器使用 HtmlRenderer
- **WHEN** 预览服务器生成 HTML
- **THEN** 应创建 HtmlRenderer 实例并调用其渲染方法
### Requirement: HTML 渲染必须接收元素对象
系统 SHALL 使 HtmlRenderer 的渲染方法接收元素对象TextElement, ImageElement 等),而不是字典。
#### Scenario: render_text 接收 TextElement 对象
- **WHEN** 调用 `renderer.render_text(elem)`
- **THEN** `elem` 参数应为 TextElement 对象
#### Scenario: render_image 接收 ImageElement 对象
- **WHEN** 调用 `renderer.render_image(elem, base_path)`
- **THEN** `elem` 参数应为 ImageElement 对象
#### Scenario: render_shape 接收 ShapeElement 对象
- **WHEN** 调用 `renderer.render_shape(elem)`
- **THEN** `elem` 参数应为 ShapeElement 对象
#### Scenario: render_table 接收 TableElement 对象
- **WHEN** 调用 `renderer.render_table(elem)`
- **THEN** `elem` 参数应为 TableElement 对象
### Requirement: HTML 渲染必须通过元素属性访问数据
系统 SHALL 通过元素对象的属性(如 `elem.content`, `elem.box`)访问数据,而不是通过字典的 `get()` 方法。
#### Scenario: 访问文本元素属性
- **WHEN** 渲染文本元素
- **THEN** 应使用 `elem.content`, `elem.box`, `elem.font` 等属性
#### Scenario: 访问图片元素属性
- **WHEN** 渲染图片元素
- **THEN** 应使用 `elem.src`, `elem.box` 等属性
#### Scenario: 访问形状元素属性
- **WHEN** 渲染形状元素
- **THEN** 应使用 `elem.shape`, `elem.box`, `elem.fill`, `elem.line` 等属性
#### Scenario: 访问表格元素属性
- **WHEN** 渲染表格元素
- **THEN** 应使用 `elem.data`, `elem.position`, `elem.col_widths`, `elem.style` 等属性
### Requirement: HtmlRenderer 必须与 PptxRenderer 共享元素抽象层
系统 SHALL 使 HtmlRenderer 和 PptxRenderer 都基于相同的元素数据类(定义在 core/elements.py确保一致性。
#### Scenario: 两个渲染器使用相同的元素类型
- **WHEN** 开发者查看 HtmlRenderer 和 PptxRenderer
- **THEN** 两者都应导入并使用 `from core.elements import TextElement, ImageElement, ShapeElement, TableElement`
#### Scenario: 元素验证在创建时完成
- **WHEN** 元素对象传递给 HtmlRenderer
- **THEN** 元素已经在创建时完成验证HtmlRenderer 不需要再次验证
#### Scenario: 添加新元素类型时两个渲染器同步更新
- **WHEN** 在 core/elements.py 中添加新元素类型(如 VideoElement
- **THEN** 需要在 HtmlRenderer 和 PptxRenderer 中都实现对应的渲染方法
### Requirement: 系统必须复用现有的解析逻辑
系统 SHALL 复用 `yaml2pptx.py` 中现有的 `Presentation` 类和模板渲染逻辑。