# 维护指南

本文档提供 yaml2pptx 项目的维护指南。

## 代码审查要点

在审查代码时，检查以下要点：

### 结构和设计

- [ ] 模块文件大小合理（150-300 行）
- [ ] 无循环依赖
- [ ] 单一职责原则
- [ ] 清晰的接口和抽象

### 代码质量

- [ ] 所有类和函数有文档字符串
- [ ] 使用中文注释
- [ ] 元素验证在 `__post_init__` 中完成
- [ ] 导入语句按标准库、第三方库、本地模块排序

### 测试

- [ ] 有相应的测试用例
- [ ] 测试覆盖率足够
- [ ] 测试文件在 `tests/` 目录下

### 约束检查

- [ ] 使用 `uv run` 运行脚本
- [ ] 测试文件在 `temp/` 目录
- [ ] 面向中文开发者
- [ ] 不污染主机环境

## 性能优化建议

### 1. 模板缓存

Presentation 类已实现模板缓存，避免重复加载：

```python
def get_template(self, template_name):
    if template_name not in self.template_cache:
        self.template_cache[template_name] = self._load_template(template_name)
    return self.template_cache[template_name]
```

### 2. 元素验证

只在创建时验证一次，渲染时不再验证：

```python
# 创建时验证
elem = TextElement(**elem_dict)  # __post_init__ 验证

# 渲染时直接使用，不重复验证
self._render_text(slide, elem)
```

### 3. 文件监听

预览模式使用 watchdog 高效监听文件变化：

```python
class YAMLChangeHandler(FileSystemEventHandler):
    def on_modified(self, event):
        if event.src_path.endswith('.yaml'):
            # 重新加载和渲染
```

## 代码质量工具

### 格式化

使用 Black 格式化 Python 代码：

```bash
uv run black .
```

### Linting

使用 Pylint 检查代码质量：

```bash
uv run pylint core/ loaders/ renderers/ validators/
```

### 类型检查

使用 mypy 进行类型检查：

```bash
uv run mypy core/
```

## 常见维护任务

### 添加新的依赖

1. 在 `pyproject.toml` 中添加依赖
2. 更新 `README.md` 的依赖项列表
3. 运行测试确保兼容性

```toml
[project]
dependencies = [
    "python-pptx>=0.6.21",
    "pyyaml>=6.0",
    "flask>=3.0",
    "watchdog>=3.0",
    "new-dependency>=1.0",
]
```

### 更新文档

功能变更后，同步更新以下文档：

- `README.md` - 用户文档
- `README_DEV.md` - 开发文档
- 相关的 `docs/` 子文档

### 版本发布

1. 更新版本号（在 pyproject.toml 中）
2. 更新 CHANGELOG
3. 创建 git tag
4. 发布到 PyPI（如果需要）

## 调试技巧

### 使用预览模式

```bash
uv run yaml2pptx.py preview temp/test.yaml
```

### 查看详细错误

```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

### 使用 Python 调试器

```bash
uv run python -m pdb yaml2pptx.py convert test.yaml
```

## 问题排查

### 常见问题

1. **导入错误**：检查是否使用 `uv run`
2. **依赖缺失**：运行 `uv pip install -e .[dev]`
3. **测试失败**：检查 `temp/` 目录权限

### 获取帮助

- 查看项目 Issues
- 查看 `README.md` 和 `README_DEV.md`
- 联系维护者

## 相关文档

- [开发规范](development-guide.md) - 编码规范
- [测试规范](testing.md) - 测试指南

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