PPTX/openspec/specs/font-theme/spec.md

Font Theme

Purpose

字体主题系统提供可复用的字体配置管理能力，允许用户在 metadata 中定义字体配置模板，通过引用方式应用到元素，实现统一的字体样式管理。支持文档和模板库的字体作用域隔离，以及跨域字体引用。

Requirements

Requirement: 系统必须支持在 metadata 中定义 fonts 字段

系统 SHALL 支持在文档和模板库的 YAML metadata 中定义 fonts 字段，用于存储可复用的字体配置。模板库的 fonts 与文档的 fonts 使用相同的定义和验证规则。

Scenario: 定义 fonts 字段（文档）

• WHEN 文档 metadata 中定义 fonts 字段
• THEN 系统成功解析并存储字体配置字典

Scenario: 定义 fonts 字段（模板库）

• WHEN 模板库 metadata 中定义 fonts 字段
• THEN 系统成功解析并存储字体配置字典

Scenario: fonts 字段为空字典

• WHEN metadata 中定义 fonts: {}
• THEN 系统接受空的字体配置字典

Scenario: fonts 字段未定义

• WHEN metadata 中未定义 fonts 字段
• THEN 系统正常处理，fonts 为空字典

Requirement: fonts 字段必须包含命名字体配置

fonts 字段 SHALL 包含一个或多个命名字体配置，每个配置是一个字体属性字典。

Scenario: 定义单个字体配置

• WHEN fonts 中定义 title: {family: "Arial", size: 44, bold: true}
• THEN 系统创建名为 title 的字体配置

Scenario: 定义多个字体配置

• WHEN fonts 中定义 title、subtitle、body 等多个配置
• THEN 系统为每个配置创建独立的字体对象

Requirement: 文档 metadata 必须支持 version 和 author 字段

文档 metadata SHALL 支持可选的 version 和 author 字段。

Scenario: 文档包含 version 和 author

• WHEN 文档 metadata 包含 version: "1.0" 和 author: "作者名"
• THEN 系统成功解析并存储这些字段

Scenario: 文档不包含 version 和 author

• WHEN 文档 metadata 不包含 version 和 author 字段
• THEN 系统正常处理，这些字段为可选项

Requirement: 系统必须支持 fonts_default 字段

系统 SHALL 支持在文档和模板库的 metadata 中定义可选的 fonts_default 字段，指定默认字体配置的引用。文档的 fonts_default 可以引用文档或模板库的 fonts，模板库的 fonts_default 只能引用模板库的 fonts。

Scenario: 定义 fonts_default 引用（文档）

• WHEN 文档 metadata 中定义 fonts_default: "@body"
• AND body 存在于文档 metadata.fonts 中
• THEN 系统将 fonts_default 解析为对 fonts.body 的引用

Scenario: 定义 fonts_default 引用（模板库）

• WHEN 模板库 metadata 中定义 fonts_default: "@base"
• AND base 存在于模板库 metadata.fonts 中
• THEN 系统将 fonts_default 解析为对 fonts.base 的引用

Scenario: 文档 fonts_default 引用模板库字体

• WHEN 文档 metadata.fonts_default: "@template-base"
• AND template-base 存在于模板库 metadata.fonts 中
• THEN 系统成功解析默认字体

Scenario: 模板库 fonts_default 不能引用文档字体

• WHEN 模板库 metadata.fonts_default: "@doc-body"
• AND doc-body 只存在于文档 metadata.fonts 中
• THEN 系统抛出 ERROR，错误代码为 FONT_DEFAULT_INVALID

Scenario: fonts_default 未定义

• WHEN metadata 中未定义 fonts_default 字段
• THEN 系统使用 python-pptx 的默认字体

Scenario: fonts_default 引用不存在的配置

• WHEN fonts_default: "@undefined" 且 undefined 不存在
• THEN 系统抛出 ERROR，错误代码为 FONT_DEFAULT_INVALID

Scenario: fonts_default 必须是引用格式

• WHEN fonts_default: "Arial"（直接字体名称）
• THEN 系统抛出 ERROR，错误代码为 FONT_DEFAULT_INVALID

Requirement: 文档元素和内联模板元素必须支持跨域引用字体

文档中的元素和内联模板（文档中定义的 templates）中的元素 SHALL 优先引用文档的 fonts，文档没有时可引用模板库的 fonts。

Scenario: 元素引用文档中存在的字体

• WHEN 文档元素定义 font: "@title"
• AND title 存在于文档 metadata.fonts 中
• THEN 系统使用文档的 title 配置

Scenario: 元素引用文档不存在但模板库存在的字体

• WHEN 文档元素定义 font: "@template-title"
• AND template-title 不存在于文档 fonts 中
• AND template-title 存在于模板库 metadata.fonts 中
• THEN 系统使用模板库的 template-title 配置

Scenario: 元素引用不存在的字体（文档和模板库都没有）

• WHEN 文档元素定义 font: "@nonexistent"
• AND nonexistent 不存在于文档和模板库的 fonts 中
• THEN 系统抛出 ERROR，错误代码为 FONT_NOT_FOUND
• AND 错误消息包含"引用的字体配置不存在"

Scenario: 同名字体时优先使用文档的

• WHEN 文档元素定义 font: "@title"
• AND title 同时存在于文档 fonts 和模板库 fonts 中
• THEN 系统使用文档的 title 配置（不使用模板库的）

Scenario: 内联模板元素引用文档字体

• WHEN 内联模板（文档 templates 中定义）的元素定义 font: "@body"
• AND body 存在于文档 metadata.fonts 中
• THEN 系统使用文档的 body 配置

Scenario: 内联模板元素引用模板库字体

• WHEN 内联模板的元素定义 font: "@template-body"
• AND template-body 只存在于模板库 metadata.fonts 中
• THEN 系统使用模板库的 template-body 配置

Requirement: 元素 font 字段必须支持多种引用方式

元素 font 字段 SHALL 支持字符串引用（整体引用）、字典引用（继承覆盖或独立定义）两种形式。引用的目标根据元素所在作用域决定。

Scenario: 文档元素引用文档字体

• WHEN 文档元素定义 font: "@title"
• AND title 存在于文档 metadata.fonts 中
• THEN 系统使用文档的 title 配置

Scenario: 文档元素引用模板库字体

• WHEN 文档元素定义 font: "@template-title"
• AND template-title 只存在于模板库 metadata.fonts 中
• THEN 系统使用模板库的 template-title 配置

Scenario: 模板元素只能引用模板库字体

• WHEN 外部模板元素定义 font: "@title"
• AND title 只存在于文档 metadata.fonts 中
• THEN 系统抛出 ERROR，错误代码为 TEMPLATE_FONT_REF_DOC_FORBIDDEN

Scenario: 字典继承覆盖

• WHEN 元素定义 font: {parent: "@title", size: 60}
• THEN 系统继承引用字体的所有属性，覆盖 size 为 60

Scenario: 字典独立定义

• WHEN 元素定义 font: {family: "SimSun", size: 24}
• THEN 系统使用定义的属性，未定义的属性继承 fonts_default

Scenario: font 字段未定义

• WHEN 元素未定义 font 字段
• THEN 元素使用 fonts_default 或系统默认字体

Requirement: 文档 fonts 的 parent 必须支持跨域引用

文档 metadata.fonts 中定义的字体配置，其 parent 字段 SHALL 可以引用文档内部的字体配置或模板库的字体配置。

Scenario: parent 引用文档内部的字体

• WHEN 文档 metadata.fonts 中定义 heading: {parent: "@base"}
• AND base 存在于文档 fonts 中
• THEN 系统成功继承 base 的属性

Scenario: parent 引用模板库的字体

• WHEN 文档 metadata.fonts 中定义 custom: {parent: "@template-base"}
• AND template-base 存在于模板库 metadata.fonts 中
• THEN 系统成功继承 template-base 的属性

Scenario: parent 引用不存在的字体（文档和模板库都没有）

• WHEN 文档 metadata.fonts 中定义 heading: {parent: "@nonexistent"}
• AND nonexistent 不存在于文档和模板库的 fonts 中
• THEN 系统抛出 ERROR，错误代码为 FONT_NOT_FOUND
• AND 错误消息包含"引用的字体配置不存在"

Scenario: 同名字体时 parent 优先引用文档的

• WHEN 文档 metadata.fonts 中定义 heading: {parent: "@base"}
• AND base 同时存在于文档 fonts 和模板库 fonts 中
• THEN 系统使用文档的 base 配置

Requirement: parent 字段必须引用有效域中的字体配置

font 字典中的 parent 字段 SHALL 引用有效域中的配置。文档 fonts 的 parent 可以引用文档或模板库的 fonts，模板库 fonts 的 parent 只能引用模板库的 fonts。

Scenario: 文档字体 parent 引用文档字体

• WHEN 文档 fonts 中定义 heading: {parent: "@title"}
• AND title 存在于文档 metadata.fonts 中
• THEN 系统成功继承 title 的属性

Scenario: 文档字体 parent 引用模板库字体

• WHEN 文档 fonts 中定义 custom: {parent: "@template-base"}
• AND template-base 存在于模板库 metadata.fonts 中
• THEN 系统成功继承 template-base 的属性

Scenario: 模板库字体 parent 引用模板库字体

• WHEN 模板库 fonts 中定义 heading: {parent: "@base"}
• AND base 存在于模板库 metadata.fonts 中
• THEN 系统成功继承 base 的属性

Scenario: 模板库字体 parent 引用文档字体（禁止）

• WHEN 模板库 fonts 中定义 custom: {parent: "@doc-base"}
• THEN 系统抛出 ERROR，错误代码为 TEMPLATE_PARENT_REF_DOC_FORBIDDEN

Scenario: parent 引用不存在的配置

• WHEN parent: "@undefined" 且 undefined 不存在
• THEN 系统抛出 ERROR，错误代码为 FONT_NOT_FOUND

Scenario: parent 必须是引用格式

• WHEN parent: "Arial"（直接字体名称）
• THEN 系统抛出 ERROR

Requirement: 系统必须检测跨域循环引用

系统 SHALL 在解析字体引用时检测跨域循环引用，包括文档和模板库之间的循环。

Scenario: 文档内部循环引用

• WHEN 文档 fonts.a.parent: "@b" 且 fonts.b.parent: "@a"
• THEN 系统抛出 ERROR，错误代码为 CIRCULAR_REFERENCE
• AND 错误消息包含"检测到字体引用循环"和完整路径

Scenario: 模板库内部循环引用

• WHEN 模板库 fonts.x.parent: "@y" 且 fonts.y.parent: "@x"
• THEN 系统抛出 ERROR，错误代码为 CIRCULAR_REFERENCE
• AND 错误消息包含"检测到字体引用循环"和完整路径

Scenario: 跨域循环引用

• WHEN 文档 fonts.a.parent: "@template-b"
• AND 模板库 fonts.b.parent: "@template-c"
• AND 模板库 fonts.c.parent: "@doc-a"
• THEN 系统抛出 ERROR，错误代码为 CIRCULAR_REFERENCE
• AND 错误消息包含"检测到跨域字体引用循环"和完整路径

Scenario: 跨域引用链不循环

• WHEN 文档 fonts.a.parent: "@template-b"
• AND 模板库 fonts.b.parent: "@template-c"
• AND 模板库 fonts.c 没有引用其他字体
• THEN 系统成功解析，不报错

Requirement: 系统必须检测并拒绝引用循环

系统 SHALL 在解析字体引用时检测循环引用，包括单域内部循环和跨域循环，检测到循环时抛出 ERROR。

Scenario: 直接循环引用

• WHEN fonts.title.parent: "@title"（引用自身）
• THEN 系统抛出 ERROR，错误代码为 CIRCULAR_REFERENCE

Scenario: 间接循环引用（单域）

• WHEN fonts.a.parent: "@b" 且 fonts.b.parent: "@a"
• THEN 系统抛出 ERROR，显示完整的引用循环路径

Scenario: 跨域循环引用

• WHEN 文档 fonts.a 引用模板库 fonts.b
• AND 模板库 fonts.b 引用模板库 fonts.c
• AND 模板库 fonts.c 引用文档 fonts.a
• THEN 系统抛出 ERROR，错误代码为 CIRCULAR_REFERENCE
• AND 错误消息包含"检测到跨域字体引用循环"

Scenario: 深层引用但不循环

• WHEN 引用链深度超过 5 层但没有循环
• THEN 系统成功解析

Scenario: 引用链深度超过限制

• WHEN 引用链深度超过 10 层
• THEN 系统抛出 ERROR，提示引用深度超限

Scenario: 错误信息包含引用路径

• WHEN 系统检测到循环引用
• THEN 错误信息包含完整的引用路径

Requirement: 文档和模板库的 fonts_default 必须独立验证

文档的 metadata.fonts_default SHALL 只能引用文档或模板库中存在的字体配置，模板库的 metadata.fonts_default SHALL 只能引用模板库中存在的字体配置。

Scenario: 文档 fonts_default 引用文档字体

• WHEN 文档 metadata.fonts_default: "@body"
• AND body 存在于文档 metadata.fonts 中
• THEN 系统成功解析默认字体

Scenario: 文档 fonts_default 引用模板库字体

• WHEN 文档 metadata.fonts_default: "@template-base"
• AND template-base 存在于模板库 metadata.fonts 中
• THEN 系统成功解析默认字体

Scenario: 文档 fonts_default 引用不存在的字体

• WHEN 文档 metadata.fonts_default: "@nonexistent"
• AND nonexistent 不存在于文档和模板库的 fonts 中
• THEN 系统抛出 ERROR，错误代码为 FONT_DEFAULT_INVALID
• AND 错误消息包含"fonts_default 引用的字体配置不存在"

Scenario: 模板库 fonts_default 引用模板库字体

• WHEN 模板库 metadata.fonts_default: "@base"
• AND base 存在于模板库 metadata.fonts 中
• THEN 系统成功解析默认字体

Scenario: 模板库 fonts_default 引用文档字体

• WHEN 模板库 metadata.fonts_default: "@doc-body"
• AND doc-body 只存在于文档 metadata.fonts 中
• THEN 系统抛出 ERROR，错误代码为 FONT_DEFAULT_INVALID
• AND 错误消息包含"模板库 fonts_default 只能引用模板库内部的字体配置"

Requirement: 系统必须支持属性继承链

字体属性解析 SHALL 按照优先级顺序继承：parent → 当前定义 → fonts_default → 系统默认。跨域继承时，文档可继承模板库的，模板库不能继承文档的。

Scenario: parent 定义了基础属性

• WHEN fonts.title 定义 size: 44，元素定义 font: {parent: "@title", bold: true}
• THEN 元素使用 size: 44（继承）、bold: true（覆盖）

Scenario: 文档字体 parent 继承模板库字体属性

• WHEN 文档 fonts.custom 定义 parent: "@template-base"
• AND 模板库 fonts.base 定义 family: "Arial", size: 18
• THEN custom 继承 family 和 size

Scenario: 模板库字体 parent 不能继承文档字体属性

• WHEN 模板库 fonts.custom 定义 parent: "@doc-base"
• THEN 系统抛出 ERROR，错误代码为 TEMPLATE_PARENT_REF_DOC_FORBIDDEN

Scenario: parent 未定义的属性继承 fonts_default

• WHEN fonts_default 定义 size: 18，元素定义 font: {parent: "@title"} 且 title 未定义 size
• THEN 元素使用 size: 18（从 fonts_default 继承）

Scenario: 当前定义覆盖 parent

• WHEN parent 定义 size: 44，当前定义 size: 60
• THEN 元素使用 size: 60（当前定义覆盖 parent）

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

• WHEN 内联模板（文档中定义）元素未定义 font
• THEN 元素继承文档的 fonts_default 配置

Scenario: 模板元素定义了 font

• WHEN 模板元素定义 font: "@title"
• THEN 元素使用 font: "@title"，不继承 fonts_default

Scenario: fonts_default 未定义时模板元素行为

• WHEN 模板元素未定义 font
• AND 文档和模板库都未定义 fonts_default
• THEN 元素使用系统默认字体

Requirement: 表格元素必须支持 font 和 header_font 字段

表格元素 SHALL 支持 font 和 header_font 字段，分别控制数据单元格和表头的字体样式。

Scenario: 表格定义整体字体

• WHEN 表格定义 font: {family: "Arial", size: 14}
• THEN 数据单元格和表头都应用该字体（表头可被 header_font 覆盖）

Scenario: 表格定义表头字体

• WHEN 表格定义 header_font: {bold: true, color: "#ffffff"}
• THEN 表头应用该字体，数据单元格继承 font 或 fonts_default

Scenario: 表头字体继承表格字体

• WHEN 表格定义 font: {size: 14} 且 header_font: {parent: "@font", bold: true}
• THEN 表头继承 size: 14，覆盖 bold: true

Scenario: 表格仅定义 header_font

• WHEN 表格仅定义 header_font: {bold: true}
• THEN 表头应用 bold: true，数据单元格继承 fonts_default

Requirement: 系统必须移除旧的表格字体语法

系统 SHALL 移除 style.font_size 和 style.header_color 字段的处理逻辑。

Scenario: 旧语法字段不再生效

• WHEN 表格定义 style: {font_size: 14, header_color: "#fff"}
• THEN 系统忽略这些字段，使用 font 和 header_font 替代

Scenario: style 字段保留用于非字体属性

• WHEN 表格定义 style: {header_bg: "#4a90e2"}
• THEN 系统正常处理背景色等非字体属性