# 开发指南

## 快速开始

### 本地开发

```bash
# 1. 进入后端目录
cd /vol1/1000/docker_server/traefik/web/ws/backend

# 2. 使用启动脚本（自动创建虚拟环境、安装依赖）
./start.sh

# 或者手动启动
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

访问：
- API 文档: http://localhost:8000/docs
- 健康检查: http://localhost:8000/health

### Docker 开发

```bash
cd /vol1/1000/docker_server/traefik/web/ws

# 构建镜像
docker compose build backend

# 启动服务
docker compose up -d backend

# 查看日志
docker compose logs -f backend

# 进入容器
docker compose exec backend bash
```

## 开发流程

### 1. 添加新的 API 端点

**示例：添加实验数据 API**

```bash
# 1. 创建端点文件
touch app/api/v1/endpoints/experiments.py
```

```python
# app/api/v1/endpoints/experiments.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/")
async def get_experiments():
    """获取实验列表"""
    return {"experiments": []}

@router.get("/{experiment_id}")
async def get_experiment(experiment_id: str):
    """获取实验详情"""
    return {"id": experiment_id}
```

```python
# 2. 在 app/api/v1/router.py 中注册
from app.api.v1.endpoints import experiments

api_router.include_router(
    experiments.router, 
    prefix="/experiments", 
    tags=["experiments"]
)
```

### 2. 添加数据模型

```bash
# 创建模型文件
touch app/models/experiment.py
```

```python
# app/models/experiment.py
from sqlalchemy import Column, String, Integer, DateTime
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class Experiment(Base):
    __tablename__ = "experiments"
    
    id = Column(Integer, primary_key=True)
    name = Column(String(200))
    description = Column(String(1000))
    created_at = Column(DateTime)
```

### 3. 添加 Pydantic 模式

```bash
# 创建模式文件
touch app/schemas/experiment.py
```

```python
# app/schemas/experiment.py
from pydantic import BaseModel
from datetime import datetime
from typing import Optional

class ExperimentBase(BaseModel):
    name: str
    description: Optional[str] = None

class ExperimentCreate(ExperimentBase):
    pass

class ExperimentResponse(ExperimentBase):
    id: int
    created_at: datetime
    
    class Config:
        from_attributes = True
```

### 4. 添加业务逻辑

```bash
# 创建服务文件
touch app/services/experiment_service.py
```

```python
# app/services/experiment_service.py
from sqlalchemy.orm import Session
from app.models.experiment import Experiment
from app.schemas.experiment import ExperimentCreate

async def create_experiment(db: Session, data: ExperimentCreate):
    """创建实验"""
    experiment = Experiment(**data.dict())
    db.add(experiment)
    db.commit()
    db.refresh(experiment)
    return experiment
```

## 代码规范

### Python 风格

- 遵循 PEP 8 规范
- 使用类型提示
- 函数添加文档字符串

```python
async def get_strain_detail(strain_id: str) -> dict:
    """
    获取菌种详情
    
    Args:
        strain_id: 菌种 ID
        
    Returns:
        dict: 菌种详细信息
        
    Raises:
        HTTPException: 菌种不存在时
    """
    pass
```

### 命名规范

- 文件名：`snake_case.py`
- 类名：`PascalCase`
- 函数名：`snake_case`
- 常量：`UPPER_CASE`

### 目录组织

```
app/
├── api/v1/endpoints/    # 按功能模块组织
│   ├── strains.py       # 菌种相关
│   ├── genes.py         # 基因相关
│   └── upload.py        # 上传相关
├── models/              # 数据库模型
├── schemas/             # 数据验证模式
└── services/            # 业务逻辑
```

## 测试

### 单元测试

```bash
# 安装测试依赖
pip install pytest pytest-asyncio httpx

# 运行测试
pytest
```

### API 测试

```bash
# 使用测试脚本
./test_api.sh

# 或使用 curl
curl http://localhost:8000/health
```

## 数据库迁移

```bash
# 安装 alembic
pip install alembic

# 初始化
alembic init alembic

# 创建迁移
alembic revision --autogenerate -m "Add experiments table"

# 执行迁移
alembic upgrade head

# 回滚
alembic downgrade -1
```

## 调试技巧

### 1. 日志输出

```python
import logging

logger = logging.getLogger(__name__)

@router.get("/debug")
async def debug_endpoint():
    logger.info("Debug endpoint called")
    logger.debug(f"Data: {data}")
    return {"status": "ok"}
```

### 2. 断点调试

```python
# 使用 pdb
import pdb; pdb.set_trace()

# 或使用 breakpoint()
breakpoint()
```

### 3. 查看 SQL 查询

```python
# 在配置中启用 SQL 日志
DATABASE_URL = "postgresql://...?echo=true"
```

## 常见问题

### Q: 导入错误？

确保在项目根目录运行，并使用正确的 Python 路径：

```bash
export PYTHONPATH=/vol1/1000/docker_server/traefik/web/ws/backend:$PYTHONPATH
```

### Q: 数据库连接失败？

检查 `.env` 文件中的 `DATABASE_URL` 配置。

### Q: CORS 错误？

在 `app/core/config.py` 中添加允许的源。

## 部署检查清单

- [ ] 修改生产环境 `SECRET_KEY`
- [ ] 配置正确的 `DATABASE_URL`
- [ ] 更新 `ALLOWED_ORIGINS`
- [ ] 运行数据库迁移
- [ ] 测试所有 API 端点
- [ ] 配置日志记录
- [ ] 设置监控和告警
- [ ] 备份数据库

## 贡献流程

1. 创建功能分支
2. 开发并测试
3. 提交代码（commit message 规范）
4. 提交 Pull Request
5. Code Review
6. 合并到主分支

## 联系方式

如有问题，请联系开发团队。