## Context 当前系统中,`description` 字段已在以下位置被解析: - `core/presentation.py`: 演示文稿级别的 `metadata.description` - `core/template.py`: 模板级别的 `template.description` - `core/presentation.py`: 幻灯片级别的 `slide.description` 在 `render_slide` 方法返回值中 然而,PPTX 渲染器 (`renderers/pptx_renderer.py`) 的 `add_slide` 方法只处理 `background` 和 `elements`,完全忽略了 `description` 字段。 python-pptx 库原生支持备注功能,通过 `slide.notes_slide.notes_text_frame.text` 即可设置。 ## Goals / Non-Goals **Goals:** - 将幻灯片的 `description` 字段写入 PPT 备注页 - 仅处理幻灯片级别的 description,不涉及模板或演示文稿级别的 description - 保持向后兼容,没有 description 时不设置备注 **Non-Goals:** - 不实现富文本备注(仅支持纯文本) - 不合并模板的 description - 不处理演示文稿级别的 metadata.description ## Decisions ### 1. 备注内容来源 **决策**: 仅使用幻灯片自己的 `description` 字段 **理由**: - 幻灯片 description 是用户针对具体页面编写的说明 - 模板 description 描述的是模板用途,不适合作为单个幻灯片的备注 - 避免复杂的合并逻辑,保持简单清晰 **考虑的替代方案**: - 合并模板 description 和幻灯片 description → 过于复杂,可能产生冗余内容 - 仅在没有幻灯片 description 时使用模板 description → 增加认知负担 ### 2. 无 description 时的行为 **决策**: 不设置备注,保持备注页为空 **理由**: - python-pptx 默认创建空备注页 - 不需要额外判断或清理操作 - 保持行为可预测 ### 3. 代码位置 **决策**: 在 `PptxGenerator` 类中添加私有方法 `_set_notes` **理由**: - 与现有的 `_render_background`、`_render_element` 等方法保持一致 - 封装备注设置逻辑,便于测试和维护 - 不影响 `add_slide` 方法的主流程 ## Risks / Trade-offs ### Risk: 长文本可能导致备注溢出 **影响**: description 内容过长时,可能在备注页中显示不佳 **缓解**: python-pptx 会自动处理文本换行,这是库的默认行为,无需额外处理 ### Trade-off: 仅支持纯文本 **限制**: python-pptx 的备注不支持富文本格式(加粗、颜色等) **权衡**: 备注的主要用途是演讲者参考,纯文本已满足需求;富文本支持需要更复杂的实现,收益不大 ### Risk: 现有 spec 需要更新 **影响**: `page-description` spec 明确规定 "description不写入PPTX文件" **缓解**: 这正是本次变更的目的,需要更新该 spec 以反映新行为