Files

lanyuanxiaoyao f1aae96a04 refactor: 重构外部模板系统，改为单文件模板库模式

主要变更：
- 将 templates_dir 参数改为 template_file，支持单个模板库 YAML 文件
- 添加模板库 YAML 验证功能
- 为模板添加 base_dir 支持，正确解析相对路径资源
- 内联模板与外部模板同名时改为警告（内联优先）
- 移除模板缓存机制，直接使用模板库字典
- 更新所有相关测试以适配新的模板加载方式

此重构简化了模板管理，使模板资源的路径解析更加清晰明确。

2026-03-05 13:27:12 +08:00

5.5 KiB

Raw Blame History

Template Library

Purpose

Template library 提供集中的模板管理机制，允许将多个模板定义存储在单个 YAML 文件中，通过模板名称引用。

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 系统正常处理

5.5 KiB Raw Blame History