lanyuanxiaoyao
cd7988cbd5
Add core Python script (yaml2pptx.py) for converting YAML to PowerPoint: - Element rendering: text, image, shape, table, chart - Template system with placeholders - PPTX generation with python-pptx OpenSpec workflow setup: - 3 archived changes: browser-preview, template-dir-cli, yaml-to-pptx - 7 main specifications covering all core modules - Config and documentation structure 30 files changed, 4984 insertions(+)
80 lines
3.8 KiB
Markdown
80 lines
3.8 KiB
Markdown
## 1. 准备工作
|
||
|
||
- [x] 1.1 在 `yaml2pptx.py` 的 Inline script metadata 中添加 `flask` 和 `watchdog` 依赖
|
||
- [x] 1.2 在文件顶部添加预览模式相关的导入语句（使用条件导入，仅在预览模式下导入）
|
||
|
||
## 2. 命令行参数
|
||
|
||
- [x] 2.1 在 `parse_args()` 函数中添加 `--preview` 参数（布尔类型，默认 False）
|
||
- [x] 2.2 在 `parse_args()` 函数中添加 `--port` 参数（整数类型，默认 5000）
|
||
|
||
## 3. HTML 渲染函数
|
||
|
||
- [x] 3.1 实现 `render_text_element_to_html(elem)` 函数，将文本元素转换为 HTML `<div>` 标签
|
||
- [x] 3.2 实现 `render_shape_element_to_html(elem)` 函数，将形状元素转换为 HTML `<div>` 标签
|
||
- [x] 3.3 实现 `render_table_element_to_html(elem)` 函数，将表格元素转换为 HTML `<table>` 标签
|
||
- [x] 3.4 实现 `render_image_element_to_html(elem, base_path)` 函数，将图片元素转换为 HTML `<img>` 标签
|
||
- [x] 3.5 实现 `render_slide_to_html(slide_data, index)` 函数，渲染单个幻灯片为 HTML
|
||
- [x] 3.6 实现 `generate_preview_html(yaml_file, template_dir)` 函数，生成完整的预览 HTML 页面
|
||
|
||
## 4. HTML 模板
|
||
|
||
- [x] 4.1 定义 `HTML_TEMPLATE` 常量，包含完整的 HTML 页面结构、CSS 样式和 SSE 客户端 JavaScript
|
||
- [x] 4.2 定义 `ERROR_TEMPLATE` 常量，用于显示 YAML 解析错误
|
||
|
||
## 5. Flask 应用
|
||
|
||
- [x] 5.1 创建 Flask 应用实例 `app = Flask(__name__)`
|
||
- [x] 5.2 实现主页面路由 `@app.route('/')`，返回预览 HTML
|
||
- [x] 5.3 实现 SSE 事件流路由 `@app.route('/events')`，推送文件变化通知
|
||
|
||
## 6. 文件监听
|
||
|
||
- [x] 6.1 实现 `YAMLChangeHandler` 类，继承 `FileSystemEventHandler`
|
||
- [x] 6.2 在 `on_modified()` 方法中检测 `.yaml` 文件变化，推送更新通知到队列
|
||
- [x] 6.3 创建全局队列 `change_queue = queue.Queue()` 用于通知文件变化
|
||
|
||
## 7. 预览服务器启动
|
||
|
||
- [x] 7.1 实现 `start_preview_server(yaml_file, template_dir, port)` 函数
|
||
- [x] 7.2 在函数中启动 watchdog 监听器，监听 YAML 文件所在目录
|
||
- [x] 7.3 在函数中使用 `webbrowser.open()` 自动打开浏览器
|
||
- [x] 7.4 在函数中启动 Flask 应用，监听指定端口
|
||
- [x] 7.5 添加 Ctrl+C 信号处理，优雅退出服务器
|
||
|
||
## 8. 主函数修改
|
||
|
||
- [x] 8.1 在 `main()` 函数中添加条件判断：`if args.preview:`
|
||
- [x] 8.2 在预览模式分支中调用 `start_preview_server()`
|
||
- [x] 8.3 在非预览模式分支中保持原有的 PPTX 生成逻辑
|
||
|
||
## 9. 错误处理
|
||
|
||
- [x] 9.1 在预览 HTML 生成中捕获 `YAMLError`，返回错误页面
|
||
- [x] 9.2 在 Flask 路由中添加异常处理，避免服务器崩溃
|
||
- [x] 9.3 在端口占用时捕获异常，提示用户使用 `--port` 参数
|
||
|
||
## 10. 日志输出
|
||
|
||
- [x] 10.1 在预览服务器启动时输出日志：监听的文件路径、预览 URL、停止方法
|
||
- [x] 10.2 在文件变化时输出日志：`[INFO] 检测到文件变化: <文件路径>`
|
||
- [x] 10.3 在服务器停止时输出日志：`[INFO] 已停止`
|
||
|
||
## 11. 测试
|
||
|
||
- [x] 11.1 测试基本功能：启动预览服务器，浏览器自动打开
|
||
- [x] 11.2 测试文件监听：修改 YAML 文件，浏览器自动刷新
|
||
- [x] 11.3 测试模板支持：使用模板的 YAML 文件能正确预览
|
||
- [x] 11.4 测试错误处理：YAML 语法错误时显示错误页面
|
||
- [x] 11.5 测试所有元素类型：文本、形状、表格、图片都能正确渲染
|
||
- [x] 11.6 测试多幻灯片：多个幻灯片垂直排列显示
|
||
- [x] 11.7 测试向后兼容：不使用 `--preview` 参数时，PPTX 生成功能正常
|
||
- [x] 11.8 测试自定义端口：`--port` 参数能正确指定端口
|
||
- [x] 11.9 测试 Ctrl+C 退出：能优雅停止服务器
|
||
|
||
## 12. 文档更新
|
||
|
||
- [x] 12.1 在 README.md 中添加预览功能的使用说明
|
||
- [x] 12.2 在 README.md 中添加预览功能的示例命令
|
||
- [x] 12.3 在 README.md 中说明预览效果与 PPTX 可能存在差异
|