lanyuanxiaoyao/PPTX
1
0
Fork 0
Code Activity
Files
98098dc911f7cf84f7bed2e1e4c0ca6b526abee1
PPTX/openspec/changes/archive/2026-03-05-template-metadata-and-font-ref/tasks.md
lanyuanxiaoyao 98098dc911 feat: 实现模板库metadata和跨域字体引用系统 
实现了统一的metadata结构和字体作用域系统，支持文档和模板库之间的单向字体引用。

主要变更：
- 模板库必须包含metadata字段（包括size、fonts、fonts_default）
- 实现文档和模板库的size一致性校验
- 实现字体作用域系统（文档可引用模板库字体，反之不可）
- 实现跨域循环引用检测
- 实现fonts_default级联规则（模板库→文档→系统默认）
- 添加错误代码常量（SIZE_MISMATCH、FONT_NOT_FOUND等）
- 更新文档和开发者指南

测试覆盖：
- 新增33个测试（单元测试20个，集成测试13个）
- 所有457个测试通过

Breaking Changes：
- 模板库文件必须包含metadata字段
- 模板库metadata.size为必填字段
- 文档和模板库的size必须一致

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-03-05 18:12:05 +08:00

3.2 KiB
Raw Blame History

Implementation Tasks

0. 清理旧代码和测试

  • 0.1 识别并标记需要清理的旧测试
  • 0.2 清理 tests/unit/test_template.py 中向后兼容性相关测试
  • 0.3 清理 tests/integration/test_template_library.py 中向后兼容性相关测试
  • 0.4 清理旧版本的模板库元数据处理逻辑

1. YAML 加载和验证

  • 1.1 在 loaders/yaml_loader.py 中创建 validate_metadata() 函数
  • 1.2 修改 validate_presentation_yaml() 调用 validate_metadata()
  • 1.3 修改 validate_template_library_yaml() 验证模板库必须包含 metadata
  • 1.4 在 validate_template_library_yaml() 中验证模板库 fonts_default 只能引用模板库内部字体

2. Size 一致性校验

  • 2.1 在 core/presentation.py 中添加 size 一致性校验
  • 2.2 添加 size 一致性校验的单元测试

3. FontResolver 跨域支持

  • 3.1 扩展 FontResolver 类支持 scope 和 template_fonts 参数
  • 3.2 修改 _resolve_reference() 方法根据作用域限制引用范围
  • 3.3 实现跨域循环引用检测
  • 3.4 添加 parent 引用的跨域限制

4. Presentation 类扩展

  • 4.1 在 Presentation 中解析和存储模板库 metadata.fonts
  • 4.2 创建文档作用域的 FontResolver
  • 4.3 创建模板库作用域的 FontResolver

5. Template 类扩展

  • 5.1 修改 Template.from_data() 接收 scope 和 font_resolver 参数
  • 5.2 修改 Template.render() 应用正确的 FontResolver 和 fonts_default 级联
  • 5.3 添加表格双字体字段的处理

6. 错误代码定义

  • 6.1 在 validators/result.py 中添加新的错误代码：
    • SIZE_MISMATCH - 文档和模板库尺寸不一致
    • TEMPLATE_FONT_REF_DOC_FORBIDDEN - 模板元素引用文档字体
    • TEMPLATE_PARENT_REF_DOC_FORBIDDEN - 模板库 parent 引用文档字体
    • FONT_NOT_FOUND - 字体配置不存在
    • CIRCULAR_REFERENCE - 循环引用（包括跨域）
    • FONT_DEFAULT_INVALID - fonts_default 引用无效
    • TEMPLATE_LIBRARY_MISSING_METADATA - 模板库缺少 metadata 字段
    • TEMPLATE_LIBRARY_METADATA_MISSING_SIZE - 模板库 metadata 缺少 size
    • TEMPLATE_LIBRARY_METADATA_INVALID_SIZE - 模板库 metadata.size 无效

7. 单元测试

  • 7.1 添加 validate_metadata() 的单元测试
  • 7.2 添加 FontResolver 跨域引用的单元测试
  • 7.3 添加 fonts_default 级联的单元测试
  • 7.4 添加跨域循环引用检测的单元测试（包括单域内循环和跨域循环）
  • 7.5 添加模板库 fonts_default 验证的单元测试

8. 集成测试

  • 8.1 添加跨域字体引用的集成测试
  • 8.2 添加 size 一致性校验的集成测试
  • 8.3 添加完整渲染流程的集成测试
  • 8.4 添加表格双字体字段（font 和 header_font）的集成测试

9. 文档更新

  • 9.1 更新 README.md 添加模板库 metadata 说明和示例
  • 9.2 更新 README_DEV.md 记录错误代码和作用域规则
  • 9.3 添加模板库示例文件

10. 代码清理和格式化

  • 10.1 验证旧测试已完全清理
  • 10.2 代码格式化和添加中文注释

11. 最终测试

  • 11.1 运行完整的测试套件
  • 11.2 手动测试关键场景
  • 11.3 确保所有测试通过
View Git Blame Copy Permalink