lanyuanxiaoyao
f1aae96a04
主要变更： - 将 templates_dir 参数改为 template_file，支持单个模板库 YAML 文件 - 添加模板库 YAML 验证功能 - 为模板添加 base_dir 支持，正确解析相对路径资源 - 内联模板与外部模板同名时改为警告（内联优先） - 移除模板缓存机制，直接使用模板库字典 - 更新所有相关测试以适配新的模板加载方式 此重构简化了模板管理，使模板资源的路径解析更加清晰明确。
5.4 KiB
5.4 KiB
ADDED Requirements
Requirement: 模板库文件必须包含 templates 字段
模板库文件 SHALL 包含必需的 templates 字段，该字段为字典类型，键为模板名称，值为模板定义。
Scenario: 验证模板库文件格式
- WHEN 系统加载模板库文件
- THEN 系统验证文件包含
templates字段 - AND
templates字段必须为字典类型
Scenario: 模板库文件缺少 templates 字段时报错
- WHEN 模板库文件不包含
templates字段 - THEN 系统抛出错误，错误代码为
TEMPLATE_LIBRARY_MISSING_TEMPLATES_FIELD - AND 错误消息包含"缺少必需字段 'templates'"
Scenario: templates 字段类型错误时报错
- WHEN 模板库文件的
templates字段不是字典类型 - THEN 系统抛出错误，错误代码为
TEMPLATE_LIBRARY_MISSING_TEMPLATES_FIELD - AND 错误消息包含"'templates' 必须是字典"
Requirement: 模板库文件必须支持元数据字段
模板库文件 SHALL 支持可选的元数据字段，包括 description、version、author 等。
Scenario: 加载包含元数据的模板库文件
- WHEN 模板库文件包含
description、version、author等字段 - THEN 系统成功加载这些元数据字段
- AND 元数据不影响模板的加载和使用
Scenario: 不包含元数据字段时正常加载
- WHEN 模板库文件仅包含
templates字段，不包含任何元数据 - THEN 系统正常加载，不要求元数据字段
Requirement: 模板库文件必须递归验证每个模板的结构
系统 SHALL 对模板库中的每个模板递归验证其结构，包括 vars 和 elements 字段的正确性。
Scenario: 验证模板的 vars 字段
- WHEN 模板库中的模板定义了
vars字段 - THEN 系统验证
vars为列表类型 - AND 验证每个变量定义包含
name字段 - AND 如果
vars存在但不为列表，抛出错误
Scenario: 验证模板的 elements 字段
- WHEN 模板库中的模板定义了
elements字段 - THEN 系统验证
elements为列表类型 - AND 验证
elements字段存在且不为空 - AND 如果
elements不存在或为空，抛出错误
Scenario: 验证多个模板的结构
- WHEN 模板库包含多个模板定义
- THEN 系统验证每个模板的结构完整性
- AND 如果某个模板结构错误，错误消息包含模板名称和具体位置
Requirement: 系统必须从模板库文件按名称查询模板
系统 SHALL 支持通过模板名称从模板库文件中查询模板，查询方式为字典键查找。
Scenario: 通过名称从模板库加载模板
- WHEN 幻灯片指定
template: title-slide - AND 用户提供
--template /path/to/templates.yaml - THEN 系统从模板库文件的
templates.title-slide加载模板定义
Scenario: 模板名称不存在时报错
- WHEN 幻灯片引用的模板名称在模板库中不存在
- THEN 系统抛出错误，错误代码为
TEMPLATE_NOT_FOUND_IN_LIBRARY - AND 错误消息包含"模板库中找不到指定模板名称: <模板名>"
Scenario: 模板库文件不存在时报错
- WHEN 用户提供的
--template文件路径不存在 - THEN 系统抛出错误，错误代码为
TEMPLATE_LIBRARY_FILE_NOT_FOUND - AND 错误消息包含"模板库文件不存在"
Requirement: 模板库中的图片资源路径必须相对于模板库文件所在目录
系统 SHALL 在渲染外部模板时，将图片元素的相对路径解析为相对于模板库文件所在目录的绝对路径。
Scenario: 解析模板中的图片相对路径
- WHEN 模板库文件位于
/lib/theme.yaml - AND 模板中的图片元素定义
src: "./assets/logo.png" - THEN 系统将路径解析为
/lib/assets/logo.png
Scenario: 图片绝对路径保持不变
- WHEN 模板中的图片元素定义绝对路径
src: "/usr/share/images/logo.png" - THEN 系统不修改该路径
Scenario: 图片路径解析失败时显示完整路径
- WHEN 解析后的图片路径不存在
- THEN 错误消息显示解析后的绝对路径
- AND 用户可以准确找到问题文件位置
Requirement: 模板库加载不应缓存模板
系统 SHALL 每次从模板库加载模板时创建新的模板对象，不使用缓存机制。
Scenario: 每次加载创建新对象
- WHEN 多个幻灯片使用同一个模板名称
- THEN 系统每次都从模板库重新加载模板定义
- AND 每次创建新的 Template 对象
Scenario: 模板库文件修改后立即生效
- WHEN 模板库文件在运行时被修改
- THEN 下一次加载模板时使用新的定义
- AND 不需要重启程序
Requirement: 命令行参数必须支持 --template 指定模板库文件
系统 SHALL 支持 --template 参数指定模板库文件路径，替代原有的 --template-dir 参数。
Scenario: 使用 --template 参数
- WHEN 用户执行
yaml2pptx.py convert input.yaml --template /path/to/theme.yaml - THEN 系统加载
/path/to/theme.yaml作为模板库文件 - AND 可以从该文件引用模板
Scenario: --template 参数可选
- WHEN 演示文稿仅使用内联模板或自定义元素
- THEN 用户可以不提供
--template参数 - AND 系统正常处理