209 lines
5.5 KiB
Markdown
209 lines
5.5 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)
|
||
|
||
## Тестирование
|
||
|
||
**Покрытие: 99%**
|
||
|
||
- ✅ Unit тесты (119 tests) - вся логика
|
||
- ✅ Integration тесты - интеграция с DB API
|
||
- ✅ E2E тесты - полный стек
|
||
|
||
Запуск:
|
||
```bash
|
||
.\run_all_tests.bat # Все (unit + integration)
|
||
.\run_unit_tests.bat # Только unit
|
||
.\run_integration_tests.bat # Integration (требует DB API)
|
||
.\run_e2e_tests.bat # E2E (требует все сервисы)
|
||
```
|
||
|
||
Подробнее: [TESTING.md](TESTING.md)
|
||
|
||
## Документация
|
||
|
||
- [TESTING.md](TESTING.md) - руководство по тестированию
|
||
- [PRODUCTION_CHECKLIST.md](PRODUCTION_CHECKLIST.md) - чек-лист для продакшн
|
||
- [DB_API_CONTRACT.md](DB_API_CONTRACT.md) - контракт с DB API
|
||
- [PROJECT_STATUS.md](PROJECT_STATUS.md) - статус проекта
|
||
|
||
## Status
|
||
|
||
**Проект готов к продакшн**
|
||
|
||
- Backend полностью реализован (все endpoints, services, interfaces)
|
||
- Frontend интегрирован (HTML/CSS/JS)
|
||
- 99% test coverage (unit + integration + E2E)
|
||
- Docker ready
|
||
- Требуется: настройка `.env` и сертификатов
|
||
|
||
**Перед деплоем:** см. [PRODUCTION_CHECKLIST.md](PRODUCTION_CHECKLIST.md)
|
||
|
||
## License
|
||
|
||
Proprietary
|