lanyuanxiaoyao
98098dc911
实现了统一的metadata结构和字体作用域系统，支持文档和模板库之间的单向字体引用。 主要变更： - 模板库必须包含metadata字段（包括size、fonts、fonts_default） - 实现文档和模板库的size一致性校验 - 实现字体作用域系统（文档可引用模板库字体，反之不可） - 实现跨域循环引用检测 - 实现fonts_default级联规则（模板库→文档→系统默认） - 添加错误代码常量（SIZE_MISMATCH、FONT_NOT_FOUND等） - 更新文档和开发者指南 测试覆盖： - 新增33个测试（单元测试20个，集成测试13个） - 所有457个测试通过 Breaking Changes： - 模板库文件必须包含metadata字段 - 模板库metadata.size为必填字段 - 文档和模板库的size必须一致 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
174 lines
7.1 KiB
Markdown
174 lines
7.1 KiB
Markdown
# Template Library Delta Spec
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: 模板库必须包含 metadata 结构
|
||
|
||
模板库文件 SHALL 必须包含 metadata 字段，与文档使用相同的结构，包含 `size`（必填）、`version`、`author`、`description`、`fonts`、`fonts_default`。
|
||
|
||
#### Scenario: 模板库包含完整的 metadata
|
||
|
||
- **WHEN** 模板库文件包含 metadata 字段，包含 size、version、author、description、fonts、fonts_default
|
||
- **THEN** 系统成功解析并存储这些元数据
|
||
|
||
#### Scenario: 模板库缺少 metadata 字段
|
||
|
||
- **WHEN** 模板库文件不包含 metadata 字段
|
||
- **THEN** 系统抛出 ERROR，错误代码为 `TEMPLATE_LIBRARY_MISSING_METADATA`
|
||
- **AND** 错误消息包含"模板库必须包含 metadata 字段"
|
||
|
||
#### Scenario: 模板库 metadata 缺少 size 字段
|
||
|
||
- **WHEN** 模板库包含 metadata 但缺少 size 字段
|
||
- **THEN** 系统抛出 ERROR，错误代码为 `TEMPLATE_LIBRARY_METADATA_MISSING_SIZE`
|
||
- **AND** 错误消息包含"模板库 metadata 缺少必填字段 'size'"
|
||
|
||
#### Scenario: 模板库 metadata 的 size 值无效
|
||
|
||
- **WHEN** 模板库 metadata.size 不是有效的尺寸值（如 "16:9" 或 "4:3"）
|
||
- **THEN** 系统抛出 ERROR，错误代码为 `TEMPLATE_LIBRARY_METADATA_INVALID_SIZE`
|
||
|
||
### Requirement: 模板库 metadata 必须使用与文档相同的验证规则
|
||
|
||
模板库 metadata 的字段验证 SHALL 与文档 metadata 使用相同的规则。
|
||
|
||
#### Scenario: 模板库 metadata.fonts 验证
|
||
|
||
- **WHEN** 模板库 metadata.fonts 中定义字体配置
|
||
- **THEN** 系统使用与文档 fonts 相同的验证规则
|
||
|
||
#### Scenario: 模板库 metadata.fonts_default 验证
|
||
|
||
- **WHEN** 模板库 metadata.fonts_default 引用字体配置
|
||
- **THEN** 系统验证引用存在于模板库 metadata.fonts 中
|
||
|
||
#### Scenario: 模板库 metadata.version 和 author 可选
|
||
|
||
- **WHEN** 模板库 metadata 包含或不含 version、author 字段
|
||
- **THEN** 系统正常处理，这些字段为可选项
|
||
|
||
### Requirement: 系统必须校验文档和模板库的 size 一致性
|
||
|
||
系统 SHALL 在加载模板库时校验文档的 metadata.size 与模板库的 metadata.size 是否一致。
|
||
|
||
#### Scenario: 文档和模板库 size 一致
|
||
|
||
- **WHEN** 文档 metadata.size 为 "16:9" 且模板库 metadata.size 也为 "16:9"
|
||
- **THEN** 系统正常加载，不报错
|
||
|
||
#### Scenario: 文档和模板库 size 不一致
|
||
|
||
- **WHEN** 文档 metadata.size 为 "16:9" 但模板库 metadata.size 为 "4:3"
|
||
- **THEN** 系统抛出 ERROR，错误代码为 `SIZE_MISMATCH`
|
||
- **AND** 错误消息包含"文档尺寸 '16:9' 与模板库尺寸 '4:3' 不一致"
|
||
|
||
### Requirement: 模板库 fonts 的 parent 只能引用模板库内部
|
||
|
||
模板库 metadata.fonts 中定义的字体配置，其 parent 字段 SHALL 只能引用模板库内部的字体配置。
|
||
|
||
#### Scenario: parent 引用模板库内部的字体
|
||
|
||
- **WHEN** 模板库 metadata.fonts 中定义 heading: {parent: "@base"} 且 base 存在于模板库 fonts 中
|
||
- **THEN** 系统成功解析继承关系
|
||
|
||
#### Scenario: parent 引用文档的字体
|
||
|
||
- **WHEN** 模板库 metadata.fonts 中定义 custom: {parent: "@doc-font"}
|
||
- **THEN** 系统抛出 ERROR，错误代码为 `TEMPLATE_PARENT_REF_DOC_FORBIDDEN`
|
||
- **AND** 错误消息包含"模板库字段的 parent 不能引用文档的字体配置"
|
||
|
||
#### Scenario: parent 引用不存在的字体
|
||
|
||
- **WHEN** 模板库 metadata.fonts 中定义 heading: {parent: "@nonexistent"}
|
||
- **THEN** 系统抛出 ERROR，错误代码为 `FONT_NOT_FOUND`
|
||
- **AND** 错误消息包含"引用的字体配置不存在"
|
||
|
||
### Requirement: 外部模板元素只能引用模板库的 fonts
|
||
|
||
外部模板（模板库中定义的模板）中的元素 SHALL 只能引用模板库 metadata.fonts 中定义的字体配置。
|
||
|
||
#### Scenario: 模板元素引用模板库的字体
|
||
|
||
- **WHEN** 外部模板元素定义 font: "@title" 且 title 存在于模板库 fonts 中
|
||
- **THEN** 系统成功应用字体配置
|
||
|
||
#### Scenario: 模板元素引用文档的字体
|
||
|
||
- **WHEN** 外部模板元素定义 font: "@doc-title" 且 doc-title 只存在于文档 fonts 中
|
||
- **THEN** 系统抛出 ERROR，错误代码为 `TEMPLATE_FONT_REF_DOC_FORBIDDEN`
|
||
- **AND** 错误消息包含"模板元素不能引用文档的字体配置"
|
||
|
||
#### Scenario: 模板元素引用同名字体（只使用模板库的）
|
||
|
||
- **WHEN** 外部模板元素定义 font: "@title"
|
||
- **AND** title 同时存在于文档 fonts 和模板库 fonts 中
|
||
- **THEN** 系统只使用模板库的 title 配置（不查找文档）
|
||
|
||
### Requirement: 模板元素的 fonts_default 级联规则
|
||
|
||
外部模板元素未定义 font 时 SHALL 级联使用 fonts_default：优先文档 fonts_default，文档没有则使用模板库 fonts_default。
|
||
|
||
#### Scenario: 模板元素未定义 font，文档有 fonts_default
|
||
|
||
- **WHEN** 模板元素未定义 font
|
||
- **AND** 文档定义了 metadata.fonts_default: "@body"
|
||
- **THEN** 元素使用文档的 fonts_default 配置
|
||
|
||
#### Scenario: 模板元素未定义 font，文档没有 fonts_default
|
||
|
||
- **WHEN** 模板元素未定义 font
|
||
- **AND** 文档未定义 fonts_default
|
||
- **AND** 模板库定义了 metadata.fonts_default: "@base"
|
||
- **THEN** 元素使用模板库的 fonts_default 配置
|
||
|
||
#### Scenario: 模板元素未定义 font，都没有 fonts_default
|
||
|
||
- **WHEN** 模板元素未定义 font
|
||
- **AND** 文档和模板库都未定义 fonts_default
|
||
- **THEN** 元素使用系统默认字体
|
||
|
||
### Requirement: 表格元素的双字体字段应用相同规则
|
||
|
||
表格元素的 font 和 header_font 字段 SHALL 应用与普通元素相同的字体引用规则。
|
||
|
||
#### Scenario: 表格的 font 引用模板库字体
|
||
|
||
- **WHEN** 模板中的表格定义 font: "@table-body"
|
||
- **AND** table-body 存在于模板库 fonts 中
|
||
- **THEN** 系统成功应用字体配置
|
||
|
||
#### Scenario: 表格的 header_font 引用模板库字体
|
||
|
||
- **WHEN** 模板中的表格定义 header_font: "@table-header"
|
||
- **AND** table-header 存在于模板库 fonts 中
|
||
- **THEN** 系统成功应用字体配置
|
||
|
||
#### Scenario: 表格的 font 为 null
|
||
|
||
- **WHEN** 模板中的表格定义 font: null 或未定义
|
||
- **THEN** 系统按 fonts_default 级联规则处理
|
||
|
||
## MODIFIED Requirements
|
||
|
||
### Requirement: 模板库文件必须包含元数据字段
|
||
|
||
模板库文件 SHALL 必须包含 metadata 字段，元数据结构与文档相同，包含 `size`（必填）、`version`、`author`、`description`、`fonts`、`fonts_default`。
|
||
|
||
#### Scenario: 加载包含完整元数据的模板库文件
|
||
|
||
- **WHEN** 模板库文件包含 metadata 字段，包含 size、version、author、description、fonts、fonts_default
|
||
- **THEN** 系统成功加载这些元数据字段
|
||
- **AND** size 字段必须为有效值
|
||
- **AND** fonts 和 fonts_default 按字体主题规则验证
|
||
|
||
#### Scenario: 模板库 metadata 缺少必填的 size 字段
|
||
|
||
- **WHEN** 模板库 metadata 中缺少 size 字段
|
||
- **THEN** 系统抛出错误，错误代码为 `TEMPLATE_LIBRARY_METADATA_MISSING_SIZE`
|
||
|
||
#### Scenario: 模板库缺少 metadata 字段
|
||
|
||
- **WHEN** 模板库文件不包含 metadata 字段
|
||
- **THEN** 系统抛出错误，错误代码为 `TEMPLATE_LIBRARY_MISSING_METADATA`
|
||
- **AND** 错误消息包含"模板库必须包含 metadata 字段"
|