# FastAPI 后端项目

PBMDB (Plant Beneficial Microbe Database) 农业有益微生物综合信息数据库后端 API 服务。

## 📁 项目结构

```
backend/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI 应用入口
│   ├── api/
│   │   ├── __init__.py
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── router.py    # API 路由汇总
│   │       └── endpoints/
│   │           ├── __init__.py
│   │           ├── strains.py      # 菌种资源 API
│   │           ├── genomes.py      # 基因组学数据 API
│   │           ├── genes.py        # 基因资源 API
│   │           ├── upload.py       # 数据汇交上传 API
│   │           └── analysis.py     # 智能分析 API
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py        # 应用配置
│   │   └── security.py      # 认证安全
│   ├── models/              # SQLAlchemy 数据模型
│   │   └── __init__.py
│   ├── schemas/             # Pydantic 数据模式
│   │   └── __init__.py
│   └── services/            # 业务逻辑层
│       └── __init__.py
├── requirements.txt         # Python 依赖
├── Dockerfile              # Docker 构建文件
├── .env.example           # 环境变量示例
└── README.md              # 本文件
```

## 🚀 技术栈

- **FastAPI**: 现代、高性能 Python Web 框架
- **Uvicorn**: ASGI 服务器
- **SQLAlchemy**: ORM 数据库工具
- **PostgreSQL**: 关系型数据库
- **Pydantic**: 数据验证和设置管理

## 🎯 核心功能模块

### 1. 菌种资源 (`/api/v1/strains`)
- 菌种列表查询（分类、搜索、分页）
- 菌种详情展示
- 菌种分类树

### 2. 基因组学数据 (`/api/v1/genomes`)
- 基因组数据列表（基因组学/转录组学/其他组学）
- 基因组详情
- 物种分类树

### 3. 基因资源 (`/api/v1/genes`)
- 基因列表查询（功能分类）
- 基因详情
- 功能基因分类

### 4. 数据汇交 (`/api/v1/upload`)
- 基因组数据上传
- 宏基因组数据上传
- 原始测序数据上传
- 上传口令验证
- 上传状态查询

### 5. 智能分析 (`/api/v1/analysis`)
- 智能问答（基于知识图谱）
- 基因挖掘（序列比对）
- 菌株评估
- 知识图谱查询
- 分析任务状态查询

## ⚙️ 环境配置

### 1. 创建环境变量文件

```bash
cd /vol1/1000/docker_server/traefik/web/ws/backend
cp .env.example .env
```

编辑 `.env` 文件：

```bash
# 项目信息
PROJECT_NAME=PBMDB API
VERSION=1.0.0

# 数据库配置
DATABASE_URL=postgresql://webws_admin:your_password@postgres:5432/webws_database

# 安全配置
SECRET_KEY=your-secret-key-here-change-in-production

# CORS 配置
ALLOWED_ORIGINS=https://amiap.hzau.edu.cn,http://localhost:3000

# 文件上传配置
MAX_UPLOAD_SIZE=104857600
UPLOAD_DIR=/app/uploads
```

## 🏃 本地开发

### 使用虚拟环境

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

# 创建虚拟环境
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
- ReDoc 文档: http://localhost:8000/redoc
- 健康检查: http://localhost:8000/health

## 🐳 Docker 部署

### 1. 更新 docker-compose.yml

在 `/vol1/1000/docker_server/traefik/web/ws/docker-compose.yml` 中添加后端服务：

```yaml
services:
  # ... 现有服务 ...
  
  backend:
    build: ./backend
    container_name: webws-backend
    restart: unless-stopped
    environment:
      - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
    volumes:
      - ./backend/uploads:/app/uploads
    networks:
      - frontend
    depends_on:
      - postgres
    labels:
      - "traefik.enable=true"
      
      # HTTP 路由 - 重定向到 HTTPS
      - "traefik.http.routers.webws-api-http.rule=Host(`amiap.hzau.edu.cn`) && PathPrefix(`/ABM/api`)"
      - "traefik.http.routers.webws-api-http.entrypoints=web"
      - "traefik.http.routers.webws-api-http.priority=100"
      - "traefik.http.routers.webws-api-http.middlewares=redirect-to-https"
      
      # HTTPS 路由
      - "traefik.http.routers.webws-api-https.rule=Host(`amiap.hzau.edu.cn`) && PathPrefix(`/ABM/api`)"
      - "traefik.http.routers.webws-api-https.entrypoints=websecure"
      - "traefik.http.routers.webws-api-https.priority=100"
      - "traefik.http.routers.webws-api-https.tls.certresolver=myresolver"
      
      # StripPrefix 中间件（移除 /ABM/api 前缀）
      - "traefik.http.routers.webws-api-https.middlewares=api-stripprefix"
      - "traefik.http.middlewares.api-stripprefix.stripprefix.prefixes=/ABM/api"
      
      - "traefik.http.services.webws-api.loadbalancer.server.port=8000"
```

### 2. 构建并启动

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

# 构建镜像
docker compose build backend

# 启动服务
docker compose up -d backend

# 查看日志
docker compose logs -f backend
```

## 📡 API 访问地址

部署后，API 通过以下地址访问：

- **外部访问**: https://amiap.hzau.edu.cn/ABM/api/
- **API 文档**: https://amiap.hzau.edu.cn/ABM/api/docs
- **容器间访问**: http://webws-backend:8000/

## 🔧 路由说明

### URL 路径处理

由于使用了 Traefik `StripPrefix` 中间件，路径会自动处理：

**用户访问**: `https://amiap.hzau.edu.cn/ABM/api/strains/`
**FastAPI 接收**: `/api/v1/strains/` (已移除 `/ABM/api`)

### 路由优先级

```
Priority 100: /ABM/api/** → 后端 API 服务
Priority 47:  /ABM/**     → Nginx 静态文件服务
```

不会产生冲突，Traefik 优先匹配更高优先级和更具体的路径。

## 📊 数据库迁移

### 使用 Alembic

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

# 初始化迁移（首次）
alembic init alembic

# 创建迁移
alembic revision --autogenerate -m "Initial migration"

# 执行迁移
alembic upgrade head
```

## 🧪 测试 API

### 使用 curl

```bash
# 健康检查
curl https://amiap.hzau.edu.cn/ABM/api/health

# 获取菌种列表
curl https://amiap.hzau.edu.cn/ABM/api/api/v1/strains/

# 获取基因组数据
curl https://amiap.hzau.edu.cn/ABM/api/api/v1/genomes/
```

### 使用 Swagger UI

访问 https://amiap.hzau.edu.cn/ABM/api/docs 进行交互式测试。

## 📝 开发指南

### 添加新的 API 端点

1. 在 `app/api/v1/endpoints/` 下创建新文件
2. 定义路由和处理函数
3. 在 `app/api/v1/router.py` 中注册路由

### 添加数据模型

1. 在 `app/models/` 下创建 SQLAlchemy 模型
2. 在 `app/schemas/` 下创建 Pydantic 模式
3. 运行数据库迁移

### 添加业务逻辑

在 `app/services/` 下创建服务层代码，保持控制器简洁。

## 🔒 安全注意事项

1. **生产环境**必须修改 `SECRET_KEY`
2. 使用环境变量管理敏感信息
3. 启用 HTTPS（已配置）
4. 实现完整的认证系统（待实现）
5. 添加请求频率限制

## 🚀 性能优化

1. 使用数据库连接池
2. 启用查询缓存（Redis）
3. 异步文件处理
4. 压缩响应数据
5. CDN 加速静态资源

## 📚 相关文档

- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
- [Pydantic 文档](https://docs.pydantic.dev/)
- [SQLAlchemy 文档](https://docs.sqlalchemy.org/)
- [Uvicorn 文档](https://www.uvicorn.org/)

## 📞 联系方式

如有问题，请联系项目维护团队。