init

guide-admin.md

@@ -0,0 +1,415 @@
+# Руководство администратора
+
+> AI Assistant — Telegram-бот для управления задачами с ИИ-анализом сообщений в групповых чатах.
+
+Администратор — пользователь с расширенными правами, назначенный суперадмином или автоматически при добавлении в качестве админа проекта. Администратор может управлять задачами и проектами, к которым ему предоставлен доступ.
+
+---
+
+## Оглавление
+
+1. [Начало работы](#1-начало-работы)
+2. [Главное меню](#2-главное-меню)
+3. [Работа с проектами](#3-работа-с-проектами)
+4. [Создание задач](#4-создание-задач)
+5. [Просмотр и фильтрация задач](#5-просмотр-и-фильтрация-задач)
+6. [Редактирование задач](#6-редактирование-задач)
+7. [Мониторинг сообщений в чатах](#7-мониторинг-сообщений-в-чатах)
+8. [Режимы работы бота](#8-режимы-работы-бота)
+9. [Обработка предложений ИИ](#9-обработка-предложений-ии)
+10. [База знаний проекта](#10-база-знаний-проекта)
+11. [Управление админами проекта](#11-управление-админами-проекта)
+12. [Настройки бота](#12-настройки-бота)
+13. [Справочник команд](#13-справочник-команд)
+
+---
+
+## 1. Начало работы
+
+### 1.1. Регистрация
+
+Для начала работы напишите боту в Telegram команду `/start`. Бот автоматически зарегистрирует вас в системе.
+
+Если суперадмин назначил вас администратором, при следующем `/start` вы увидите расширенное меню.
+
+### 1.2. Как стать администратором
+
+Вы можете стать администратором двумя путями:
+- **Суперадмин** назначает вас через меню «👤 Админы».
+- **Суперадмин или другой админ** добавляет вас как админа проекта — в этом случае вы автоматически получаете статус администратора.
+
+---
+
+## 2. Главное меню
+
+После `/start` администратору доступны кнопки:
+
+| Кнопка | Описание |
+|---|---|
+| **📁 Проекты** | Управление назначенными проектами |
+| **📋 Задачи** | Создание задач, список задач, мои задачи |
+
+При нажатии на **📋 Задачи** открывается подменю:
+
+| Кнопка | Описание |
+|---|---|
+| **🧷 Добавить задачу** | Ручное создание задачи |
+| **🗓 Список задач** | Все задачи в назначенных проектах |
+| **📗 Мои задачи** | Только задачи, назначенные на вас |
+
+---
+
+## 3. Работа с проектами
+
+### 3.1. Просмотр проектов
+
+Нажмите **📁 Проекты** или отправьте `/projects`.
+
+Вы видите **только те проекты**, к которым вас добавили как админа.
+
+### 3.2. Управление проектом
+
+Выберите проект из списка. Доступные действия:
+
+| Действие | Описание |
+|---|---|
+| ✏️ Изменить название | Ввести новое имя проекта |
+| 👥 Админы проекта | Управление администраторами этого проекта |
+| 📚 База знаний | Загрузка и удаление документов |
+| 💬 Управление чатами | Привязка групповых чатов к проекту |
+| 🗑 Удалить проект | Удаление проекта со всеми данными |
+
+---
+
+## 4. Создание задач
+
+### 4.1. Ручное создание
+
+1. Нажмите **📋 Задачи** → **🧷 Добавить задачу** (или кнопку в главном меню).
+2. Выберите проект из списка доступных вам проектов.
+3. Отправьте текст задачи.
+
+### 4.2. Формат ввода задачи
+
+Бот поддерживает гибкий формат. Вы можете указать название, исполнителей и дедлайн в одном или нескольких сообщениях.
+
+**Примеры:**
+
+Только название:
+```
+Создать отчёт
+```
+
+С исполнителем:
+```
+Создать отчёт
+@ivan
+```
+
+С дедлайном:
+```
+Провести встречу с партнерами 23.03.2025
+```
+
+Всё вместе:
+```
+@ivan @maria подготовить презентацию 15.04.2025
+```
+
+### 4.3. Подтверждение задачи
+
+После ввода бот покажет превью задачи:
+- **Название** — первая строка вашего сообщения
+- **Связанные люди** — найденные `@username`
+- **Дедлайн** — найденная дата в формате `ДД.ММ.ГГГГ`
+
+Далее вы можете:
+- **Изменить описание** — добавить развёрнутое описание задачи
+- **Подтвердить создание задачи** — сохранить задачу в системе
+
+Если что-то не так — просто отправьте новое сообщение с исправленными данными.
+
+### 4.4. Описание задачи
+
+Нажав «Изменить описание», отправьте текст описания. Поддерживается форматирование Telegram (жирный, курсив, код и т.д.).
+
+---
+
+## 5. Просмотр и фильтрация задач
+
+### 5.1. Список задач проекта
+
+1. Нажмите **📋 Задачи** → **🗓 Список задач**.
+2. Выберите проект.
+3. Бот покажет задачи со статусом «CREATED» (по умолчанию).
+
+### 5.2. Фильтрация
+
+Вы можете комбинировать фильтры:
+
+#### По статусу
+Нажмите одну из кнопок под списком задач:
+- **CREATED** — созданные
+- **IN_WORK** — в работе
+- **BLOCKED** — заблокированные
+- **FINISHED** — завершённые
+- **CANCELLED** — отменённые
+
+#### По исполнителю
+Два способа:
+- Отправьте `@username` одного или нескольких пользователей
+- Перешлите сообщение от нужного пользователя
+
+#### По дате дедлайна
+Отправьте дату в формате `ДД.ММ.ГГГГ`, например:
+```
+15.04.2025
+```
+
+---
+
+## 6. Редактирование задач
+
+Выберите задачу из списка. Откроется карточка задачи с информацией:
+- ID и название
+- Статус
+- Описание
+- Дедлайн
+- Исполнители
+
+### 6.1. Изменение названия
+
+Нажмите **Изменить название** → введите новое название.
+
+### 6.2. Изменение описания
+
+Нажмите **Изменить описание** → введите новый текст описания. Поддерживается форматирование.
+
+### 6.3. Изменение дедлайна
+
+Нажмите **Изменить дату дедлайна** → введите новую дату.
+
+Поддерживаемые форматы:
+- Абсолютная дата: `23.03.2025`
+- Относительная: `+3` (через 3 дня от текущей даты), `-1` (на день раньше)
+
+### 6.4. Изменение исполнителей
+
+Нажмите **Изменить людей**.
+
+- **Добавить:** отправьте `@username` или перешлите сообщение от пользователя.
+- **Убрать:** нажмите на имя пользователя в списке под сообщением.
+
+### 6.5. Изменение статуса
+
+Нажмите **Изменить статус** → выберите новый статус из списка.
+
+Доступные статусы:
+
+| Статус | Значение |
+|---|---|
+| CREATED | Задача создана |
+| IN_WORK | В работе |
+| BLOCKED | Заблокирована |
+| FINISHED | Завершена |
+| CANCELLED | Отменена |
+
+**Примечание:** когда задача переводится в статус **FINISHED**, автоматически создаётся задача на проверку для ответственного лица.
+
+---
+
+## 7. Мониторинг сообщений в чатах
+
+Мониторинг позволяет боту автоматически обнаруживать задачи в групповых чатах.
+
+### 7.1. Включение мониторинга
+
+В **групповом чате**, где бот является администратором:
+
+```
+/monitor on
+```
+
+С указанием проекта:
+```
+/monitor on 5
+```
+
+### 7.2. Выключение
+
+```
+/monitor off
+```
+
+### 7.3. Проверка статуса
+
+```
+/status
+```
+
+### 7.4. Как бот распознаёт задачи
+
+Бот считает сообщение задачей, если:
+- Содержит упоминание `@username`
+- **Или** является ответом (reply) на другое сообщение
+
+Примеры:
+```
+@Alex подготовь презентацию до завтра
+```
+```
+(reply на сообщение)
+Сделай, пожалуйста, до конца дня
+```
+
+---
+
+## 8. Режимы работы бота
+
+Бот имеет два режима работы, настраиваемых для каждого чата отдельно.
+
+### 8.1. TRAINING (обучение)
+
+- Бот отправляет администратору предложение создать задачу.
+- Администратор решает: подтвердить или отклонить.
+- Задачи создаются **только после подтверждения**.
+
+### 8.2. PRODUCTION (рабочий)
+
+- Бот создаёт задачи **автоматически**.
+- Если дедлайн не определён, бот предлагает установить его интерактивно.
+
+### 8.3. Переключение
+
+В групповом чате:
+```
+/bot_mode
+```
+
+Бот покажет текущий режим и кнопки для переключения.
+
+---
+
+## 9. Обработка предложений ИИ
+
+В режиме TRAINING бот отправляет вам (как администратору) предложения по обнаруженным задачам.
+
+### Доступные действия:
+
+| Кнопка | Описание |
+|---|---|
+| ✅ Подтвердить | Создать задачу |
+| ❌ Отклонить | Не создавать задачу |
+| 📅 Дедлайн | Изменить или убрать предложенный дедлайн |
+| 👤 Исполнитель | Изменить назначенного исполнителя |
+
+### Работа с дедлайном:
+- **Принять** предложенный ИИ дедлайн
+- **Изменить** — откроется календарь
+- **Убрать** — задача будет без дедлайна
+
+### Изменение исполнителя:
+- Отправьте `@username`
+- Или перешлите сообщение от пользователя
+
+---
+
+## 10. База знаний проекта
+
+Каждый проект может иметь базу знаний — документы, по которым бот отвечает на вопросы.
+
+### 10.1. Загрузка документа
+
+1. Откройте проект → **📚 База знаний** → **➕ Загрузить файл**.
+2. Отправьте файл:
+   - Формат: `.txt` или `.docx`
+   - Размер: не более **5 МБ**
+3. Бот обработает документ (разобьёт на части и создаст эмбеддинги).
+
+### 10.2. Удаление документа
+
+В базе знаний → **🗑 Удалить документ** → выберите документ.
+
+### 10.3. Поиск по базе знаний
+
+В **групповом чате**, привязанном к проекту:
+
+```
+/find какой порядок согласования договоров?
+```
+
+Бот найдёт релевантные фрагменты в документах проекта и сформирует ответ с помощью ИИ.
+
+**Важно:** команда `/find` работает только в чатах, привязанных к проекту.
+
+---
+
+## 11. Управление админами проекта
+
+Вы можете добавлять и удалять других администраторов для своих проектов.
+
+### 11.1. Просмотр
+
+Откройте проект → **👥 Админы проекта**.
+
+### 11.2. Добавление
+
+1. Нажмите **➕ Добавить админа**.
+2. Нажмите **👤 Выбрать пользователя**.
+3. Выберите пользователя из контактов Telegram.
+
+**Требование:** пользователь должен хотя бы раз написать боту.
+
+### 11.3. Удаление
+
+Нажмите на имя админа → **🗑 Убрать из проекта**.
+
+---
+
+## 12. Настройки бота
+
+**Команда:** `/settings` (в личных сообщениях)
+
+### Уведомления о дедлайнах
+
+1. Нажмите **Уведомления**.
+2. **Включить/выключить** — переключатель.
+3. **Изменить время** — отправьте время в формате `ЧЧ:ММ` (часовой пояс UTC+3).
+
+Бот уведомляет о приближающихся дедлайнах:
+- За один день до дедлайна
+- В день дедлайна
+
+---
+
+## 13. Справочник команд
+
+| Команда | Где | Описание |
+|---|---|---|
+| `/start` | ЛС | Главное меню |
+| `/settings` | ЛС | Настройки бота (уведомления) |
+| `/projects` | ЛС | Список ваших проектов |
+| `/my_tasks` | ЛС | Мои задачи как исполнителя |
+| `/monitor on\|off [id]` | Группа | Включить/выключить мониторинг |
+| `/status` | Группа | Проверить статус мониторинга |
+| `/bot_mode` | Группа | Переключить режим бота (TRAINING / PRODUCTION) |
+| `/find <запрос>` | Группа | Поиск по базе знаний проекта |
+
+> **ЛС** — личные сообщения с ботом.
+> **Группа** — групповой чат, где бот является администратором.
+
+---
+
+## Частые вопросы
+
+**Не вижу кнопки «📁 Проекты» в меню**
+→ Вам не назначен ни один проект. Попросите суперадмина добавить вас как админа проекта.
+
+**Бот не создаёт задачи из сообщений в чате**
+→ Проверьте: 1) бот — администратор группы, 2) мониторинг включён (`/status`), 3) сообщения содержат `@username` или reply.
+
+**Пользователь не найден при добавлении к задаче**
+→ Пользователь должен хотя бы раз написать боту `/start`, чтобы зарегистрироваться в системе.
+
+**Команда `/find` не работает**
+→ Чат должен быть привязан к проекту, и в проекте должны быть загружены документы.

guide-superadmin.md

@@ -0,0 +1,365 @@
+# Руководство суперадминистратора
+
+> AI Assistant — Telegram-бот для управления задачами с ИИ-анализом сообщений в групповых чатах.
+
+Суперадминистратор — это роль с максимальными правами в системе. Суперадминов добавляет разработчик. Удалить суперадмина через интерфейс бота нельзя.
+
+---
+
+## Оглавление
+
+1. [Начало работы](#1-начало-работы)
+2. [Управление проектами](#2-управление-проектами)
+3. [Привязка чатов к проектам](#3-привязка-чатов-к-проектам)
+4. [Управление администраторами](#4-управление-администраторами)
+5. [Управление админами проектов](#5-управление-админами-проектов)
+6. [Мониторинг сообщений](#6-мониторинг-сообщений)
+7. [Режимы работы бота](#7-режимы-работы-бота)
+8. [Обработка предложений ИИ (TRAINING)](#8-обработка-предложений-ии-training)
+9. [Управление задачами](#9-управление-задачами)
+10. [База знаний](#10-база-знаний)
+11. [Настройки уведомлений](#11-настройки-уведомлений)
+
+---
+
+## 1. Начало работы
+
+1. Напишите боту в Telegram команду `/start`.
+2. Бот определит вас как суперадмина и покажет расширенное меню с кнопками:
+   - **📁 Проекты** — управление проектами
+   - **📋 Задачи** — работа с задачами
+   - **👤 Админы** — управление администраторами
+
+---
+
+## 2. Управление проектами
+
+Проект — основная единица организации работы. К проекту привязываются чаты, задачи, администраторы и база знаний.
+
+### 2.1. Создание проекта
+
+**Команда:** `/create_project` (только в личных сообщениях)
+
+Или через меню:
+1. Нажмите **📁 Проекты**.
+2. Нажмите **➕ Создать проект**.
+3. Введите название проекта.
+4. После создания бот предложит привязать чаты.
+
+### 2.2. Просмотр проектов
+
+**Команда:** `/projects` или кнопка **📁 Проекты**
+
+Суперадмин видит **все** проекты в системе (обычные админы — только свои).
+
+### 2.3. Управление проектом
+
+Выберите проект из списка. Доступные действия:
+
+| Действие | Описание |
+|---|---|
+| ✏️ Изменить название | Ввести новое имя проекта |
+| 👥 Админы проекта | Управление администраторами проекта |
+| 📚 База знаний | Загрузка/удаление документов |
+| 💬 Управление чатами | Привязка групповых чатов |
+| 🗑 Удалить проект | Удаление проекта со всеми данными |
+
+### 2.4. Удаление проекта
+
+При удалении проекта удаляются **все** связанные задачи и данные. Бот запросит подтверждение.
+
+---
+
+## 3. Привязка чатов к проектам
+
+Чтобы бот мог мониторить сообщения в групповом чате и создавать задачи:
+
+1. Добавьте бота в нужную Telegram-группу.
+2. Назначьте бота **администратором** группы.
+3. Откройте управление проектом → **💬 Управление чатами**.
+4. Нажмите **📢 Выбрать группу** и выберите нужный чат из списка.
+
+Один чат может быть привязан только к одному проекту. При перепривязке бот предупредит, что чат был перемещён из другого проекта.
+
+---
+
+## 4. Управление администраторами
+
+### 4.1. Просмотр администраторов
+
+Нажмите **👤 Админы** в главном меню или через `/settings`.
+
+В списке отображаются:
+- **⭐** — отметка суперадминов
+- Обычные админы (назначенные через бота)
+
+### 4.2. Добавление администратора
+
+1. В списке админов нажмите **➕ Добавить администратора**.
+2. Нажмите **👤 Выбрать пользователя**.
+3. Выберите пользователя из списка контактов Telegram.
+
+**Требование:** пользователь должен хотя бы раз написать боту, чтобы появиться в базе данных.
+
+### 4.3. Удаление администратора
+
+1. Нажмите на имя администратора в списке.
+2. Нажмите **🗑 Удалить админа**.
+
+**Важно:** суперадминов удалить нельзя — эта кнопка для них не отображается. Для изменения списка суперадминов обратитесь к разработчику.
+
+---
+
+## 5. Управление админами проектов
+
+Админ проекта — это пользователь с правами управления конкретным проектом (создание задач, просмотр списка задач, управление базой знаний).
+
+### 5.1. Просмотр админов проекта
+
+1. Откройте проект → **👥 Админы проекта**.
+2. Отобразится список текущих админов проекта.
+
+### 5.2. Добавление админа проекта
+
+1. Нажмите **➕ Добавить админа**.
+2. Нажмите **👤 Выбрать пользователя** и выберите из контактов.
+3. Если пользователь ещё не является глобальным админом, бот автоматически назначит ему этот статус.
+
+### 5.3. Удаление админа проекта
+
+1. Нажмите на имя админа → **🗑 Убрать из проекта**.
+
+---
+
+## 6. Мониторинг сообщений
+
+Мониторинг — функция, при которой бот анализирует сообщения в групповом чате и определяет, содержат ли они задачи.
+
+### 6.1. Включение мониторинга
+
+В **групповом чате**, где бот является администратором:
+
+```
+/monitor on
+```
+
+Опционально можно указать ID проекта:
+
+```
+/monitor on 5
+```
+
+### 6.2. Выключение мониторинга
+
+```
+/monitor off
+```
+
+### 6.3. Проверка статуса
+
+```
+/status
+```
+
+Бот ответит: «Мониторинг: ВКЛ» или «Мониторинг: ВЫКЛ».
+
+### 6.4. Как бот распознаёт задачи
+
+Бот считает сообщение потенциальной задачей, если:
+- В сообщении есть упоминание `@username`, **или**
+- Сообщение является ответом (reply) на другое сообщение.
+
+Примеры сообщений, которые бот распознает:
+```
+@Alex подготовь презентацию до завтра
+```
+```
+(reply на сообщение пользователя)
+Сделай, пожалуйста, до конца дня
+```
+
+Если в сообщении нет ни `@username`, ни reply — оно игнорируется.
+
+---
+
+## 7. Режимы работы бота
+
+### 7.1. Просмотр текущего режима
+
+В **групповом чате**:
+
+```
+/bot_mode
+```
+
+### 7.2. Режим TRAINING (обучение)
+
+- Бот отправляет суперадмину предложение создать задачу.
+- Суперадмин может подтвердить, отклонить, изменить дедлайн или исполнителя.
+- Задача создаётся **только после подтверждения**.
+
+Рекомендуется начинать с этого режима для обучения ИИ и проверки качества распознавания.
+
+### 7.3. Режим PRODUCTION (рабочий)
+
+- Бот создаёт задачи **автоматически** без подтверждения.
+- Если ИИ не может определить дедлайн, отправляется интерактивный запрос на установку дедлайна.
+
+### 7.4. Переключение режима
+
+Нажмите на кнопку нужного режима под сообщением, которое появится после `/bot_mode`.
+
+---
+
+## 8. Обработка предложений ИИ (TRAINING)
+
+Когда бот работает в режиме TRAINING, при обнаружении задачи в чате суперадмин получает сообщение с предложением:
+
+### Доступные действия:
+
+| Кнопка | Описание |
+|---|---|
+| ✅ Подтвердить | Создать задачу как предложено |
+| ❌ Отклонить | Отклонить — не создавать задачу |
+| 📅 Дедлайн | Просмотреть/изменить предложенный ИИ дедлайн |
+| 👤 Исполнитель | Изменить назначенного исполнителя |
+
+### Управление дедлайном:
+
+При нажатии на кнопку дедлайна:
+- **Принять** — сохранить предложенную ИИ дату
+- **Изменить** — открыть календарь для выбора даты
+- **Убрать** — убрать дедлайн
+
+### Изменение исполнителя:
+
+- Отправьте `@username` пользователя
+- Или перешлите сообщение от нужного пользователя
+
+---
+
+## 9. Управление задачами
+
+### 9.1. Создание задачи вручную
+
+1. Нажмите **📋 Задачи** → **🧷 Добавить задачу**.
+2. Выберите проект (суперадмин видит все проекты).
+3. Отправьте текст задачи. Примеры формата:
+   ```
+   Создать отчёт
+   @username
+   ```
+   ```
+   @username должен закончить планирование
+   ```
+   ```
+   Провести встречу с партнерами 23.03.2025
+   ```
+4. Бот покажет превью задачи с полями: название, исполнители, дедлайн.
+5. Вы можете:
+   - **Изменить описание** — добавить развёрнутое описание
+   - **Подтвердить создание задачи** — сохранить задачу
+
+### 9.2. Просмотр списка задач
+
+1. Нажмите **📋 Задачи** → **🗓 Список задач**.
+2. Выберите проект.
+3. Используйте фильтры:
+
+| Фильтр | Как использовать |
+|---|---|
+| По статусу | Нажмите кнопку нужного статуса (CREATED, IN_WORK, BLOCKED, FINISHED, CANCELLED) |
+| По исполнителю | Отправьте `@username` или перешлите сообщение от пользователя |
+| По дате дедлайна | Отправьте дату в формате `ДД.ММ.ГГГГ` |
+
+### 9.3. Редактирование задачи
+
+Выберите задачу из списка. Доступные действия:
+
+| Действие | Описание |
+|---|---|
+| Изменить название | Ввести новое название |
+| Изменить описание | Ввести новое описание (поддерживается HTML-форматирование) |
+| Изменить дату дедлайна | Формат: `ДД.ММ.ГГГГ` или `+3` / `-1` (дней от текущей даты) |
+| Изменить людей | Добавить `@username` / переслать сообщение, или убрать нажатием на имя |
+| Изменить статус | Выбрать новый статус из списка |
+
+### 9.4. Статусы задач
+
+| Статус | Значение |
+|---|---|
+| CREATED | Задача создана, ожидает начала |
+| IN_WORK | В работе |
+| BLOCKED | Заблокирована |
+| FINISHED | Завершена |
+| CANCELLED | Отменена |
+
+### 9.5. Автоматическая проверка выполненных задач
+
+Когда исполнитель помечает задачу как **FINISHED**:
+- Создаётся задача «Проверить выполнение задачи #N» и назначается на того, кто создал исходную задачу (или на первого суперадмина).
+- Суперадмин получает уведомление в ЛС.
+
+---
+
+## 10. База знаний
+
+Каждый проект может иметь собственную базу знаний — набор документов, по которым бот отвечает на вопросы.
+
+### 10.1. Загрузка документов
+
+1. Откройте проект → **📚 База знаний** → **➕ Загрузить файл**.
+2. Отправьте файл в формате `.txt` или `.docx` (не более 5 МБ).
+3. Бот автоматически обработает документ и добавит его в базу знаний.
+
+### 10.2. Удаление документов
+
+1. В базе знаний нажмите **🗑 Удалить документ**.
+2. Выберите документ для удаления.
+
+### 10.3. Поиск по базе знаний
+
+В **групповом чате**, привязанном к проекту:
+
+```
+/find что такое ПЗУ?
+```
+
+Бот найдёт релевантную информацию в документах проекта и сформирует ответ с помощью ИИ.
+
+---
+
+## 11. Настройки уведомлений
+
+### 11.1. Открытие настроек
+
+**Команда:** `/settings` (в личных сообщениях)
+
+### 11.2. Уведомления о дедлайнах
+
+1. В настройках нажмите **Уведомления**.
+2. Доступные действия:
+   - **Включить/выключить** — переключатель уведомлений о дедлайнах
+   - **Изменить время** — отправьте время в формате `ЧЧ:ММ` (часовой пояс UTC+3)
+
+Бот уведомляет о приближающихся дедлайнах:
+- За день до дедлайна
+- В день дедлайна
+
+---
+
+## Краткий справочник команд суперадмина
+
+| Команда | Где | Описание |
+|---|---|---|
+| `/start` | ЛС | Главное меню |
+| `/settings` | ЛС | Настройки бота (уведомления) |
+| `/create_project` | ЛС | Создать новый проект |
+| `/projects` | ЛС | Список проектов |
+| `/my_tasks` | ЛС | Мои задачи как исполнителя |
+| `/monitor on\|off [id]` | Группа | Включить/выключить мониторинг |
+| `/status` | Группа | Проверить статус мониторинга |
+| `/bot_mode` | Группа | Переключить режим бота |
+| `/find <запрос>` | Группа | Поиск по базе знаний проекта |
+
+> **ЛС** — личные сообщения с ботом, **Группа** — групповой чат, где бот администратор.

guide-user.md

@@ -0,0 +1,246 @@
+# Руководство пользователя
+
+> AI Assistant — Telegram-бот для управления задачами с ИИ-анализом сообщений в групповых чатах.
+
+Это руководство для обычных пользователей — тех, кому назначаются задачи. Вам не нужно настраивать бота или управлять проектами — достаточно знать, как просматривать свои задачи, менять их статус и получать уведомления.
+
+---
+
+## Оглавление
+
+1. [Начало работы](#1-начало-работы)
+2. [Главное меню](#2-главное-меню)
+3. [Как вам назначают задачи](#3-как-вам-назначают-задачи)
+4. [Просмотр своих задач](#4-просмотр-своих-задач)
+5. [Работа с задачей](#5-работа-с-задачей)
+6. [Фильтрация задач](#6-фильтрация-задач)
+7. [Быстрый доступ к задачам из любого чата](#7-быстрый-доступ-к-задачам-из-любого-чата)
+8. [Уведомления о дедлайнах](#8-уведомления-о-дедлайнах)
+9. [Частые вопросы](#9-частые-вопросы)
+
+---
+
+## 1. Начало работы
+
+### 1.1. Регистрация
+
+Чтобы начать работу с ботом:
+
+1. Найдите бота в Telegram по его username.
+2. Нажмите **Start** или отправьте команду `/start`.
+3. Бот автоматически зарегистрирует вас в системе.
+
+**Важно:** вы должны написать боту хотя бы раз, иначе система не сможет назначать вам задачи.
+
+### 1.2. Приветственное сообщение
+
+После `/start` бот отправит приветствие с информацией о доступных функциях и покажет клавиатуру с кнопками.
+
+---
+
+## 2. Главное меню
+
+После регистрации вам доступна кнопка:
+
+| Кнопка | Описание |
+|---|---|
+| **📋 Задачи** | Открыть меню задач |
+
+При нажатии на **📋 Задачи** откроется подменю:
+
+| Кнопка | Описание |
+|---|---|
+| **📗 Мои задачи** | Список задач, назначенных на вас |
+
+Если вам не назначено ни одной задачи, список будет пустым.
+
+---
+
+## 3. Как вам назначают задачи
+
+Задачи могут быть назначены вам несколькими способами:
+
+### 3.1. Автоматически из группового чата
+
+Если бот мониторит групповой чат и кто-то напишет сообщение с упоминанием вашего `@username`:
+
+```
+@ваш_username подготовь отчёт до пятницы
+```
+
+Бот распознает это как задачу и назначит её на вас (автоматически или после подтверждения администратором, в зависимости от режима работы).
+
+Также задача может быть создана, если кто-то ответит (reply) на ваше сообщение с указанием действия.
+
+### 3.2. Вручную администратором
+
+Администратор может создать задачу через бота и указать вас как исполнителя с помощью `@username`.
+
+### 3.3. Уведомление о назначении
+
+Когда на вас назначена новая задача, бот может прислать уведомление в личные сообщения.
+
+---
+
+## 4. Просмотр своих задач
+
+### 4.1. Через меню
+
+1. Нажмите **📋 Задачи** → **📗 Мои задачи**.
+2. Бот покажет список задач со статусом «CREATED» (новые задачи).
+
+### 4.2. Через команду
+
+Отправьте боту в личные сообщения:
+
+```
+/my_tasks
+```
+
+### 4.3. Информация в карточке задачи
+
+Для каждой задачи отображается:
+- **ID** и **название**
+- **Статус** (CREATED, IN_WORK, BLOCKED, FINISHED, CANCELLED)
+- **Описание** (если есть)
+- **Дедлайн** (если установлен)
+- **Исполнители** (список `@username`)
+
+---
+
+## 5. Работа с задачей
+
+### 5.1. Открытие задачи
+
+Нажмите на задачу в списке. Откроется карточка с полной информацией и кнопками управления.
+
+### 5.2. Изменение статуса
+
+Это основное действие, доступное вам. Вы можете менять статус задачи:
+
+| Статус | Когда ставить |
+|---|---|
+| **CREATED** | Задача только создана (начальный статус) |
+| **IN_WORK** | Вы начали работать над задачей |
+| **BLOCKED** | Работа заблокирована (ожидание, внешние зависимости) |
+| **FINISHED** | Задача выполнена |
+| **CANCELLED** | Задача отменена |
+
+Нажмите **Изменить статус** и выберите нужный.
+
+### 5.3. Что происходит при завершении задачи
+
+Когда вы ставите статус **FINISHED**:
+- Ответственному лицу (тому, кто создал задачу) автоматически создаётся задача на проверку.
+- Он получит уведомление: «Исполнитель отметил задачу #N как выполненную».
+- Уведомления о дедлайне этой задачи отключаются.
+
+### 5.4. Другие доступные действия
+
+В зависимости от задачи вам также могут быть доступны:
+
+| Действие | Описание |
+|---|---|
+| Изменить название | Ввести новое название задачи |
+| Изменить описание | Ввести новое описание |
+| Изменить дедлайн | Формат: `ДД.ММ.ГГГГ` или `+3` / `-1` (сдвиг в днях) |
+| Изменить людей | Добавить `@username` или убрать исполнителя |
+
+---
+
+## 6. Фильтрация задач
+
+При просмотре своих задач вы можете фильтровать их двумя способами:
+
+### 6.1. По статусу
+
+Нажмите кнопку нужного статуса под списком задач:
+- CREATED
+- IN_WORK
+- BLOCKED
+- FINISHED
+- CANCELLED
+
+### 6.2. По дате дедлайна
+
+Отправьте дату в формате `ДД.ММ.ГГГГ`:
+```
+15.04.2025
+```
+
+Бот покажет только задачи с дедлайном в указанный день.
+
+---
+
+## 7. Быстрый доступ к задачам из любого чата
+
+Вы можете получить список своих задач прямо из любого чата Telegram с помощью инлайн-запроса.
+
+### Как это работает:
+
+1. В **любом** чате (даже в другом диалоге) начните вводить:
+   ```
+   @имя_бота Задачи
+   ```
+2. Появится выпадающий список ваших задач.
+3. Нажмите на задачу — и информация о ней будет отправлена в текущий чат.
+
+Это удобно, когда нужно быстро поделиться информацией о задаче с коллегой.
+
+---
+
+## 8. Уведомления о дедлайнах
+
+Бот автоматически уведомляет о приближающихся дедлайнах:
+
+- **За день до дедлайна** — напоминание о том, что срок подходит к концу.
+- **В день дедлайна** — уведомление о наступлении срока.
+
+Уведомление содержит:
+- ID и название задачи
+- Дату дедлайна
+- Текущий статус задачи
+
+При получении уведомления вы можете нажать **Подробнее о задаче**, чтобы открыть карточку задачи.
+
+**Примечание:** если задача завершена (статус FINISHED), уведомления о дедлайне отключаются автоматически.
+
+---
+
+## 9. Частые вопросы
+
+### Я не вижу никаких задач
+- Убедитесь, что вы написали боту `/start` хотя бы раз.
+- Возможно, вам ещё не назначены задачи. Уточните у администратора.
+- Проверьте фильтр по статусу — возможно, выбран статус, по которому нет задач.
+
+### Мне не приходят уведомления
+- Убедитесь, что вы не заблокировали бота в Telegram.
+- Уведомления настраивает администратор. Возможно, они отключены.
+
+### Бот не распознаёт мой @username в чате
+- Проверьте, что вы написали боту `/start` — это необходимо для регистрации.
+- Убедитесь, что у вас установлен username в настройках Telegram.
+
+### Как узнать, кто создал задачу?
+- В карточке задачи может быть указан создатель. Если нет — уточните у администратора.
+
+### Я случайно поставил статус FINISHED
+- Откройте задачу и измените статус обратно на нужный (например, IN_WORK).
+- Учтите, что при переводе в FINISHED уже создана задача на проверку — администратор получил уведомление.
+
+### Как мне связаться с администратором бота?
+- Обратитесь к тому, кто добавил бота в ваш рабочий чат — это администратор или суперадминистратор системы.
+
+---
+
+## Краткий справочник
+
+| Действие | Как сделать |
+|---|---|
+| Открыть меню | `/start` в ЛС с ботом |
+| Мои задачи | `/my_tasks` или **📋 Задачи** → **📗 Мои задачи** |
+| Инлайн-запрос задач | `@имя_бота Задачи` в любом чате |
+| Фильтр по статусу | Кнопки под списком задач |
+| Фильтр по дате | Отправить дату в формате `ДД.ММ.ГГГГ` |
+| Изменить статус задачи | Открыть задачу → Изменить статус |