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(+)
98 lines
3.3 KiB
Markdown
98 lines
3.3 KiB
Markdown
# YAML Parsing
|
||
|
||
## Purpose
|
||
|
||
YAML parsing 系统负责读取和验证演示文稿和模板的 YAML 文件。它支持 UTF-8 编码、验证颜色格式、验证文件结构，并提供清晰的错误消息帮助用户定位问题。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 系统必须能解析演示文稿 YAML 文件
|
||
|
||
系统 SHALL 能够解析包含 metadata 和 slides 的演示文稿 YAML 文件，并验证其结构的正确性。
|
||
|
||
#### Scenario: 解析有效的演示文稿 YAML
|
||
|
||
- **WHEN** 提供一个包含 `metadata` 和 `slides` 字段的 YAML 文件
|
||
- **THEN** 系统成功解析并返回 Python 字典结构
|
||
|
||
#### Scenario: 检测缺少必需字段
|
||
|
||
- **WHEN** 提供的 YAML 文件缺少 `slides` 字段
|
||
- **THEN** 系统抛出验证错误，明确指出缺少必需字段
|
||
|
||
#### Scenario: 处理无效的 YAML 语法
|
||
|
||
- **WHEN** 提供的文件包含无效的 YAML 语法（如缩进错误）
|
||
- **THEN** 系统抛出解析错误，包含行号和错误描述
|
||
|
||
### Requirement: 系统必须验证颜色值格式
|
||
|
||
系统 SHALL 验证模板和演示文稿 YAML 文件中的颜色值为有效的十六进制格式。
|
||
|
||
#### Scenario: 验证有效的颜色值
|
||
|
||
- **WHEN** 模板或演示文稿 YAML 文件中包含 `color: "#4a90e2"` 的颜色值
|
||
- **THEN** 系统接受该颜色值
|
||
|
||
#### Scenario: 验证颜色值格式错误
|
||
|
||
- **WHEN** 颜色值格式不正确（如 "blue" 或 "#xyz"）
|
||
- **THEN** 系统抛出验证错误，提示使用 #RRGGBB 格式
|
||
|
||
#### Scenario: 支持短格式颜色值
|
||
|
||
- **WHEN** 颜色值为短格式 "#fff"
|
||
- **THEN** 系统自动扩展为 "#ffffff" 并接受
|
||
|
||
### Requirement: 系统必须能解析模板 YAML 文件
|
||
|
||
系统 SHALL 能够解析包含 vars 定义和 elements 列表的模板 YAML 文件。
|
||
|
||
#### Scenario: 解析有效的模板文件
|
||
|
||
- **WHEN** 提供一个包含 `vars` 和 `elements` 字段的模板 YAML 文件
|
||
- **THEN** 系统成功解析并返回模板对象
|
||
|
||
#### Scenario: 验证变量定义的完整性
|
||
|
||
- **WHEN** 模板 vars 中的变量缺少 `name` 字段
|
||
- **THEN** 系统抛出验证错误，指出变量定义不完整
|
||
|
||
#### Scenario: 验证必需变量标记
|
||
|
||
- **WHEN** 模板 vars 中定义了 `required: true` 的变量
|
||
- **THEN** 系统记录该变量为必需变量，在渲染时必须提供值
|
||
|
||
### Requirement: 系统必须支持 UTF-8 编码
|
||
|
||
系统 SHALL 以 UTF-8 编码读取所有 YAML 文件，支持中文等多字节字符。
|
||
|
||
#### Scenario: 解析包含中文的 YAML 文件
|
||
|
||
- **WHEN** 提供包含中文字符的 YAML 文件
|
||
- **THEN** 系统正确解析中文内容，不出现乱码
|
||
|
||
#### Scenario: 处理 BOM 标记
|
||
|
||
- **WHEN** YAML 文件包含 UTF-8 BOM 标记
|
||
- **THEN** 系统能够正确处理并解析文件内容
|
||
|
||
### Requirement: 系统必须提供清晰的错误消息
|
||
|
||
系统 SHALL 在 YAML 解析失败时提供包含文件路径、行号、错误原因的详细错误消息。
|
||
|
||
#### Scenario: YAML 语法错误的错误消息
|
||
|
||
- **WHEN** YAML 文件在第 10 行存在缩进错误
|
||
- **THEN** 错误消息包含 "文件路径, 第 10 行: 缩进错误" 等信息
|
||
|
||
#### Scenario: 文件不存在的错误消息
|
||
|
||
- **WHEN** 尝试加载不存在的 YAML 文件
|
||
- **THEN** 错误消息明确指出文件路径不存在
|
||
|
||
#### Scenario: 权限不足的错误消息
|
||
|
||
- **WHEN** YAML 文件存在但没有读取权限
|
||
- **THEN** 错误消息提示权限不足，无法读取文件
|