lanyuanxiaoyao
f1aae96a04
主要变更： - 将 templates_dir 参数改为 template_file，支持单个模板库 YAML 文件 - 添加模板库 YAML 验证功能 - 为模板添加 base_dir 支持，正确解析相对路径资源 - 内联模板与外部模板同名时改为警告（内联优先） - 移除模板缓存机制，直接使用模板库字典 - 更新所有相关测试以适配新的模板加载方式 此重构简化了模板管理，使模板资源的路径解析更加清晰明确。
7.9 KiB
7.9 KiB
REMOVED Requirements
Requirement: 模板文件必须可从指定目录加载
Reason: 被模板库系统替代，外部模板现在通过 --template 参数指定的单个 YAML 文件加载，而不是从目录加载多个文件。
Migration: 用户需要将分散在目录中的模板文件合并为一个模板库文件，并使用 --template 参数替代 --template-dir 参数。
Requirement: 模板名称必须是纯文件名
Reason: 模板库使用字典键查询，不再受文件命名规则限制。模板名称可以是任意字符串，只要作为字典键有效即可。
Migration: 不需要迁移，新的模板名称规则更加宽松。
Requirement: 未指定模板目录时必须报错
Reason: 被"未指定模板库文件时必须报错"需求替代。使用 --template 参数而非 --template-dir。
Migration: 更新命令行脚本和文档，使用 --template 参数。
Requirement: 缓存已加载的模板
Reason: 模板库加载性能开销小，移除缓存机制简化代码逻辑，避免一致性问题。
Migration: 不需要迁移，性能影响可忽略。
MODIFIED Requirements
Requirement: 模板文件必须可从指定位置加载
系统 SHALL 支持从两个位置加载模板：内联模板（在文档 YAML 的 templates 字段中定义）和外部模板（通过 --template 参数指定的模板库文件）。
Scenario: 从内联模板加载
- WHEN 幻灯片指定
template: title-slide - AND 文档 YAML 的
templates字段定义了title-slide模板 - THEN 系统从内联模板字典中加载模板定义
Scenario: 从模板库文件加载
- WHEN 幻灯片指定
template: content-slide - AND 用户提供
--template /path/to/theme.yaml - AND 模板库文件的
templates.content-slide存在 - THEN 系统从模板库文件中加载模板定义
Scenario: 模板库文件不存在时报错
- WHEN 幻灯片引用外部模板，但
--template指定的文件不存在 - THEN 系统抛出错误，错误代码为
TEMPLATE_LIBRARY_FILE_NOT_FOUND
Scenario: 模板名称在两者中都不存在时报错
- WHEN 幻灯片引用的模板名称既不在内联模板中，也不在模板库中
- THEN 系统抛出错误，错误代码为
TEMPLATE_NOT_FOUND_IN_LIBRARY - AND 错误消息包含"模板库中找不到指定模板名称"
Requirement: 内联和外部模板同名时必须发出警告
系统 SHALL 检测内联模板和外部模板的同名冲突，返回 WARNING 级别的验证问题，并优先使用内联模板。
Scenario: 同名冲突时发出警告
- WHEN 幻灯片引用的模板名称同时存在于内联模板和模板库中
- THEN 系统生成 WARNING 级别的验证问题
- AND 错误代码为
TEMPLATE_NAME_CONFLICT - AND 错误消息包含"模板名称冲突: '' 同时存在于内联模板和外部模板库"
- AND 系统优先使用内联模板
Scenario: 同名冲突时优先使用内联模板
- WHEN 内联模板和外部模板都定义了
title-slide - AND 幻灯片引用
template: title-slide - THEN 系统使用内联模板的定义
- AND 忽略模板库中的同名模板
Scenario: 无冲突时正常加载
- WHEN 模板名称仅存在于内联模板或外部模板库中
- THEN 系统正常加载，不发出警告
Requirement: 系统必须支持自定义幻灯片
系统 SHALL 支持不使用模板的自定义幻灯片，以及同时使用模板和自定义元素的混合模式幻灯片。自定义元素的图片相对路径应相对于文档 YAML 所在目录解析。
Scenario: 渲染自定义幻灯片
- WHEN 幻灯片未指定
template字段，直接包含elements列表 - THEN 系统跳过模板渲染，直接处理元素列表
- AND 自定义元素的图片相对路径相对于文档 YAML 所在目录解析
Scenario: 自定义元素的图片路径解析
- WHEN 文档 YAML 位于
/doc/presentation.yaml - AND 自定义元素包含图片
src: "./images/chart.png" - THEN 系统将路径解析为
/doc/images/chart.png
Scenario: 自定义幻灯片和模板混合使用
- WHEN 演示文稿中部分幻灯片使用模板，部分为自定义
- THEN 系统正确处理两种类型的幻灯片
- AND 模板元素的图片相对于模板库目录，自定义元素的图片相对于文档目录
Scenario: 混合模式幻灯片同时使用模板和自定义元素
- WHEN 幻灯片同时指定了
template字段和elements列表 - THEN 系统先渲染模板获取模板元素列表，再追加自定义元素列表，生成最终的元素列表
- AND 模板元素的图片已解析为绝对路径（相对于模板库）
- AND 自定义元素的图片已解析为绝对路径（相对于文档）
Scenario: 混合模式中模板元素在前
- WHEN 幻灯片使用混合模式，模板元素和自定义元素位置重叠
- THEN 自定义元素在 z 轴上覆盖模板元素（后渲染在上层）
Requirement: 模板与自定义元素必须支持变量共享
系统 SHALL 允许自定义元素访问模板中定义的变量，实现主题色、布局参数等值的统一控制。
Scenario: 自定义元素使用模板变量
- WHEN 幻灯片使用
template: content-slide，提供vars: {theme_color: "#3949ab"} - AND 自定义元素中定义
fill: "{theme_color}" - THEN 系统将自定义元素中的
{theme_color}替换为"#3949ab"
Scenario: 自定义元素使用模板默认变量
- WHEN 模板定义了
default: "#3949ab"的theme_color变量 - AND 幻灯片未提供该变量值
- AND 自定义元素引用
{theme_color} - THEN 系统使用模板的默认值
"#3949ab"进行替换
Scenario: 自定义元素引用未定义变量时报错
- WHEN 自定义元素引用了
{undefined_var} - AND 该变量未在模板 vars 中定义
- AND 也未由幻灯片提供
- THEN 系统抛出错误，指出未定义的变量
Requirement: 混合模式必须保持向后兼容
系统 SHALL 在不使用混合模式时，保持与现有版本完全一致的行为。
Scenario: 仅使用模板时不指定 elements
- WHEN 幻灯片仅指定
template字段，不包含elements字段 - THEN 系统表现与现有版本完全一致，仅渲染模板元素
Scenario: 仅使用自定义元素时不指定 template
- WHEN 幻灯片仅指定
elements字段，不包含template字段 - THEN 系统表现与现有版本完全一致，仅渲染自定义元素
Scenario: 既不使用模板也不使用自定义元素
- WHEN 幻灯片既不指定
template也不指定elements - THEN 系统生成空幻灯片（仅包含背景设置）
Requirement: 混合模式必须支持内联模板
系统 SHALL 在混合模式中支持内联模板与外部模板库，功能保持一致。
Scenario: 内联模板与自定义元素混合使用
- WHEN 幻灯片引用内联模板（在 YAML 文件的
templates字段中定义） - AND 同时包含
elements列表 - THEN 系统正确渲染内联模板元素
- AND 追加自定义元素
- AND 图片路径正确解析（内联模板相对于文档目录）
Scenario: 外部模板与自定义元素混合使用
- WHEN 幻灯片引用外部模板（从
--template指定的模板库加载） - AND 同时包含
elements列表 - THEN 系统正确加载外部模板
- AND 渲染模板元素
- AND 追加自定义元素
- AND 图片路径正确解析（外部模板相对于模板库目录）
Scenario: 内联和外部模板在同一演示文稿中混合使用
- WHEN 演示文稿同时定义了内联模板和使用外部模板
- AND 部分幻灯片使用混合模式
- THEN 系统正确处理所有组合情况