josedario87
eb6d19906b
## 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
358 lines
13 KiB
Markdown
358 lines
13 KiB
Markdown
# 🎛️ 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> |