refactor: 重构文档结构，采用渐进式信息披露模式

将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
2026-03-06 15:11:36 +08:00
parent 98098dc911
commit 124ef0e5ce
41 changed files with 5238 additions and 2228 deletions
--- a/docs/reference/validation.md
+++ b/docs/reference/validation.md
@@ -0,0 +1,191 @@
+# 验证功能
+
+yaml2pptx 提供强大的验证功能，在转换前自动检查 YAML 文件，提前发现问题。
+
+## 验证级别
+
+验证结果分为三个级别：
+
+### ERROR（错误）
+
+阻止转换的严重问题：
+- 文件不存在（图片、模板文件等）
+- YAML 语法错误
+- 必需的变量未提供
+- 无效的数据类型
+
+### WARNING（警告）
+
+影响视觉效果但不阻止转换的问题：
+- 元素超出页面范围
+- 字体大小过小或过大
+- 颜色格式不规范但可解析
+
+### INFO（信息）
+
+优化建议和提示：
+- 性能优化建议
+- 最佳实践提示
+
+## 验证内容
+
+### YAML 语法和结构
+
+- 检查 YAML 语法是否正确
+- 检查必需字段是否存在
+- 检查数据类型是否正确
+
+### 元素边界
+
+- 检查元素是否超出页面范围
+- 0.1 英寸容忍度内的超出会发出警告
+
+### 资源文件
+
+- 检查图片文件是否存在
+- 检查模板文件是否存在
+- 验证文件路径是否有效
+
+### 颜色格式
+
+- 检查颜色格式是否正确（#RGB 或 #RRGGBB）
+- 检查颜色值是否有效
+
+### 字体配置
+
+- 检查字体大小是否合理（<6 或 >72 会警告）
+- 检查字体引用是否存在
+- 检查字体引用循环
+
+### 表格数据
+
+- 检查表格数据一致性
+- 检查列数是否匹配
+
+## 使用验证
+
+### 独立验证
+
+```bash
+uv run yaml2pptx.py check presentation.yaml
+```
+
+### 使用模板时验证
+
+```bash
+uv run yaml2pptx.py check presentation.yaml --template ./templates.yaml
+```
+
+### 自动验证
+
+转换时默认会自动验证：
+
+```bash
+uv run yaml2pptx.py convert presentation.yaml output.pptx
+```
+
+### 跳过验证
+
+```bash
+uv run yaml2pptx.py convert presentation.yaml output.pptx --skip-validation
+```
+
+## 验证结果示例
+
+### 有错误和警告
+
+```
+正在检查 YAML 文件...
+
+- 错误 (2):
+  [幻灯片 2, 元素 1] 无效的颜色格式: red (应为 #RRGGBB)
+  [幻灯片 3, 元素 2] 图片文件不存在: logo.png
+
+-  警告 (1):
+  [幻灯片 1, 元素 1] 元素右边界超出: 10.50 > 10
+
+检查完成: 发现 2 个错误, 1 个警告
+转换已终止
+```
+
+### 验证通过
+
+```
+正在检查 YAML 文件...
+
+检查完成: 未发现问题
+```
+
+### 仅警告
+
+```
+正在检查 YAML 文件...
+
+-  警告 (2):
+  [幻灯片 1, 元素 1] 元素右边界超出: 10.05 > 10
+  [幻灯片 2, 元素 2] 字体大小过小: 5
+
+检查完成: 发现 2 个警告
+```
+
+## 常见验证错误
+
+### 文件不存在
+
+```
+错误: 图片文件未找到: images/logo.png
+```
+
+**解决方法**：检查图片路径是否正确
+
+### YAML 语法错误
+
+```
+错误: YAML 语法错误: 第 15 行
+```
+
+**解决方法**：检查缩进和语法，确保 YAML 格式正确
+
+### 缺少必需变量
+
+```
+错误: 缺少必需变量: title
+```
+
+**解决方法**：在 `vars` 中提供该变量
+
+### 无效颜色格式
+
+```
+错误: 无效的颜色格式: red (应为 #RRGGBB)
+```
+
+**解决方法**：使用 `#ff0000` 格式
+
+## 验证容忍度
+
+几何验证时，允许 0.1 英寸的容忍度：
+
+- 超出 ≤ 0.1 英寸：不报错
+- 超出 > 0.1 英寸：发出警告
+
+```python
+TOLERANCE = 0.1  # 英寸
+
+if right > slide_width + TOLERANCE:
+    # 报告 WARNING
+```
+
+## 最佳实践
+
+1. **开发时频繁验证**：使用 `check` 命令快速验证
+2. **修复所有错误**：确保没有 ERROR 级别的问题
+3. **关注警告**：WARNING 虽不阻止转换，但可能影响视觉效果
+4. **使用预览模式**：结合预览模式查看实际效果
+
+## 相关文档
+
+- [命令行选项](commands.md) - 所有命令和参数
+- [故障排查](../troubleshooting.md) - 常见问题解决
+
+[返回文档索引](../README.md)