1
0

feat: 添加模板变量验证功能

- 在 ResourceValidator 中添加 validate_template_vars 方法
- 在验证阶段检查用户是否提供了模板所需的必需变量
- 缺少必需变量时返回 ERROR 级别错误
- 添加 9 个单元测试用例验证功能
- 同步更新 OpenSpec 规格文档
This commit is contained in:
2026-03-03 01:00:21 +08:00
parent e31a7e9bed
commit ef3fa6a06a
9 changed files with 468 additions and 89 deletions

View File

@@ -0,0 +1,46 @@
## Context
当前验证器 (`validators/validator.py`) 已具备以下验证能力:
- YAML 结构验证slides 字段)
- 元素类型和属性验证
- 几何验证(元素位置和尺寸)
- 资源验证(图片文件、模板文件存在性)
但缺少对模板变量完整性的验证。当 YAML 使用模板时,如果用户没有提供模板所需的必需变量(如 `title`),验证器仍会返回成功,直到转换阶段才发现问题。
## Goals / Non-Goals
**Goals:**
- 在验证阶段检查用户是否提供了模板所需的必需变量
- 当缺少必需变量时返回 ERROR 级别错误,阻止转换
- 提供清晰的错误信息,指出缺少哪个必需变量
**Non-Goals:**
- 不验证模板变量值的类型正确性(由渲染阶段处理)
- 不验证模板变量值的业务逻辑有效性
- 不修改现有的验证错误格式
## Decisions
### 方案:在 ResourceValidator 中添加 validate_template_vars 方法
**选择理由:**
1. ResourceValidator 已负责模板相关的验证validate_template职责匹配
2. 可以复用现有的模板加载逻辑
3. 对主验证器的影响最小,只需在现有验证流程中调用新方法
**替代方案考虑:**
- 在主验证器中直接实现:会导致主验证器代码膨胀
- 新增专门的 TemplateVarValidator增加复杂度与现有架构不符
### 实现要点:
1. 在 ResourceValidator 中添加 `validate_template_vars` 方法
2. 加载模板文件后,检查模板的 `vars` 字段中的 `required: true` 变量
3. 从幻灯片数据中获取 `vars` 字段,与模板要求的必需变量对比
4. 缺少必需变量时,添加 ERROR 级别问题
## Risks / Trade-offs
**潜在风险:**
- [风险] 重复加载模板文件 → [缓解] ResourceValidator 已在 validate_template 中加载一次,可复用加载结果或缓存
- [风险] vars 字段嵌套层级复杂 → [缓解] 仅检查顶层 vars 字段,不处理嵌套引用