# [DEF:DocArchitecture:Module]
# @TIER: STANDARD
# @PURPOSE: Placeholder architecture document reserved for future normalized project architecture guidance.
# @RELATION: DEPENDS_ON -> [DEF:Std:Architecture:Standard]

Architecture guidance currently lives in `.ai/standards/architecture.md` and `.ai/MODULE_MAP.md`.

---

## Интеграционное тестирование с Testcontainers

Проект использует [Testcontainers](https://testcontainers-python.readthedocs.io/) для интеграционных тестов, требующих реальных сервисов (PostgreSQL, ClickHouse, Apache Superset).

### Принцип

Каждая тестовая сессия получает изолированные Docker-контейнеры на случайных портах. Контейнеры уничтожаются после завершения сессии. Это гарантирует отсутствие утечек состояния между запусками.

### Поддерживаемые сервисы

| Сервис | Образ | Scope | Конфигурация |
|--------|-------|-------|-------------|
| PostgreSQL | `postgres:16-alpine` | session | `backend/tests/integration/conftest.py` |
| ClickHouse | `clickhouse/clickhouse-server:24.3` | module | `test_translate_clickhouse.py` |
| Apache Superset | `apache/superset:4.1.2` | session | `backend/tests/integration/conftest.py` |

### Apache Superset Testcontainers

**Решение:** [ADR-0012 — Superset Testcontainers](./adr/ADR-0012-superset-testcontainers.md)

**Архитектура:**
```
Test Session
├── PostgresContainer (общий)          # DB: superset_meta
├── Init Container (краткоживущий)     # db upgrade → create-admin → init
└── Web Container (на всю сессию)      # superset run -p 8088
```

**Запуск:**
```bash
cd backend && source .venv/bin/activate
python -m pytest tests/integration/test_superset_integration.py -v
# 8 passed in ~25s
```

**Доступные fixtures:**
- `superset_db_url` — PostgreSQL URI для метаданных Superset
- `superset_container` — запущенный веб-сервер Superset
- `superset_url` — `http://host:port`
- `superset_admin_headers` — авторизованная сессия (admin:admin123)

**Ограничения:**
- JWT-авторизация (`/api/v1/security/login`) требует дополнительной конфигурации FAB-permission'ов
- Метаданные хранятся в SQLite (образ 4.1.2 не содержит psycopg2)

# [/DEF:DocArchitecture:Module]