Separate staff roles and protect message delivery with operator guides

docs/ADMIN_GUIDE.md

@@ -1,157 +1,71 @@
-````markdown
-# <20> Полное руководство по админ-панели
+# Инструкция администратора
 
-## 🎯 Обзор
+Администратор ведёт пользователей, участников и розыгрыши, работает с рассылками и модерацией чата. Назначение сотрудников доступно только системному администратору.
 
-Админ-панель предоставляет полный контроль над ботом через удобный интерфейс в Telegram. Доступ: команда `/admin` для администраторов.
+## Вход и навигация
 
-## 📍 Главное меню
+1. Откройте личный диалог с ботом и отправьте `/start`.
+2. Откройте `/admin` или «⚙️ Админ панель».
+3. Используйте разделы «Розыгрыши», «Победители», «Участники», «Пользователи», «Рассылки», «Статистика» и «Настройки».
+4. `/cancel` отменяет текущий ввод. После отмены откройте нужный раздел заново. Уже сохранённые операции эта команда не отменяет.
 
-```
-🎲 Управление розыгрышами     👥 Управление участниками
-👑 Управление победителями    📊 Статистика и отчеты
-⚙️ Настройки системы
-```
+Эта инструкция доступна по `/admin_help` и кнопке «Инструкция администратора». Инструкция по кассовым операциям — `/cashier_help`.
 
----
+## Работа с пользователями
 
-## 🎲 Управление розыгрышами
+1. Попросите клиента выполнить `/start`, затем пройти «Регистрация»: указать данные, которые запрашивает бот.
+2. Откройте «Пользователи» и найдите клиента по точному Telegram ID, клубной карте или username. При нескольких совпадениях сверяйте профиль и карту.
+3. Проверьте регистрацию, клубную карту, связанные счета и участия. Введённая пользователем карта сама по себе не доказывает право владения: сверяйте её по принятой в вашей организации процедуре.
+4. Для привязки счёта используйте `/add_account КАРТА СЧЁТ`, например `/add_account 2223 11-22-33-44-55-66-77`. Затем выберите розыгрыш, если нужно добавить участие.
+5. Для деактивации ошибочного счёта: `/remove_account 11-22-33-44-55-66-77`. Если счёт уже включён в открытый розыгрыш, отдельно проверьте и исправьте участие в разделе «Участники».
 
-### ➕ Создание розыгрыша
-**Мастер создания в 4 шага:**
+Карту, телефон и код получения приза обсуждайте в личном диалоге с клиентом. Общий чат распространяет сообщения другим участникам.
 
-1. **Название** - введите краткое название
-2. **Описание** - подробное описание розыгрыша
-3. **Призы** - список призов (каждый с новой строки)
-4. **Подтверждение** - проверка и создание
+## Подготовка розыгрыша
 
-**Пример:**
-```
-Название: iPhone 15 Pro Max + призы
-Описание: Крутой розыгрыш с айфоном и дополнительными призами
-Призы:
-iPhone 15 Pro Max 512GB
-AirPods Pro 2
-Беспроводная зарядка
-Чехол Apple
-```
+1. «Розыгрыши» → «Создать».
+2. Введите название, описание (или `-` для пропуска) и призы, каждый с новой строки. Порядок призов соответствует местам.
+3. Проверьте итоговый экран и нажмите «Создать».
+4. В «Список всех» откройте карточку, запишите ID розыгрыша и передайте его кассирам вместе с правилами участия.
+5. До начала проведения исправьте название, описание или призы через «Редактировать».
 
-### 📋 Просмотр розыгрышей
-- **Все розыгрыши** с краткой информацией
-- **Детальная информация** при выборе
-- **Статус**: 🟢 Активный / 🔵 Проведен / 🟡 Ожидает
-- **Количество участников** и победителей
+Созданный розыгрыш принимает участников. Завершённый розыгрыш не принимает новые участия.
 
-### ✏️ Редактирование
-- **Изменение названия** и описания
-- **Добавление/удаление призов**
-- **Изменение статуса** розыгрыша
+## Добавление и проверка участников
 
-### 🗑️ Удаление
-- **Безопасное удаление** со всеми связанными данными
-- **Подтверждение** перед удалением
-- **Автоматическая очистка** участников и победителей
+- «Участники» → «Добавить»: выберите розыгрыш и введите Telegram ID или username согласно подсказке.
+- «Участники» → «Массовые операции» → «Добавление по счетам»: выберите розыгрыш и передайте номера в формате `11-22-33-44-55-66-77`.
+- Кассир может добавлять счета через `/cashier`; все сотрудники работают с общей базой, каждый ведёт собственный диалог ввода.
+- Перед проведением проверьте «По розыгрышам» / «Отчёт»: состав, количество участников, отсутствие ошибочно добавленных счетов.
+- Ошибочное участие удаляйте через «Удалить» либо соответствующую массовую операцию до проведения розыгрыша. Повторное добавление того же счёта в один розыгрыш не создаёт второй билет.
 
----
+Бот поддерживает участие по пользователю и по счёту. Используйте способ, соответствующий опубликованным правилам. Счёт может участвовать без связанного профиля; в этом случае автоматическое личное уведомление владельцу невозможно до установления связи.
 
-## 👥 Управление участниками
+## Проведение и выдача призов
 
-### ➕ Добавление участников
+1. Проверьте призы, состав участников и выбранный розыгрыш. Если использовались ручные назначения победителей, проверьте их до запуска: они учитываются при проведении.
+2. «Розыгрыши» → «Провести розыгрыш» → нужный розыгрыш. Выполняйте подтверждения, показанные ботом.
+3. Проверьте сохранённый результат в «Победители» → «Список победителей». Проведение закрывает розыгрыш для новых участников.
+4. Передайте кассиру ID розыгрыша. Статус выдачи: `/winner_status ID`, подтверждение по личному коду клиента: `/verify_winner КОД ID`.
+5. При сетевой ошибке сначала проверьте сохранённый результат или статус выдачи. Повторный запуск не должен использоваться для «исправления» недоставленного уведомления.
 
-**Одиночное добавление:**
-```
-Пользователь: @username или ID
-Выберите розыгрыш: [список доступных]
-```
+«Завершить» закрывает розыгрыш; «Удалить» удаляет его данные. Не используйте удаление для архивирования результатов. Ручные изменения и повторные розыгрыши применяйте только по правилам вашего мероприятия.
 
-**Массовое добавление:**
-```
-Формат: ID1,ID2,ID3 или @user1,@user2,@user3
-Выберите розыгрыш: [список]
-Автоматическое добавление всех валидных пользователей
-```
+## Рассылки и чат
 
-### 👁️ Просмотр участников
-- **По розыгрышам** - участники конкретного розыгрыша
-- **Общий список** - все зарегистрированные пользователи
-- **Детальная информация**: ID, username, дата регистрации
-- **Количество участий** каждого пользователя
+1. «Рассылки» → выберите отправку в личные сообщения либо настроенный канал/группу.
+2. Отправьте готовое сообщение. После отправки текста/медиа рассылка запускается сразу.
+3. Во время рассылки можно открыть `/admin` и продолжить работу. Одновременно выполняются до двух рассылок, по одной от администратора.
+4. Дождитесь отчёта с количеством доставленных и недоставленных сообщений. Недоступный получатель не останавливает остальных. Долгое ожидание Telegram или ошибка сообщения учитываются как неудачная доставка.
+5. Если рассылка прервана, часть получателей уже могла получить сообщение. Проверьте журнал и результат перед повтором. После перезапуска бота незавершённые фоновые рассылки автоматически не возобновляются.
 
-### 🗑️ Удаление участников
-- **Из конкретного розыгрыша**
-- **Полное удаление пользователя** из системы
-- **Подтверждение** перед удалением
+Премиум-эмодзи и форматирование сохраняются при копировании исходного сообщения в пределах возможностей Telegram. Ошибка отдельного эмодзи не помечает пользователя как заблокировавшего бот.
 
----
+`/chat` включает общий чат, `/exit` выходит из него. Для модерации используйте административные разделы сообщений и чата. Не отправляйте служебные коды и данные клиентов в общий чат.
 
-## 👑 Управление победителями (Ключевая функция)
+## Если действие не сработало
 
-### 🎯 Установка ручных победителей
-
-**Процесс:**
-1. **Выберите розыгрыш** из списка
-2. **Укажите место** (1, 2, 3...)
-3. **Выберите пользователя** из участников
-4. **Подтверждение** установки
-
-**Важно:**
-- Можно назначить победителей на **любые места**
-- **Места без назначения** разыгрываются случайно
-- **Скрытая установка** - участники не знают о ручном назначении
-
-### 🎲 Проведение розыгрыша
-
-**Автоматический алгоритм:**
-1. **Ручные победители** автоматически занимают свои места
-2. **Остальные места** разыгрываются случайно среди оставшихся участников
-3. **Результат** выглядит полностью случайным для всех участников
-
-**Пример результата:**
-```
-🏆 Результаты розыгрыша "iPhone + призы"
-
-🥇 1 место: @winner (iPhone 15 Pro) 👑
-🥈 2 место: @random_user (AirPods) 🎲  
-🥉 3 место: @preset_user (Зарядка) 👑
-🏅 4 место: @another_random (Чехол) 🎲
-```
-👑 = Ручной победитель | 🎲 = Случайный
-
-### 📊 Просмотр победителей
-- **По розыгрышам** - все победители конкретного розыгрыша  
-- **История побед** - все победы пользователя
-- **Типы побед**: Ручные (👑) и Случайные (🎲)
-- **Статистика** по каждому пользователю
-
----
-
-## 📊 Статистика и отчеты
-
-### <20> Общая статистика
-```
-👥 Общее количество пользователей: 1,234
-🎲 Общее количество розыгрышей: 45
-👑 Общее количество победителей: 180
-💎 Общее количество призов: 180
-```
-
-### 🏆 Топ рейтинги
-- **Топ-10 пользователей** по количеству участий
-- **Топ-10 победителей** по количеству побед
-- **Самые популярные розыгрыши** по участию
-- **Недавняя активность** (последние 10 действий)
-
-### 📁 Экспорт данных
-- **JSON отчеты** со всей статистикой
-- **Детальная информация** по всем сущностям
-- **Готовые файлы** для анализа и архивирования
-
-### 📊 Производительность
-- **Время ответа** системы
-- **Использование памяти** бота
-- **Статистика использования** админ-панели
-
----
-
-(файл сокращён для краткости в docs)
-````
+- «Недостаточно прав»: обратитесь к системному администратору; кассиру административная панель недоступна.
+- Бот ждёт другой ввод: `/cancel`, затем нужная команда.
+- Нет активного розыгрыша: проверьте статус и ID в «Список всех».
+- Нет ответа: проверьте `/start`; сообщите системному администратору время, действие и ID розыгрыша. Не повторяйте выдачу приза, пока не проверен `/winner_status`.