lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
5.9 KiB
5.9 KiB
架构设计
本文档说明 yaml2pptx 项目的代码结构和技术决策。
项目概述
yaml2pptx 是一个将 YAML 格式的演示文稿源文件转换为 PPTX 文件的工具，支持模板系统和浏览器预览功能。
代码结构
项目采用模块化架构，按功能职责组织代码：
html2pptx/
├── yaml2pptx.py (200 行) # 入口脚本，CLI + main 函数
├── utils.py (74 行) # 工具函数（日志、颜色转换）
├── core/ # 核心领域模型
│ ├── elements.py (200 行) # 元素抽象层（dataclass + validate）
│ ├── template.py (191 行) # 模板系统
│ ├── condition_evaluator.py # 条件表达式评估器
│ └── presentation.py (91 行) # 演示文稿类
├── loaders/ # 数据加载层
│ └── yaml_loader.py (113 行) # YAML 加载和验证
├── validators/ # 验证层
│ ├── __init__.py # 导出主验证器
│ ├── result.py (70 行) # 验证结果数据结构
│ ├── validator.py (150 行) # 主验证器
│ ├── geometry.py (120 行) # 几何验证器
│ └── resource.py (110 行) # 资源验证器
├── renderers/ # 渲染层
│ ├── pptx_renderer.py (292 行) # PPTX 渲染器
│ └── html_renderer.py (172 行) # HTML 渲染器（预览）
└── preview/ # 预览功能
└── server.py (244 行) # Flask 服务器 + 文件监听
依赖关系
yaml2pptx.py (入口)
↓
├─→ utils (工具函数)
├─→ loaders.yaml_loader (YAML 加载)
├─→ validators.validator (验证器)
│ ↓
│ ├─→ validators.result (验证结果)
│ ├─→ validators.geometry (几何验证)
│ ├─→ validators.resource (资源验证)
│ └─→ core.elements (元素验证)
├─→ core.presentation (演示文稿)
│ ↓
│ ├─→ core.template (模板)
│ └─→ core.elements (元素)
├─→ renderers.pptx_renderer (PPTX 生成)
│ ↓
│ └─→ core.elements
└─→ preview.server (预览服务)
↓
└─→ renderers.html_renderer
↓
└─→ core.elements
依赖原则
- 单向依赖：入口 → 验证/渲染 → 核心 ← 加载
- 无循环依赖
- 核心层不依赖其他业务模块
- 验证层可以调用核心层的元素验证方法
模块概览
入口层 (yaml2pptx.py)
- 职责：CLI 参数解析、流程编排
- 包含：
/// script依赖声明parse_args()- 命令行参数解析main()- 主流程编排handle_convert()- 转换流程
- 不包含：业务逻辑、数据处理
工具层 (utils/)
- 职责：通用工具函数
- 包含：
- 日志函数：
log_info(),log_success(),log_error(),log_progress() - 颜色转换：
hex_to_rgb(),validate_color()
- 日志函数：
加载层 (loaders/)
- 职责：YAML 文件加载和验证
- 包含：
YAMLError- 自定义异常load_yaml_file()- 加载 YAML 文件validate_presentation_yaml()- 验证演示文稿结构
核心层 (core/)
elements.py
- 职责：定义元素数据类和工厂函数
- 包含：
FontConfig- 字体配置数据类TextElement,ImageElement,ShapeElement,TableElementcreate_element()- 元素工厂函数
template.py
- 职责：模板加载和变量解析
- 包含：
Template类- 变量解析：
resolve_value(),resolve_element() - 条件渲染：
evaluate_condition() - 模板渲染：
render()
condition_evaluator.py
- 职责：安全地评估条件表达式
- 包含：
ConditionEvaluator类- 使用 simpleeval 库进行安全评估
presentation.py
- 职责：演示文稿管理和幻灯片渲染
- 包含：
Presentation类- 内联模板存储和查找
- 幻灯片渲染：
render_slide()
验证层 (validators/)
- 职责：YAML 文件验证
- 包含：
ValidationIssue,ValidationResult- 验证结果结构GeometryValidator- 几何验证器ResourceValidator- 资源验证器Validator- 主验证器
渲染层 (renderers/)
pptx_renderer.py
- 职责：PPTX 文件生成
- 包含：
PptxGenerator类- 渲染方法：
_render_text(),_render_image(),_render_shape(),_render_table()
html_renderer.py
- 职责：HTML 预览渲染
- 包含：
HtmlRenderer类- 渲染方法：
render_text(),render_image(),render_shape(),render_table()
预览层 (preview/)
- 职责：浏览器预览和热重载
- 包含：
- Flask 应用：
create_flask_app() - 文件监听：
YAMLChangeHandler - 预览服务器：
start_preview_server()
- Flask 应用：
技术决策概要
1. 元素抽象层使用 dataclass
- 理由：简洁性、类型提示、创建时验证
- 实现：
@dataclass装饰器 +__post_init__验证
2. 创建时验证
- 理由：尽早失败、清晰错误位置
- 实现：在
__post_init__中进行验证
3. 验证职责分层
- 元素级验证：放在元素类本身
- 系统级验证：放在独立的验证器模块
4. 模板系统架构
- 内联模板：在源文件中定义，适合简单场景
- 外部模板库：独立文件，适合复用和共享