busya
bc32dd65ef
Updated status in spec.md, plan.md, tasks.md, research.md, data-model.md, ux_reference.md, quickstart.md. All 72 tasks completed. 34/34 tests passing.
124 lines
4.5 KiB
Markdown
124 lines
4.5 KiB
Markdown
# 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-кода
|