docs/guide-admin.md

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

> 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` не работает**
→ Чат должен быть привязан к проекту, и в проекте должны быть загружены документы.