# 代码规范

## Python后端规范

### 代码风格

遵循PEP 8规范，使用Black进行代码格式化：

```bash
# 安装格式化工具
pip install black isort

# 格式化代码
black .
isort .
```

### 导入顺序

1. 标准库
2. 第三方库
3. 本地应用/库

```python
# 1. 标准库
import os
from datetime import datetime

# 2. 第三方库
from fastapi import APIRouter, Depends
from sqlalchemy import select

# 3. 本地应用
from app.models import User
from app.schemas import UserCreate
```

### 命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 模块 | 小写下划线 | `user_service.py` |
| 类 | 大驼峰 | `UserService` |
| 函数 | 小写下划线 | `get_user_by_id` |
| 常量 | 全大写下划线 | `MAX_RETRY_COUNT` |
| 变量 | 小写下划线 | `user_name` |

### 类型注解

所有函数必须包含类型注解：

```python
from typing import Optional

def get_user_by_id(user_id: int) -> Optional[User]:
    """根据ID获取用户"""
    ...
```

### 异步函数

使用async/await进行异步编程：

```python
async def get_user(user_id: int) -> User:
    async with async_session() as session:
        result = await session.execute(
            select(User).where(User.id == user_id)
        )
        return result.scalar_one_or_none()
```

## TypeScript前端规范

### 代码风格

使用Prettier和ESLint：

```bash
npm run lint    # 检查代码
npm run format  # 格式化代码
```

### 组件规范

- 使用函数组件
- 使用TypeScript严格模式
- Props接口定义

```typescript
interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

export function Button({ label, onClick, variant = 'primary' }: ButtonProps) {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick}>
      {label}
    </button>
  );
}
```

### 目录结构

```
frontend/
├── app/              # Next.js App Router页面
├── components/       # React组件
│   ├── ui/         # 基础UI组件
│   └── features/    # 业务组件
├── lib/             # 工具函数
└── types/           # 类型定义
```

## 提交规范

遵循Conventional Commits：

```
feat: 添加新功能
fix: 修复bug
docs: 文档更新
style: 代码格式（不影响功能）
refactor: 重构
test: 测试相关
chore: 构建/工具
```

示例：
```
feat(auth): 添加邮箱验证功能
fix(dashboard): 修复图表数据加载问题
docs(api): 更新API文档
```