# Forum Topics Mode Design

**Date:** 2026-03-31
**Status:** Approved — ready for implementation
**Scope:** `adapter/telegram/` — расширение существующего адаптера

---

## Контекст

Forum Topics — опциональный advanced-режим поверх существующих виртуальных DM-чатов.
Пользователь подключает свою Telegram-супергруппу с Topics — и его чаты появляются
как нативные темы Telegram. DM и Forum работают **одновременно**: один контекст,
две поверхности.

---

## Принцип работы

Каждый чат (`chat_id` = UUID) получает опциональный `forum_thread_id`.

- Пользователь пишет в DM → бот отвечает в DM с тегом `[Чат #N]`
- Пользователь пишет в Forum-тему → бот отвечает в ту же тему (без тега)
- Контекст (`chat_id`) один и тот же — платформа видит единый разговор

---

## БД — изменения схемы

```sql
ALTER TABLE tg_users ADD COLUMN forum_group_id INTEGER;
ALTER TABLE chats    ADD COLUMN forum_thread_id INTEGER;
```

`forum_group_id` — ID супергруппы пользователя (NULL если группа не подключена).
`forum_thread_id` — ID темы в форуме (NULL если чат создан только в DM).

Новые функции в `db.py`:
```python
def set_forum_group(tg_user_id: int, group_id: int) -> None
def get_forum_group(tg_user_id: int) -> int | None
def set_forum_thread(chat_id: str, thread_id: int) -> None
def get_chat_by_thread(tg_user_id: int, thread_id: int) -> dict | None
```

---

## Онбординг — `/forum`

### FSM

```python
class ForumSetupState(StatesGroup):
    waiting_for_group = State()   # ждём пересылку из группы
```

### Флоу

```
/forum
→ FSM: ForumSetupState.waiting_for_group
→ "Создай супергруппу, включи Topics, добавь меня администратором
   с правом управления темами. Затем перешли мне любое сообщение из группы."

[пользователь пересылает сообщение]
→ Проверить: forward_from_chat.type == "supergroup"
→ Проверить права бота (администратор + can_manage_topics)
   ❌ нет прав → объяснить что именно не так, остаться в состоянии
→ Сохранить forum_group_id в БД
→ Создать Forum-тему для каждого существующего активного DM-чата
→ Записать forum_thread_id для каждого чата
→ Ответить в DM: "✅ Группа подключена! Твои чаты теперь доступны в Forum-темах."
→ FSM: clear
```

### Проверка прав

```python
async def check_forum_admin(bot: Bot, group_id: int) -> bool:
    member = await bot.get_chat_member(group_id, (await bot.get_me()).id)
    return (
        member.status in ("administrator", "creator")
        and getattr(member, "can_manage_topics", False)
    )
```

---

## Создание чатов — синхронизация

### `/new` в DM (группа подключена)

1. Создать UUID-запись в `chats` (как сейчас)
2. `create_forum_topic(bot, group_id, chat_name)` → получить `thread_id`
3. Записать `forum_thread_id` в БД
4. Переключить FSM на новый чат
5. Ответить в DM: `"✅ [chat_name] создан."`

### `/new` в DM (группа НЕ подключена)

Без изменений — только DM-чат.

### `/new` в Forum-теме

1. Определить `thread_id` из `message.message_thread_id`
2. Создать UUID-запись в `chats` с `forum_thread_id = thread_id`
3. Название: из аргумента `/new Название` или из названия темы (`message.chat.forum_topic_created.name` при создании — иначе запросить у Telegram)
4. Ответить в теме: `"✅ Чат зарегистрирован. Пиши здесь!"`

---

## Маршрутизация сообщений

### Определение источника

```python
def is_forum_message(message: Message) -> bool:
    return message.message_thread_id is not None

def resolve_chat_id(message: Message, tg_user_id: int) -> str | None:
    if is_forum_message(message):
        chat = db.get_chat_by_thread(tg_user_id, message.message_thread_id)
        return chat["chat_id"] if chat else None
    else:
        # DM — берём active_chat_id из FSM StateData (как сейчас)
        return None  # caller reads from FSM
```

### Ответ

- Пришло из DM → `bot.send_message(tg_user_id, f"[{chat_name}] {text}")`
- Пришло из Forum-темы → `bot.send_message(group_id, text, message_thread_id=thread_id)`

В Forum-теме тег `[Чат #N]` **не нужен** — тема сама является визуальным разделителем.

---

## Обработчики — изменения

### `handlers/forum.py` (новый файл)

```python
router = Router(name="forum")

@router.message(Command("forum"))
async def cmd_forum(message, state): ...          # запускает онбординг

@router.message(ForumSetupState.waiting_for_group, F.forward_from_chat)
async def handle_group_forward(message, state, dispatcher): ...  # регистрирует группу
```

### `handlers/chat.py` — изменения

- `handle_message`: если `is_forum_message` → брать `chat_id` из БД по `thread_id`, отвечать в тему
- `cmd_new_chat`: ветвление по источнику (DM vs Forum) и наличию `forum_group_id`

### `states.py` — добавить

```python
class ForumSetupState(StatesGroup):
    waiting_for_group = State()
```

---

## Что НЕ реализуем

- Отслеживание создания тем пользователем без `/new` — Telegram не присылает событие создания темы в боте
- Синхронизация удаления темы ↔ архивация DM-чата (только через команды)
- Поддержка нескольких групп на одного пользователя

---

## Порядок реализации

1. `db.py` — миграция + 4 новых функции
2. `states.py` — `ForumSetupState`
3. `handlers/forum.py` — `/forum` + onboarding
4. `handlers/chat.py` — `cmd_new_chat` с ветвлением, `handle_message` с Forum-маршрутизацией
5. `converter.py` — `is_forum_message`, `resolve_chat_id`