# 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** 错误消息提示权限不足，无法读取文件