182 lines
4.6 KiB
Markdown
182 lines
4.6 KiB
Markdown
# Brief Bench FastAPI
|
||
|
||
FastAPI backend для системы тестирования RAG с multi-user поддержкой.
|
||
|
||
## Возможности
|
||
|
||
- 🔐 JWT авторизация (8-значный логин)
|
||
- 🌐 Multi-environment: ИФТ, ПСИ, ПРОМ
|
||
- 📊 Bench mode: batch тестирование
|
||
- 🤖 Backend mode: имитация бота (вопросы по одному)
|
||
- 💾 Сохранение сессий анализа
|
||
- 🔒 mTLS для RAG backend
|
||
- 📝 Аннотации и экспорт
|
||
|
||
## Требования
|
||
|
||
- Python 3.11+
|
||
- Docker & Docker Compose (для деплоя)
|
||
- Доступ к DB API сервису
|
||
- mTLS сертификаты для RAG backend (опционально)
|
||
|
||
## Быстрый старт
|
||
|
||
### 1. Клонировать репозиторий
|
||
|
||
```bash
|
||
cd /path/to/brief-bench-fastapi
|
||
```
|
||
|
||
### 2. Настроить окружение
|
||
|
||
Скопируйте `.env.example` в `.env` и заполните:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
nano .env
|
||
```
|
||
|
||
**Обязательные переменные:**
|
||
- `JWT_SECRET_KEY` - секретный ключ для JWT (сгенерируйте новый!)
|
||
- `DB_API_URL` - URL DB API сервиса
|
||
- `IFT_RAG_HOST`, `PSI_RAG_HOST`, `PROD_RAG_HOST` - хосты RAG backend
|
||
|
||
### 3. Разместить сертификаты (если используется mTLS)
|
||
|
||
```
|
||
certs/
|
||
ift/
|
||
ca.crt
|
||
client.key
|
||
client.crt
|
||
psi/
|
||
...
|
||
prod/
|
||
...
|
||
```
|
||
|
||
### 4. Запустить с Docker Compose
|
||
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
Приложение доступно на `http://localhost:8000`
|
||
|
||
### 5. Проверить здоровье
|
||
|
||
```bash
|
||
curl http://localhost:8000/health
|
||
```
|
||
|
||
## Разработка
|
||
|
||
### Локальный запуск (без Docker)
|
||
|
||
```bash
|
||
# Создать виртуальное окружение
|
||
python -m venv venv
|
||
source venv/bin/activate # Linux/Mac
|
||
# или
|
||
venv\Scripts\activate # Windows
|
||
|
||
# Установить зависимости
|
||
pip install -r requirements.txt
|
||
|
||
# Запустить
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
### Структура проекта
|
||
|
||
```
|
||
brief-bench-fastapi/
|
||
├── app/
|
||
│ ├── api/v1/ # API endpoints
|
||
│ ├── models/ # Pydantic models
|
||
│ ├── services/ # Business logic
|
||
│ ├── interfaces/ # API clients (DB, RAG)
|
||
│ ├── middleware/ # Middleware
|
||
│ ├── utils/ # Utilities (JWT, etc.)
|
||
│ ├── config.py # Configuration
|
||
│ ├── dependencies.py # DI
|
||
│ └── main.py # FastAPI app
|
||
├── static/ # Frontend files
|
||
├── tests/ # Tests
|
||
├── certs/ # mTLS certificates
|
||
├── .env # Environment variables
|
||
├── requirements.txt # Python dependencies
|
||
├── Dockerfile # Docker image
|
||
├── docker-compose.yml # Docker Compose
|
||
└── DB_API_CONTRACT.md # DB API contract
|
||
```
|
||
|
||
## API Endpoints
|
||
|
||
### Authentication
|
||
- `POST /api/v1/auth/login` - Авторизация (8-значный логин)
|
||
|
||
### Health
|
||
- `GET /health` - Health check
|
||
- `GET /` - Root info
|
||
|
||
## DB API Contract
|
||
|
||
См. [DB_API_CONTRACT.md](DB_API_CONTRACT.md) для полного описания контракта с DB API сервисом.
|
||
|
||
## Интерфейсы (Interfaces)
|
||
|
||
### TgBackendInterface
|
||
|
||
Базовый класс для всех API клиентов. **Требует реализации пользователем!**
|
||
|
||
См. `app/interfaces/base.py` для заглушки и требований.
|
||
|
||
### DBApiClient
|
||
|
||
Наследуется от `TgBackendInterface`, предоставляет методы для работы с DB API:
|
||
- `login_user()`
|
||
- `get_user_settings()`, `update_user_settings()`
|
||
- `save_session()`, `get_sessions()`, `get_session()`, `delete_session()`
|
||
|
||
## Deployment
|
||
|
||
### Docker Compose
|
||
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
### Logs
|
||
|
||
```bash
|
||
docker-compose logs -f fastapi
|
||
```
|
||
|
||
### Остановить
|
||
|
||
```bash
|
||
docker-compose down
|
||
```
|
||
|
||
## Security
|
||
|
||
- JWT токены с 30-дневной экспирацией
|
||
- mTLS сертификаты только на сервере
|
||
- Secrets в .env (не коммитить в git!)
|
||
- CORS настроен (обновить в production)
|
||
|
||
## TODO
|
||
|
||
- [ ] Реализовать `TgBackendInterface` (пользователь)
|
||
- [ ] Добавить endpoints для settings, query, analysis
|
||
- [ ] Добавить RAG service
|
||
- [ ] Добавить frontend интеграцию
|
||
- [ ] Добавить тесты
|
||
- [ ] Rate limiting
|
||
- [ ] Logging middleware
|
||
|
||
## License
|
||
|
||
Proprietary
|