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(+)
187 lines
6.3 KiB
Markdown
187 lines
6.3 KiB
Markdown
# Browser Preview Server
|
||
|
||
## Purpose
|
||
|
||
Browser Preview Server 负责提供浏览器实时预览功能，包括启动 Web 服务、监听 YAML 文件变化、通过 Server-Sent Events (SSE) 推送更新通知到浏览器。它是预览模式的核心组件，协调文件监听、HTML 生成和浏览器刷新的整个流程。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 系统必须支持通过命令行参数启用预览模式
|
||
|
||
系统 SHALL 在 `yaml2pptx.py` 中提供 `--preview` 参数，启用浏览器预览模式。
|
||
|
||
#### Scenario: 使用 --preview 参数启动预览服务器
|
||
|
||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview`
|
||
- **THEN** 系统启动预览服务器，而不是生成 PPTX 文件
|
||
|
||
#### Scenario: 不使用 --preview 参数时保持原有行为
|
||
|
||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml`
|
||
- **THEN** 系统生成 PPTX 文件，不启动预览服务器
|
||
|
||
#### Scenario: --preview 参数与其他参数兼容
|
||
|
||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview --template-dir templates`
|
||
- **THEN** 系统启动预览服务器，并使用指定的模板目录
|
||
|
||
### Requirement: 系统必须提供 HTTP 服务
|
||
|
||
系统 SHALL 使用 Flask 启动 HTTP 服务器，监听指定端口，提供预览页面。
|
||
|
||
#### Scenario: 启动 HTTP 服务器
|
||
|
||
- **WHEN** 预览模式启动
|
||
- **THEN** 系统在默认端口 5000 启动 Flask HTTP 服务器
|
||
|
||
#### Scenario: 自定义端口
|
||
|
||
- **WHEN** 用户使用 `--port 8080` 参数
|
||
- **THEN** 系统在端口 8080 启动 HTTP 服务器
|
||
|
||
#### Scenario: 端口被占用时报错
|
||
|
||
- **WHEN** 指定的端口已被其他服务占用
|
||
- **THEN** 系统抛出错误，提示端口被占用，建议使用 `--port` 参数指定其他端口
|
||
|
||
#### Scenario: 提供主页面路由
|
||
|
||
- **WHEN** 浏览器访问 `http://localhost:5000/`
|
||
- **THEN** 系统返回包含所有幻灯片预览的 HTML 页面
|
||
|
||
### Requirement: 系统必须监听 YAML 文件变化
|
||
|
||
系统 SHALL 使用 watchdog 监听 YAML 文件所在目录，检测文件修改事件。
|
||
|
||
#### Scenario: 监听 YAML 文件修改
|
||
|
||
- **WHEN** 用户修改并保存 YAML 文件
|
||
- **THEN** 系统检测到文件变化事件
|
||
|
||
#### Scenario: 监听模板文件修改
|
||
|
||
- **WHEN** 用户修改并保存模板文件（如 `templates/title_slide.yaml`）
|
||
- **THEN** 系统检测到文件变化事件
|
||
|
||
#### Scenario: 忽略非 YAML 文件变化
|
||
|
||
- **WHEN** 用户修改其他类型的文件（如 `.txt`、`.md`）
|
||
- **THEN** 系统不触发预览更新
|
||
|
||
#### Scenario: 防抖处理
|
||
|
||
- **WHEN** 用户在短时间内多次保存文件（如 1 秒内保存 3 次）
|
||
- **THEN** 系统仅触发一次预览更新，避免频繁刷新
|
||
|
||
### Requirement: 系统必须通过 SSE 推送更新通知
|
||
|
||
系统 SHALL 提供 Server-Sent Events (SSE) 端点，当文件变化时推送更新通知到浏览器。
|
||
|
||
#### Scenario: 提供 SSE 端点
|
||
|
||
- **WHEN** 浏览器连接到 `http://localhost:5000/events`
|
||
- **THEN** 系统建立 SSE 连接，保持连接打开
|
||
|
||
#### Scenario: 文件变化时推送更新
|
||
|
||
- **WHEN** 检测到 YAML 文件变化
|
||
- **THEN** 系统通过 SSE 连接发送 `data: reload` 消息到所有连接的浏览器
|
||
|
||
#### Scenario: 浏览器接收更新后自动刷新
|
||
|
||
- **WHEN** 浏览器接收到 `reload` 消息
|
||
- **THEN** 浏览器自动刷新页面，显示最新的预览内容
|
||
|
||
#### Scenario: SSE 连接断开时自动重连
|
||
|
||
- **WHEN** SSE 连接因网络问题断开
|
||
- **THEN** 浏览器自动尝试重新连接到 SSE 端点
|
||
|
||
### Requirement: 系统必须自动打开浏览器
|
||
|
||
系统 SHALL 在预览服务器启动后，自动在默认浏览器中打开预览页面。
|
||
|
||
#### Scenario: 启动后自动打开浏览器
|
||
|
||
- **WHEN** 预览服务器启动成功
|
||
- **THEN** 系统自动在默认浏览器中打开 `http://localhost:5000/`
|
||
|
||
#### Scenario: 浏览器打开失败时提示 URL
|
||
|
||
- **WHEN** 系统无法自动打开浏览器（如无图形界面环境）
|
||
- **THEN** 系统在终端输出预览 URL，提示用户手动打开
|
||
|
||
### Requirement: 系统必须提供清晰的日志输出
|
||
|
||
系统 SHALL 在终端输出清晰的日志信息，帮助用户了解预览服务器的状态。
|
||
|
||
#### Scenario: 启动时输出日志
|
||
|
||
- **WHEN** 预览服务器启动
|
||
- **THEN** 系统输出以下信息：
|
||
- 正在监听的 YAML 文件路径
|
||
- 预览服务器的 URL
|
||
- 停止服务器的方法（按 Ctrl+C）
|
||
|
||
#### Scenario: 文件变化时输出日志
|
||
|
||
- **WHEN** 检测到文件变化
|
||
- **THEN** 系统输出 `[INFO] 检测到文件变化: <文件路径>`
|
||
|
||
#### Scenario: 错误时输出日志
|
||
|
||
- **WHEN** 发生错误（如 YAML 解析错误）
|
||
- **THEN** 系统输出 `[ERROR]` 级别的日志，包含错误详情
|
||
|
||
### Requirement: 系统必须支持优雅退出
|
||
|
||
系统 SHALL 支持通过 Ctrl+C 优雅地停止预览服务器。
|
||
|
||
#### Scenario: 按 Ctrl+C 停止服务器
|
||
|
||
- **WHEN** 用户按下 Ctrl+C
|
||
- **THEN** 系统停止文件监听和 HTTP 服务器，输出 `[INFO] 已停止`，然后退出
|
||
|
||
#### Scenario: 停止时清理资源
|
||
|
||
- **WHEN** 服务器停止
|
||
- **THEN** 系统关闭所有 SSE 连接，停止 watchdog 监听器，释放端口
|
||
|
||
### Requirement: 系统必须处理 YAML 解析错误
|
||
|
||
系统 SHALL 在 YAML 解析失败时，在预览页面显示友好的错误信息，而不是崩溃。
|
||
|
||
#### Scenario: YAML 语法错误时显示错误页面
|
||
|
||
- **WHEN** YAML 文件存在语法错误（如缺少冒号、缩进错误）
|
||
- **THEN** 系统在预览页面显示错误信息，包括错误类型和行号
|
||
|
||
#### Scenario: 错误修复后自动恢复
|
||
|
||
- **WHEN** 用户修复 YAML 错误并保存
|
||
- **THEN** 系统检测到文件变化，重新解析 YAML，显示正常的预览内容
|
||
|
||
#### Scenario: 错误页面仍然监听文件变化
|
||
|
||
- **WHEN** 预览页面显示错误信息
|
||
- **THEN** 系统继续监听文件变化，等待用户修复错误
|
||
|
||
### Requirement: 系统必须支持多幻灯片预览
|
||
|
||
系统 SHALL 在预览页面中显示所有幻灯片，支持用户查看完整的演示文稿。
|
||
|
||
#### Scenario: 垂直排列显示所有幻灯片
|
||
|
||
- **WHEN** YAML 文件包含多个幻灯片
|
||
- **THEN** 系统在预览页面中垂直排列显示所有幻灯片，每个幻灯片之间有间距
|
||
|
||
#### Scenario: 显示幻灯片编号
|
||
|
||
- **WHEN** 预览页面显示幻灯片
|
||
- **THEN** 每个幻灯片右下角显示编号（如 "幻灯片 1"、"幻灯片 2"）
|
||
|
||
#### Scenario: 幻灯片尺寸一致
|
||
|
||
- **WHEN** 预览页面显示多个幻灯片
|
||
- **THEN** 所有幻灯片使用相同的尺寸（960x540 像素，16:9 比例）
|