tgex-backend/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a FastAPI + Telegram Bot backend application for managing Telegram channel integrations. The project uses:
- **FastAPI** for HTTP API endpoints
- **aiogram** for Telegram bot functionality
- **Tortoise ORM** (async) for database operations
- **PostgreSQL** with asyncpg driver
- **aerich** for database migrations
- **uv** for Python package management

## Development Commands

### Environment Setup
```bash
# Install dependencies (using uv)
uv sync

# Start PostgreSQL (via Docker Compose)
docker-compose up -d

# Run database migrations
make migrate-up  # or: export $(cat .env | xargs) && aerich upgrade
```

### Running the Application
```bash
# Start the FastAPI server
uv run uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
```

### Code Quality
```bash
# Run linter (Ruff)
uv run ruff check .

# Format code
uv run ruff format .

# Type checking (mypy with strict mode)
uv run mypy .
```

### Testing
```bash
# Run all tests
uv run pytest

# Run a single test file
uv run pytest tests/test_file.py

# Run a specific test
uv run pytest tests/test_file.py::test_function_name
```

### Database Migrations
```bash
# Create a new migration (auto-generated based on model changes)
make migrate-create  # or: source .env && aerich migrate

# Apply migrations
make migrate-up  # or: source .env && aerich upgrade

# Rollback one migration
make migrate-down  # or: source .env && aerich downgrade
```

**Important Migration Workflow:**

1. **For simple model changes**: Let aerich auto-generate the migration:
   ```bash
   source .env && aerich migrate --name "descriptive_name"
   ```

2. **For complex refactorings** (table renames, data migration, etc.):
   - **FIRST**: Update domain models to reflect the new structure
   - **THEN**: Run `aerich migrate` to auto-generate the migration file
   - **FINALLY**: Edit the generated file to add data migration logic

   Example workflow:
   ```bash
   # 1. Update models in src/domain/
   # 2. Generate migration (will create base ALTER TABLE statements)
   source .env && aerich migrate --name "refactor_tables"
   # 3. Edit the generated file in migrations/models/ to add:
   #    - Data migration SQL (INSERT ... SELECT)
   #    - Proper ordering of operations
   #    - Comments explaining complex logic
   ```

3. **For custom constraints** (CHECK, custom indexes, etc.):
   ```bash
   source .env && aerich migrate --name "add_check_constraint" --empty
   # Then edit and add: # ruff: noqa and # mypy: ignore-errors at the top
   ```

**Migration Best Practices:**
- Always test migrations on a copy of production data
- Use transactions (`RUN_IN_TRANSACTION = True`)
- Add comments explaining complex data transformations
- For table renames with data migration:
  1. Rename old table to `old_*`
  2. Create new table structure
  3. Migrate data with `INSERT INTO new SELECT ... FROM old`
  4. Drop old table last
- Include proper downgrade logic (even if it loses some data)

## Architecture

### Layered Architecture

The codebase follows a clean architecture pattern with clear separation of concerns:

1. **Domain Layer** (`src/domain/`)
   - Tortoise ORM models that represent database entities
   - All models inherit from `domain.base.TimestampedModel` which provides:
     - Auto-generated `id` (UUID primary key)
     - Timestamps: `created_at`, `updated_at`, `deleted_at`
     - Timezone-aware datetime fields
   - Use `class Meta: table = 'table_name'` for explicit table naming

2. **Use Case Layer** (`src/usecase/`)
   - Business logic functions organized by feature
   - Each use case is a standalone function with signature: `async def use_case_name(self: 'Usecase', ...) -> ReturnType`
   - Depends on Protocol interfaces (Database, TelegramBotWriter, JWTEncoder)
   - Use cases are assembled in the `Usecase` dataclass for dependency injection
   - **IMPORTANT RULES:**
     - Один use case отвечает за полноценный сценарий «от триггера до завершения»
     - Use case НЕ должен вызывать другие use cases (общую логику выносить в хелперы/сервисы)
     - Use case содержит ВСЮ бизнес-логику, включая управление состояниями диалога
     - Use case может отправлять сообщения пользователям через `self.telegram_bot` protocol
     - Всегда оборачивать операции БД в `async with self.database.transaction()`

3. **Adapter Layer** (`src/adapter/`)
   - Concrete implementations of protocol interfaces:
     - `Postgres`: Database operations (implements Database protocol)
     - `Telegram`: Telegram bot integration (implements TelegramWriter protocol)
     - `JWT`: Token encoding/decoding (implements JWTEncoder protocol)

4. **Controller Layer** (`src/controller/`)
   - **HTTP controllers** (`src/controller/http/`): FastAPI route handlers
   - **Telegram callbacks** (`src/controller/telegram_callback/`): Telegram event handlers
   - **ВАЖНО: Controllers - это тонкий слой роутинга**
     - Контроллер только извлекает данные из событий (HTTP request / Telegram update)
     - Валидирует базовые параметры (user exists, message not empty)
     - Вызывает соответствующий use case
     - НЕ содержит бизнес-логику
     - НЕ обращается к базе данных напрямую
     - НЕ отправляет сообщения пользователям
   - Все handlers регистрируются через декораторы на `telegram_callback_router`
   - Handlers импортируются в `__init__.py` для auto-регистрации

5. **DTO Layer** (`src/dto/`)
   - Pydantic models for request/response validation
   - Separate from domain models to decouple API contracts from database schema

### Key Architectural Patterns

**Dependency Injection via Protocols:**
- Use cases depend on Protocol interfaces, not concrete implementations
- Allows for easy testing and swapping implementations
- See `src/usecase/__init__.py` for protocol definitions

**Transaction Management:**
- Database uses context-aware transactions via `DatabaseBase.transaction()`
- Session stored in ContextVar (`_session_ctx`) for implicit session access
- Always use `async with database.transaction()` for database operations
- The session is accessible via `database.session` within transaction context

**Shared Base Classes:**
- `shared/datebase_base.py`: Base database class with connection pooling and migration checking
- `shared/telegram_base.py`: Base Telegram bot class with polling lifecycle
- `shared/logger/`: Structured logging with JSON and console formatters

**Configuration:**
- All config in `src/config.py` using Pydantic Settings
- Environment variables loaded from `.env` file
- Nested config via double underscore: `DB__URL`, `TELEGRAM__TOKEN`

### Application Lifecycle

1. **Startup** (in `src/main.py`):
   - Logger initialized
   - Adapters instantiated (Postgres, Telegram, JWT)
   - Usecase dataclass created with adapter dependencies
   - FastAPI lifespan context:
     - Connect to database (includes migration check)
     - Start Telegram bot polling

2. **Request Flow**:
   - HTTP: FastAPI route → Controller → Usecase → Adapter → Database
   - Telegram: Event → Telegram callback → Usecase → Adapter → Database

3. **Shutdown**:
   - Stop Telegram bot polling
   - Close database connections

### Important Implementation Details

**Database Session Management:**
- DO NOT create sessions manually
- Use `async with database.transaction()` which handles begin/commit/rollback
- Access session via `database.session` property within transaction context
- Session lifecycle is managed by ContextVars for thread-safety

**Telegram Bot Integration:**
- Bot runs in polling mode (not webhook)
- Routers registered in `src/controller/telegram_callback/`
- Base class handles graceful shutdown of polling task

**Authentication:**
- JWT-based authentication for HTTP endpoints
- Login flow: Telegram bot → Login token → JWT access token
- Use `get_current_user` dependency for protected routes

**Code Style:**
- Single quotes for strings (configured in Ruff)
- Line length: 120 characters
- Python 3.13+ syntax
- Strict mypy typing enabled

### Telegram Bot Patterns

**State Management:**
- Состояния хранятся в БД через модель `TelegramState`
- Используется `TelegramStateEnum` для типизации состояний (не строки!)
- Database protocol методы: `get_telegram_state()`, `set_telegram_state()`, `clear_telegram_state()`

**Controller Pattern (Telegram):**
```python
from aiogram import F
from aiogram.filters import Command
from aiogram.types import Message

@telegram_callback_router.message(Command('command_name'))
async def cmd_handler(message: Message) -> None:
    if not message.from_user:
        log.error('Failed to get user data')
        return

    usecase = dependencies.get_usecase()
    await usecase.some_use_case(
        telegram_id=message.from_user.id,
        chat_id=message.chat.id
    )
```

**Use Case Pattern (Telegram):**
```python
from src import domain

async def some_use_case(self: 'Usecase', telegram_id: int, chat_id: int) -> None:
    async with self.database.transaction():
        # 1. Получить/проверить пользователя
        user = await self.database.get_user(telegram_id=telegram_id)
        if not user:
            await self.telegram_bot.send_message('❌ Не авторизован', chat_id=chat_id)
            return

        # 2. Получить состояние (если нужно)
        state = await self.database.get_telegram_state(telegram_id)

        # 3. Бизнес-логика
        # ...

        # 4. Обновить состояние
        await self.database.set_telegram_state(
            telegram_id=telegram_id,
            state=domain.TelegramStateEnum.SOME_STATE,
            context={'key': 'value'}
        )

        # 5. Отправить сообщение
        await self.telegram_bot.send_message('✅ Успешно', chat_id=chat_id)
```

**Inline Keyboard Pattern:**
```python
from aiogram.types import InlineKeyboardButton

# В use case:
buttons = [
    [InlineKeyboardButton(text='Кнопка', callback_data='callback_id:value')]
    for item in items
]
await self.telegram_bot.send_message_with_inline_keyboard(
    'Выберите опцию:', chat_id=chat_id, buttons=buttons
)
```

**Callback Query Handler:**
```python
@telegram_callback_router.callback_query(F.data.startswith('prefix:'))
async def callback_handler(callback: CallbackQuery) -> None:
    if not callback.from_user or not callback.data:
        return

    usecase = dependencies.get_usecase()
    await usecase.handle_callback(
        telegram_id=callback.from_user.id,
        chat_id=callback.message.chat.id,
        callback_data=callback.data,
        message_id=callback.message.message_id
    )
    await callback.answer()  # Убрать "loading" на кнопке
```

**Text Message Filters:**
```python
# Обрабатывать только не-команды
@telegram_callback_router.message(F.text & ~F.text.startswith('/'))
async def text_handler(message: Message) -> None:
    # Этот handler НЕ сработает для команд типа /start
    ...
```

**Важные правила для Telegram handlers:**
- Специфичные фильтры (Command) регистрировать РАНЬШЕ общих (F.text)
- Использовать `~F.text.startswith('/')` для исключения команд в текстовых handlers
- Всегда проверять `message.from_user` перед использованием
- Callback handlers должны вызывать `await callback.answer()` в конце
- НЕ импортировать aiogram типы в usecase layer (только через TYPE_CHECKING в Protocol)

### Adding New Protocol Methods

When adding new functionality that requires protocol methods:

**1. Define Protocol in usecase layer (`src/usecase/__init__.py`):**
```python
if typing.TYPE_CHECKING:
    from aiogram.types import InlineKeyboardButton  # Импорт только для типов

class TelegramBotWriter(typing.Protocol):
    async def send_message_with_inline_keyboard(
        self, text: str, chat_id: int, buttons: list[list['InlineKeyboardButton']]
    ) -> None: ...
```

**2. Implement in adapter (`src/adapter/telegram_bot.py`):**
```python
from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup

class TelegramBot(TelegramBase):
    async def send_message_with_inline_keyboard(
        self, text: str, chat_id: int, buttons: list[list[InlineKeyboardButton]]
    ) -> None:
        keyboard = InlineKeyboardMarkup(inline_keyboard=buttons)
        await self.bot.send_message(chat_id=chat_id, text=text, reply_markup=keyboard)
```

**3. Use in use case:**
```python
from aiogram.types import InlineKeyboardButton  # Можно импортировать в use case

buttons = [[InlineKeyboardButton(text='Text', callback_data='data')]]
await self.telegram_bot.send_message_with_inline_keyboard('Message', chat_id, buttons)
```

**Типизация Enum в Domain:**
- Используйте `enum.StrEnum` для строковых enum (Python 3.11+)
- Enum значения в lowercase с underscores
- Используйте `fields.CharEnumField()` в Tortoise ORM

```python
import enum
from tortoise import fields
from .base import TimestampedModel

class TelegramStateEnum(enum.StrEnum):
    CREATIVE_WAITING_CHANNEL = 'creative_waiting_channel'
    CREATIVE_WAITING_NAME = 'creative_waiting_name'

class TelegramState(TimestampedModel):
    state = fields.CharEnumField(TelegramStateEnum, max_length=26)

    class Meta:
        table = 'telegram_state'
```

**Database Constraints:**
- Foreign keys: Use `fields.ForeignKeyField()` with `on_delete=fields.CASCADE`
- Unique constraints: Use `unique=True` or `unique_together` in Meta
- CHECK constraints: Cannot be defined in Tortoise models - create manual migrations
- Indexes: Use `index=True` on fields or define in Meta

Example with CHECK constraint:
```bash
# Create empty migration
export $(cat .env | xargs) && aerich migrate --name "add_check_constraint" --empty
```

Then edit the created file:
```python
# migrations/models/1_xxx_add_check_constraint.py
# ruff: noqa
# mypy: ignore-errors
from tortoise import BaseDBAsyncClient

RUN_IN_TRANSACTION = True

async def upgrade(db: BaseDBAsyncClient) -> str:
    return """
        ALTER TABLE "table_name"
            ADD CONSTRAINT "constraint_name"
            CHECK (your_condition);
    """

async def downgrade(db: BaseDBAsyncClient) -> str:
    return """
        ALTER TABLE "table_name"
            DROP CONSTRAINT IF EXISTS "constraint_name";
    """
```