# 架构设计

本文档说明 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`, `TableElement`
  - `create_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()`

## 技术决策概要

### 1. 元素抽象层使用 dataclass

- **理由**：简洁性、类型提示、创建时验证
- **实现**：`@dataclass` 装饰器 + `__post_init__` 验证

### 2. 创建时验证

- **理由**：尽早失败、清晰错误位置
- **实现**：在 `__post_init__` 中进行验证

### 3. 验证职责分层

- **元素级验证**：放在元素类本身
- **系统级验证**：放在独立的验证器模块

### 4. 模板系统架构

- **内联模板**：在源文件中定义，适合简单场景
- **外部模板库**：独立文件，适合复用和共享

## 相关文档

- [模块详解](modules/) - 各模块详细说明
- [开发规范](development-guide.md) - 编码规范和约定
- [扩展指南](extending.md) - 添加新功能

[返回开发文档索引](../README.md)