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规范文件
3.3 KiB
3.3 KiB
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
- 更新数据模型类，添加description属性（Metadata、Template、Slide）
- 更新YAML解析器，读取metadata、模板和幻灯片的description字段
- 添加测试用例验证description正确读取和保留
- 更新文档说明新字段的用法
回滚策略:
- 由于是新增可选字段，移除该字段不会影响现有功能
- 如需回滚，只需从数据模型和解析器中移除description相关代码
Open Questions
无。本设计较为简单直接，没有未解决的技术问题。