Separate staff roles and protect message delivery with operator guides

docs/CASHIER_GUIDE.md

@@ -0,0 +1,79 @@
+# Инструкция кассира
+
+Кассир привязывает счета к клиентам, добавляет участие в открытых розыгрышах, проверяет победителей и отмечает выдачу призов. Создание и проведение розыгрышей, изменение победителей, управление сотрудниками, рассылки и модерация доступны другим ролям.
+
+## Начало смены
+
+1. В личном диалоге с ботом выполните `/start`, затем `/cashier`.
+2. Если доступа нет, отправьте `/my_id` и передайте показанный Telegram ID системному администратору для назначения роли кассира.
+3. Получите от администратора ID и название нужного розыгрыша, условия участия и порядок выдачи призов.
+4. Инструкция доступна по `/cashier_help` и кнопке «Инструкция кассира» в кассе.
+
+Работайте со своего Telegram-аккаунта. Другой кассир может одновременно выполнять свои операции. `/cancel` отменяет текущий ввод, но не откатывает уже сохранённые счета или выдачу.
+
+## Привязка счёта к клиенту
+
+1. Клиент должен запустить бот и пройти регистрацию. Сверьте клубную карту с клиентом по рабочей процедуре.
+2. Проверьте профиль клиента командой `/user_info 2223`, где `2223` — его клубная карта. Затем отправьте команду, указав карту и счёт:
+
+   ```text
+   /add_account 2223 11-22-33-44-55-66-77
+   ```
+
+3. Проверьте ответ бота: карту, владельца и номер счёта.
+4. Если нужно участие, выберите предложенный розыгрыш. Привязка счёта к клиенту и добавление в розыгрыш — отдельные операции.
+
+Для нескольких клиентов отправьте `/add_account` без аргументов и следуйте подсказке: по одной паре `КАРТА СЧЁТ` на строку. Проверяйте итоговый отчёт, особенно пропуски и ошибки.
+
+## Добавление счетов в розыгрыш
+
+1. `/cashier` → выберите нужное название открытого розыгрыша.
+2. Отправьте счета, каждый с новой строки:
+
+   ```text
+   11-22-33-44-55-66-77
+   88-99-00-11-22-33-44
+   ```
+
+3. За один ввод допускается до 1000 распознанных счетов.
+4. Проверьте количества «Добавлено», «Пропущено» и ошибки. Повтор того же счёта в том же розыгрыше не создаёт второго участия.
+
+Если розыгрыш уже проведён или закрыт, бот отклонит добавление. Если активных розыгрышей нет, обратитесь к администратору. Кассир не может открыть или создать розыгрыш.
+
+Счёт без привязки к клиенту тоже может быть добавлен. Чтобы клиент получил личное уведомление и мог подтвердить выигрыш по коду, сначала проверьте привязку счёта к его зарегистрированному профилю.
+
+## Исправление счёта
+
+Для деактивации:
+
+```text
+/remove_account 11-22-33-44-55-66-77
+```
+
+Деактивация не заменяет удаление уже созданного участия. Если счёт попал не в тот розыгрыш, сообщите администратору ID розыгрыша и номер счёта: он проверит и исправит участие. Не добавляйте произвольный новый счёт вместо ошибочного.
+
+## Проверка и выдача приза
+
+1. Узнайте ID проведённого розыгрыша у администратора.
+2. Проверьте выдачу: `/winner_status 12`, где `12` — пример ID.
+3. Попросите клиента открыть «Мой код» в своём боте. Сверьте личность/карту и приз по рабочей процедуре. Код не публикуется в общем чате.
+4. Когда готовы зафиксировать выдачу, отправьте:
+
+   ```text
+   /verify_winner AB12CD34 12
+   ```
+
+5. Проверьте подтверждение бота, место, приз и данные победителя. Повторно проверьте `/winner_status 12` при сомнении.
+
+Команда `/verify_winner` изменяет статус: выигрыш помечается полученным. Это не просто поиск. Повторное подтверждение одного выигрыша отклоняется, в том числе при одновременной работе кассиров. Ошибка уведомления победителю не отменяет сохранённое подтверждение выдачи.
+
+Если выигрыш не найден, проверьте код, ID, завершение розыгрыша и предыдущую выдачу. Если у клиента несколько призовых мест, согласуйте с администратором порядок выдачи: команда подтверждает одно ещё не полученное место за вызов. При отсутствии привязки победившего счёта к профилю обратитесь к администратору.
+
+## Когда обращаться к администратору
+
+- Неверная карта или владелец, неизвестный счёт, ошибка участия.
+- Нет открытого розыгрыша или требуется изменение результата.
+- Код не подходит, статус выдачи расходится с фактической выдачей.
+- Бот не отвечает: попробуйте `/start`, затем сообщите время, команду и ID розыгрыша. Не повторяйте выдачу без проверки статуса.
+
+Кассиру доступны обычные пользовательские функции, включая чат. `/chat` распространяет сообщения участникам; `/exit` завершает режим чата. Все кассовые команды выполняйте в личном диалоге с ботом.