poker/ADMIN_USER_MANAGEMENT.md

Управление пользователями (Админ-панель)

Обзор

Добавлена полноценная система управления пользователями в админ-панели с возможностью просмотра статистики, фильтрации, редактирования, блокировки и удаления пользователей.

Новые возможности

📊 Статистика пользователей

• Всего пользователей — общее количество зарегистрированных
• Активных (сегодня) — пользователи с входом сегодня
• Заблокировано — количество заблокированных аккаунтов
• Админов — количество администраторов

🔍 Фильтры

• По роли: Все / Админы / Пользователи
• По статусу: Все / Активные / Заблокированные
• Поиск по логину: Динамический поиск

📋 Таблица пользователей

Отображаемые данные:

• Логин — имя пользователя (с пометкой "Вы" для текущего)
• Роль — 👑 Админ или 👤 Пользователь
• IP адрес — последний известный IP
• Последний вход — относительное время ("2 ч назад", "Вчера")
• Статус — ✅ Активен или 🚫 Заблокирован
• Действия — кнопки управления

⚙️ Действия с пользователями

1. ✏️ Редактировать

   • Изменить роль (Админ/Пользователь)
   • Изменить статус (Активен/Заблокирован)
   • Сменить пароль (опционально)

2. 🚫/✅ Заблокировать/Разблокировать

   • Быстрая блокировка/разблокировка
   • Заблокированные пользователи не могут войти

3. 🗑️ Удалить

   • Полное удаление пользователя
   • Требует двойного подтверждения
   • Нельзя удалить себя

Использование

Открыть вкладку "Пользователи"

1. Войдите как администратор (admin / admin)
2. Откройте Админ-панель (меню → ⚙️ Админ)
3. Выберите вкладку 👥 Пользователи

Просмотр и фильтрация

┌─────────────────────────────────────────────┐
│ [Все роли ▼] [Все статусы ▼] [🔍 Поиск...] │
└─────────────────────────────────────────────┘

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

Редактирование пользователя

1. Нажмите ✏️ напротив пользователя
2. Откроется модальное окно:

   ┌─────────────────────────────────┐
   │ ✏️ Редактирование пользователя │
   ├─────────────────────────────────┤
   │ Логин: [username] (readonly)    │
   │ Роль: [Пользователь ▼]         │
   │ Статус: [Активен ▼]            │
   │ Новый пароль: [________]        │
   │                                  │
   │ [💾 Сохранить] [❌ Отмена]     │
   └─────────────────────────────────┘
   

3. Внесите изменения
4. Нажмите 💾 Сохранить

Блокировка пользователя

Быстрая блокировка:

• Нажмите 🚫 напротив пользователя
• Подтвердите действие
• Пользователь заблокирован

Эффект:

• Пользователь не сможет войти в систему
• При попытке входа: "Ваш аккаунт заблокирован"
• Статус в таблице: 🚫 Заблокирован

Разблокировка:

• Нажмите ✅ напротив заблокированного пользователя
• Подтвердите действие

Удаление пользователя

⚠️ ВНИМАНИЕ: Действие необратимо!

1. Нажмите 🗑️ напротив пользователя
2. Подтвердите удаление (1-е окно)
3. Подтвердите ещё раз (2-е окно для безопасности)
4. Пользователь удалён полностью

Что удаляется:

• Запись пользователя из БД
• Настройки пользователя
• История игр сохраняется для статистики

Ограничения:

• Нельзя удалить себя
• Нельзя удалить единственного админа (рекомендуется)

API Endpoints

POST /api/admin/users

Получить список пользователей с фильтрами.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Body:

{
  "role": "admin|user|",
  "status": "active|banned|",
  "search": "логин для поиска"
}

Response:

{
  "users": [
    {
      "id": "uuid",
      "username": "admin",
      "role": "admin",
      "banned": 0,
      "ipAddress": "127.0.0.1",
      "lastLogin": "2026-02-01T12:00:00Z",
      "createdAt": "2026-01-01T00:00:00Z",
      "totalGames": 42,
      "totalWins": 18,
      "totalChipsWon": 15000
    }
  ],
  "stats": {
    "total": 10,
    "active": 3,
    "banned": 1,
    "admins": 2
  }
}

POST /api/admin/user/update

Обновить данные пользователя.

Body:

{
  "username": "user123",
  "role": "admin",
  "banned": false,
  "password": "новый_пароль" // опционально
}

Response:

{
  "success": true
}

POST /api/admin/user/ban

Заблокировать/разблокировать пользователя.

Body:

{
  "username": "user123",
  "banned": true
}

Response:

{
  "success": true
}

POST /api/admin/user/delete

Удалить пользователя.

Body:

{
  "username": "user123"
}

Response:

{
  "success": true
}

Errors:

• 403 — Нельзя удалить себя
• 404 — Пользователь не найден
• 500 — Ошибка сервера

База данных

Новые поля в таблице users

ALTER TABLE users ADD COLUMN banned INTEGER DEFAULT 0;
ALTER TABLE users ADD COLUMN ip_address TEXT;

Описание:

• banned — флаг блокировки (0 = активен, 1 = заблокирован)
• ip_address — последний известный IP адрес пользователя

Миграция

Поля добавляются автоматически при запуске сервера, если их нет:

✅ Добавлено поле banned в таблицу users
✅ Добавлено поле ip_address в таблицу users

Безопасность

Проверки на сервере

1. Авторизация: Только админы имеют доступ к API
2. Валидация: Проверка наличия обязательных полей
3. Защита от самоблокировки: Нельзя заблокировать/удалить себя
4. Проверка при входе: Блокированные пользователи не могут войти

Логирование

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

database.logAction(adminId, adminUsername, 'update_user', { 
  target: 'user123', 
  changes: { role: 'admin', banned: true }
});

Типы действий:

• view_users — просмотр списка пользователей
• update_user — изменение данных пользователя
• ban_user — блокировка пользователя
• unban_user — разблокировка пользователя
• delete_user — удаление пользователя

Интерфейс

Цветовая индикация

Роли:

• 👑 Админ — фиолетовый градиент
• 👤 Пользователь — серый фон

Статусы:

• ✅ Активен — зелёный фон
• 🚫 Заблокирован — красный фон

Адаптивность

• Desktop (>1024px): Полная таблица
• Tablet (768-1024px): Компактные столбцы
• Mobile (<768px): Горизонтальная прокрутка таблицы

Анимации

• Плавное появление вкладки (fadeInUp 0.3s)
• Hover эффекты на строках таблицы
• Увеличение кнопок при наведении (scale 1.1)

Примеры использования

Создать нового админа

1. Зарегистрируйте пользователя обычным способом
2. Войдите как админ
3. Откройте вкладку 👥 Пользователи
4. Найдите нужного пользователя
5. Нажмите ✏️ Редактировать
6. Измените роль на 👑 Администратор
7. Сохраните

Заблокировать спамера

1. Откройте вкладку 👥 Пользователи
2. Найдите спамера в списке или через поиск
3. Нажмите 🚫 Заблокировать
4. Подтвердите действие
5. Пользователь заблокирован

Посмотреть активных сегодня

1. Откройте вкладку 👥 Пользователи
2. В верхней панели статистики смотрите "Активных (сегодня)"
3. Или используйте фильтр и отсортируйте по "Последний вход"

Сбросить пароль пользователю

1. Откройте вкладку 👥 Пользователи
2. Найдите пользователя
3. Нажмите ✏️ Редактировать
4. Введите новый пароль в поле "Новый пароль"
5. Нажмите 💾 Сохранить
6. Сообщите пользователю новый пароль

Ограничения и рекомендации

Ограничения

• ❌ Нельзя редактировать/удалять себя
• ❌ Нельзя заблокировать себя
• ❌ Удаление необратимо (нет корзины)

Рекомендации

• ✅ Всегда имейте минимум 2 админов
• ✅ Используйте блокировку вместо удаления (можно отменить)
• ✅ Регулярно проверяйте список активных пользователей
• ✅ Следите за IP адресами для выявления дубликатов
• ✅ Логируйте важные действия через вкладку "📋 Логи"

Отладка

Проверка прав доступа

// В консоли браузера
console.log(currentUser?.role); // Должно быть "admin"

Проверка токена

// В консоли браузера
console.log(localStorage.getItem('token'));

Проверка API

# Получить список пользователей
curl -X POST http://localhost:3000/api/admin/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"role":"","status":"","search":""}'

Логи действий

Все административные действия записываются в таблицу action_logs:

SELECT * FROM action_logs 
WHERE action_type IN ('update_user', 'ban_user', 'delete_user')
ORDER BY timestamp DESC
LIMIT 20;

Обновления

Версия 1.0 (2026-02-01)

• ✅ Базовое управление пользователями
• ✅ Фильтры и поиск
• ✅ Редактирование, блокировка, удаление
• ✅ Статистика пользователей
• ✅ Отслеживание IP адресов
• ✅ Проверка блокировки при входе

Планируется:

• 📋 Экспорт списка пользователей в CSV
• 📊 Расширенная статистика по пользователям
• 🔍 Фильтр по дате регистрации
• 📧 Отправка уведомлений пользователям
• 🔐 Двухфакторная аутентификация для админов

---

Документация актуальна для версии: 1.0
Дата: 2026-02-01
Автор: GitHub Copilot