lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
173 lines
3.2 KiB
Markdown
173 lines
3.2 KiB
Markdown
# 维护指南
|
||
|
||
本文档提供 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)
|