# Modular Architecture

## Purpose

定义项目的模块化架构规格，确保代码按功能职责组织，模块大小适中，依赖关系清晰，易于维护和扩展。

## Requirements

### Requirement: 代码必须按功能模块组织

系统必须将代码按照功能职责拆分为独立的模块文件，每个模块文件的代码行数应控制在 150-300 行之间，确保代码易于阅读和维护。

#### Scenario: 单文件脚本拆分为多个模块

- **WHEN** 开发者查看项目结构
- **THEN** 系统应包含以下模块文件：
  - `yaml2pptx.py`（入口脚本，约 100 行）
  - `core/elements.py`（元素数据类）
  - `core/template.py`（模板系统）
  - `core/presentation.py`（演示文稿类）
  - `loaders/yaml_loader.py`（YAML 加载）
  - `renderers/pptx_renderer.py`（PPTX 渲染器）
  - `renderers/html_renderer.py`（HTML 渲染器）
  - `preview/server.py`（预览服务器）
  - `utils.py`（工具函数）

#### Scenario: 每个模块文件大小适中

- **WHEN** 开发者打开任意模块文件
- **THEN** 文件代码行数应在 150-300 行之间（入口脚本除外，约 100 行）

### Requirement: 模块必须按层次组织

系统必须采用四层架构组织代码：入口层（yaml2pptx.py）、核心层（core/）、加载层（loaders/）、渲染层（renderers/）、预览层（preview/），每层职责清晰。

#### Scenario: 核心层包含领域模型

- **WHEN** 开发者查看 core/ 目录
- **THEN** 应包含元素数据类（elements.py）、模板系统（template.py）、演示文稿类（presentation.py）

#### Scenario: 加载层负责数据输入

- **WHEN** 开发者查看 loaders/ 目录
- **THEN** 应包含 YAML 加载和验证逻辑（yaml_loader.py）

#### Scenario: 渲染层负责数据输出

- **WHEN** 开发者查看 renderers/ 目录
- **THEN** 应包含 PPTX 渲染器（pptx_renderer.py）和 HTML 渲染器（html_renderer.py）

#### Scenario: 预览层提供可选功能

- **WHEN** 开发者查看 preview/ 目录
- **THEN** 应包含 Flask 服务器和文件监听逻辑（server.py）

### Requirement: 模块间依赖关系必须清晰

系统必须保持清晰的依赖方向：入口层 → 渲染层 → 核心层 ← 加载层，避免循环依赖。

#### Scenario: 依赖方向单向流动

- **WHEN** 开发者分析模块导入关系
- **THEN** 依赖关系应为：
  - yaml2pptx.py 导入 renderers、loaders、core、preview
  - renderers 导入 core
  - loaders 导入 core
  - core 不导入其他业务模块（只导入标准库和第三方库）
  - preview 导入 renderers 和 core

#### Scenario: 不存在循环依赖

- **WHEN** 开发者运行脚本
- **THEN** 系统不应出现循环导入错误

### Requirement: 入口脚本必须保持单一职责

yaml2pptx.py 必须仅包含 CLI 参数解析和主流程编排，所有业务逻辑应委托给相应的模块。

#### Scenario: 入口脚本只负责 CLI 和流程编排

- **WHEN** 开发者查看 yaml2pptx.py
- **THEN** 文件应仅包含：
  - `/// script` 依赖声明
  - `parse_args()` 函数（CLI 参数解析）
  - `main()` 函数（流程编排）
  - 必要的导入语句

#### Scenario: 入口脚本代码行数精简

- **WHEN** 开发者统计 yaml2pptx.py 的代码行数
- **THEN** 应约为 100 行（不包括注释和空行）

### Requirement: 保持向后兼容的使用方式

系统必须保持 `uv run yaml2pptx.py` 的使用方式不变，用户无需修改现有的调用方式。

#### Scenario: CLI 使用方式不变

- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml output.pptx`
- **THEN** 系统应正常生成 PPTX 文件，行为与重构前一致

#### Scenario: CLI 参数保持兼容

- **WHEN** 用户使用 `--template-dir`、`--preview`、`--port` 等参数
- **THEN** 系统应正确解析并执行相应功能