new_lottery_bot/docs/ADMIN_GUIDE.md

# Инструкция администратора

Администратор ведёт пользователей, участников и розыгрыши, работает с рассылками и модерацией чата. Назначение сотрудников доступно только системному администратору.

## Вход и навигация

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`. Если счёт уже включён в открытый розыгрыш, отдельно проверьте и исправьте участие в разделе «Участники».

Карту, телефон и код получения приза обсуждайте в личном диалоге с клиентом. Общий чат распространяет сообщения другим участникам.

## Подготовка розыгрыша

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. При сетевой ошибке сначала проверьте сохранённый результат или статус выдачи. Повторный запуск не должен использоваться для «исправления» недоставленного уведомления.

«Завершить» закрывает розыгрыш; «Удалить» удаляет его данные. Не используйте удаление для архивирования результатов. Ручные изменения и повторные розыгрыши применяйте только по правилам вашего мероприятия.

## Рассылки и чат

1. «Рассылки» → выберите отправку в личные сообщения либо настроенный канал/группу.
2. Отправьте готовое сообщение. После отправки текста/медиа рассылка запускается сразу.
3. Во время рассылки можно открыть `/admin` и продолжить работу. Одновременно выполняются до двух рассылок, по одной от администратора.
4. Дождитесь отчёта с количеством доставленных и недоставленных сообщений. Недоступный получатель не останавливает остальных. Долгое ожидание Telegram или ошибка сообщения учитываются как неудачная доставка.
5. Если рассылка прервана, часть получателей уже могла получить сообщение. Проверьте журнал и результат перед повтором. После перезапуска бота незавершённые фоновые рассылки автоматически не возобновляются.

Премиум-эмодзи и форматирование сохраняются при копировании исходного сообщения в пределах возможностей Telegram. Ошибка отдельного эмодзи не помечает пользователя как заблокировавшего бот.

`/chat` включает общий чат, `/exit` выходит из него. Для модерации используйте административные разделы сообщений и чата. Не отправляйте служебные коды и данные клиентов в общий чат.

## Если действие не сработало

- «Недостаточно прав»: обратитесь к системному администратору; кассиру административная панель недоступна.
- Бот ждёт другой ввод: `/cancel`, затем нужная команда.
- Нет активного розыгрыша: проверьте статус и ID в «Список всех».
- Нет ответа: проверьте `/start`; сообщите системному администратору время, действие и ID розыгрыша. Не повторяйте выдачу приза, пока не проверен `/winner_status`.