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