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规范文件
83 lines
3.3 KiB
Markdown
83 lines
3.3 KiB
Markdown
# Design: Add Description Field to Metadata, Templates, and Slides
|
||
|
||
## Context
|
||
|
||
当前项目使用YAML格式的模板文件和演示文稿定义。YAML文件包含metadata（元数据）部分和slides列表。模板系统（`template-system` spec）定义了模板的结构，包括vars、elements等字段。演示文稿通过YAML文件定义slides列表，每个slide可以引用模板或定义自定义元素。
|
||
|
||
项目目前没有内置的机制来描述文档整体、页面或幻灯片的用途。开发者只能通过元素内容和变量名来推断，这降低了演示文稿、模板和幻灯片的可维护性。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- 为metadata添加可选的description字段
|
||
- 为模板文件添加可选的description字段
|
||
- 为幻灯片定义添加可选的description字段
|
||
- 确保description字段在数据模型中被正确解析和保留
|
||
- 保持完全的向后兼容性
|
||
- 不影响渲染逻辑和输出结果
|
||
|
||
**Non-Goals:**
|
||
- 不将description写入最终的PPTX文件（PowerPoint备注功能不在本次范围）
|
||
- 不实现description的验证逻辑（如长度限制、格式要求）
|
||
- 不实现基于description的搜索或过滤功能
|
||
|
||
## Decisions
|
||
|
||
### 1. Description字段为可选的字符串类型
|
||
|
||
**决策:** description字段为可选字段，类型为字符串，可以为空字符串。
|
||
|
||
**理由:**
|
||
- 保持简单，不过度设计
|
||
- 用户可以自由描述，不受格式限制
|
||
- 可选设计确保向后兼容
|
||
|
||
**替代方案考虑:**
|
||
- 使用结构化格式（如对象，包含title、content等子字段）- 过于复杂，当前需求不需要
|
||
|
||
### 2. Description不参与渲染
|
||
|
||
**决策:** description字段仅用于文档目的，不传递给渲染器，不影响PPTX生成。
|
||
|
||
**理由:**
|
||
- PowerPoint的备注功能需要额外处理，且不在当前需求范围
|
||
- 保持渲染逻辑简单，避免引入不必要的复杂性
|
||
|
||
**替代方案考虑:**
|
||
- 将description写入PPTX备注 - 需要额外的python-pptx API调用，增加复杂度
|
||
|
||
### 3. 在数据模型层面实现
|
||
|
||
**决策:** 在数据模型类（Metadata/Document、Template、Slide）中添加description属性，在YAML解析时读取该字段。
|
||
|
||
**理由:**
|
||
- 与现有代码结构一致
|
||
- 便于统一处理和访问
|
||
- metadata中的description可以描述整个文档
|
||
|
||
**替代方案考虑:**
|
||
- 仅在YAML解析时保留，不添加到数据模型 - 会导致信息丢失，不利于后续使用
|
||
|
||
## Risks / Trade-offs
|
||
|
||
| 风险 | 缓解措施 |
|
||
|------|----------|
|
||
| description字段可能被滥用或包含不恰当内容 | 依赖用户自律，不添加内容验证 |
|
||
| 增加数据模型的字段数量 | 影响很小，仅增加一个可选字符串字段 |
|
||
| 用户可能期望description能影响输出 | 在文档中明确说明description仅用于文档目的 |
|
||
|
||
## Migration Plan
|
||
|
||
1. 更新数据模型类，添加description属性（Metadata、Template、Slide）
|
||
2. 更新YAML解析器，读取metadata、模板和幻灯片的description字段
|
||
3. 添加测试用例验证description正确读取和保留
|
||
4. 更新文档说明新字段的用法
|
||
|
||
**回滚策略:**
|
||
- 由于是新增可选字段，移除该字段不会影响现有功能
|
||
- 如需回滚，只需从数据模型和解析器中移除description相关代码
|
||
|
||
## Open Questions
|
||
|
||
无。本设计较为简单直接，没有未解决的技术问题。
|