Add Pulse Telegram bot spec: commands, inline buttons, architecture

Projects/Pulse/Telegram-Bot.md

@@ -0,0 +1,148 @@
+# Pulse — Telegram Bot
+
+Бот как полноценный интерфейс к Pulse. Управление задачами и привычками без захода на сайт.
+
+## Авторизация
+
+### Связка аккаунта
+1. Пользователь отправляет `/start`
+2. Бот отвечает: "Привет! Твой chat_id: `123456789`. Добавь его в настройках профиля на сайте."
+3. После привязки бот может отправлять уведомления и принимать команды
+
+### Альтернатива: Magic Link
+- `/login` → бот отправляет одноразовую ссылку для входа
+- Или код подтверждения, который вводишь на сайте
+
+## Команды
+
+### Задачи
+
+| Команда | Описание |
+|---------|----------|
+| `/tasks` | Список задач на сегодня (все) |
+| `/tasks remaining` | Только невыполненные задачи |
+| `/tasks all` | Все активные задачи |
+| `/task <текст>` | Создать новую задачу |
+| `/done <id>` | Отметить задачу выполненной |
+| `/undone <id>` | Снять отметку выполнения |
+
+**Примеры:**
+```
+/task Купить молоко
+/task Позвонить врачу !высокий @завтра
+/done 15
+```
+
+**Флаги при создании:**
+- `!высокий` / `!средний` / `!низкий` — приоритет
+- `@сегодня` / `@завтра` / `@10.02` — дедлайн
+- `🔔17:00` — напоминание
+
+### Привычки
+
+| Команда | Описание |
+|---------|----------|
+| `/habits` | Привычки на сегодня |
+| `/habits all` | Все привычки |
+| `/check <id>` | Отметить привычку выполненной |
+| `/uncheck <id>` | Снять отметку |
+
+**Примеры:**
+```
+/habits
+/check 3
+```
+
+### Статистика
+
+| Команда | Описание |
+|---------|----------|
+| `/stats` | Краткая статистика (выполнено сегодня, streak) |
+| `/stats week` | Статистика за неделю |
+
+### Настройки
+
+| Команда | Описание |
+|---------|----------|
+| `/settings` | Текущие настройки уведомлений |
+| `/notify on` / `/notify off` | Вкл/выкл уведомления |
+| `/morning 09:00` | Установить время утреннего уведомления |
+
+## Inline кнопки
+
+Для удобства бот отправляет сообщения с кнопками:
+
+### Список задач
+```
+📋 Задачи на сегодня:
+
+1. [ ] Купить молоко
+2. [ ] Позвонить врачу (!)
+3. [✓] Оплатить счета
+
+[✅ Отметить] [➕ Новая задача]
+```
+
+При нажатии "Отметить" → показать список для выбора.
+
+### Уведомление о привычке
+```
+🔔 Напоминание: Гитара 🎸
+
+Время заниматься! (17:00)
+
+[✅ Выполнено] [⏰ Напомни через 30 мин]
+```
+
+## Быстрые ответы
+
+Бот понимает текст без команд в контексте:
+- После `/tasks` можно просто написать "купить хлеб" → создаст задачу
+- После показа списка можно написать "1" → отметит задачу #1
+
+## Архитектура
+
+### Хранение состояния
+- Redis или in-memory map для user states
+- Состояния: `idle`, `awaiting_task_text`, `awaiting_habit_check`
+
+### Обработка команд
+```go
+type BotHandler struct {
+    taskService   *service.TaskService
+    habitService  *service.HabitService
+    userService   *service.UserService
+}
+
+func (h *BotHandler) HandleUpdate(update tgbotapi.Update) {
+    // роутинг команд
+}
+```
+
+### Связь с основным API
+- Бот использует те же сервисы что и HTTP API
+- Авторизация по telegram_chat_id → user_id
+
+## Безопасность
+
+- Команды работают только для привязанных аккаунтов
+- Rate limiting на создание задач
+- Логирование действий через бота
+
+## TODO
+
+- [ ] Базовые команды: /start, /tasks, /habits
+- [ ] Создание задач через /task
+- [ ] Отметка выполнения: /done, /check
+- [ ] Inline кнопки для быстрых действий
+- [ ] Контекстные быстрые ответы
+- [ ] Настройки через бота
+
+## Приоритет реализации
+
+1. **MVP:** /start, /tasks, /habits, /done, /check
+2. **v1.1:** Создание задач, inline кнопки
+3. **v1.2:** Быстрые ответы, статистика, настройки
+
+---
+*Создано: 2026-02-06*