ss-tools/specs/032-translate-requests-httpx/quickstart.md

Quickstart: Async Backend Refactoring

Feature: 032-translate-requests-httpx Date: 2026-06-04

Development Setup

# 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 (после каждого этапа рефакторинга)

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"

Линтинг

cd backend
python -m ruff check .

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

# Терминал 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

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

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

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

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

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

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

Docker

# Полный стек
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-кода