# 开发规范

本文档说明 yaml2pptx 项目的开发规范和约定。

## Python 环境

### 必须使用 uv 运行脚本

```bash
# 正确
uv run yaml2pptx.py input.yaml output.pptx

# 错误 - 严禁直接使用主机环境的 python
python yaml2pptx.py input.yaml output.pptx
```

### 依赖管理

- 所有依赖在 `pyproject.toml` 的 `[project.dependencies]` 中声明
- uv 会自动安装依赖，无需手动 `pip install`

## 命令行接口

### 子命令架构

```bash
# check - 验证 YAML 文件
uv run yaml2pptx.py check <input> [--template <path>]

# convert - 转换为 PPTX
uv run yaml2pptx.py convert <input> [output] [--template <path>] [--skip-validation] [--force]

# preview - 启动预览服务器
uv run yaml2pptx.py preview <input> [--template <path>] [--port <port>] [--host <host>] [--no-browser]
```

### 参数说明

- `--template`：指定模板库文件路径
- `--skip-validation`：convert 专用，跳过自动验证
- `--force/-f`：convert 专用，强制覆盖已存在文件
- `--port`：preview 专用，指定端口
- `--host`：preview 专用，指定主机地址
- `--no-browser`：preview 专用，不自动打开浏览器

## 文件组织

### 代码文件

- 每个模块文件控制在 150-300 行
- 入口脚本约 200 行
- 使用有意义的文件名和目录结构

### 测试文件

- 所有测试文件、临时文件必须放在 `temp/` 目录下
- 不污染项目根目录

## 代码风格

### 导入顺序

```python
# 1. 标准库
import sys
from pathlib import Path

# 2. 第三方库
import yaml
from pptx import Presentation

# 3. 本地模块
from utils import log_info
from core.elements import TextElement
```

### 文档字符串

- 每个模块必须有模块级文档字符串
- 每个类和函数必须有文档字符串
- 使用中文编写注释和文档

### 命名规范

- **模块名**：小写 + 下划线（如 `yaml_loader.py`）
- **类名**：大驼峰（如 `TextElement`）
- **函数名**：小写 + 下划线（如 `load_yaml_file()`）
- **常量**：大写 + 下划线（如 `HTML_TEMPLATE`）

## 项目约束

1. **面向中文开发者**：注释、文档、错误消息使用中文
2. **使用 uv 运行**：严禁直接使用主机环境的 python
3. **测试文件隔离**：所有测试文件放在 `temp/` 目录
4. **不污染主机环境**：不修改主机的 Python 配置

## 验证容忍度

几何验证时，允许 0.1 英寸的容忍度：

```python
TOLERANCE = 0.1  # 英寸

if right > slide_width + TOLERANCE:
    # 报告 WARNING
```

## 最佳实践

### 模块职责

- 每个模块职责明确，单一功能
- 模块间通过清晰接口通信
- 避免循环依赖

### 错误处理

- 使用自定义异常类（如 `YAMLError`）
- 提供清晰的错误信息
- 包含错误位置（文件、行号、元素）

### 日志

- 使用统一的日志函数（`log_info()`, `log_success()`, `log_error()`）
- 显示友好的中文错误信息

## 相关文档

- [架构设计](architecture.md) - 代码结构
- [扩展指南](extending.md) - 添加新功能

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