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:
@@ -0,0 +1,99 @@
|
||||
## 1. 准备工作
|
||||
|
||||
- [ ] 1.1 备份原始 yaml2pptx.py 文件为 yaml2pptx.py.backup
|
||||
- [x] 1.2 创建目录结构（core/, loaders/, renderers/, preview/）
|
||||
- [x] 1.3 在各目录下创建 __init__.py 文件
|
||||
|
||||
## 2. 基础设施层（utils + loaders）
|
||||
|
||||
- [x] 2.1 创建 utils.py，提取日志函数（log_info, log_success, log_error, log_progress）
|
||||
- [x] 2.2 在 utils.py 中提取颜色转换函数（hex_to_rgb, validate_color）
|
||||
- [x] 2.3 创建 loaders/yaml_loader.py，提取 YAMLError 异常类
|
||||
- [x] 2.4 在 loaders/yaml_loader.py 中提取 load_yaml_file 函数
|
||||
- [x] 2.5 在 loaders/yaml_loader.py 中提取验证函数（validate_presentation_yaml, validate_template_yaml）
|
||||
- [x] 2.6 更新 yaml2pptx.py 的导入语句，导入 utils 和 loaders 模块
|
||||
- [x] 2.7 测试 YAML 加载功能（运行 `uv run yaml2pptx.py --help` 确认无导入错误）
|
||||
|
||||
## 3. 核心抽象层（core/elements）
|
||||
|
||||
- [x] 3.1 创建 core/elements.py，定义 TextElement dataclass（包含 type, content, box, font 字段）
|
||||
- [x] 3.2 在 TextElement 中实现 __post_init__ 验证方法（验证 box 长度）
|
||||
- [x] 3.3 定义 ImageElement dataclass（包含 type, src, box 字段及验证）
|
||||
- [x] 3.4 定义 ShapeElement dataclass（包含 type, shape, box, fill, line 字段及验证）
|
||||
- [x] 3.5 定义 TableElement dataclass（包含 type, data, position, col_widths, style 字段及验证）
|
||||
- [x] 3.6 实现 create_element 工厂函数，根据 type 字段创建对应的元素对象
|
||||
- [x] 3.7 测试元素创建和验证（创建测试用例验证各元素类型）
|
||||
|
||||
## 4. 核心抽象层（core/template + presentation）
|
||||
|
||||
- [x] 4.1 创建 core/template.py，提取 Template 类
|
||||
- [x] 4.2 更新 Template 类的导入，使用 loaders.yaml_loader 和 utils
|
||||
- [x] 4.3 创建 core/presentation.py，提取 Presentation 类
|
||||
- [x] 4.4 更新 Presentation 类的导入，使用 loaders.yaml_loader 和 core.template
|
||||
- [x] 4.5 修改 Presentation.render_slide 方法，使元素通过 create_element 转换为元素对象
|
||||
- [ ] 4.6 测试模板渲染功能（使用现有的 YAML 文件测试）
|
||||
|
||||
## 5. PPTX 渲染器
|
||||
|
||||
- [x] 5.1 创建 renderers/pptx_renderer.py，定义 PptxGenerator 类
|
||||
- [x] 5.2 在 PptxGenerator.__init__ 中实现幻灯片尺寸设置逻辑
|
||||
- [x] 5.3 实现 PptxGenerator.add_slide 方法（创建幻灯片、设置背景、调用 _render_element）
|
||||
- [x] 5.4 实现 _render_element 方法（使用 isinstance 检查元素类型并分发）
|
||||
- [x] 5.5 实现 _render_text 方法（从原 add_text_element 迁移，使用元素对象属性）
|
||||
- [x] 5.6 实现 _render_image 方法（从原 add_image_element 迁移，使用元素对象属性）
|
||||
- [x] 5.7 实现 _render_shape 方法（从原 add_shape_element 迁移，使用元素对象属性）
|
||||
- [x] 5.8 实现 _render_table 方法（从原 add_table_element 迁移，使用元素对象属性）
|
||||
- [x] 5.9 实现 _render_background 方法（从原 set_slide_background 迁移）
|
||||
- [x] 5.10 实现 PptxGenerator.save 方法
|
||||
- [x] 5.11 更新 PptxGenerator 的导入，使用 core.elements 和 utils
|
||||
- [x] 5.12 测试 PPTX 生成功能（生成测试 PPTX 文件并验证）
|
||||
|
||||
## 6. HTML 渲染器
|
||||
|
||||
- [x] 6.1 创建 renderers/html_renderer.py，定义 HtmlRenderer 类
|
||||
- [x] 6.2 实现 HtmlRenderer.render_slide 方法（生成幻灯片 HTML 容器）
|
||||
- [x] 6.3 实现 render_text 方法（从原 render_text_element_to_html 迁移，使用元素对象属性）
|
||||
- [x] 6.4 实现 render_image 方法（从原 render_image_element_to_html 迁移，使用元素对象属性）
|
||||
- [x] 6.5 实现 render_shape 方法（从原 render_shape_element_to_html 迁移，使用元素对象属性）
|
||||
- [x] 6.6 实现 render_table 方法（从原 render_table_element_to_html 迁移，使用元素对象属性）
|
||||
- [x] 6.7 更新 HtmlRenderer 的导入，使用 core.elements
|
||||
- [ ] 6.8 测试 HTML 渲染功能（生成测试 HTML 并在浏览器中验证）
|
||||
|
||||
## 7. 预览服务器
|
||||
|
||||
- [x] 7.1 创建 preview/server.py，提取 Flask 应用相关代码
|
||||
- [x] 7.2 提取 HTML_TEMPLATE 和 ERROR_TEMPLATE 常量
|
||||
- [x] 7.3 提取 YAMLChangeHandler 类
|
||||
- [x] 7.4 提取 create_flask_app 函数
|
||||
- [x] 7.5 提取 start_preview_server 函数
|
||||
- [x] 7.6 实现 generate_preview_html 函数（使用 HtmlRenderer）
|
||||
- [x] 7.7 更新 preview/server.py 的导入，使用 core.presentation 和 renderers.html_renderer
|
||||
- [ ] 7.8 测试预览服务器功能（启动预览服务器并验证热重载）
|
||||
|
||||
## 8. 入口脚本重构
|
||||
|
||||
- [x] 8.1 重构 yaml2pptx.py，只保留 `/// script` 头部、parse_args 和 main 函数
|
||||
- [x] 8.2 更新 main 函数的导入语句（导入所有需要的模块）
|
||||
- [x] 8.3 更新 main 函数中的 Presentation 和 PptxGenerator 使用（使用新的模块路径）
|
||||
- [x] 8.4 更新 main 函数中的预览模式调用（使用 preview.server）
|
||||
- [x] 8.5 删除 yaml2pptx.py 中已迁移的代码（保留约 100 行）
|
||||
- [x] 8.6 验证 yaml2pptx.py 的代码行数（应约为 100 行）
|
||||
|
||||
## 9. 完整测试
|
||||
|
||||
- [x] 9.1 测试基本 PPTX 生成（`uv run yaml2pptx.py input.yaml output.pptx`）
|
||||
- [x] 9.2 测试自动输出文件名（`uv run yaml2pptx.py input.yaml`）
|
||||
- [x] 9.3 测试模板功能（使用带模板的 YAML 文件）
|
||||
- [x] 9.4 测试所有元素类型（text, image, shape, table）
|
||||
- [ ] 9.5 测试预览模式（`uv run yaml2pptx.py input.yaml --preview`）
|
||||
- [ ] 9.6 测试 --template-dir 参数
|
||||
- [ ] 9.7 测试错误处理（无效的 YAML、缺失的图片等）
|
||||
- [x] 9.8 对比重构前后生成的 PPTX 文件（确保输出一致）
|
||||
|
||||
## 10. 清理和文档
|
||||
|
||||
- [x] 10.1 检查所有模块的导入语句，确保没有未使用的导入
|
||||
- [x] 10.2 检查是否存在循环依赖（运行脚本验证）
|
||||
- [x] 10.3 验证所有文件的代码行数（每个模块 150-300 行，入口约 100 行）
|
||||
- [x] 10.4 添加模块级文档字符串（说明每个模块的职责）
|
||||
- [x] 10.5 删除 yaml2pptx.py.backup 备份文件（如果测试通过）
|
||||
Reference in New Issue
Block a user