lanyuanxiaoyao
ed940f0690
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)
2.8 KiB
2.8 KiB
Why
yaml2pptx.py 脚本已增长到 1,245 行，包含了 YAML 解析、模板系统、元素渲染、PPTX 生成、HTML 预览等多个功能模块。单文件结构导致代码难以阅读、维护和扩展，对开发者和 LLM 工具都不友好。需要将其重构为模块化结构，同时引入元素抽象层，为未来添加新元素类型和渲染器奠定基础。
What Changes
- 将 yaml2pptx.py 拆分为多个功能模块文件，按 core/loaders/renderers/preview 四层架构组织
- 引入元素抽象层，使用 dataclass 定义元素数据类（TextElement, ImageElement, ShapeElement, TableElement）
- 在元素创建时进行验证（
__post_init__方法） - 重构 PPTX 生成器，将渲染器内置在 PptxGenerator 类中
- 重构 HTML 渲染器，作为独立的 HtmlRenderer 类用于预览功能
- 保持 yaml2pptx.py 作为单一入口点，所有依赖声明保留在入口脚本的
/// script头部 - 保持向后兼容：
uv run yaml2pptx.py的使用方式不变
Capabilities
New Capabilities
modular-architecture: 模块化代码架构，将单文件脚本拆分为 core（核心领域模型）、loaders（加载器）、renderers（渲染器）、preview（预览服务）四层结构，每个模块职责清晰，文件大小控制在 150-300 行element-abstraction: 元素抽象层，定义统一的元素接口和数据类，支持元素验证和未来扩展新元素类型
Modified Capabilities
element-rendering: 从函数式渲染改为基于元素数据类的面向对象渲染，引入元素抽象层和创建时验证pptx-generation: 重构为内置渲染器的架构，PptxGenerator 类内部包含 PPTX 渲染逻辑，通过元素类型分发到对应的渲染方法html-rendering: 从内联函数重构为独立的 HtmlRenderer 类，与 PptxRenderer 共享元素抽象层
Impact
代码结构：
- yaml2pptx.py：从 1,245 行缩减为约 100 行（仅保留 CLI 和 main 函数）
- 新增文件：
- core/elements.py（元素数据类）
- core/template.py（Template 类）
- core/presentation.py（Presentation 类）
- loaders/yaml_loader.py（YAML 加载和验证）
- renderers/pptx_renderer.py（PptxGenerator）
- renderers/html_renderer.py（HtmlRenderer）
- preview/server.py（Flask 服务器和文件监听）
- utils.py（工具函数）
导入路径：
- 内部导入路径会发生变化（如
from core.elements import TextElement） - 外部使用方式不变（
uv run yaml2pptx.py input.yaml output.pptx）
依赖管理：
- 所有依赖保持在 yaml2pptx.py 的
/// script头部 - 预览功能的依赖（flask, watchdog）不再可选，统一在入口声明
测试和验证：
- 需要验证所有现有功能在重构后仍正常工作
- 需要测试 YAML 解析、模板渲染、PPTX 生成、HTML 预览等完整流程