PPTX/openspec/changes/archive/2026-03-02-refactor-yaml2pptx-modular/specs/element-rendering/spec.md at 7ef29ea03945af87f54338ec91142f6d3cd1d882

Files

lanyuanxiaoyao ed940f0690 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)

2026-03-02 16:43:45 +08:00

2.4 KiB

Raw Blame History

MODIFIED Requirements

Requirement: 系统必须使用元素数据类进行渲染

系统 SHALL 使用元素数据类（TextElement, ImageElement, ShapeElement, TableElement）进行渲染，而不是直接处理字典数据。渲染器接收元素对象，通过类型检查分发到对应的渲染方法。

Scenario: 渲染器接收元素对象

WHEN 渲染器的 _render_element() 方法被调用
THEN 系统应接收元素对象（如 TextElement 实例），而不是字典

Scenario: 通过类型检查分发渲染

WHEN 渲染器处理元素对象
THEN 系统应使用 isinstance() 检查元素类型，分发到对应的渲染方法（如 _render_text(), _render_image()）

Scenario: 元素验证在创建时完成

WHEN 元素对象被创建
THEN 系统应在 __post_init__ 方法中完成验证，渲染时不再需要验证

Requirement: 渲染器必须内置在生成器中

系统 SHALL 将渲染逻辑内置在 PptxGenerator 类中，作为私有方法（_render_text(), _render_image() 等），而不是独立的函数。

Scenario: 渲染方法作为生成器的私有方法

WHEN 开发者查看 PptxGenerator 类
THEN 应包含 _render_text(), _render_image(), _render_shape(), _render_table() 等私有方法

Scenario: 渲染方法接收元素对象

WHEN 调用 _render_text(slide, elem) 方法
THEN elem 参数应为 TextElement 对象，包含 content、box、font 等属性

ADDED Requirements

Requirement: 元素渲染必须支持元素对象的属性访问

系统 SHALL 通过元素对象的属性（如 elem.content, elem.box, elem.font）访问数据，而不是通过字典的 get() 方法。

Scenario: 访问文本元素的属性

WHEN 渲染文本元素
THEN 系统应使用 elem.content 而不是 elem.get('content', '')

Scenario: 访问图片元素的属性

WHEN 渲染图片元素
THEN 系统应使用 elem.src 和 elem.box 而不是 elem.get('src') 和 elem.get('box')

Scenario: 访问形状元素的属性

WHEN 渲染形状元素
THEN 系统应使用 elem.shape, elem.fill, elem.line 等属性

Scenario: 访问表格元素的属性

WHEN 渲染表格元素
THEN 系统应使用 elem.data, elem.position, elem.col_widths, elem.style 等属性

2.4 KiB Raw Blame History Unescape Escape