# 开发规范快速检查清单

> 参考完整文档: `@/Python项目开发准则.md`

## 📋 代码生成前检查

### 1. 编码规范 (Ch3, Ch11)
- [ ] PEP 8 格式正确（使用 black）
- [ ] 所有函数/类都有 **完整的类型注解**
- [ ] 所有公开 API 都有 **Google 风格 docstring**
- [ ] 函数参数有类型、返回值有类型
- [ ] 命名规范正确：`snake_case` 函数、`PascalCase` 类、`UPPER_CASE` 常量

### 2. 异常处理 (Ch4)
- [ ] 捕获 **具体异常**（禁止裸 `except:` 或 `except Exception:`）
- [ ] 异常都有明确的错误信息
- [ ] 自定义异常继承自基异常类
- [ ] 关键操作都有 try-except

### 3. 数据验证 (Ch11 - Pydantic)
- [ ] 所有外部输入都用 **Pydantic BaseModel** 验证
- [ ] 使用 `Field()` 定义约束（min_length, pattern 等）
- [ ] 实现 `@field_validator` 自定义验证
- [ ] 验证失败返回结构化错误响应

### 4. 异步编程 (Ch10)
- [ ] I/O 密集任务使用 asyncio（网络、文件）
- [ ] 异步函数都有 `async def` 和完整类型注解
- [ ] 并发操作使用 `asyncio.gather()` + `Semaphore` 限流
- [ ] 所有异步操作都有超时设置
- [ ] 异步测试使用 `@pytest.mark.asyncio`

### 5. 日志记录 (Ch15)
- [ ] 关键操作都有日志（INFO 级别）
- [ ] 错误都有日志记录 + `exc_info=True`
- [ ] **禁止在日志中记录敏感信息**（密码、密钥）
- [ ] 使用正确的日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL）

### 6. 测试覆盖 (Ch5)
- [ ] 单元测试覆盖率 **≥80%**
- [ ] 每个功能点至少 1 个测试用例
- [ ] 测试文件在 `tests/` 与 `src/` 结构对应
- [ ] 使用 pytest fixtures 和 parametrize
- [ ] 禁止空测试（pass 或 TODO）

### 7. 安全检查 (Ch12)
- [ ] **禁止硬编码** 密码、API 密钥、敏感信息
- [ ] 敏感配置都从 `.env` 读取（用 `os.getenv()`）
- [ ] 所有文件操作都有异常处理
- [ ] 禁止 `eval()`、`exec()`
- [ ] 没有 SQL 注入风险（用参数化查询）

### 8. 代码质量 (Ch16)
- [ ] 函数不超过 40 行
- [ ] 类的职责 **单一**（SRP）
- [ ] 没有硬编码的魔法数字，用常量
- [ ] 没有重复代码（DRY 原则）
- [ ] 复杂度 ≤10（使用 radon cc 检查）

### 9. 架构一致 (Ch7)
- [ ] 遵循分层架构（domain → services → adapters → infra）
- [ ] 上层不依赖下层具体实现
- [ ] 使用接口或抽象类隔离
- [ ] 业务逻辑不直接读写文件/网络/数据库

### 10. API 设计 (Ch14)
- [ ] 使用标准 REST 端点命名（GET/POST/PUT/PATCH/DELETE）
- [ ] 错误响应格式统一（code/message/details）
- [ ] HTTP 状态码正确（200/201/204/400/401/422/500）
- [ ] API 版本化（/api/v1/...）
- [ ] 自动生成 OpenAPI 文档

---

## 🔧 运行质量检查

```bash
# 1. 代码格式
uv run black src/ tests/ --check

# 2. 代码检查 + 自动修复
uv run ruff check src/ tests/ --fix

# 3. 类型检查
uv run mypy src/

# 4. 单元测试 + 覆盖率
uv run pytest tests/ --cov=src/autoreport --cov-fail-under=80

# 5. 安全扫描（可选）
uv run bandit -r src/ -f screen
uv run pip-audit

# 一键运行所有检查
uv run python scripts/check.py
```

---

## 📌 常见错误对照表

### ❌ 常见违规 → ✅ 改正方式

| 违规 | 改正 |
|------|------|
| `except:` | `except ValueError as e:` |
| `def fn(x):` | `def fn(x: int) -> str:` |
| 缺 docstring | 添加 Google 风格 docstring |
| 硬编码密码 | `password = os.getenv("DB_PASSWORD")` |
| 全局变量 | 用参数或类属性 |
| 直接修改入参 | `return [x+1 for x in items]` |
| 无验证输入 | 使用 Pydantic BaseModel |
| 日志中有密码 | 掩码：`f"{email[:2]}***@{domain}"` |

---

## 🚀 快速命令

### 生成新模块
```bash
# 模块结构
src/autoreport/new_module/
├── __init__.py      # 导出公开 API
├── models.py        # 数据模型（Pydantic）
├── service.py       # 业务逻辑
└── utils.py         # 工具函数

# 对应测试
tests/unit/test_new_module/
├── test_models.py
├── test_service.py
└── test_utils.py
```

### 添加新依赖
```bash
# 生产依赖
uv pip install <package>
uv pip freeze > requirements.txt

# 开发依赖
uv pip install --dev <package>
uv pip freeze > requirements-dev.txt
```

---

## 📚 完整文档章节参考

| 章节 | 内容 | 何时查看 |
|-----|------|---------|
| Ch11 | Pydantic 验证 | 处理用户输入时 |
| Ch10 | 异步编程 | 网络/文件操作时 |
| Ch14 | API 设计 | 编写 API 端点时 |
| Ch15 | 日志规范 | 添加日志时 |
| Ch20 | 避坑指南 | 不确定最佳实践时 |

---

## 💡 AI 提示词模板

### 快速开发
```
请遵守《Python项目开发准则》：
- 完整类型注解 + docstring
- 异常处理规范、关键操作有日志
- 可运行的代码，包含单元测试（≥80% 覆盖率）
```

### 新功能开发
```
请严格遵守《Python项目开发准则》完成以下任务：
## 开发规范
- 所有代码必须符合 PEP 8 和项目编码规范
- 完整的类型注解、Google 风格 docstring
- 异常处理捕获具体异常，关键操作有日志

## 数据验证
- 使用 Pydantic v2 进行输入验证（参见第11章）

## 测试和质量
- 编写单元测试，覆盖率 ≥ 80%
- 运行 black、ruff、mypy 检查
```

### 代码审查
```
请按照《Python项目开发准则》审查以下代码：
1. 检查是否符合 PEP 8 和命名规范
2. 验证类型注解和 docstring 的完整性
3. 评估异常处理和日志的适当性
4. 指出改进建议（附上修复示例）
```
