new_lottery_bot/docs/ADMIN_COMMANDS.md

Админские команды - Руководство

🎯 Управление счетами

/add_account - Добавить счет пользователю

Привязывает счет к зарегистрированному пользователю по клубной карте.

Формат:

/add_account <club_card> <account_number>

Пример:

/add_account 2223 11-22-33-44-55-66-77

Что происходит:

• Система проверяет существование пользователя с указанной клубной картой
• Создает новую запись счета в таблице accounts
• Отправляет уведомление владельцу о добавлении счета
• Счет становится активным и может участвовать в розыгрышах

Возможные ошибки:

• "Пользователь с клубной картой X не найден" - пользователь не зарегистрирован
• "Счет уже существует" - этот номер счета уже привязан к другому пользователю

---

/remove_account - Деактивировать счет

Делает счет неактивным (не удаляет из БД).

Формат:

/remove_account <account_number>

Пример:

/remove_account 11-22-33-44-55-66-77

Что происходит:

• Устанавливает флаг is_active = False
• Счет остается в БД, но не может участвовать в новых розыгрышах
• История участия сохраняется

---

🏆 Управление выигрышами

/verify_winner - Подтвердить выигрыш

Подтверждает выигрыш по коду верификации пользователя.

Формат:

/verify_winner <verification_code> <lottery_id>

Пример:

/verify_winner AB12CD34 1

Процесс верификации:

1. Пользователь сообщает администратору свой код верификации
2. Администратор проверяет, что пользователь является победителем указанного розыгрыша
3. Система устанавливает флаг is_claimed = True для выигрыша
4. Отправляется уведомление победителю о подтверждении

Что происходит:

• Поиск пользователя по коду верификации
• Проверка наличия выигрыша в указанном розыгрыше
• Установка флага is_claimed = True
• Отправка подтверждающего сообщения победителю

Возможные ошибки:

• "Розыгрыш не найден" - неверный lottery_id
• "Выигрыш не найден" - неверный код или пользователь не победитель
• "Выигрыш уже был подтвержден" - повторная попытка подтверждения

---

/winner_status - Статус победителей

Показывает всех победителей розыгрыша и их статус подтверждения.

Формат:

/winner_status <lottery_id>

Пример:

/winner_status 1

Отображаемая информация:

• 🏆 Место и приз
• 👤 Имя и клубная карта победителя
• 💳 Номер счета (если участвовал через счет)
• ✅ Статус подтверждения (подтвержден / ожидает)
• 📨 Статус уведомления (отправлено / нет)

Статусы:

• ✅ - Выигрыш подтвержден (is_claimed = True)
• ⏳ - Ожидает подтверждения (is_claimed = False)
• 📨 - Уведомление отправлено (is_notified = True)
• 📭 - Уведомление не отправлено (is_notified = False)

---

👤 Информация о пользователе

/user_info - Информация о пользователе

Показывает полную информацию о пользователе по клубной карте.

Формат:

/user_info <club_card>

Пример:

/user_info 2223

Отображаемая информация:

• 🎫 Клубная карта
• 👤 Имя и Telegram username
• 📞 Телефон (если указан)
• 🔑 Код верификации
• 📅 Дата регистрации
• 💳 Список всех счетов (активные и неактивные)
• 🏆 История выигрышей

---

🔄 Автоматические уведомления

При проведении розыгрыша (/conduct через кнопку) система автоматически:

1. Определяет владельцев счетов-победителей

   • Ищет запись в таблице accounts
   • Находит владельца через owner_id

2. Создает токен верификации

   • Генерирует уникальный токен для каждого выигрыша
   • Устанавливает срок действия 24 часа
   • Сохраняет в таблице winner_verifications

3. Отправляет уведомление победителю

   🎉 Поздравляем! Ваш счет выиграл!
   
   🎯 Розыгрыш: Название розыгрыша
   🏆 Место: 1
   🎁 Приз: Приз первого места
   💳 Счет: 11-22-33-44-55-66-77
   
   🔑 Ваш код верификации: AB12CD34
   
   Для получения приза свяжитесь с администратором
   и предоставьте этот код.
   

4. Устанавливает флаг уведомления

   • is_notified = True в таблице winners

---

🔐 Система верификации

Как это работает:

1. При регистрации пользователя:

   • Генерируется уникальный 8-символьный код (например, AB12CD34)
   • Сохраняется в users.verification_code
   • Пользователь может посмотреть свой код через /my_code

2. При выигрыше:

   • Владельцу счета отправляется сообщение с его кодом верификации
   • Создается токен в таблице winner_verifications

3. При подтверждении выигрыша:

   • Администратор запрашивает код у победителя
   • Вводит команду /verify_winner AB12CD34 1
   • Система проверяет соответствие кода и наличие выигрыша
   • Устанавливает is_claimed = True

Преимущества:

• 🔒 Безопасность: Только владелец знает свой код
• ✅ Проверка: Невозможно подтвердить чужой выигрыш
• 📊 Отслеживание: Полная история подтверждений
• ⏱️ Контроль: Токены имеют срок действия

---

📊 Типичные сценарии

Сценарий 1: Новый пользователь с двумя счетами

1. Пользователь: /start → "Зарегистрироваться"
2. Пользователь: Вводит клубную карту "2223"
3. Пользователь: Вводит телефон или пропускает
4. Система: Показывает код верификации "AB12CD34"

5. Админ: /add_account 2223 11-22-33-44-55-66-77
6. Админ: /add_account 2223 88-99-00-11-22-33-44

7. Пользователь: /my_accounts
   → Видит оба счета

Сценарий 2: Проведение розыгрыша и подтверждение

1. Админ: Создает розыгрыш через интерфейс
2. Счета участвуют автоматически
3. Админ: Нажимает "Провести розыгрыш"

4. Система: Автоматически отправляет уведомления:
   "🎉 Поздравляем! Ваш счет выиграл!
    💳 Счет: 11-22-33-44-55-66-77
    🔑 Ваш код верификации: AB12CD34"

5. Победитель: Связывается с админом, называет код "AB12CD34"

6. Админ: /verify_winner AB12CD34 1
7. Система: Подтверждает выигрыш, отправляет уведомление победителю

Сценарий 3: Проверка статуса всех победителей

1. Админ: /winner_status 1

Результат:
🏆 Победители розыгрыша 'Новогодний розыгрыш':

✅ 1 место - Главный приз
   👤 Иван (КК: 2223)
   💳 11-22-33-44-55-66-77
   ✅ Подтвержден

⏳ 2 место - Второй приз
   👤 Петр (КК: 3334)
   💳 22-33-44-55-66-77-88
   ⏳ Ожидает подтверждения

---

🛠️ Техническая информация

Таблицы базы данных:

accounts - Счета пользователей

• account_number - Номер счета (формат XX-XX-XX-XX-XX-XX-XX)
• owner_id - ID владельца (FK → users.id)
• is_active - Активен ли счет
• created_at - Дата создания

winner_verifications - Токены верификации выигрышей

• winner_id - ID выигрыша (FK → winners.id)
• verification_token - Уникальный токен
• is_verified - Подтвержден ли
• verified_at - Время подтверждения
• expires_at - Срок действия (24 часа)

winners - Победители (расширенная)

• Добавлены поля: is_notified, is_claimed

users - Пользователи (расширенная)

• Добавлены поля: club_card_number, phone, is_registered, verification_code

---

📝 Полезные команды для пользователей

• /start - Главное меню / регистрация
• /my_code - Показать свой код верификации
• /my_accounts - Список моих счетов

---

⚠️ Важные замечания

1. Код верификации - строго конфиденциальная информация
2. Один счет = один владелец (нельзя передать счет другому)
3. Деактивация счета - не удаляет историю участия
4. Токены верификации - действуют 24 часа
5. Уведомления - отправляются автоматически только если пользователь зарегистрирован

---

🆘 Решение проблем

Пользователь не получил уведомление о выигрыше:

• Проверить /winner_status <lottery_id> - должна быть отметка 📨
• Возможно, пользователь заблокировал бота
• Проверить telegram_id пользователя через /user_info

Не получается подтвердить выигрыш:

• Проверить код верификации: /user_info <club_card>
• Убедиться что lottery_id верный
• Проверить что выигрыш еще не подтвержден

Счет не добавляется:

• Убедиться что пользователь зарегистрирован
• Проверить формат номера счета (7 пар цифр через дефис)
• Проверить что счет уникален (не добавлен другому пользователю)