brief-rags-bench/PRODUCTION_CHECKLIST.md

# Production Readiness Checklist

Полная проверка готовности Brief Bench FastAPI к развертыванию в продакшн.

## Backend (FastAPI)

### Код и архитектура
- [x] **Все API endpoints реализованы**
  - Auth: `/api/v1/auth/login`
  - Settings: GET/PUT `/api/v1/settings`
  - Query: POST `/api/v1/query/bench`, `/api/v1/query/backend`
  - Analysis: CRUD `/api/v1/analysis/sessions`
  - Health: `/health`

- [x] **Бизнес-логика покрыта тестами: 99%**
  - 119 unit tests (99% coverage)
  - Integration tests (DB API)
  - E2E tests (полный стек)

- [x] **Services реализованы**
  - AuthService (JWT токены)
  - RagService (RAG backends: IFT, PSI, PROD)

- [x] **Interfaces реализованы**
  - TgBackendInterface (базовый HTTP клиент)
  - DBApiClient (DB API integration)

- [x] **Models валидация**
  - Все Pydantic models для request/response
  - Валидация входных данных

## Frontend (Static Files)

- [x] **HTML/CSS/JS файлы**
  - index.html
  - styles.css (Material Design)
  - app.js (основная логика)
  - api-client.js (API клиент)
  - settings.js (настройки)

- [x] **Интеграция с backend**
  - API client использует `/api/v1` endpoints
  - JWT токены в localStorage
  - Правильная обработка ошибок (401, 502, etc.)
  - StaticFiles монтированы в main.py

- [x] **UI функциональность**
  - Login screen
  - Multi-environment tabs (IFT, PSI, PROD)
  - Settings panel
  - Query interface
  - Results display
  - Session management

## Конфигурация (ТРЕБУЕТ ВНИМАНИЯ!)

### КРИТИЧНО - Сделать перед деплоем:

- [ ] **1. Создать `.env` файл**
  ```bash
  cp .env.example .env
  nano .env
  ```

- [ ] **2. Сгенерировать новый JWT_SECRET_KEY**
  ```python
  import secrets
  print(secrets.token_urlsafe(32))
  ```
  Заменить в `.env`:
  ```
  JWT_SECRET_KEY=<сгенерированный-ключ>
  ```

- [ ] **3. Настроить DB_API_URL**
  ```
  DB_API_URL=http://your-db-api-host:8080/api/v1
  ```

- [ ] **4. Настроить RAG backend hosts**
  ```
  IFT_RAG_HOST=your-ift-rag-host.com
  PSI_RAG_HOST=your-psi-rag-host.com
  PROD_RAG_HOST=your-prod-rag-host.com
  ```

- [ ] **5. Разместить mTLS сертификаты (если используются)**
  ```
  certs/
    ift/
      ca.crt
      client.key
      client.crt
    psi/
      ca.crt
      client.key
      client.crt
    prod/
      ca.crt
      client.key
      client.crt
  ```

- [ ] **6. Настроить CORS для production**

  Отредактировать [app/main.py:21](app/main.py#L21):
  ```python
  # Было:
  allow_origins=["*"],  # TODO: Configure properly in production

  # Стало (если нужно ограничить):
  allow_origins=["https://your-domain.com"],
  ```

  **ИЛИ** оставить `["*"]` если:
  - Фронтенд и бэкенд на одном домене/IP (CORS не нужен)
  - JWT токены обеспечивают безопасность

- [ ] **7. Отключить DEBUG режим**
  ```
  DEBUG=false
  ```

## Docker & Deployment

- [x] **Dockerfile готов**
  - Multi-stage build
  - Копирует static/ файлы
  - Expose 8000
  - Uvicorn с правильными параметрами

- [x] **docker-compose.yml готов**
  - Порты пробрасываются (8000:8000)
  - Volume для certs (read-only)
  - Volume для static файлов
  - .env подключается
  - restart: unless-stopped

## Безопасность

- [x] **Authentication**
  - JWT токены (30 дней expiration)
  - Bearer token authentication
  - Middleware для проверки токенов

- [x] **Secrets management**
  - .env не в git (.gitignore)
  - .env.integration не в git
  - .env.e2e не в git
  - ВАЖНО: Сменить JWT_SECRET_KEY в продакшн!

- [x] **mTLS сертификаты**
  - Хранятся только на сервере
  - Read-only volume в Docker
  - Не коммитятся в git

- [ ] **HTTPS (рекомендуется)**
  - Настроить reverse proxy (nginx/traefik)
  - Let's Encrypt сертификаты
  - Редирект HTTP → HTTPS

## Документация

- [x] **README.md** - основная документация
- [x] **DB_API_CONTRACT.md** - контракт с DB API
- [x] **TESTING.md** - полное руководство по тестированию
- [x] **PROJECT_STATUS.md** - статус реализации
- [x] **tests/integration/README.md** - интеграционные тесты
- [x] **tests/e2e/README.md** - E2E тесты

## Pre-Deployment Testing

### Локальное тестирование

- [ ] **1. Запустить unit тесты**
  ```bash
  .\run_unit_tests.bat
  # Ожидается: 119 tests passed, 99% coverage
  ```

- [ ] **2. Запустить integration тесты** (если DB API доступно)
  ```bash
  .\run_integration_tests.bat
  # Требует: DB API running на localhost:8081
  ```

- [ ] **3. Локальный запуск**
  ```bash
  uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
  ```

- [ ] **4. Проверить основные endpoint'ы**
  ```bash
  # Health check
  curl http://localhost:8000/health

  # Frontend доступен
  curl http://localhost:8000/

  # Login (замените на реальный тестовый логин)
  curl -X POST "http://localhost:8000/api/v1/auth/login?login=12345678"
  ```

- [ ] **5. Проверить frontend в браузере**
  - Открыть http://localhost:8000/
  - Войти с тестовым логином
  - Проверить все три окружения (IFT, PSI, PROD)
  - Проверить Settings panel
  - Отправить тестовый запрос (если RAG доступен)

### Docker тестирование

- [ ] **1. Build Docker image**
  ```bash
  docker-compose build
  ```

- [ ] **2. Запустить контейнер**
  ```bash
  docker-compose up -d
  ```

- [ ] **3. Проверить логи**
  ```bash
  docker-compose logs -f fastapi
  # Не должно быть ошибок
  ```

- [ ] **4. Проверить доступность**
  ```bash
  curl http://localhost:8000/health
  curl http://localhost:8000/
  ```

- [ ] **5. Остановить**
  ```bash
  docker-compose down
  ```

## Deployment Steps

### 1. Подготовка сервера

```bash
# Клонировать на сервер
git clone <your-repo> /opt/brief-bench-fastapi
cd /opt/brief-bench-fastapi

# Создать .env из шаблона
cp .env.example .env
nano .env
# Заполнить все переменные!
```

### 2. Разместить сертификаты

```bash
# Создать директорию для сертификатов
mkdir -p certs/{ift,psi,prod}

# Скопировать сертификаты
# scp или другим способом разместить в certs/
```

### 3. Запуск

```bash
# Build и запуск
docker-compose up -d

# Проверка логов
docker-compose logs -f fastapi

# Проверка health
curl http://localhost:8000/health
```

### 4. Настройка reverse proxy (опционально, но рекомендуется)

**Nginx конфиг:**
```nginx
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Для long-running RAG запросов
        proxy_read_timeout 1800s;
        proxy_connect_timeout 1800s;
        proxy_send_timeout 1800s;
    }
}
```

## Post-Deployment Verification

После деплоя проверить:

- [ ] Health endpoint работает: `curl https://your-domain.com/health`
- [ ] Frontend загружается: `https://your-domain.com/`
- [ ] Login работает с реальным пользователем
- [ ] Settings загружаются для всех окружений
- [ ] Query работает для каждого окружения
- [ ] Session save/load работает
- [ ] Логи не содержат ошибок: `docker-compose logs -f`

## Мониторинг и обслуживание

### Логи

```bash
# Просмотр логов
docker-compose logs -f fastapi

# Последние 100 строк
docker-compose logs --tail=100 fastapi
```

### Restart

```bash
# Перезапуск после изменений
docker-compose restart fastapi

# Полный rebuild
docker-compose down
docker-compose up -d --build
```

### Обновление

```bash
# Pull изменений
git pull origin main

# Rebuild и restart
docker-compose down
docker-compose up -d --build
```

### Backup

Критичные данные:
- `.env` - секреты и конфигурация
- `certs/` - mTLS сертификаты
- Пользовательские данные хранятся в DB API (не в FastAPI)

## Performance Considerations

- RAG запросы могут занимать до 30 минут (настроено)
- Async/await для всех I/O операций
- Connection pooling в httpx clients
- Рассмотреть rate limiting для production
- Рассмотреть caching для settings (опционально)

## Troubleshooting

### Проблема: Контейнер не запускается

**Проверить:**
1. Логи: `docker-compose logs fastapi`
2. `.env` существует и заполнен
3. Порт 8000 не занят: `netstat -an | grep 8000`

### Проблема: Frontend не загружается

**Проверить:**
1. Static файлы скопированы в Docker: `docker exec -it brief-bench-fastapi ls /app/static`
2. main.py монтирует `/static`
3. index.html существует

### Проблема: RAG запросы падают с timeout

**Проверить:**
1. RAG backends доступны с сервера
2. mTLS сертификаты правильные
3. `RAG_REQUEST_TIMEOUT=1800` в .env
4. Nginx/proxy timeouts настроены (если используется)

### Проблема: 401 Unauthorized

**Проверить:**
1. JWT токен в localStorage браузера
2. JWT_SECRET_KEY одинаковый между запусками
3. Токен не истек (30 дней по умолчанию)

## Final Checklist Summary

Перед деплоем в продакшн:

1. Backend код готов (99% coverage)
2. Frontend интегрирован
3. Docker конфигурация готова
4. **`.env` создан и заполнен**
5. **`JWT_SECRET_KEY` сгенерирован новый**
6. **RAG hosts настроены**
7. **DB_API_URL настроен**
8. **mTLS сертификаты размещены** (если используются)
9. **CORS настроен** (при необходимости)
10. **DEBUG=false**
11. Unit тесты passed
12. Integration тесты passed (опционально)
13. Локальное тестирование пройдено
14. Docker build успешен

---

**Статус готовности: ПОЧТИ ГОТОВ**

**Готово:** Код, тесты, Docker, документация
**Требуется:** Конфигурация окружения (.env, сертификаты, финальная настройка)

После выполнения пунктов из раздела "КРИТИЧНО" → **ГОТОВ К ПРОДАКШН**