Files

hotwa 4c9a7d0978 docs: 添加中文文档，新增前端和后端代码

- 新增 README_CN.md 中文文档
- 新增 frontend/ Vue 3 前端项目
- 新增 web/ FastAPI 后端项目

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2026-01-08 22:31:06 +08:00

3.7 KiB

Raw Blame History

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)

# Start development server with hot reload
pixi run api-dev

# Run tests
pixi run api-test

Direct commands

# 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)

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)

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

# 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:

CORS_ORIGINS=https://example.com,https://app.example.com

3.7 KiB Raw Blame History