# YAML Validation

## Purpose

提供 YAML 演示文稿文件的验证能力，在转换为 PPTX 之前检查各种潜在问题，包括结构验证、几何验证、资源验证和样式验证。支持独立验证命令和转换前自动验证。

## Requirements

### Requirement: 独立验证命令

系统必须提供独立的 check 子命令，用于验证 YAML 文件而不执行转换。

#### Scenario: 执行独立验证

- **WHEN** 用户运行 `yaml2pptx.py check input.yaml`
- **THEN** 系统验证 YAML 文件并输出验证结果，不生成 PPTX 文件

#### Scenario: 验证时指定模板目录

- **WHEN** 用户运行 `yaml2pptx.py check input.yaml --template-dir ./templates`
- **THEN** 系统在验证时使用指定的模板目录来检查模板文件

### Requirement: 转换前自动验证

系统必须在转换 YAML 为 PPTX 之前自动执行验证，除非用户明确跳过。

#### Scenario: 默认自动验证

- **WHEN** 用户运行 `yaml2pptx.py input.yaml output.pptx`
- **THEN** 系统在转换前自动验证 YAML 文件

#### Scenario: 跳过自动验证

- **WHEN** 用户运行 `yaml2pptx.py input.yaml output.pptx --no-check`
- **THEN** 系统跳过验证，直接执行转换

#### Scenario: 验证失败阻止转换

- **WHEN** 自动验证发现 ERROR 级别的问题
- **THEN** 系统输出错误信息并终止转换，返回非零退出码

### Requirement: 元素自验证

系统中的每个元素类型必须能够验证自身的完整性和有效性。

#### Scenario: 元素验证自身属性

- **WHEN** 创建或验证元素对象
- **THEN** 元素类检查自身的必需字段、数据类型、值有效性（如颜色格式、枚举值、字体大小）

#### Scenario: 元素验证与系统验证分离

- **WHEN** 执行验证
- **THEN** 元素类负责自身属性验证（不需要全局上下文的验证），系统验证器负责需要全局上下文的验证（如几何验证需要页面尺寸、资源验证需要文件路径）

### Requirement: 结构验证

系统必须验证 YAML 文件的结构完整性和数据类型正确性。

#### Scenario: 检测缺少必需字段

- **WHEN** YAML 文件缺少 slides 字段
- **THEN** 系统报告 ERROR 级别错误："缺少必需字段 'slides'"

#### Scenario: 检测数据类型错误

- **WHEN** slides 字段不是列表类型
- **THEN** 系统报告 ERROR 级别错误："'slides' 必须是一个列表"

#### Scenario: 检测元素类型无效

- **WHEN** 元素的 type 字段值不是 text/image/shape/table 之一
- **THEN** 系统报告 ERROR 级别错误："不支持的元素类型: {type}"

#### Scenario: 检测无效的枚举值

- **WHEN** shape 元素的 shape 字段值不是 rectangle/ellipse/rounded_rectangle 之一
- **THEN** 系统报告 ERROR 级别错误："不支持的形状类型: {shape}"

### Requirement: 几何验证

系统必须验证元素的位置和尺寸是否在页面范围内。

#### Scenario: 检测元素超出页面右边界

- **WHEN** 元素的 left + width 超出页面宽度 0.1 英寸以上
- **THEN** 系统报告 WARNING 级别警告："元素右边界超出: {right} > {width}"

#### Scenario: 检测元素超出页面下边界

- **WHEN** 元素的 top + height 超出页面高度 0.1 英寸以上
- **THEN** 系统报告 WARNING 级别警告："元素下边界超出: {bottom} > {height}"

#### Scenario: 容忍计算精度误差

- **WHEN** 元素的边界超出页面范围不超过 0.1 英寸
- **THEN** 系统不报告警告

#### Scenario: 检测元素完全在页面外

- **WHEN** 元素的 left >= 页面宽度 或 top >= 页面高度
- **THEN** 系统报告 WARNING 级别警告："元素完全在页面外"

#### Scenario: 检测表格超出页面范围

- **WHEN** 表格的 position[0] + sum(col_widths) 超出页面宽度 0.1 英寸以上
- **THEN** 系统报告 WARNING 级别警告："表格超出页面宽度"

### Requirement: 资源验证

系统必须验证 YAML 文件引用的外部资源是否存在。

#### Scenario: 检测图片文件不存在

- **WHEN** image 元素的 src 指向的文件不存在
- **THEN** 系统报告 ERROR 级别错误："图片文件不存在: {src}"

#### Scenario: 支持相对路径图片

- **WHEN** image 元素的 src 是相对路径
- **THEN** 系统相对于 YAML 文件所在目录解析路径

#### Scenario: 检测模板文件不存在

- **WHEN** 幻灯片引用的 template 文件不存在
- **THEN** 系统报告 ERROR 级别错误："模板文件不存在: {template}"

#### Scenario: 验证模板文件结构

- **WHEN** 模板文件存在但结构不正确（缺少 elements 字段）
- **THEN** 系统报告 ERROR 级别错误："模板文件结构错误: {template}"

### Requirement: 样式验证

系统必须验证样式相关属性的有效性和合理性。

#### Scenario: 检测无效的颜色格式

- **WHEN** 颜色值不符合 #RGB 或 #RRGGBB 格式
- **THEN** 系统报告 ERROR 级别错误："无效的颜色格式: {color}"

#### Scenario: 检测字体过小

- **WHEN** 字体大小小于 8pt
- **THEN** 系统报告 WARNING 级别警告："字体太小: {size}pt (建议 >= 8pt)"

#### Scenario: 检测字体过大

- **WHEN** 字体大小大于 100pt
- **THEN** 系统报告 WARNING 级别警告："字体太大: {size}pt (建议 <= 100pt)"

### Requirement: 分级错误报告

系统必须按照严重程度对验证问题进行分级报告。

#### Scenario: ERROR 级别阻止转换

- **WHEN** 验证发现 ERROR 级别问题
- **THEN** 系统在独立验证模式下返回非零退出码，在自动验证模式下阻止转换

#### Scenario: WARNING 级别不阻止转换

- **WHEN** 验证仅发现 WARNING 级别问题
- **THEN** 系统输出警告信息但允许转换继续，返回零退出码

#### Scenario: 显示问题位置

- **WHEN** 验证发现问题
- **THEN** 系统输出包含幻灯片编号和元素编号的位置信息："[幻灯片 {n}, 元素 {m}]"

#### Scenario: 分类统计问题数量

- **WHEN** 验证完成
- **THEN** 系统输出问题统计："发现 {n} 个错误, {m} 个警告"

### Requirement: 清晰的命令行输出

系统必须以清晰易读的格式输出验证结果。

#### Scenario: 使用图标区分级别

- **WHEN** 输出验证结果
- **THEN** 系统使用 "❌" 表示 ERROR，"⚠️" 表示 WARNING，"ℹ️" 表示 INFO

#### Scenario: 按级别分组显示

- **WHEN** 输出验证结果
- **THEN** 系统按 ERROR、WARNING、INFO 分组显示问题

#### Scenario: 验证通过的提示

- **WHEN** 验证未发现任何问题
- **THEN** 系统输出："✅ 验证通过，未发现问题"