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.