PPTX/openspec/changes/archive/2026-03-02-refactor-yaml2pptx-modular/tasks.md

1. 准备工作

• 1.1 备份原始 yaml2pptx.py 文件为 yaml2pptx.py.backup
• 1.2 创建目录结构（core/, loaders/, renderers/, preview/）
• 1.3 在各目录下创建 init.py 文件

2. 基础设施层（utils + loaders）

• 2.1 创建 utils.py，提取日志函数（log_info, log_success, log_error, log_progress）
• 2.2 在 utils.py 中提取颜色转换函数（hex_to_rgb, validate_color）
• 2.3 创建 loaders/yaml_loader.py，提取 YAMLError 异常类
• 2.4 在 loaders/yaml_loader.py 中提取 load_yaml_file 函数
• 2.5 在 loaders/yaml_loader.py 中提取验证函数（validate_presentation_yaml, validate_template_yaml）
• 2.6 更新 yaml2pptx.py 的导入语句，导入 utils 和 loaders 模块
• 2.7 测试 YAML 加载功能（运行 uv run yaml2pptx.py --help 确认无导入错误）

3. 核心抽象层（core/elements）

• 3.1 创建 core/elements.py，定义 TextElement dataclass（包含 type, content, box, font 字段）
• 3.2 在 TextElement 中实现 post_init 验证方法（验证 box 长度）
• 3.3 定义 ImageElement dataclass（包含 type, src, box 字段及验证）
• 3.4 定义 ShapeElement dataclass（包含 type, shape, box, fill, line 字段及验证）
• 3.5 定义 TableElement dataclass（包含 type, data, position, col_widths, style 字段及验证）
• 3.6 实现 create_element 工厂函数，根据 type 字段创建对应的元素对象
• 3.7 测试元素创建和验证（创建测试用例验证各元素类型）

4. 核心抽象层（core/template + presentation）

• 4.1 创建 core/template.py，提取 Template 类
• 4.2 更新 Template 类的导入，使用 loaders.yaml_loader 和 utils
• 4.3 创建 core/presentation.py，提取 Presentation 类
• 4.4 更新 Presentation 类的导入，使用 loaders.yaml_loader 和 core.template
• 4.5 修改 Presentation.render_slide 方法，使元素通过 create_element 转换为元素对象
• 4.6 测试模板渲染功能（使用现有的 YAML 文件测试）

5. PPTX 渲染器

• 5.1 创建 renderers/pptx_renderer.py，定义 PptxGenerator 类
• 5.2 在 PptxGenerator.init 中实现幻灯片尺寸设置逻辑
• 5.3 实现 PptxGenerator.add_slide 方法（创建幻灯片、设置背景、调用 _render_element）
• 5.4 实现 _render_element 方法（使用 isinstance 检查元素类型并分发）
• 5.5 实现 _render_text 方法（从原 add_text_element 迁移，使用元素对象属性）
• 5.6 实现 _render_image 方法（从原 add_image_element 迁移，使用元素对象属性）
• 5.7 实现 _render_shape 方法（从原 add_shape_element 迁移，使用元素对象属性）
• 5.8 实现 _render_table 方法（从原 add_table_element 迁移，使用元素对象属性）
• 5.9 实现 _render_background 方法（从原 set_slide_background 迁移）
• 5.10 实现 PptxGenerator.save 方法
• 5.11 更新 PptxGenerator 的导入，使用 core.elements 和 utils
• 5.12 测试 PPTX 生成功能（生成测试 PPTX 文件并验证）

6. HTML 渲染器

• 6.1 创建 renderers/html_renderer.py，定义 HtmlRenderer 类
• 6.2 实现 HtmlRenderer.render_slide 方法（生成幻灯片 HTML 容器）
• 6.3 实现 render_text 方法（从原 render_text_element_to_html 迁移，使用元素对象属性）
• 6.4 实现 render_image 方法（从原 render_image_element_to_html 迁移，使用元素对象属性）
• 6.5 实现 render_shape 方法（从原 render_shape_element_to_html 迁移，使用元素对象属性）
• 6.6 实现 render_table 方法（从原 render_table_element_to_html 迁移，使用元素对象属性）
• 6.7 更新 HtmlRenderer 的导入，使用 core.elements
• 6.8 测试 HTML 渲染功能（生成测试 HTML 并在浏览器中验证）

7. 预览服务器

• 7.1 创建 preview/server.py，提取 Flask 应用相关代码
• 7.2 提取 HTML_TEMPLATE 和 ERROR_TEMPLATE 常量
• 7.3 提取 YAMLChangeHandler 类
• 7.4 提取 create_flask_app 函数
• 7.5 提取 start_preview_server 函数
• 7.6 实现 generate_preview_html 函数（使用 HtmlRenderer）
• 7.7 更新 preview/server.py 的导入，使用 core.presentation 和 renderers.html_renderer
• 7.8 测试预览服务器功能（启动预览服务器并验证热重载）

8. 入口脚本重构

• 8.1 重构 yaml2pptx.py，只保留 /// script 头部、parse_args 和 main 函数
• 8.2 更新 main 函数的导入语句（导入所有需要的模块）
• 8.3 更新 main 函数中的 Presentation 和 PptxGenerator 使用（使用新的模块路径）
• 8.4 更新 main 函数中的预览模式调用（使用 preview.server）
• 8.5 删除 yaml2pptx.py 中已迁移的代码（保留约 100 行）
• 8.6 验证 yaml2pptx.py 的代码行数（应约为 100 行）

9. 完整测试

• 9.1 测试基本 PPTX 生成（uv run yaml2pptx.py input.yaml output.pptx）
• 9.2 测试自动输出文件名（uv run yaml2pptx.py input.yaml）
• 9.3 测试模板功能（使用带模板的 YAML 文件）
• 9.4 测试所有元素类型（text, image, shape, table）
• 9.5 测试预览模式（uv run yaml2pptx.py input.yaml --preview）
• 9.6 测试 --template-dir 参数
• 9.7 测试错误处理（无效的 YAML、缺失的图片等）
• 9.8 对比重构前后生成的 PPTX 文件（确保输出一致）

10. 清理和文档

• 10.1 检查所有模块的导入语句，确保没有未使用的导入
• 10.2 检查是否存在循环依赖（运行脚本验证）
• 10.3 验证所有文件的代码行数（每个模块 150-300 行，入口约 100 行）
• 10.4 添加模块级文档字符串（说明每个模块的职责）
• 10.5 删除 yaml2pptx.py.backup 备份文件（如果测试通过）