feat: 添加模板变量验证功能
- 在 ResourceValidator 中添加 validate_template_vars 方法 - 在验证阶段检查用户是否提供了模板所需的必需变量 - 缺少必需变量时返回 ERROR 级别错误 - 添加 9 个单元测试用例验证功能 - 同步更新 OpenSpec 规格文档
This commit is contained in:
@@ -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 字段,不处理嵌套引用
|
||||
Reference in New Issue
Block a user