refactor: 重构文档结构，采用渐进式信息披露模式
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
193
docs/development/architecture.md
Normal file
193
docs/development/architecture.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# 架构设计
|
||||
|
||||
本文档说明 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)
|
||||
Reference in New Issue
Block a user