lanyuanxiaoyao
ef3fa6a06a
- 在 ResourceValidator 中添加 validate_template_vars 方法 - 在验证阶段检查用户是否提供了模板所需的必需变量 - 缺少必需变量时返回 ERROR 级别错误 - 添加 9 个单元测试用例验证功能 - 同步更新 OpenSpec 规格文档
47 lines
1.9 KiB
Markdown
47 lines
1.9 KiB
Markdown
## 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 字段，不处理嵌套引用
|