lanyuanxiaoyao
2fd8bc1b4a
添加可选的description字段用于文档目的，不影响渲染输出。 主要更改： - core/presentation.py: 添加metadata.description属性 - core/template.py: 添加template.description属性 - tests: 添加16个新测试用例验证description功能 - docs: 更新README.md和README_DEV.md文档 - specs: 新增page-description规范文件
131 lines
4.9 KiB
Markdown
131 lines
4.9 KiB
Markdown
# Page Description
|
||
|
||
## Purpose
|
||
|
||
Page Description功能允许用户为文档元数据、模板和幻灯片添加描述信息，用于说明文档概要、页面的用途、设计意图或内容概要。这提高了演示文稿、模板和幻灯片的可读性和可维护性。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: metadata必须支持可选的description字段
|
||
|
||
演示文稿的metadata SHALL 支持可选的 `description` 字段，用于描述整个演示文稿的概要和用途。
|
||
|
||
#### Scenario: metadata包含description字段
|
||
|
||
- **WHEN** YAML文件的metadata定义了 `description: "这是关于项目年度总结的演示文稿"`
|
||
- **THEN** 系统成功加载该描述字段，可通过metadata对象访问
|
||
|
||
#### Scenario: metadata不包含description字段
|
||
|
||
- **WHEN** YAML文件的metadata未定义 `description` 字段
|
||
- **THEN** 系统正常加载演示文稿，description属性为None或空字符串
|
||
|
||
#### Scenario: metadata description为空字符串
|
||
|
||
- **WHEN** metadata定义了 `description: ""`
|
||
- **THEN** 系统接受空字符串作为有效值
|
||
|
||
### Requirement: 模板必须支持可选的description字段
|
||
|
||
模板 SHALL 支持可选的 `description` 字段，用于描述该模板的用途和设计意图。
|
||
|
||
#### Scenario: 模板包含description字段
|
||
|
||
- **WHEN** 模板文件定义了 `description: "用于章节标题页的模板，包含主标题和副标题"`
|
||
- **THEN** 系统成功加载该描述字段，可通过模板对象访问
|
||
|
||
#### Scenario: 模板不包含description字段
|
||
|
||
- **WHEN** 模板文件未定义 `description` 字段
|
||
- **THEN** 系统正常加载模板，description属性为None或空字符串
|
||
|
||
#### Scenario: description为空字符串
|
||
|
||
- **WHEN** 模板文件定义了 `description: ""`
|
||
- **THEN** 系统接受空字符串作为有效值
|
||
|
||
### Requirement: 幻灯片必须支持可选的description字段
|
||
|
||
幻灯片定义 SHALL 支持可选的 `description` 字段，用于描述该幻灯片的作用和内容。
|
||
|
||
#### Scenario: 幻灯片包含description字段
|
||
|
||
- **WHEN** 幻灯片定义了 `description: "介绍项目背景和目标"`
|
||
- **THEN** 系统成功加载该描述字段，可通过幻灯片对象访问
|
||
|
||
#### Scenario: 幻灯片不包含description字段
|
||
|
||
- **WHEN** 幻灯片定义未包含 `description` 字段
|
||
- **THEN** 系统正常处理幻灯片，description属性为None或空字符串
|
||
|
||
### Requirement: description字段不得影响渲染逻辑
|
||
|
||
系统 SHALL 在渲染过程中忽略 `description` 字段，不影响最终的PPTX输出。
|
||
|
||
#### Scenario: 渲染包含description的模板
|
||
|
||
- **WHEN** 系统渲染包含 `description` 字段的模板
|
||
- **THEN** description不参与元素渲染，不影响输出结果
|
||
|
||
#### Scenario: 渲染包含description的幻灯片
|
||
|
||
- **WHEN** 系统渲染包含 `description` 字段的幻灯片
|
||
- **THEN** description不写入PPTX文件，不影响输出结果
|
||
|
||
### Requirement: YAML解析器必须正确解析description字段
|
||
|
||
系统 SHALL 从YAML文件中正确读取 `description` 字段，并将其传递给数据模型。
|
||
|
||
#### Scenario: 解析metadata中的description
|
||
|
||
- **WHEN** YAML文件的metadata包含 `description: "文档描述"`
|
||
- **THEN** 解析器将该字符串传递给metadata对象的description属性
|
||
|
||
#### Scenario: 解析模板中的description
|
||
|
||
- **WHEN** YAML文件中的模板包含 `description: "这是描述"`
|
||
- **THEN** 解析器将该字符串传递给模板对象的description属性
|
||
|
||
#### Scenario: 解析幻灯片中的description
|
||
|
||
- **WHEN** YAML文件中的幻灯片包含 `description: "幻灯片描述"`
|
||
- **THEN** 解析器将该字符串传递给幻灯片对象的description属性
|
||
|
||
### Requirement: 数据模型必须包含description属性
|
||
|
||
元数据、模板和幻灯片数据模型 SHALL 包含 `description` 属性，用于存储描述信息。
|
||
|
||
#### Scenario: metadata对象包含description属性
|
||
|
||
- **WHEN** 开发者访问metadata对象
|
||
- **THEN** 可以通过 `metadata.description` 获取描述信息
|
||
|
||
#### Scenario: 模板对象包含description属性
|
||
|
||
- **WHEN** 开发者访问模板对象
|
||
- **THEN** 可以通过 `template.description` 获取描述信息
|
||
|
||
#### Scenario: 幻灯片对象包含description属性
|
||
|
||
- **WHEN** 开发者访问幻灯片对象
|
||
- **THEN** 可以通过 `slide.description` 获取描述信息
|
||
|
||
### Requirement: description字段必须支持中文字符
|
||
|
||
系统 SHALL 支持在 `description` 字段中使用中文字符和其他Unicode字符。
|
||
|
||
#### Scenario: metadata description包含中文
|
||
|
||
- **WHEN** metadata的description包含中文字符，如 "这是关于项目的演示文稿"
|
||
- **THEN** 系统正确处理，不出现编码错误
|
||
|
||
#### Scenario: description包含中文
|
||
|
||
- **WHEN** 模板或幻灯片的description包含中文字符，如 "这是中文描述"
|
||
- **THEN** 系统正确处理，不出现编码错误
|
||
|
||
#### Scenario: description包含多行文本
|
||
|
||
- **WHEN** description字段使用YAML多行文本格式
|
||
- **THEN** 系统正确读取完整的描述内容
|