feat: Complete Admin Dashboard with game control and player management (v0.0.8-alpha)
## Major Features Added - **🎛️ Complete Admin Dashboard**: Real-time player monitoring with detailed stats - **👥 Player Management**: Individual and mass player kicking with proper notifications - **🎯 Global Round Control**: Advance/retreat rounds across all rooms simultaneously - **⏸️ Game Control**: Pause/resume games from admin interface - **🔔 Client Notifications**: Players receive alerts for kicks and round changes ## Technical Improvements - **🏗️ Official Colyseus API**: Replaced global variable hacks with `matchMaker.query()` and `matchMaker.remoteRoomCall()` - **📡 Proper Client Communication**: Implemented broadcast messages for `adminKicked`, `gamePaused`, `gameResumed`, `roundChanged` - **🎮 Enhanced GameRoom Methods**: Added `pauseGame()`, `resumeGame()`, `advanceRound()`, `previousRound()`, `_forceClientDisconnect()`, `_forceDisconnectAllClients()`, `getInspectData()` ## UI/UX Enhancements - **📊 Detailed Player Info**: Name, room, role, producer type, and current tokens (🦃☕🌽) - **🚫 Proper Kick Notifications**: Clients auto-redirect to home with clear messaging - **🎨 Improved Admin Interface**: Better organized controls for non-technical commentators - **📱 Responsive Design**: Works well on different screen sizes ## Bug Fixes - **🔧 Fixed Admin Service URLs**: Now correctly calls Colyseus server (port 2567) instead of admin server (port 3001) - **✅ Mass Kick Notifications**: All players receive proper notifications when expelled en masse - **🔄 Auto-redirect**: Kicked clients properly return to home screen ## Architecture - **🏗️ Clean API Design**: All admin endpoints use official Colyseus patterns - **🔒 Type Safety**: Maintained TypeScript sync between server and clients - **📦 Microservices Ready**: Separated concerns between game server and admin interface **Breaking Changes:** None - fully backward compatible **Migration:** No migration needed
This commit is contained in:
358
admin/README.md
Normal file
358
admin/README.md
Normal file
@@ -0,0 +1,358 @@
|
||||
# 🎛️ SnatchGame Admin Dashboard
|
||||
|
||||
[](https://github.com/username/snatchgame)
|
||||
[](https://vuejs.org/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
|
||||
**Interfaz de administración completa** para el control y monitoreo en tiempo real del juego **SnatchGame**. Diseñada para administradores técnicos, personal no-técnico y comentaristas deportivos.
|
||||
|
||||
## 📊 Características Principales
|
||||
|
||||
### **🔄 Monitoreo en Tiempo Real**
|
||||
- **👥 Lista de Jugadores Detallada**: Nombre, sala, rol, tipo de productor
|
||||
- **🎯 Estado de Tokens**: Cantidad actual de 🦃 pavos, ☕ café, 🌽 maíz por jugador
|
||||
- **📈 Estadísticas Globales**: Jugadores conectados, partidas activas, ronda actual
|
||||
- **🔗 Estado de Conexión**: Indicador visual de jugadores conectados/desconectados
|
||||
- **⚡ Actualización Automática**: SSE con polling cada 500ms
|
||||
|
||||
### **🎮 Control del Juego**
|
||||
- **⏮️ Retroceder Ronda**: Cambio global a ronda anterior (mínimo 1)
|
||||
- **⏭️ Avanzar Ronda**: Cambio global a ronda siguiente (máximo 10)
|
||||
- **⏸️ Pausar Juego**: Pausar todas las partidas activas
|
||||
- **▶️ Reanudar Juego**: Reanudar partidas pausadas
|
||||
|
||||
### **👥 Gestión de Jugadores**
|
||||
- **🚫 Expulsar Jugador Individual**: Con notificación automática al cliente
|
||||
- **🚫🚫 Expulsar Todos los Jugadores**: Vaciar todas las salas con notificaciones
|
||||
- **🏠 Redirección Automática**: Los jugadores expulsados vuelven al home
|
||||
- **📱 Notificaciones Inmediatas**: Alerts personalizados para cada acción
|
||||
|
||||
### **🎯 Usuarios Objetivo**
|
||||
- **👨💼 Administrador No-Técnico**: Vista limpia con estadísticas esenciales
|
||||
- **👨💻 IT Profesional**: Información de debugging y estado técnico
|
||||
- **🎙️ Comentaristas Deportivos**: Información clara para narración en vivo
|
||||
|
||||
## 🏗️ Arquitectura Técnica
|
||||
|
||||
### **Stack Tecnológico**
|
||||
- **Frontend**: Vue 3 + Composition API + TypeScript
|
||||
- **Build Tool**: Vite (desarrollo) + Express (producción)
|
||||
- **Comunicación**: HTTP (control) + fetch API
|
||||
- **Styling**: CSS vanilla con diseño responsivo
|
||||
- **Types**: Auto-generados desde servidor con schema-codegen
|
||||
|
||||
### **Comunicación con Servidor**
|
||||
```typescript
|
||||
// Admin Service comunica con servidor Colyseus
|
||||
adminService.kickPlayer(playerId) // → POST /api/admin/kick-player
|
||||
adminService.advanceRound() // → POST /api/admin/advance-round
|
||||
adminService.pauseGame() // → POST /api/admin/pause-game
|
||||
```
|
||||
|
||||
### **Arquitectura del Sistema**
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ Admin UI │ │ Colyseus │ │ Game Client │
|
||||
│ Port 3001 │───▶│ Server │◄──▶│ Port 3000 │
|
||||
│ (Vue 3) │ │ Port 2567 │ │ (Vue 3) │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
│ │ │
|
||||
└───── HTTP/Fetch ──────┘ │
|
||||
│ │
|
||||
┌───────────▼───────────┐ │
|
||||
│ Notifications │ │
|
||||
│ (adminKicked, │◄─────────┘
|
||||
│ roundChanged) │
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
## 🚀 Instalación y Ejecución
|
||||
|
||||
### **Prerrequisitos**
|
||||
- Node.js >= 18.0.0
|
||||
- npm >= 8.0.0
|
||||
- Servidor Colyseus ejecutándose en puerto 2567
|
||||
|
||||
### **Desarrollo**
|
||||
```bash
|
||||
# Desde el directorio admin
|
||||
cd admin
|
||||
|
||||
# Instalar dependencias
|
||||
npm install
|
||||
|
||||
# Generar tipos desde servidor
|
||||
npm run generate-types
|
||||
|
||||
# Iniciar desarrollo
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### **Producción**
|
||||
```bash
|
||||
# Build para producción
|
||||
npm run build
|
||||
|
||||
# Iniciar servidor Express
|
||||
npm start
|
||||
```
|
||||
|
||||
### **URLs**
|
||||
- **Desarrollo**: http://localhost:3001
|
||||
- **Producción**: Configurado según variables de entorno
|
||||
|
||||
## 📁 Estructura del Proyecto
|
||||
|
||||
```
|
||||
admin/
|
||||
├── src/
|
||||
│ ├── components/ # Componentes Vue
|
||||
│ ├── services/ # Servicios de comunicación
|
||||
│ │ └── adminService.ts # API client para servidor Colyseus
|
||||
│ ├── types/ # Tipos auto-generados
|
||||
│ │ ├── GameState.ts # Estado del juego
|
||||
│ │ ├── Player.ts # Información de jugador
|
||||
│ │ ├── TokenInventory.ts # Inventario de tokens
|
||||
│ │ └── index.ts # Re-exports y tipos auxiliares
|
||||
│ ├── App.vue # Componente principal
|
||||
│ └── main.ts # Entry point
|
||||
├── server.js # Express server (producción)
|
||||
├── package.json # Dependencias y scripts
|
||||
├── vite.config.ts # Configuración Vite
|
||||
└── README.md # Este archivo
|
||||
```
|
||||
|
||||
## 🎨 Interfaz de Usuario
|
||||
|
||||
### **Dashboard Principal**
|
||||
```
|
||||
📊 SnatchGame Dashboard 🟢 Conectado
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 👥 Jugadores: 6 🎮 Partidas: 2 🎯 Ronda: 3 │
|
||||
│ 📊 Estado: En progreso │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
🎛️ Control del Juego
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ ⏮️ Retroceder ⏭️ Avanzar ⏸️ Pausar ▶️ Reanudar │
|
||||
│ Ronda Ronda Juego Juego │
|
||||
│ │
|
||||
│ 🚫 Expulsar 🚫🚫 Expulsar │
|
||||
│ Jugador Jugadores │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
👥 Lista de Jugadores (6)
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Juan Carlos 🟢 Sala: a3f2b1 │
|
||||
│ Comerciante 🦃 Productor de Pavos │
|
||||
│ 🦃 3 ☕ 2 🌽 1 🚫 Expulsar │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ María López 🟢 Sala: a3f2b1 │
|
||||
│ Comerciante ☕ Productor de Café │
|
||||
│ 🦃 1 ☕ 4 🌽 2 🚫 Expulsar │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### **Responsive Design**
|
||||
- **Desktop**: Layout de 2 columnas con información completa
|
||||
- **Tablet**: Layout adaptativo con botones optimizados
|
||||
- **Mobile**: Layout vertical con información esencial
|
||||
|
||||
## ⚙️ Configuración
|
||||
|
||||
### **Variables de Entorno**
|
||||
```env
|
||||
# .env.development
|
||||
VITE_ADMIN_PORT=3001
|
||||
NODE_ENV=development
|
||||
|
||||
# .env.production
|
||||
VITE_ADMIN_PORT=3001
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
### **AdminService Configuration**
|
||||
```typescript
|
||||
// src/services/adminService.ts
|
||||
class AdminService {
|
||||
private serverUrl = 'http://localhost:2567' // Colyseus server
|
||||
|
||||
// Todos los métodos apuntan al servidor Colyseus
|
||||
async kickPlayer(playerId: string) { /* ... */ }
|
||||
async advanceRound() { /* ... */ }
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 API Reference
|
||||
|
||||
### **AdminService Methods**
|
||||
|
||||
#### **Control de Jugadores**
|
||||
```typescript
|
||||
// Expulsar jugador específico
|
||||
await adminService.kickPlayer('player-session-id')
|
||||
|
||||
// Expulsar todos los jugadores
|
||||
await adminService.kickAllPlayers()
|
||||
```
|
||||
|
||||
#### **Control del Juego**
|
||||
```typescript
|
||||
// Pausar todas las partidas
|
||||
await adminService.pauseGame()
|
||||
|
||||
// Reanudar partidas pausadas
|
||||
await adminService.resumeGame()
|
||||
```
|
||||
|
||||
#### **Control de Rondas**
|
||||
```typescript
|
||||
// Avanzar ronda globalmente
|
||||
await adminService.advanceRound()
|
||||
|
||||
// Retroceder ronda globalmente
|
||||
await adminService.previousRound()
|
||||
```
|
||||
|
||||
#### **Gestión de Partidas**
|
||||
```typescript
|
||||
// Cancelar partida específica
|
||||
await adminService.cancelGame('room-id')
|
||||
|
||||
// Cancelar todas las partidas
|
||||
await adminService.cancelGame()
|
||||
```
|
||||
|
||||
### **Endpoints del Servidor**
|
||||
Todos los endpoints están en el **servidor Colyseus** (puerto 2567):
|
||||
|
||||
- `GET /api/admin/stats` - Estadísticas en tiempo real
|
||||
- `POST /api/admin/kick-player` - Expulsar jugador específico
|
||||
- `POST /api/admin/kick-all-players` - Expulsar todos los jugadores
|
||||
- `POST /api/admin/pause-game` - Pausar juego
|
||||
- `POST /api/admin/resume-game` - Reanudar juego
|
||||
- `POST /api/admin/advance-round` - Avanzar ronda
|
||||
- `POST /api/admin/previous-round` - Retroceder ronda
|
||||
- `POST /api/admin/cancel-game` - Cancelar partida
|
||||
|
||||
## 🔔 Sistema de Notificaciones
|
||||
|
||||
### **Notificaciones a Clientes**
|
||||
El admin puede enviar notificaciones automáticas que los clientes reciben:
|
||||
|
||||
```typescript
|
||||
// El cliente recibe estos mensajes automáticamente
|
||||
client.onMessage("adminKicked", (data) => {
|
||||
alert("🚫 Has sido expulsado por el administrador")
|
||||
// Auto-redirección a home screen
|
||||
})
|
||||
|
||||
client.onMessage("roundChanged", (data) => {
|
||||
alert(`🎯 ${data.message}`) // "Ronda 3 - Cambio realizado por el administrador"
|
||||
})
|
||||
```
|
||||
|
||||
### **Experiencia del Usuario**
|
||||
1. **Admin ejecuta acción** (expulsar, cambiar ronda, etc.)
|
||||
2. **Servidor procesa** usando API oficial de Colyseus
|
||||
3. **Clientes reciben notificación** inmediata y automática
|
||||
4. **Redirección automática** cuando corresponde (expulsión)
|
||||
|
||||
## 🛠️ Desarrollo
|
||||
|
||||
### **Scripts Disponibles**
|
||||
```bash
|
||||
# Desarrollo con hot reload
|
||||
npm run dev
|
||||
|
||||
# Generar tipos desde servidor
|
||||
npm run generate-types
|
||||
|
||||
# Build para producción
|
||||
npm run build
|
||||
|
||||
# Preview del build
|
||||
npm run preview
|
||||
|
||||
# Servidor Express (producción)
|
||||
npm start
|
||||
```
|
||||
|
||||
### **Debugging**
|
||||
```bash
|
||||
# Verificar que el servidor Colyseus esté ejecutándose
|
||||
curl http://localhost:2567/
|
||||
|
||||
# Verificar endpoint de stats
|
||||
curl http://localhost:2567/api/admin/stats
|
||||
|
||||
# Ver logs del admin en desarrollo
|
||||
npm run dev
|
||||
# Abrir DevTools (F12) para logs detallados
|
||||
```
|
||||
|
||||
### **Type Generation**
|
||||
```bash
|
||||
# Los tipos se generan automáticamente desde el servidor
|
||||
cd admin
|
||||
npm run generate-types
|
||||
|
||||
# Esto ejecuta:
|
||||
# cd ../server && npx schema-codegen src/rooms/GameRoom.ts --ts --output ../admin/src/types/
|
||||
```
|
||||
|
||||
## 🚀 Deploy
|
||||
|
||||
### **Docker (Recomendado)**
|
||||
```bash
|
||||
# Desde el directorio raíz del proyecto
|
||||
docker-compose up -d
|
||||
|
||||
# El admin estará disponible en el puerto configurado
|
||||
```
|
||||
|
||||
### **Manual**
|
||||
```bash
|
||||
# Build admin
|
||||
cd admin
|
||||
npm run build
|
||||
|
||||
# Start en producción
|
||||
npm start
|
||||
```
|
||||
|
||||
## 🤝 Contribuir
|
||||
|
||||
### **Estructura de Contribución**
|
||||
1. **Servidor primero**: Implementar nuevos endpoints en `/server/src/app.config.ts`
|
||||
2. **GameRoom methods**: Agregar métodos necesarios en `/server/src/rooms/GameRoom.ts`
|
||||
3. **AdminService**: Actualizar `/admin/src/services/adminService.ts`
|
||||
4. **UI Components**: Modificar `/admin/src/App.vue` según necesidad
|
||||
5. **Types**: Regenerar con `npm run generate-types`
|
||||
|
||||
### **Convenciones**
|
||||
- **Endpoints**: Prefijo `/api/admin/` para todas las rutas admin
|
||||
- **Métodos GameRoom**: Prefijo `_` para métodos admin (ej: `_forceClientDisconnect`)
|
||||
- **Notificaciones**: Mensajes descriptivos en español para usuarios
|
||||
- **Error Handling**: Try/catch en todos los métodos async
|
||||
|
||||
## 📄 Licencia
|
||||
|
||||
Este microservicio es parte del proyecto **SnatchGame** bajo licencia **MIT**.
|
||||
|
||||
## 🙋♂️ Soporte
|
||||
|
||||
- **Documentación Principal**: `/README.md` (directorio raíz)
|
||||
- **Guía Técnica**: `/CLAUDE.md`
|
||||
- **Issues**: [GitHub Issues](https://github.com/username/snatchgame/issues)
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**🎛️ Admin Dashboard Completo para SnatchGame**
|
||||
|
||||
*Control total • Monitoreo en tiempo real • Notificaciones automáticas*
|
||||
|
||||
</div>
|
||||
Reference in New Issue
Block a user