# 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

无。本设计较为简单直接，没有未解决的技术问题。