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

## Концепция

Один бот, несколько чатов, две поверхности:

- базовая поверхность — личка с ботом (DM)
- опциональная advanced-поверхность — Topics в пользовательской Forum-группе

При первом запуске пользователь начинает в DM: бот создаёт первый чат и
переключает пользователя в него. Если позже пользователь подключает Forum-группу
через `/forum`, существующие чаты получают соответствующие темы в супергруппе.

DM и Forum используют один и тот же `chat_id`: пользователь может писать
либо в личке, либо в forum topic, а платформа видит единый разговор.

---

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

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

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

---

## Чаты в DM и Forum Topics

### Как это работает
- После `/start` бот создаёт `Чат #1` в DM
- В DM активный чат хранится как `active_chat_id`
- Ответы в личке приходят в общий поток с тегом `[Чат #N]`
- После `/forum` пользователь привязывает свою супергруппу с Topics
- Каждый чат может получить соответствующую тему (`forum_thread_id`)
- В forum-теме ответы приходят без тега, прямо в тему
- История forum-разговоров хранится нативно в Telegram

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

| Команда | Действие |
|---|---|
| `/new` | Создать новый чат |
| `/chats` | Показать список всех чатов |
| `/forum` | Подключить Forum-группу |

В forum-темах поддерживается тот же разговорный контекст, а `/new` может
зарегистрировать текущую тему как отдельный чат.

### Создание нового чата
1. Пользователь пишет `/new [название]` или нажимает кнопку
2. Бот создаёт новый чат в локальной БД: `Чат #N` или указанное название
3. Если Forum уже подключён, бот дополнительно создаёт новую тему в привязанной группе
4. В DM бот переключает `active_chat_id` на новый чат

### В моке
- DM-чаты работают сразу после `/start`
- Если Forum подключён, темы создаются реально через Bot API
- Сообщения из DM и forum topic передаются в `MockPlatformClient` с одним и тем же `chat_id`

---

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

### Флоу сообщения
1. Пользователь пишет текст в DM или в forum topic
2. Бот показывает `typing...`
3. Запрос уходит в платформу (сейчас — MockPlatformClient)
4. Бот отвечает:
   - в DM: с тегом `[Чат #N]`
   - в forum topic: без тега, в ту же тему

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

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

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

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

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

---

## Настройки

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

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

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

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

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

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

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

```
🧩 Скиллы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

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

```text
[Start] -> ChatState.idle
              ↓
      ForumSetupState.waiting_for_group
              ↓
      ChatState.waiting_response -> ChatState.idle
              ↓
           SettingsState.*
```

---

## Стек

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