docs/guide-superadmin.md

# Руководство суперадминистратора

> 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 <запрос>` | Группа | Поиск по базе знаний проекта |

> **ЛС** — личные сообщения с ботом, **Группа** — групповой чат, где бот администратор.