hotwa
4c9a7d0978
- 新增 README_CN.md 中文文档 - 新增 frontend/ Vue 3 前端项目 - 新增 web/ FastAPI 后端项目 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
156 lines
3.7 KiB
Markdown
156 lines
3.7 KiB
Markdown
# Web Backend Agent Guide
|
|
|
|
## Overview
|
|
|
|
FastAPI backend for BtToxin Pipeline - provides REST API for task submission, status monitoring, and result retrieval.
|
|
|
|
## Tech Stack
|
|
|
|
- **Framework**: FastAPI
|
|
- **Validation**: Pydantic + pydantic-settings
|
|
- **Storage**: Redis (cache) + File system (persistence)
|
|
- **Testing**: pytest
|
|
- **ASGI Server**: Uvicorn
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
web/backend/
|
|
├── __init__.py # Package marker
|
|
├── main.py # FastAPI application entry point
|
|
├── config.py # Configuration and system constraints
|
|
├── models.py # Data models (TaskStatus, TaskMeta, etc.)
|
|
└── storage.py # Redis + file hybrid storage
|
|
```
|
|
|
|
## Development Commands
|
|
|
|
### Via pixi (recommended)
|
|
|
|
```bash
|
|
# Start development server with hot reload
|
|
pixi run api-dev
|
|
|
|
# Run tests
|
|
pixi run api-test
|
|
```
|
|
|
|
### Direct commands
|
|
|
|
```bash
|
|
# Start server
|
|
uvicorn web.backend.main:app --reload --host 0.0.0.0 --port 8000
|
|
|
|
# Run tests
|
|
pytest web/backend/ -v
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Health Check
|
|
|
|
```
|
|
GET /api/health
|
|
Response: {"status": "healthy"}
|
|
```
|
|
|
|
### API Documentation
|
|
|
|
When `DEBUG=true`:
|
|
- Swagger UI: http://localhost:8000/api/docs
|
|
- ReDoc: http://localhost:8000/api/redoc
|
|
|
|
## Data Models
|
|
|
|
### TaskStatus (Enum)
|
|
|
|
```python
|
|
PENDING = "pending" # Waiting to be processed
|
|
QUEUED = "queued" # In queue, waiting for slot
|
|
RUNNING = "running" # Currently executing
|
|
COMPLETED = "completed" # Successfully finished
|
|
FAILED = "failed" # Execution failed
|
|
```
|
|
|
|
### PipelineStage (Enum)
|
|
|
|
```python
|
|
DIGGER = "digger" # Running BtToxin_Digger
|
|
SHOTER = "shoter" # Running Shoter scoring
|
|
PLOTS = "plots" # Generating heatmap plots
|
|
BUNDLE = "bundle" # Bundling results
|
|
```
|
|
|
|
### TaskMeta (Dataclass)
|
|
|
|
Task metadata stored in Redis and `task_meta.json`:
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| task_id | str | Unique task identifier |
|
|
| status | TaskStatus | Current execution status |
|
|
| current_stage | PipelineStage | Current pipeline stage |
|
|
| progress | int | Progress percentage (0-100) |
|
|
| submission_time | str | ISO8601 timestamp |
|
|
| start_time | str | ISO8601 timestamp |
|
|
| completion_time | str | ISO8601 timestamp |
|
|
| filename | str | Original uploaded filename |
|
|
| file_size | int | File size in bytes |
|
|
| lang | str | Report language (en/zh) |
|
|
| error_message | str | Error description if failed |
|
|
| token_hash | str | SHA256 hash for auth |
|
|
|
|
## Storage Strategy
|
|
|
|
Hybrid Redis + file storage:
|
|
|
|
- **Primary**: `/data/jobs/<task_id>/task_meta.json` (persistent)
|
|
- **Cache**: Redis `task:{task_id}:meta` (fast access)
|
|
- **Write order**: File first, then Redis
|
|
- **Read order**: Redis first, file on cache miss
|
|
|
|
## Configuration
|
|
|
|
Environment variables (see `config.py`):
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| REDIS_URL | redis://localhost:6379/0 | Redis connection |
|
|
| JOBS_DIR | /data/jobs | Task storage directory |
|
|
| TASK_TIMEOUT | 21600 | Task timeout (6 hours) |
|
|
| MAX_ACTIVE_PIPELINES | 4 | Max concurrent tasks |
|
|
| TASK_THREADS | 4 | Threads per task |
|
|
| CORS_ORIGINS | * | Allowed CORS origins |
|
|
| DEBUG | false | Enable debug mode |
|
|
|
|
## System Constraints
|
|
|
|
Defined in `SystemConstraints` class:
|
|
|
|
- Max upload size: 50 MB
|
|
- Min free disk: 20 GB
|
|
- Task timeout: 6 hours
|
|
- Result retention: 30 days
|
|
- Allowed extensions: .fna, .fa, .fasta
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all backend tests
|
|
pixi run api-test
|
|
|
|
# Run with verbose output
|
|
pytest web/backend/ -v
|
|
|
|
# Run specific test file
|
|
pytest web/backend/test_storage.py -v
|
|
```
|
|
|
|
## CORS Configuration
|
|
|
|
CORS is configured to allow frontend access. Set `CORS_ORIGINS` environment variable for production:
|
|
|
|
```bash
|
|
CORS_ORIGINS=https://example.com,https://app.example.com
|
|
```
|