lanyuanxiaoyao
83ff827ad1
Implements comprehensive validation before PPTX conversion to catch errors early. Includes element-level validation (colors, fonts, table consistency) and system-level validation (geometry, resources). Supports standalone check command and automatic validation during conversion.
194 lines
6.5 KiB
Markdown
194 lines
6.5 KiB
Markdown
# 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** 系统输出："✅ 验证通过，未发现问题"
|