```bash
aigw-project/
└── src/
    └── tenera_etl/                     # следует использовать своё название
        ├── api/
        │   ├── v1/
        │   │   ├── __init__.py
        │   │   ├── router.py
        │   │   ├── schemas.py           # pydantic models
        │   │   ├── service.py
        │   │   ├── models.py            # db models, data classes, named tuples
        │   │   ├── exceptions.py
        │   │   └── utils.py
        │   ├── __init__.py
        │   ├── middleware.py
        │   ├── os_router.py             # роутер для health и status endpoints
        │   ├── metric_router.py         # !BETA! роутер для оценки сервиса
        │   └── schemas.py               # валидация endpoint-ов из os_router и metric_router
        ├── interfaces/                  # интерфейсы для подключения к внешним AC
        ├── logger/
        │   ├── __init__.py
        │   ├── context_vars.py          # управление контекстом запросов для логирования
        │   ├── logger.py                # реализация логгера
        │   ├── models.py                # модели логов, метрик, событий аудита
        │   ├── utils.py                 # функции + маскирование args
        │   └── uvicorn_logging_config.py # конфигурация логирования uvicorn
        ├── __main__.py
        ├── base.py
        ├── config.py                    # global configs
        ├── exceptions.py                # global exceptions
        └── context.py

├── tests/
│   └── integration_tests/
│       ├── fixtures/
│       │   └── fixture_*.py
│       ├── conftest.py
│       ├── gigachat_interface/         # тесты интерфейсов (на GigaController)
│       │   └── test_gptchat_*.py
│       └── v1_api/
│           ├── constants.py
│           ├── test_service.py         # тесты бизнес-логики
│           └── test_service_*.py

├── app.sh                              # запуск в OpenShift, содержит tool.poetry.scripts
├── Dockerfile                          # основной Dockerfile
├── Dockerfile-k8s                      # локальный Docker
├── pyproject.toml
├── poetry.lock
├── .env                                # переменные окружения
└── .gitignore
```


## 📁 Назначение ключевых файлов

### `src/tenera_etl/`

| Файл                     | Назначение |
|--------------------------|------------|
| `__main__.py`            | Точка входа. Запускает FastAPI-приложение. |
| `config.py`              | Загрузка и обработка переменных окружения. |
| `base.py`                | Базовые классы и типы, переиспользуемые в проекте. |
| `context.py`             | Реализация паттерна `AppContext` - единая точка доступа к зависимостям. |

---

### `src/tenera_etl/logger/`

| Файл                         | Назначение |
|------------------------------|------------|
| `context_vars.py`            | Контекстные переменные для логирования (`Request-ID` и др.). ⚠️ Не редактировать.|
| `logger.py`                  | Основной логгер приложения. ⚠️ Не редактировать. |
| `models.py`                  | Модели логов, метрик, аудита. ⚠️ Не редактировать. |
| `utils.py`                   | Утилиты логгера, включая маскирование данных. |
| `uvicorn_logging_config.py` | Конфигурация логгирования `uvicorn`. |

---

### `src/tenera_etl/api/`

| Файл               | Назначение |
|--------------------|------------|
| `__init__.py`      | Конфигуратор FastAPI - регистрация версий и роутов. |
| `os_router.py`     | Инфраструктурные endpoint'ы (`/health`, `/status`). ⚠️ Не редактировать. |
| `metric_router.py` | Метрики (BETA). ⚠️ Не редактировать. |
| `schemas.py`       | Схемы (Pydantic) для `os_router` и `metric_router`. ⚠️ Не редактировать. |
| `middleware.py`    | Мидлвар для логирования входящих и исходящих запросов. ⚠️ Не редактировать. |

---

### `src/tenera_etl/api/v1/`

| Файл             | Назначение |
|------------------|------------|
| `router.py`      | Основные endpoint'ы бизнес-логики (`v1`). |
| `schemas.py`     | Pydantic-схемы запросов и ответов. |
| `models.py`      | Модели данных (DB, классы, namedtuples). |
| `service.py`     | Реализация бизнес-логики. |
| `utils.py`       | Утилиты и вспомогательные функции. |
| `exceptions.py`  | Исключения (`RestNotFound`, `InvalidUserData`, и др.). |

---

### `src/tenera_etl/interfaces/`

| Файл / Папка | Назначение |
|--------------|------------|
| *всё содержимое* | Интерфейсы взаимодействия с внешними системами (АС и пр.). |


Пример логирования в коде:

```python
from tenera_etl.logger import logger

logger.info("End processing user registration request")
```
⚠️ Не передавайте в logger.info(...) ничего, кроме строки - она будет записана в поле message.

Маскирование чувствительных данных

В файле logger/utils.py реализовано маскирование:

    все поля, содержащие ключевые слова вроде password, token, secret, будут скрыты;

    работает автоматически, но вы можете конфигурировать список слов и правила.

Перед добавлением кастомной маскировки - ознакомьтесь с документацией, чтобы избежать утечки данных.