new_lottery_bot/docs/REGISTRATION_SYSTEM.md

Система регистрации и верификации выигрышей

Архитектура

Модели данных

1. User (Расширенная)

• club_card_number - номер клубной карты (уникальный идентификатор клиента)
• phone - телефон для связи
• is_registered - прошел ли полную регистрацию
• verification_code - секретный код для подтверждения выигрыша (генерируется автоматически)

2. Account (Новая)

• account_number - номер счета в формате XX-XX-XX-XX-XX-XX-XX
• owner_id - владелец счета (связь с User через club_card_number)
• is_active - активен ли счет

3. WinnerVerification (Новая)

• winner_id - связь с Winner
• verification_token - токен для подтверждения выигрыша
• is_verified - подтвержден ли выигрыш
• expires_at - срок действия токена (24 часа)

Процессы

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

Инициатор: Обычный пользователь через бота

Шаги:

1. Пользователь отправляет /start
2. Бот проверяет is_registered
3. Если False - запрашивает:
   • Номер клубной карты
   • Телефон (опционально)
4. Генерируется verification_code (8-символьный уникальный код)
5. Код показывается пользователю: "Ваш код верификации: AB12CD34. Сохраните его!"
6. is_registered = True

2. Создание счета администратором

Инициатор: Администратор

Формат команды:

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

Процесс:

1. Админ отправляет команду с номером КК и счетом
2. Бот находит пользователя по club_card_number = 2223
3. Создается запись в таблице accounts:

   Account(
       account_number="11-22-33-44-55-66-77",
       owner_id=user.id,
       is_active=True
   )
   

4. Пользователю отправляется уведомление:

   ✅ К вашему профилю добавлен счет:
   11-22-33-44-55-66-77
   

3. Проведение розыгрыша с уведомлением победителей

Процесс:

1. Администратор проводит розыгрыш

2. Выбирается случайный счет (например, 11-22-33-44-55-66-77)

3. Система ищет владельца счета:

   account = Account.query.filter_by(account_number="11-22-33-44-55-66-77").first()
   user = account.owner if account else None
   

4. Создается запись Winner и WinnerVerification:

   winner = Winner(
       lottery_id=lottery.id,
       user_id=user.id if user else None,
       account_number="11-22-33-44-55-66-77",
       place=1,
       prize="iPhone 15"
   )
   
   verification = WinnerVerification(
       winner_id=winner.id,
       verification_token=generate_token(),
       expires_at=now + 24hours
   )
   

5. Если user найден - отправляется личное сообщение:

   🎉 ПОЗДРАВЛЯЕМ!
   
   Вы выиграли 1 место в розыгрыше "Новогодний розыгрыш"!
   🏆 Приз: iPhone 15
   
   📋 Ваш выигрышный счет: 11-22-33-44-55-66-77
   
   ✅ Для подтверждения выигрыша:
   1. Свяжитесь с администратором @admin_username
   2. Сообщите ваш код верификации: AB12CD34
   3. Администратор подтвердит ваш выигрыш в системе
   
   ⏰ Срок подтверждения: 24 часа
   

4. Верификация выигрыша администратором

Сценарий:

1. Победитель связывается с админом в личных сообщениях

2. Сообщает код верификации: AB12CD34

3. Админ проверяет код в боте:

   /verify_winner AB12CD34 1
   

   где 1 - ID розыгрыша

4. Система:

   • Находит пользователя по verification_code = "AB12CD34"
   • Проверяет, что у него есть выигрыш в розыгрыше #1
   • Помечает winner.is_claimed = True
   • Обновляет verification.is_verified = True

5. Победителю отправляется:

   ✅ Ваш выигрыш подтвержден!
   
   Администратор свяжется с вами для получения приза.
   

Дополнительные механизмы безопасности

1. Двухфакторная верификация (опционально)

Можно добавить отправку одноразового кода на телефон победителя.

2. Ограничение по времени

Токены верификации действуют 24 часа. После истечения срока требуется повторная генерация.

3. Логирование

Все действия с выигрышами логируются:

• Создание выигрыша
• Отправка уведомления
• Подтверждение администратором
• Получение приза

API для админа

Команды бота

/add_account <club_card> <account_number>

Добавить счет к профилю клиента

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

/remove_account <account_number>

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

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

/verify_winner <verification_code> <lottery_id>

Подтвердить выигрыш победителя

/verify_winner AB12CD34 1

/winner_status <lottery_id>

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

/winner_status 1

Результаты:
1 место - @username (КК: 2223) ✅ Подтвержден
2 место - Счет: 33-44-55-66-77-88-99 ⏳ Ожидает подтверждения
3 место - @user2 (КК: 4445) ❌ Не подтвержден (истек срок)

Аналитика и отчеты

Запросы для аналитики

-- Победители по клубным картам
SELECT 
    u.club_card_number,
    u.first_name,
    COUNT(w.id) as total_wins,
    SUM(CASE WHEN w.is_claimed THEN 1 ELSE 0 END) as claimed_wins
FROM users u
JOIN winners w ON w.user_id = u.id
GROUP BY u.id;

-- Счета с наибольшим количеством участий
SELECT 
    a.account_number,
    u.club_card_number,
    COUNT(p.id) as participation_count
FROM accounts a
JOIN users u ON u.id = a.owner_id
JOIN participations p ON p.account_id = a.id
GROUP BY a.id, u.id
ORDER BY participation_count DESC;

-- Невостребованные выигрыши
SELECT 
    l.title,
    w.place,
    w.prize,
    w.account_number,
    u.club_card_number
FROM winners w
JOIN lotteries l ON l.id = w.lottery_id
LEFT JOIN users u ON u.id = w.user_id
WHERE w.is_claimed = false
    AND w.created_at < NOW() - INTERVAL '24 hours';

Миграция существующих данных

Если у вас уже есть данные в старой схеме:

# Миграция старых account_number из users в таблицу accounts
async def migrate_accounts():
    users = await session.execute(select(User).where(User.account_number != None))
    for user in users.scalars():
        account = Account(
            account_number=user.account_number,
            owner_id=user.id,
            is_active=True
        )
        session.add(account)
        user.account_number = None  # Очищаем старое поле
    await session.commit()

Тестирование

Сценарий 1: Полный цикл выигрыша

1. Регистрация пользователя (КК: 2223)
2. Админ добавляет счет: /add_account 2223 11-22-33-44-55-66-77
3. Счет участвует в розыгрыше
4. Счет выигрывает 1 место
5. Пользователю приходит уведомление с кодом
6. Пользователь связывается с админом, сообщает код
7. Админ подтверждает: /verify_winner AB12CD34 1
8. Выигрыш получен ✅

Сценарий 2: Выигрыш незарегистрированного счета

1. Админ добавляет счет без владельца
2. Счет участвует и выигрывает
3. Бот показывает в публичном объявлении: "Счет 11-22-33-44-55-66-77 выиграл!"
4. Владелец счета регистрируется в боте
5. Админ привязывает счет к владельцу
6. Дальше стандартная процедура верификации