lanyuanxiaoyao/PPTX
1
0
Fork 0
Code Activity
Files
c73bd0fedd8a14732c8e3df37824bd66ada65c2d
PPTX/openspec/changes/archive/2026-03-02-refactor-yaml2pptx-modular/specs/pptx-generation/spec.md
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.9 KiB
Raw Blame History

MODIFIED Requirements

Requirement: PptxGenerator 必须内置渲染器

系统 SHALL 将 PptxGenerator 类重构为内置渲染器的架构，渲染逻辑作为类的私有方法，而不是独立的函数。

Scenario: PptxGenerator 包含渲染方法

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

Scenario: add_slide 方法调用内置渲染器

  • WHEN 调用 generator.add_slide(slide_data, base_path)
  • THEN 系统应在方法内部调用 _render_element() 来渲染每个元素

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

  • WHEN 渲染方法被调用
  • THEN 应接收元素对象（如 TextElement, ImageElement）而不是字典

Requirement: PptxGenerator 必须位于 renderers 模块

系统 SHALL 将 PptxGenerator 类从主脚本提取到 renderers/pptx_renderer.py 模块中。

Scenario: PptxGenerator 在独立模块中

  • WHEN 开发者查看项目结构
  • THEN PptxGenerator 类应定义在 renderers/pptx_renderer.py 文件中

Scenario: 主脚本导入 PptxGenerator

  • WHEN yaml2pptx.py 需要使用 PptxGenerator
  • THEN 应通过 from renderers.pptx_renderer import PptxGenerator 导入

ADDED Requirements

Requirement: 渲染器必须通过类型检查分发元素

系统 SHALL 在 _render_element() 方法中使用 isinstance() 检查元素类型，分发到对应的渲染方法。

Scenario: 分发文本元素

  • WHEN _render_element() 接收到 TextElement 对象
  • THEN 系统应调用 _render_text(slide, elem)

Scenario: 分发图片元素

  • WHEN _render_element() 接收到 ImageElement 对象
  • THEN 系统应调用 _render_image(slide, elem, base_path)

Scenario: 分发形状元素

  • WHEN _render_element() 接收到 ShapeElement 对象
  • THEN 系统应调用 _render_shape(slide, elem)

Scenario: 分发表格元素

  • WHEN _render_element() 接收到 TableElement 对象
  • THEN 系统应调用 _render_table(slide, elem)

Requirement: 渲染方法必须访问元素对象的属性

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

Scenario: 访问文本元素属性

  • WHEN _render_text() 渲染文本元素
  • THEN 应使用 elem.content, elem.box, elem.font 等属性

Scenario: 访问图片元素属性

  • WHEN _render_image() 渲染图片元素
  • THEN 应使用 elem.src, elem.box 等属性

Scenario: 访问形状元素属性

  • WHEN _render_shape() 渲染形状元素
  • THEN 应使用 elem.shape, elem.box, elem.fill, elem.line 等属性

Scenario: 访问表格元素属性

  • WHEN _render_table() 渲染表格元素
  • THEN 应使用 elem.data, elem.position, elem.col_widths, elem.style 等属性
View Git Blame Copy Permalink