PPTX/docs/development/maintenance.md

维护指南

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

代码审查要点

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

结构和设计

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

代码质量

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

测试

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

约束检查

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

性能优化建议

1. 模板缓存

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

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. 元素验证

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

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

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

3. 文件监听

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

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

代码质量工具

格式化

使用 Black 格式化 Python 代码：

uv run black .

Linting

使用 Pylint 检查代码质量：

uv run pylint core/ loaders/ renderers/ validators/

类型检查

使用 mypy 进行类型检查：

uv run mypy core/

常见维护任务

添加新的依赖

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

[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（如果需要）

调试技巧

使用预览模式

uv run yaml2pptx.py preview temp/test.yaml

查看详细错误

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

使用 Python 调试器

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
• 联系维护者

相关文档

• 开发规范 - 编码规范
• 测试规范 - 测试指南

返回开发文档索引