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 пар цифр через дефис)
- Проверить что счет уникален (не добавлен другому пользователю)