# Telegram — описание прототипа

## Концепция

Один бот, несколько чатов через Topics в Forum-группе.

При первом запуске бот создаёт для пользователя персональную Forum-группу
(супергруппу с включёнными темами). Каждый новый чат с агентом — отдельная тема
внутри группы. Пользователь видит это как список чатов в одном месте.

Бот управляет группой от имени пользователя через Telegram Bot API:
создаёт темы, переименовывает, архивирует.

---

## Аутентификация

### Флоу
1. Пользователь пишет боту `/start`
2. Бот проверяет — есть ли аккаунт на платформе привязанный к этому `tg_user_id`
3. Если нет — бот отправляет одноразовую ссылку или код для входа
4. Пользователь подтверждает, платформа возвращает токен сессии
5. Бот сохраняет привязку `tg_user_id → platform_user_id`

### В моке
- Любой пользователь проходит аутентификацию автоматически
- Кнопка «Войти» → пауза 1 сек → «Вы вошли как {имя}»
- Демонстрирует флоу без реальной платформы

---

## Чаты через Forum Topics (вариант В)

### Как это работает
- Бот создаёт супергруппу с Topics для каждого нового пользователя
- Каждый чат = отдельная тема (Topic) в этой группе
- История хранится нативно в Telegram (в самой теме)
- Переключение между чатами = переключение между темами

### Управление чатами
Внутри каждой темы доступны команды:

| Команда | Действие |
|---|---|
| `/new` | Создать новый чат (новую тему) |
| `/rename Название` | Переименовать текущий чат |
| `/archive` | Архивировать текущий чат |
| `/chats` | Показать список всех чатов |

### Создание нового чата
1. Пользователь пишет `/new` или нажимает кнопку
2. Бот спрашивает название (опционально, можно пропустить)
3. Бот создаёт новую тему в группе: «Чат 1», «Чат 2» и т.д.
4. Бот отправляет в новую тему приветствие; при первом сообщении платформа автоматически поднимает контейнер

### В моке
- Группа и темы создаются реально через Bot API
- Сообщения передаются в MockPlatformClient с `chat_id` (C1, C2...)
- История в темах хранится нативно в Telegram, ничего не нужно делать

---

## Основной диалог

### Флоу сообщения
1. Пользователь пишет текст в тему
2. Бот показывает `typing...`
3. Запрос уходит в платформу (сейчас — MockPlatformClient)
4. Бот отвечает текстом агента

### Вложения
- Фото, документы, голосовые — передаются в платформу как `attachments`
- В моке: бот подтверждает получение файла и возвращает заглушку-ответ
- Форматы: PDF, изображения, текстовые файлы

### Подтверждение действий
Если агент собирается выполнить потенциально опасное действие
(отправить письмо, удалить файл, сделать запись в календарь):

```
Агент хочет выполнить действие:
📧 Отправить письмо на vasya@mail.ru
Тема: «Отчёт за неделю»

[✅ Подтвердить]  [❌ Отменить]
```

Пользователь нажимает кнопку — действие выполняется или отменяется.
В моке: кнопки работают, действие логируется, ответ-заглушка.

---

## Настройки

Доступны через `/settings` в любой теме или в главном меню бота.
Реализованы как цепочка инлайн-кнопок.

### Главное меню настроек
```
⚙️ Настройки

[🔗 Коннекторы]   [🧩 Скиллы]
[🧠 Личность]     [🔔 Уведомления]
[🔒 Безопасность] [💳 Подписка]
```

### Коннекторы
Подключение внешних сервисов. Агент получает доступ через API Proxy,
пароли пользователю вводить не нужно — только OAuth.

| Коннектор | Способ подключения |
|---|---|
| Gmail / Outlook | OAuth ссылка |
| Google Calendar | OAuth ссылка |
| GitHub | OAuth ссылка |
| Notion | OAuth ссылка |
| Telegram (читать каналы) | Уже подключён |

В моке: кнопка «Подключить» → ссылка-заглушка → «Подключено ✓»

### Скиллы
Включение/выключение навыков агента.

```
🧩 Скиллы

✅ Поиск в интернете
✅ Чтение почты
❌ Управление браузером
❌ Генерация изображений
❌ Работа с календарём
✅ Работа с файлами
❌ Генерация видео
```

Каждый скилл — кнопка-переключатель. Нажал — включил/выключил.
В моке: состояние хранится локально, платформа не вызывается.

### Личность агента (SOUL.md)
Онбординг-анкета при первом входе, потом редактирование.

```
🧠 Личность агента

Как зовут твоего агента?
[_Лямбда_____________]

Что он должен делать в первую очередь?
[_Разбирать почту_____]

Стиль общения:
[Деловой] [Дружелюбный] [Краткий]
```

В моке: данные сохраняются, агент обращается к пользователю по имени из настроек.

### Уведомления
Когда агент выполнил долгую задачу — уведомление в Telegram.

```
🔔 Уведомления

✅ Задача выполнена
✅ Требуется подтверждение действия
❌ Ежедневный дайджест
❌ Напоминания из календаря
```

В моке: уведомления отправляются через бот с задержкой (симуляция).

### Безопасность
Какие действия требуют явного подтверждения.

```
🔒 Безопасность

Всегда спрашивать перед:
✅ Отправкой письма
✅ Удалением файлов
✅ Публикацией в соцсетях
❌ Созданием события в календаре
❌ Поиском в интернете
```

### Подписка
Заглушка — реализует другая команда.

```
💳 Подписка

Текущий план: Beta (бесплатно)
Токены: ████████░░ 800/1000

[Подробнее о планах]
```

---

## FSM состояния

```
[Start] → AuthPending → AuthConfirmed
                              ↓
                         GroupSetup → Idle
                                        ↓
                              ReceivingMessage → WaitingResponse → Idle
                                        ↓
                              ConfirmAction → [Confirmed/Cancelled] → Idle
                                        ↓
                              Settings → [подменю] → Idle
```

---

## Стек

- Python 3.11+
- aiogram 3.x (Router, FSM, InlineKeyboard, Forum Topics API)
- MockPlatformClient → `platform/interface.py`
- structlog для логирования
- SQLite для хранения `tg_user_id → platform_user_id` и состояния скиллов