# Quickstart: Async Backend Refactoring

**Feature**: `032-translate-requests-httpx`
**Date**: 2026-06-04
**Status**: ✅ Implemented

## Development Setup

```bash
# 1. Убедиться, что ветка активна
git branch --show-current  # должен быть 032-translate-requests-httpx

# 2. Активировать venv и установить новые зависимости
cd backend
source .venv/bin/activate
pip install -r requirements.txt

# 3. Новые dev-зависимости для тестирования
pip install pytest-httpx pytest-asyncio

# 4. Проверить текущее состояние тестов (до рефакторинга)
python -m pytest -v --tb=short 2>&1 | tail -20
```

## Verification Commands

### Backend Tests (после каждого этапа рефакторинга)

```bash
cd backend && source .venv/bin/activate

# Все тесты
python -m pytest -v

# Только тесты затронутых модулей
python -m pytest src/plugins/translate/ src/core/ src/api/routes/ -v

# С coverage
python -m pytest --cov=src --cov-report=term-missing

# Конкретный тестовый файл
python -m pytest src/plugins/translate/__tests__/test_executor.py -v
python -m pytest src/core/utils/__tests__/test_network.py -v 2>/dev/null || echo "No tests yet"
```

### Линтинг

```bash
cd backend
python -m ruff check .
```

### Конкурентность (ручная проверка)

```bash
# Терминал 1: запустить долгую операцию
curl -X POST http://localhost:8000/translate/jobs/{job_id}/preview \
  -H "Content-Type: application/json" \
  -d '{"sample_size": 10}'

# Терминал 2 (немедленно, пока preview выполняется): проверить схему
curl -X POST http://localhost:8000/translate/check-target-schema \
  -H "Content-Type: application/json" \
  -d '{"environment_id": "...", "target_database_id": "...", "target_table": "..."}'

# Терминал 3 (немедленно): легковесный запрос
curl http://localhost:8000/health
```

### Проверка на утечки соединений

```bash
# После 500 запросов — проверить CLOSE_WAIT/TIME_WAIT:
ss -tnp | grep -c CLOSE_WAIT  # должно быть 0
lsof -i -P -n | grep python | wc -l  # должно быть стабильно
```

### Семантический аудит (после рефакторинга)

```bash
# Перестроить индекс
# (выполняется через Axiom MCP)
axiom_semantic_index rebuild rebuild_mode="full"

# Проверить контракты
axiom_semantic_validation audit_contracts

# Проверить belief-протокол
axiom_semantic_validation audit_belief_protocol
```

## Docker

```bash
# Полный стек
docker compose up --build

# Только backend (для быстрой итерации)
docker compose up --build backend db
```

## New Dependencies Checklist

- [ ] `pytest-httpx` добавлен в `requirements-dev.txt` или `pyproject.toml [dev]`
- [ ] `aiofiles` добавлен в `requirements.txt`
- [ ] `aiosmtplib` добавлен в `requirements.txt`
- [ ] `httpx` — уже есть (0.28.1), проверить совместимость версии
- [ ] Старые зависимости НЕ удаляются до завершения миграции всех тестов

## Порядок рефакторинга (Big-Bang)

Рекомендуемый порядок изменений в рамках одного PR:

1. **`core/utils/`** — AsyncAPIClient + SupersetClientAuth + SupersetClientPaginated (новые файлы)
2. **`core/superset_client/`** — миграция _base.py + 13 миксинов на async
3. **`plugins/translate/`** — LLMHttpClient (новый), миграция executor, preview, run source
4. **`api/routes/`** — замена sync SupersetClient на async в detail_routes, translate routes
5. **`core/task_manager/`** — TaskManager, EventBus, TaskLifecycle async
6. **`plugins/backup.py`, `plugins/git_plugin.py`, `plugins/storage/`** — миграция на async
7. **`services/notifications/`** — провайдеры async
8. **`services/git/`** — Git-операции через asyncio.to_thread
9. **Тесты** — замена requests_mock на pytest_httpx во всех затронутых тестовых файлах
10. **Удаление** — Tombstone старых контрактов, удаление неиспользуемого sync-кода