# Game Management: documentación

> Un panel de administración web para tu staff: jugadores desconectados, la economía y un registro de auditoría.

- URL: https://xexstudio.com/es/docs/game-management
- Versión: 2.3.0
- Ficha del producto: https://xexstudio.com/es/scripts/game-management
## Descripción general

XeX Panel se conecta a la misma base de datos MySQL/MariaDB que usa tu servidor FiveM y ofrece a tu staff una interfaz web para gestionarla.

- No requiere ningún recurso de FiveM: el panel trabaja sobre la base de datos. La página Live y el indicador de conexión leen la API HTTP de tu servidor.
- Un único adaptador (`includes/framework.php`) gestiona ESX, QBCore y Qbox, incluidas las columnas JSON que usan QBCore y Qbox.
- Los recursos opcionales (housing, banca, teléfono, facturación, ox_inventory) se detectan a partir de tu esquema. Las páginas y entradas de menú de los recursos que no uses quedan ocultas.
- Acceso basado en roles con permisos de página y de acción por rol.
- Tokens CSRF, sentencias preparadas, escape de salida y limitación de intentos de inicio de sesión.
- Verificación en dos pasos opcional (códigos TOTP de Google Authenticator, Authy o apps similares), desactivada por defecto.
- Registro de auditoría de las acciones del staff, además de webhooks a Discord, Slack o cualquier endpoint JSON.

---

## Frameworks compatibles

| Framework | Tabla de jugadores | Notas |
| --------- | ------------ | ----- |
| **ESX Legacy** | `users` | Columnas planas (`firstname`, `job`, `job_grade`, …) y una columna JSON `accounts`. |
| **QBCore** | `players` | Columnas JSON `charinfo`, `job`, `gang`, `money`, `metadata`. |
| **Qbox** (qbx_core) | `players` | Misma estructura que QBCore, más `player_groups`, que el panel mantiene sincronizada cuando cambia un trabajo. |
| **Custom** | configurable | Se trata como una estructura tipo ESX. Mapea tus nombres en `$DB_TABLES` (consulta [Configuración](#sobrescritura-de-tablas-y-columnas)). |

### Detección del framework

El instalador inspecciona tu base de datos:

1. Tabla `users` con columnas `identifier` y `accounts` → **ESX**
2. Tabla `players` con columnas `citizenid` y `charinfo` → **QBCore**, o **Qbox** cuando también existe una tabla `player_groups`
3. En cualquier otro caso → **Custom**

Puedes cambiar el valor detectado en el paso de framework del instalador (ESX, QBCore, Qbox o Custom), o más adelante editando `$FRAMEWORK` en `config.php`.

### Cómo se gestionan los datos de QBCore y Qbox

- Los nombres, el trabajo, la banda y las licencias se leen con `JSON_EXTRACT` y se escriben con `JSON_SET`, de modo que solo cambian las claves editadas. El resto de `charinfo`, `job` y `metadata` se deja como estaba.
- El dinero se escribe como números JSON (no cadenas) dentro de la columna `money`.
- Las licencias se guardan en `players.metadata.licences` (`driver`, `weapon`, `business`, más cualquier clave que añadas en Settings).
- Cambiar un trabajo establece `job.name`, `job.grade.level` y `job.onduty = false`. qb-core / qbx_core actualizan la etiqueta del trabajo, el nombre del rango y el salario desde su archivo compartido de trabajos cuando el jugador carga.
- **Qbox:** al cambiar de trabajo, la fila de trabajo de `player_groups` se sustituye (o se elimina cuando el nuevo trabajo es el trabajo por defecto "unemployed").
- Los rangos de trabajo están en `shared/jobs.lua`, no en la base de datos, así que la página Job Grades muestra en su lugar los trabajos en uso y su número de empleados.

---

## Recursos opcionales

El panel lee la lista de tablas una vez y la guarda en caché durante unos 2 minutos (`cache/schema.json`). Para cada función usa la primera fuente que exista. **Settings → System → Detected resources** muestra lo que se ha encontrado, y **Rescan** limpia la caché.

| Función | ESX / Custom | QBCore / Qbox |
| ------- | ------------ | ------------- |
| Housing | `$DB_TABLES['housing']` si está definido, después loaf_housing, esx_property (`owned_properties`), `properties` | ps-housing / qbx_properties (`properties`), qb-houses (`player_houses`) |
| Fondos de negocios | `addon_account_data` (etiquetas de `addon_account`) | qb-management (`management_funds`), qb-banking (`bank_accounts`), Renewed-Banking (`bank_accounts_new`) |
| Facturación | `billing` | qb-phone (`phone_invoices`) |
| Stashes de ox_inventory | `ox_inventory` | `ox_inventory` |
| Teléfono | `phone_phones` (o `$DB_TABLES['phone']`) | `phone_phones` (o `$DB_TABLES['phone']`) |
| Rangos de trabajo | `job_grades` | no está en la base de datos (`shared/jobs.lua`) |
| Licencias | `user_licenses` | `players.metadata.licences` |
| Skins / outfits | `users.skin`, `datastore_data` ("property") | `playerskins`, `player_outfits` |
| Premium / VIP | solo si `$DB_TABLES['premium']` está definido y la tabla existe | igual |

Cuando falta una fuente, su entrada de menú, sus secciones de página, sus tarjetas del panel principal y sus columnas de tabla quedan ocultas.

---

## Funciones

### Gestión básica

| Función | Descripción |
| ------- | ----------- |
| **Dashboard** | Dinero por cuenta, fondos de negocios, usuarios únicos, personajes, vehículos, casas, sociedades, objetos, alertas de anomalías abiertas y acciones recientes del staff. Solo se muestran las tarjetas de los datos que tiene tu servidor. |
| **Players** | Lista de jugadores con búsqueda y ordenación; perfil de jugador con identidad, trabajo, cuentas, inventario, skin y licencias editables. |
| **Vehicles** | Recuento de vehículos, modelos y garajes; borrar por matrícula, enviar al garaje, borrar vehículos de trabajo (ESX). |
| **Societies** | Fondos de trabajos y bandas, miembros con rangos e inventarios de sociedad (ESX). |
| **Housing** | Lista de propiedades con propietarios, desde el recurso de housing detectado. |
| **Job Grades** | ESX: trabajos, rangos y salarios. QBCore/Qbox: trabajos en uso y número de empleados. |
| **Licenses** | Conceder y revocar licencias (ESX `user_licenses`, QB/Qbox `metadata.licences`). |
| **Item Finder** | Encuentra quién tiene un objeto en inventarios, stashes, maleteros y guanteras. |
| **Live Server** | Jugadores conectados e información del servidor desde la URL de la API de tu servidor. |

### Operaciones avanzadas

| Función | Descripción |
| ------- | ----------- |
| **Character Kill (CK)** | Borra un personaje y sus filas en las tablas relacionadas que existan en tu servidor. |
| **Swap** | ESX: mueve todos los datos de un identifier a otro. QBCore/Qbox: mueve un personaje a otra licencia de Rockstar. |
| **Quick search** | `Ctrl+K` / `Cmd+K` desde cualquier página: jugadores (nombre o identifier), matrículas y páginas del panel. |

### Intelligence Suite

| Función | Descripción |
| ------- | ----------- |
| **Economy** | Totales, distribución de riqueza, jugadores más ricos, dinero por trabajo, jugadores con exceso de efectivo. |
| **Business Analytics** | Empleados por trabajo, fondos de sociedades, actividad por trabajo, negocios abandonados, distribución de rangos. |
| **Anomaly Detection** | Alertas de riqueza extrema y saldos negativos, con un flujo para descartarlas. |
| **Analytics** | Dinero por cuenta a lo largo del tiempo (necesita la tarea cron). |
| **Staff Activity** | Acciones del staff a lo largo del tiempo, mapa de calor por horas, desglose por categoría, ranking. |

### Administración

| Función | Descripción |
| ------- | ----------- |
| **Audit Log** | Registro de acciones del staff con filtros, paginación, exportación CSV y purga. |
| **Webhooks** | Varios endpoints con embeds de Discord, attachments de Slack o JSON genérico. |
| **Settings** | 8 pestañas: General, Appearance, Game Config, Economy, Limits, Staff, Permissions, System. |
| **Permissions** | Permisos de página y de acción por rol guardados en la base de datos, más roles personalizados. |
| **Two-step verification** | Desactivada, opcional u obligatoria para todos los admins. Códigos de 6 dígitos de una app de autenticación, 10 códigos de recuperación de un solo uso y reinicio por un Superadmin. |
| **Profile** | Cambiar tu propia contraseña; activar o desactivar la verificación en dos pasos. |

### Interfaz

- Tema oscuro con color de acento y logo configurables.
- Barra lateral agrupada en **Overview**, **Players**, **World**, **Insights** y **Admin**. Se contrae en escritorio (el estado se recuerda) y se convierte en un panel deslizante en móvil.
- Barra superior con el título de la página, búsqueda rápida, perfil y cierre de sesión.
- Visor de skin agrupado en secciones (Identity, Hair, Face, Makeup, Clothing, Damage).
- Contenido de inventarios, stashes, maleteros y guanteras mostrado con etiquetas de objeto y cantidades.
- Gráficas dibujadas con Chart.js.

---

## Requisitos

### Servidor

| Componente | Mínimo | Notas |
| --------- | ------- | ----- |
| **PHP** | 7.4 | Lo comprueba el instalador. Se recomienda PHP 8.1+ por soporte de seguridad. |
| **MySQL** | 5.7.8 | Se requieren las funciones JSON. |
| **MariaDB** | 10.2.7 | Se requieren las funciones JSON y el alias de columna `JSON`. |
| **Servidor web** | Apache 2.4 con `mod_rewrite` y `mod_headers`, o Nginx + PHP-FPM | Las reglas de protección incluidas están en `.htaccess` (solo Apache). |

El panel usa estas funciones JSON de SQL: `JSON_EXTRACT`, `JSON_UNQUOTE`, `JSON_SET`, `JSON_OBJECT` y `JSON_VALID`.

### Extensiones de PHP

| Extensión | Propósito |
| --------- | ------- |
| `pdo_mysql` | Acceso a la base de datos (obligatoria) |
| `json` | Columnas JSON, ajustes, caché (obligatoria) |
| `session` | Sesiones de inicio de sesión (obligatoria) |
| `mbstring` | Iniciales del nombre en la barra lateral, búsqueda rápida, visor de skin. El instalador la lista como opcional, pero instálala. |
| `fileinfo` | Comprobación del tipo de archivo al subir el logo |
| `curl` | Peticiones de la página Live (usa `file_get_contents` como alternativa si falta) |

El directorio del panel y `cache/` deben tener permisos de escritura para el servidor web durante la instalación (el instalador escribe `config.php`). `assets/img/` y `assets/data/` deben tener permisos de escritura para subir el logo y el catálogo de objetos.

### Entornos compatibles

- **XAMPP** (Windows) para instalaciones locales o pequeñas
- **LAMP** (Apache + PHP + MySQL/MariaDB) en Linux
- **Nginx + PHP-FPM**: traslada las reglas de `.htaccess` a tu bloque de servidor (consulta [Seguridad](#protección-de-archivos))
- **Hosting compartido** con PHP 7.4+ y MySQL/MariaDB

---

## Instalación

### Método 1: Instalador (recomendado)

#### 1. Copia los archivos

| Entorno | Ruta |
| ----------- | ---- |
| XAMPP (Windows) | `C:\xampp\htdocs\xex-panel\` |
| Linux / Apache | `/var/www/html/xex-panel/` |
| Nginx | La raíz web que tengas configurada |

#### 2. Abre el instalador

```
http://your-server/xex-panel/install/
```

El instalador tiene seis pasos:

1. **Requirements**: versión de PHP, extensiones, directorios con permisos de escritura.
2. **Database**: host, usuario, contraseña y nombre de tu base de datos de FiveM. El host puede incluir un puerto, por ejemplo `127.0.0.1:3307`.
3. **Framework**: el framework detectado viene preseleccionado. Elige ESX, QBCore, Qbox o Custom.
4. **Review**: lista las tablas del panel que se crearán y las que ya existen. Las tablas del juego no se modifican.
5. **Admin account and panel settings**: usuario, correo y contraseña del superadmin, nombre del panel y URL de la API de FiveM.
6. **Done**: muestra el resultado de cada tabla.

El instalador crea las tablas del panel con `CREATE TABLE IF NOT EXISTS` (filas iniciales con `INSERT IGNORE`), escribe `config.php` y crea `install/installed.lock`.

> **Política de contraseñas:** al menos 8 caracteres con una mayúscula, una minúscula y un número.

#### 3. Inicia sesión

```
http://your-server/xex-panel/
```

Después, borra o bloquea la carpeta `install/`.

---

### Método 2: Instalación manual

#### 1. Importa el esquema

Importa `setup/schema.sql` en tu **base de datos de FiveM** (las tablas del panel conviven con las tablas del juego):

```bash
mysql -u root -p your_database < setup/schema.sql
```

#### 2. Crea `config.php`

`config.php` no se incluye; normalmente lo escribe el instalador. Créalo en la raíz del panel con este contenido:

```php
<?php
$MODE = "production"; // "development" shows PHP errors

if ($MODE === 'production') {
    error_reporting(0);
    ini_set('display_errors', 0);
    ini_set('log_errors', 1);
} else {
    error_reporting(E_ALL);
    ini_set('display_errors', 1);
}

// ─── Database (host may include a port: 127.0.0.1:3307) ───
$DDBB_HOST = 'localhost';
$DDBB_USER = 'root';
$DDBB_PASSWORD = 'your_password';
$DATABASE_NAME = 'your_database';
$HOST = '';

// ─── Framework: "esx" | "qbcore" | "qbox" | "custom" ───
$FRAMEWORK = 'esx';

// ─── Table and column overrides (empty = framework defaults) ───
$DB_TABLES = [];

// ─── Panel ───
$PANEL_NAME = 'Admin Panel';
$API_FIVEM_URL = '';
$WEBHOOK_URL = '';

require_once __DIR__ . '/includes/bootstrap.php';
```

#### 3. Crea una cuenta de administrador

```sql
INSERT INTO superadmins (username, password, email, role, force_password_change)
VALUES ('admin', '$2y$10$your_bcrypt_hash', 'admin@example.com', 3, 1);
```

Genera el hash con `php -r "echo password_hash('your_password', PASSWORD_DEFAULT);"`. Con `force_password_change = 1` el panel pide una contraseña nueva tras el primer inicio de sesión.

#### 4. Bloquea el instalador

Crea un archivo vacío `install/installed.lock` o borra la carpeta `install/`. El instalador también se niega a ejecutarse mientras exista `config.php`, pero el archivo de bloqueo lo mantiene cerrado aunque `config.php` se mueva o se renombre.

---

### Tras la instalación

#### Página Live y estado de conexión

Configura **Settings → General → FiveM API URL**. El valor de `$API_FIVEM_URL` es solo el valor inicial por defecto. Respuestas aceptadas:

- la API de servidores de cfx.re: `https://servers-frontend.fivem.net/api/servers/single/YOUR_SERVER_ID/` (jugadores, variables del servidor y recursos)
- una lista de jugadores simple como el `http://IP:30120/players.json` de tu servidor, o cualquier JSON con un array `players`

El perfil de jugador usa la misma URL para mostrar si la licencia de Rockstar del personaje está conectada. Cuando la URL está vacía, la entrada de menú Live no tiene nada que mostrar.

#### Etiquetas de objetos

Sube tu lista de objetos en **Settings → Game Config → Item catalogue**:

- `ox_inventory/data/items.lua`
- `qb-core/shared/items.lua` (o el equivalente de Qbox)
- o un archivo JSON: `{"water": "Water"}`, `{"water": {"label": "Water"}}` o `[{"name": "water", "label": "Water"}]`

El archivo (hasta 4 MB) se analiza y se guarda como `assets/data/items.json`. Sin una subida, el panel usa la tabla `items` de ESX y, en su defecto, los nombres de objeto encontrados en los inventarios de los jugadores. **Use automatic source** elimina el catálogo subido.

#### Tarea cron de analítica (opcional)

`setup/cronjob_money_analytics.php` guarda una instantánea por cada cuenta que exista en tu servidor (ESX: bank, cash, black money; QBCore/Qbox: bank, cash, crypto; más cualquier moneda personalizada que hayas configurado).

**Linux (crontab):**
```bash
0 */6 * * * php /var/www/html/xex-panel/setup/cronjob_money_analytics.php
```

**Windows (Programador de tareas):**
1. Crear tarea básica → nombre `XeX Panel Analytics`
2. Desencadenador: diario, repetir cada 6 horas
3. Acción: Iniciar un programa
   - Programa: `C:\xampp\php\php.exe`
   - Argumentos: `C:\xampp\htdocs\xex-panel\setup\cronjob_money_analytics.php`

Sin la tarea cron, la página Analytics no tiene datos.

---

## Actualización

1. Haz una copia de seguridad de tu base de datos y de la carpeta del panel.
2. Sustituye **todos los archivos** por los de 2.3.0, **excepto**:
   - `config.php`
   - `install/installed.lock`
   - `assets/img/custom-logo.*` (si existe)
   - `assets/data/items.json` (si existe)
   - `cache/totp-key.php` (si existe: la clave de cifrado de la verificación en dos pasos)
3. Abre el panel.
   - **Desde 2.2:** no hay que hacer nada más. La verificación en dos pasos está desactivada hasta que la actives en **Settings → Staff**, así que todo el mundo inicia sesión como antes. Su tabla (`panel_admin_2fa`) se crea la primera vez que un admin la configura; no se modifica ninguna tabla existente.
   - **Desde 2.1:** un `config.php` generado por 2.1 sigue funcionando: los archivos de bootstrap y seguridad solo definen los valores que la configuración antigua no establece ya. Opcional: sube tu `items.lua` en **Settings → Game Config** (el archivo de objetos incluido con 2.1 ya no se usa) y revisa **Settings → System → Detected resources**.

### Opcional: cambiar a la configuración corta de 2.2

En 2.2, `config.php` solo contiene valores (base de datos, framework, sobrescrituras de `$DB_TABLES`, nombre del panel, URL de la API de FiveM) y termina con `require_once __DIR__ . '/includes/bootstrap.php';`. Los valores por defecto de cada framework están en `includes/framework.php`. Para regenerarlo:

1. Copia tu `config.php` actual a un lugar seguro.
2. Borra `install/installed.lock` y abre `/install/`.
3. Sigue los pasos. Las tablas del panel existentes se conservan (`CREATE TABLE IF NOT EXISTS`, `INSERT IGNORE`), y el instalador sobrescribe `config.php`.
4. El instalador también crea una cuenta de superadmin. Usa un nombre de usuario que no exista todavía, o el paso fallará.
5. La nueva configuración tiene un `$DB_TABLES` vacío. Si tu configuración antigua mapeaba algo que los valores por defecto no cubren (una clave de moneda personalizada, una tabla premium, una tabla renombrada), copia esas claves en el nuevo `$DB_TABLES`.
6. Borra o bloquea de nuevo la carpeta `install/`.

---

## Configuración

Los valores están en `config.php`. La mayoría de las opciones en tiempo de ejecución están en la página **Settings**.

### Modo de la aplicación

```php
$MODE = "production";   // errors logged only (use this in production)
$MODE = "development";  // errors shown on screen
```

### Base de datos

```php
$DDBB_HOST = 'localhost';        // or '127.0.0.1:3307' for a non-default port
$DDBB_USER = 'root';
$DDBB_PASSWORD = 'your_password';
$DATABASE_NAME = 'your_database';
```

### Framework

```php
$FRAMEWORK = 'esx';      // ESX Legacy
$FRAMEWORK = 'qbcore';   // QBCore
$FRAMEWORK = 'qbox';     // Qbox
$FRAMEWORK = 'custom';   // ESX-like layout with your own names in $DB_TABLES
```

### Sobrescritura de tablas y columnas

`$DB_TABLES` es solo para sobrescrituras. Déjalo vacío salvo que tu servidor renombre algo. Los valores por defecto están en `fw_default_tables()` en `includes/framework.php`.

```php
$DB_TABLES = [
    'account_black' => 'dirty_money',   // ESX account key for black money
    'account_coin'  => 'coins',         // extra currency stored in accounts/money JSON
    'housing'       => 'my_houses',     // ESX / Custom: housing table
    'housing_owner' => 'owner',
    'premium'       => 'my_premium',    // optional premium/VIP table
];
```

<details>
<summary><strong>Claves y valores por defecto de ESX / Custom</strong></summary>

| Clave | Por defecto | Significado |
| --- | ------- | ------- |
| `users` | `users` | Tabla de jugadores |
| `users_identifier` | `identifier` | Clave del jugador |
| `users_firstname` / `users_lastname` | `firstname` / `lastname` | Columnas de nombre |
| `users_accounts` | `accounts` | Columna JSON de cuentas |
| `users_group` | `group` | Grupo de administración |
| `users_job` / `users_job_grade` | `job` / `job_grade` | Columnas de trabajo |
| `users_inventory` | `inventory` | JSON del inventario |
| `users_skin` | `skin` | JSON de la skin |
| `users_pincode` | `pincode` | Columna del pincode |
| `users_created_at` / `users_last_seen` | `created_at` / `last_seen` | Fechas |
| `account_bank` / `account_cash` / `account_black` | `bank` / `money` / `black_money` | Claves dentro de `accounts` |
| `account_coin` | ninguno | Clave opcional de moneda extra dentro de `accounts` |
| `vehicles`, `vehicles_owner`, `vehicles_plate` | `owned_vehicles`, `owner`, `plate` | Vehículos |
| `licenses`, `licenses_owner`, `licenses_type` | `user_licenses`, `owner`, `type` | Licencias |
| `job_grades`, `jobs`, `items` | `job_grades`, `jobs`, `items` | Trabajos y objetos |
| `societies`, `society_data` | `addon_account`, `addon_account_data` | Cuentas de sociedad |
| `billing`, `datastore`, `inventory_items` | `billing`, `datastore_data`, `addon_inventory_items` | Otras tablas de ESX |
| `ox_inventory` | `ox_inventory` | Stashes de ox_inventory |
| `housing`, `housing_owner` | detección automática | Tabla de housing |
| `phone` | detección automática (`phone_phones`) | Tabla del teléfono (necesita una columna `id`) |
| `premium` | ninguno | Tabla premium (necesita una columna `identifier` con el hash de la licencia) |

Una columna que no exista en tu tabla se omite, y el campo se oculta en la interfaz.

</details>

<details>
<summary><strong>Claves y valores por defecto de QBCore / Qbox</strong></summary>

La estructura JSON de `players` (`charinfo`, `job`, `gang`, `money`, `metadata`) es fija. Estas claves sí se pueden sobrescribir:

| Clave | Por defecto | Significado |
| --- | ------- | ------- |
| `users` | `players` | Tabla de jugadores |
| `users_accounts` | `money` | Columna JSON del dinero |
| `users_inventory` | `inventory` | JSON del inventario |
| `users_last_seen` | `last_updated` | Última conexión |
| `account_bank` / `account_cash` | `bank` / `cash` | Claves dentro de `money` |
| `account_coin` | `crypto` | Se muestra como la moneda extra ("Crypto") |
| `vehicles` | `player_vehicles` | Tabla de vehículos |
| `skins` | `playerskins` | Tabla de skins |
| `ox_inventory` | `ox_inventory` | Stashes de ox_inventory |
| `phone`, `premium` | como arriba | Tablas opcionales |

Las claves exclusivas de ESX (nombres, grupo, columnas de trabajo, tabla de licencias, rangos de trabajo, sociedades, facturación, datastore, dinero negro, housing) se ignoran en QBCore/Qbox, así que una configuración antigua que las mapeara a `charinfo` no puede escribir texto plano en una columna JSON.

</details>

### Cuentas

| Framework | Cuentas mostradas |
| --------- | -------------- |
| ESX | Banco (`bank`), Efectivo (`money`), Dinero negro (`black_money`) |
| QBCore / Qbox | Banco (`bank`), Efectivo (`cash`), Crypto (`crypto`) como moneda extra |

Define `account_coin` en `$DB_TABLES` para mostrar una moneda personalizada guardada en el JSON de accounts/money. Las etiquetas mostradas se pueden editar en **Settings → Game Config → Account Labels**. La moneda extra no se cuenta en los totales de riqueza.

### Ajustes generales (Settings → General)

| Ajuste | Por defecto |
| ------- | ------- |
| Nombre del panel | `Admin Panel` (o el valor del instalador) |
| URL de la API de FiveM | valor de `$API_FIVEM_URL` |
| Símbolo / posición de la moneda | `$` / delante |
| Tiempo de expiración de sesión (segundos) | `3600` |
| TTL de la caché (segundos) | `300` |
| Máximo de intentos de inicio de sesión | `5` |
| Tiempo de bloqueo de inicio de sesión (segundos) | `900` |
| Tamaños de página de DataTable | `20,50,100` |

### Apariencia (Settings → Appearance)

- **Color de acento**: cualquier `#rrggbb`. El texto dibujado sobre el acento cambia automáticamente entre oscuro y claro para mantener el contraste.
- **Logo**: PNG, JPG o WebP, hasta 512 KB, guardado como `assets/img/custom-logo.*` y usado también como favicon. Sin logo, la barra lateral muestra las iniciales del nombre del panel.

### Game Config (Settings → Game Config)

| Ajuste | Descripción |
| ------- | ----------- |
| **Item catalogue** | Sube `items.lua` o JSON para las etiquetas de objetos |
| **Account Labels** | Nombres mostrados para banco, efectivo, dinero negro y la moneda extra |
| **License Types** | Claves de licencia ofrecidas al conceder (por defecto en ESX: `dmv`, `drive`, `drive_bike`, `drive_truck`, `weapon`; por defecto en QB: `driver`, `weapon`, `business`) |
| **Job Configuration** | Nombre del trabajo "unemployed" por defecto usado por el reinicio de trabajo y la sincronización de grupos de Qbox; lista de trabajos para el formulario de borrado de vehículos de trabajo de ESX |

### Economía (Settings → Economy)

| Ajuste | Por defecto |
| ------- | ------- |
| Multiplicador de riqueza (página Economy) | `5` |
| Multiplicador de desviación estándar (página Anomalies) | `3` |
| Ratio de exceso de efectivo / total mínimo | `0.8` / `10000` |
| Severidad: crítica / alta (× media) | `20` / `10` |
| Ventana de deduplicación de alertas (horas) | `24` |
| Umbrales de color de salario y sociedad | `5000`/`1000`, `1000000`/`100000` |
| Ventana de empleado activo / inactivo (días) | `7` / `30` |
| Tramos de riqueza | `<1K` … `>1M` |

### Límites (Settings → Limits)

Número de filas para las páginas Economy, Anomalies, Business, Staff Activity y Webhook, y para los resultados de la búsqueda rápida (jugadores `8`, vehículos `5`).

### Comprobación de actualizaciones (Settings → System)

**Settings → System** muestra **Up to date** o **Version X available** junto a la versión del panel. El panel consulta `https://xexstudio.com/api/version/xex_panel` como mucho una vez cada 12 horas (3 segundos de tiempo máximo, resultado guardado en `cache/update_check.json`). La petición no envía nada sobre tu servidor: ni dominio, ni jugadores, ni base de datos, ni ajustes. Si la tienda no responde, no se muestra nada y la página funciona como siempre. Para desactivarla, añade a `config.php` antes de la línea `require_once`:

```php
$UPDATE_CHECK = false;
```

---

## Módulos del panel

### Dashboard (`home.php`)

- Totales de dinero por cada cuenta que exista en tu servidor, más fondos de negocios
- Usuarios únicos (por licencia de Rockstar) y personajes
- Recuento de vehículos, casas, sociedades y objetos, cuando existan esas fuentes
- Filas premium activas, solo cuando hay una tabla premium configurada
- Alertas de anomalías abiertas y las últimas 8 acciones del staff (para los roles que pueden ver esas páginas)

### Players (`users.php` → `view-user.php`)

**Lista:** búsqueda y ordenación con DataTables. Las columnas siguen tu framework (grupo en ESX, banda en QB, dinero negro y moneda extra cuando existen). La lista se guarda en caché en `cache/users_<framework>.json` y se limpia tras editar jugadores.

**Perfil:**
- **Ficha resumen:** riqueza total, cuentas, recuento de vehículos, casas y licencias, estado de conexión, etiquetas y notas del staff
- **Información del jugador:** nombre, trabajo y rango, grupo y pincode (ESX), JSON del inventario, JSON de la skin. En ESX el trabajo se comprueba contra `job_grades`.
- **Cuentas:** saldos editables de las cuentas que tenga tu servidor
- **Licencias:** conceder y revocar
- **Pestañas del explorador de datos:** vehículos (con maletero y guantera), casas, inventarios (stashes de ox_inventory), teléfono, outfits, premium, cada una mostrada solo cuando existe la fuente

Las ediciones requieren el permiso de acción correspondiente y un token CSRF.

### Vehicles (`vehicles.php`)

- Recuento total, guardados y fuera/incautados, modelos y garajes
- Borrar un vehículo por matrícula (todos los frameworks)
- Enviar un vehículo a un garaje por matrícula: ESX establece `parking`, `stored = 1` y limpia `pound`; QBCore/Qbox establecen `garage`, `state = 1`, `depotprice = 0` (cada columna solo si existe)
- Borrar los vehículos de trabajo de un jugador (solo ESX, necesita una columna `job` en `owned_vehicles`)
- Los hashes de modelo de ESX se resuelven mediante la tabla `vehicles` de esx_vehicleshop cuando existe

### Societies (`societies.php` → `view-societies.php`)

- Fondos desde la fuente de fondos de negocios detectada (consulta [Recursos opcionales](#recursos-opcionales))
- Miembros del trabajo o banda con rango y última conexión
- ESX: stash de ox_inventory de la sociedad, inventario addon y armas del datastore

### Houses (`houses.php`)

- Propiedades con nombre del propietario y, cuando está disponible, shell/interior/nivel
- Oculta cuando no se detecta ningún recurso de housing

### Job Grades (`grades.php`, enlazada desde Societies)

- ESX: nombre del trabajo, rango, etiqueta y salario desde `job_grades`
- QBCore/Qbox: trabajos que tienen actualmente los jugadores, con número de empleados

### Item Finder (`itemsFinder.php` → `search-items.php`)

- Lista el catálogo de objetos
- Busca en los inventarios de jugadores (y loadouts de ESX), stashes de ox_inventory, inventarios addon y datastores de ESX, columnas de maletero/guantera de vehículos y tablas de qb-inventory (`stashitems`, `trunkitems`, `gloveboxitems`, `inventories`) cuando existen
- Muestra propietario, ubicación y cantidad

### Live Server (`live.php`)

- Jugadores conectados desde la URL de API configurada (nombre, ID de servidor, ping, licencia), con un enlace que busca en la lista de jugadores por licencia
- Cuando no se puede acceder a la API, la página muestra el error recibido
- Máximo de clientes, nombre/descripción del proyecto y recursos cuando se usa la API de cfx.re

### Character Kill (`ck_user.php` → `makeck.php`)

Borra la fila del jugador en último lugar, dentro de una transacción, después de estas filas relacionadas (cada tabla solo si existe):

| ESX / Custom (por identifier) | QBCore / Qbox (por citizenid) |
| ---------------------------- | ---------------------------- |
| filas de `addon_account_data`, `addon_inventory_items`, `datastore_data` propiedad del jugador | `player_vehicles` |
| `billing`, `owned_vehicles`, `user_licenses` | `playerskins`, `player_outfits` |
| filas de housing, teléfono y premium | `player_houses`, `phone_invoices` |
| filas de `ox_inventory` propiedad del jugador | filas de `ox_inventory` propiedad del jugador, `player_groups` (Qbox) |

Introduce el identifier de ESX o el citizenid de QB/Qbox.

### Swap (`swaps.php` → `controllers/swap-controller.php`)

- **ESX / Custom:** mueve todo del identifier antiguo al nuevo. Primero ejecuta un CK sobre el nuevo identifier y después actualiza el identifier en la tabla de jugadores, vehículos, licencias, housing, ox_inventory, cuentas/inventarios addon, datastores y facturación (identifier, sender, target). Se rechaza hacer un swap de un identifier sobre sí mismo.
- **QBCore / Qbox:** mueve un personaje (citizenid) a otra licencia de Rockstar (`license:<hash>` o el hash a secas). No se borra nada. Actualiza `players.license`, asigna el siguiente `cid` libre en la nueva licencia, actualiza `player_vehicles.license` y, en Qbox, establece `players.userId` a la fila de `users` correspondiente.

### Exportación de jugadores (`export-players.php`)

- **Export CSV** en la página Players descarga todos los personajes con identifier, nombre, trabajo, rango, banda (QB), cada cuenta y última conexión
- UTF-8 con BOM para que Excel conserve los acentos; las celdas que empiezan por `=`, `+`, `-` o `@` llevan un prefijo para evitar la inyección de fórmulas
- Requiere la acción `export_players`

### Modo demo

Define `$DEMO_MODE = true;` en `config.php` para ejecutar un panel de solo lectura, por ejemplo una demo pública con datos ficticios. Todo envío de formulario, excepto el inicio de sesión y la búsqueda de objetos, se rechaza antes de llegar a un controlador, y la barra superior muestra **Demo · read-only**. `$DEMO_LOGIN = ['demo', 'demo'];` muestra esas credenciales en la página de inicio de sesión. Crea antes esa cuenta como una cuenta de staff normal.

### Analytics (`analytics.php`)

- Una gráfica por cuenta, cada una con su propia escala, con el último total y la variación en 30 días
- Varias instantáneas del mismo día se reducen a la última

---

## Sistema de roles y permisos

### Roles integrados

| Rol | Nivel |
| ---- | ----- |
| **Viewer** | 0 |
| **Moderator** | 1 |
| **Admin** | 2 |
| **Superadmin** | 3 |

Estos cuatro roles del sistema no se pueden borrar. Los superadmins pueden crear roles personalizados (nombre, nivel, color) en la página **Permissions** y conceder páginas y acciones por rol. Los permisos guardados ahí sustituyen a los valores por defecto de abajo para ese rol. Los superadmins tienen acceso a todo.

### Acceso a páginas por defecto

| Página | Viewer | Moderator | Admin | Superadmin |
| ---- | :----: | :-------: | :---: | :--------: |
| Dashboard, Live, lista de Players, Societies, Houses, Item Finder, Job Grades, Analytics | ✅ | ✅ | ✅ | ✅ |
| Perfil de jugador, detalle de sociedad | ❌ | ✅ | ✅ | ✅ |
| Vehicles, formulario de Character Kill, formulario de Swap, reinicio de trabajo, añadir licencia, Audit Log | ❌ | ❌ | ✅ | ✅ |
| Página Licenses, Economy, Business, Anomalies, Staff Activity, Webhooks, Settings, Permissions | ❌ | ❌ | ❌ | ✅ |

Las páginas de la última fila se pueden conceder a otros roles en la página Permissions.

### Permisos de acción por defecto

| Acción | Rol mínimo |
| ------ | ------------ |
| `edit_user_data` | Admin |
| `edit_user_money` | Admin |
| `delete_job` | Admin |
| `manage_vehicles` | Admin |
| `manage_licenses` | Moderator |
| `character_kill` | Superadmin |
| `swap_players` | Superadmin |
| `create_staff` | Superadmin |
| `remove_staff` | Superadmin |
| `change_password` | Moderator |
| `view_settings` | Superadmin |
| `manage_permissions` | Superadmin |
| `export_players` | Admin |
| `export_audit` | Admin |
| `purge_audit` | Superadmin |
| `manage_webhooks` | Superadmin |

Las notas y etiquetas del staff en los perfiles de jugador requieren Moderator o superior.

---

## Sistema de webhooks

### Formatos

| Formato | Se detecta por | Payload |
| ------ | ----------- | ------- |
| **Discord** | la URL contiene `discord.com/api/webhooks` | Embed con color, campos y marca de tiempo |
| **Slack** | la URL contiene `hooks.slack.com` | Attachment con color y campos |
| **JSON genérico** | cualquier otra URL | `event`, `data` y marca de tiempo |

### Eventos (13)

| Evento | Disparador |
| ----- | ------- |
| `user.money_changed` | Saldo de cuenta editado |
| `user.data_changed` | Datos del jugador editados |
| `user.license_added` | Licencia concedida |
| `user.license_swapped` | Swap realizado |
| `user.character_killed` | Character kill realizado |
| `user.job_reset` | Trabajo reiniciado al trabajo por defecto |
| `vehicle.deleted` | Vehículo(s) borrado(s) |
| `vehicle.sent_garage` | Vehículo enviado al garaje |
| `staff.created` | Cuenta de staff creada |
| `staff.removed` | Cuenta de staff borrada |
| `staff.password_changed` | Contraseña de staff cambiada |
| `panel.login` | Inicio de sesión correcto |
| `panel.login_failed` | Inicio de sesión fallido |

### Configuración

1. Abre **Webhooks** en la barra lateral
2. Crea un webhook con un nombre, una URL y los eventos que enviar
3. Usa **Test** para enviar un payload de prueba

Cada entrega se registra en `panel_webhook_logs` (evento, payload, estado HTTP, respuesta) y se lista en la página Webhooks.

### Webhook de Discord heredado

`$WEBHOOK_URL` en `config.php` sigue recibiendo un mensaje de texto plano para las acciones registradas mediante la función de auditoría heredada. Es preferible usar la página Webhooks.

### Avatar de Discord

Los mensajes de Discord usan el avatar configurado en el propio webhook. Para cambiarlo, define `$WEBHOOK_AVATAR_URL = 'https://your-site/avatar.png';` en `config.php`.

---

## Registro de auditoría

Las acciones del staff se guardan en `panel_audit_log` y se muestran en la página **Audit Log**.

**Se registra:** marca de tiempo, nombre de usuario, rol, acción, categoría, objetivo, detalles, dirección IP, user agent.

- 7 filtros: usuario, categoría, acción, objetivo, IP, fecha desde, fecha hasta
- 50 entradas por página
- Estadísticas: hoy, esta semana, usuarios activos, inicios de sesión fallidos (24 h)
- Exportación CSV de los resultados filtrados
- Purga de entradas con más de N días (mínimo 7); el formulario de purga se muestra a los Superadmins

---

## Verificación en dos pasos

Desactivada por defecto. Cuando está activa, el admin introduce tras la contraseña un código de 6 dígitos de una app de autenticación de su móvil, así que una contraseña filtrada por sí sola no abre el panel. Funciona con Google Authenticator, Authy, Microsoft Authenticator, 2FAS, Aegis y cualquier app compatible con TOTP (RFC 6238).

### Modos (Settings → Staff → Two-step verification)

| Modo | Qué ocurre |
| ---- | ---------- |
| **Off** (por defecto) | Solo usuario y contraseña, como en 2.2. A los admins que la configuraron antes no se les pide el código mientras esté desactivada; su configuración vuelve a funcionar cuando la reactives. |
| **Optional** | Cada admin decide: **Profile → Two-step verification → Set up**. Los admins que no la tienen inician sesión solo con su contraseña. |
| **Required** | Todos los admins la necesitan. Tras la contraseña, quien no la tiene pasa directamente a la página de configuración; quien ya tiene la sesión iniciada es enviado allí en la siguiente página que cargue. Esto te incluye a ti. |

La pestaña Staff también muestra qué admins la tienen activa.

### Configurarla

1. **Profile → Set up two-step verification** (o la página que aparece al iniciar sesión cuando el modo es Required).
2. Escanea el código QR con la app o escribe la clave que aparece debajo. El QR lo dibuja tu navegador con el archivo incluido `assets/js/qrcode.min.js`; la clave no se envía a ningún servicio externo.
3. Introduce tu contraseña actual (si vienes del perfil) y el primer código de la app.
4. Guarda los 10 códigos de recuperación (cópialos o descárgalos como `.txt`). Solo se muestran una vez. Cada uno te permite iniciar sesión una vez en lugar de un código.

Desde el perfil también puedes crear **códigos de recuperación nuevos** (los antiguos dejan de funcionar) y **desactivarla** (modo Optional) o **pasarla a un móvil nuevo** (modo Required: se desactiva y se abre la página de configuración). Ambas acciones piden tu contraseña y un código o un código de recuperación.

### Iniciar sesión

- Un código se acepta durante su ventana de 30 segundos y una ventana antes y otra después, por si el reloj se desvía. Cada código funciona una sola vez.
- Los códigos erróneos cuentan para el mismo límite por IP que las contraseñas erróneas (**Max login attempts** / **Login lockout time**). Tras 5 códigos erróneos se vuelve a pedir la contraseña. El código debe introducirse en los 10 minutos siguientes a la contraseña.
- **Lost your phone? Use a recovery code**, en la página del código, acepta un código de recuperación en su lugar.

### Un admin perdió el móvil y los códigos de recuperación

Usa cualquiera de estas opciones. Cada una queda en el registro de auditoría y, si el modo es Required, el admin la vuelve a configurar en su siguiente inicio de sesión.

1. **Desde el panel:** un Superadmin (o un rol con la acción `remove_staff`) abre **Settings → Staff**, pulsa **Reset 2FA** junto al admin y confirma con su propia contraseña. Funciona con admins del mismo rol o inferior.
2. **Desde una consola** en el servidor web: `php setup/reset-2fa.php <username>`. Sin nombre de usuario, lista los admins que la tienen activa.
3. **Desde phpMyAdmin** (sin acceso a consola), cambiando el nombre de usuario:
   ```sql
   DELETE FROM panel_admin_2fa WHERE admin_id = (SELECT id FROM superadmins WHERE username = 'name');
   ```

Las opciones 2 y 3 también sirven cuando el único Superadmin es el que se ha quedado fuera.

### Dónde se guardan los datos

- Tabla `panel_admin_2fa`, una fila por cada admin con la verificación en dos pasos activa. La crea el instalador; en instalaciones existentes se crea la primera vez que un admin la configura. `superadmins` no se modifica.
- El secreto se guarda cifrado (AES-256-GCM). La clave es `$TOTP_KEY` de `config.php` si está definida; si no, `cache/totp-key.php`, que el panel crea la primera vez que alguien configura la verificación en dos pasos (`cache/` debe tener permisos de escritura, igual que para el límite de inicio de sesión).
- Para guardar la clave en `config.php`, añádela antes de que nadie configure la verificación en dos pasos (cambiar la clave después deja ilegibles las configuraciones existentes). Genera un valor con `php -r "echo base64_encode(random_bytes(32));"` y añádelo antes de la línea `require_once`:
  ```php
  $TOTP_KEY = 'the generated value';
  ```
- Conserva la clave al actualizar o mover el panel. Si se pierde, los códigos ya no se pueden comprobar y hay que reiniciar a cada admin (ver arriba).
- Los códigos de recuperación se guardan como hashes SHA-256.

### Entradas en el registro de auditoría

| Acción | Cuándo |
| ------ | ------ |
| `staff.2fa_enabled` | Un admin la activó |
| `staff.2fa_disabled` | Un admin la desactivó (o la pasó a un móvil nuevo) |
| `staff.2fa_reset` | Se desactivó para otro admin (Settings → Staff o `setup/reset-2fa.php`) |
| `staff.2fa_recovery_regenerated` | Se crearon códigos de recuperación nuevos |
| `staff.2fa_recovery_used` | Inicio de sesión con un código de recuperación (con los que quedan) |
| `panel.login_2fa_failed` | Código o código de recuperación erróneo al iniciar sesión (también envía el evento de webhook `panel.login_failed`) |
| `settings.security_updated` | Se cambió el modo |

Los inicios de sesión correctos se registran como `panel.login` con `(2FA code)` o `(recovery code)` en los detalles.

---

## Intelligence Suite

### Economy (`economy.php`)

- Totales por cuenta, riqueza media y máxima (riqueza = banco + efectivo + dinero negro; la moneda extra queda excluida)
- Jugadores más ricos, dinero por trabajo, tramos de riqueza
- Jugadores por encima del multiplicador de riqueza, jugadores con exceso de efectivo
- Gráficas

### Business Analytics (`business-analytics.php`)

- Empleados por trabajo, fondos de sociedades
- Empleados activos / semiactivos / inactivos por trabajo (por última conexión)
- Negocios abandonados, número de desempleados, distribución de rangos

### Anomaly Detection (`anomalies.php`)

| Alerta | Severidad |
| ----- | -------- |
| **Riqueza extrema** (por encima de la media + N desviaciones estándar) | Crítica, alta o media, según el múltiplo de la media |
| **Saldo negativo** | Baja |

- Las alertas se generan al cargar la página y se deduplican dentro de la ventana de deduplicación
- Filtro por severidad y tipo; descartar alertas
- Se guardan en `panel_anomaly_alerts`

### Staff Activity (`staff-activity.php`)

- Acciones totales, staff activo, media por día
- Tendencia diaria, desglose por categoría, mapa de calor por horas
- Ranking del staff y acciones más comunes
- Rango: 7, 14, 30, 60 o 90 días

---

## Personalización

### Traducciones

Los textos de la interfaz están en `translations.php` como variables `$T_*`:

```php
$T_PAGE_HOME = 'Home';
$T_TOTAL_CARS = 'Total Cars';
```

El panel se entrega en inglés.

### Tema

Elige el color de acento y el logo en **Settings → Appearance**. Para cambios más profundos, edita las variables CSS al principio de `style.css`:

```css
:root {
    --bg: #0e1116;          /* page background */
    --surface: #151a21;     /* cards */
    --border: #252c36;
    --text: #e7eaef;
    --text-2: #a7afbc;      /* secondary text */
    --accent: #c5f24a;      /* overridden by Settings → Appearance */
}
```

### Menú

Los grupos y entradas de la barra lateral se definen en `panel_menu()` en `includes/layout.php`.

---

## Referencia de la base de datos

### Tablas del panel

Se crean en tu base de datos de FiveM con `CREATE TABLE IF NOT EXISTS`. Volver a ejecutar el instalador o `setup/schema.sql` es seguro.

| Tabla | Propósito |
| ----- | ------- |
| `superadmins` | Cuentas de staff (contraseñas bcrypt, rol) |
| `analytics_money` | Instantáneas de dinero de la tarea cron |
| `panel_audit_log` | Registro de acciones del staff |
| `panel_webhooks` | Endpoints y eventos de webhooks |
| `panel_webhook_logs` | Entregas de webhooks |
| `panel_roles` | Roles y sus permisos (JSON) |
| `panel_player_notes` | Notas y etiquetas del staff sobre jugadores |
| `panel_anomaly_alerts` | Alertas de anomalías |
| `panel_settings` | Almacén clave/valor de ajustes |
| `panel_admin_2fa` | Verificación en dos pasos: secreto cifrado y códigos de recuperación con hash por admin |

### Tablas del juego que usa el panel

El panel nunca crea, elimina ni altera estas tablas. Las lee y, para las operaciones indicadas, escribe filas.

| Propósito | ESX | QBCore / Qbox | Operaciones |
| ------- | --- | ------------- | ---------- |
| Jugadores | `users` | `players` (JSON `charinfo`, `job`, `gang`, `money`, `metadata`) | Lectura / actualización / borrado (CK) / swap |
| Licencias | `user_licenses` | `players.metadata.licences` | Lectura / escritura / borrado |
| Vehículos | `owned_vehicles` | `player_vehicles` | Lectura / actualización / borrado |
| Skins / outfits | `users.skin`, `datastore_data` | `playerskins`, `player_outfits` | Lectura / actualización de skin / borrado (CK) |
| Grupos de trabajo | — | `player_groups` (Qbox) | Escritura al cambiar de trabajo / borrado (CK) |
| Rangos de trabajo | `job_grades`, `jobs` | — (`shared/jobs.lua`) | Lectura |
| Fondos de negocios | `addon_account`, `addon_account_data` | `management_funds`, `bank_accounts`, `bank_accounts_new` | Lectura |
| Facturación | `billing` | `phone_invoices` | Borrado (CK) / swap (ESX) |
| Objetos de sociedad | `addon_inventory_items`, `datastore_data` | `stashitems`, `trunkitems`, `gloveboxitems`, `inventories` | Lectura / borrado y swap (ESX) |
| ox_inventory | `ox_inventory` | `ox_inventory` | Lectura / borrado (CK) / swap (ESX) |
| Housing | loaf_housing, `owned_properties`, `properties` | `properties`, `player_houses` | Lectura / borrado (CK) / swap (ESX) |
| Teléfono | `phone_phones` | `phone_phones` | Lectura / borrado (CK, ESX) |
| Objetos | `items` | — | Lectura |
| Nombres de vehículos | `vehicles` (esx_vehicleshop) | — | Lectura |
| Usuarios de Qbox | — | `users` (Qbox) | Lectura (swap) |
| Premium | tabla configurada | tabla configurada | Lectura / borrado (CK, ESX) |

---

## Estructura de archivos

```
xex-panel/
├── config.php                      # Created by the installer (values only)
├── .htaccess                       # Apache protection rules and headers
├── index.php                       # Login
├── export-players.php              # Player list CSV export
├── home.php                        # Dashboard
├── live.php                        # Live server
├── users.php                       # Player list
├── view-user.php                   # Player profile
├── licenses.php                    # Grant licences
├── makelicenses.php                # Licence grant handler
├── delete-job.php                  # Job reset handler
├── ck_user.php                     # Character kill form
├── makeck.php                      # Character kill handler
├── swaps.php                       # Swap form
├── societies.php                   # Society list
├── view-societies.php              # Society detail
├── grades.php                      # Job grades
├── houses.php                      # Housing
├── vehicles.php                    # Vehicles
├── itemsFinder.php                 # Item catalogue and search form
├── search-items.php                # Item search results
├── analytics.php                   # Money over time
├── economy.php                     # Economy
├── business-analytics.php          # Business analytics
├── anomalies.php                   # Anomaly detection
├── staff-activity.php              # Staff activity
├── audit.php                       # Audit log
├── webhooks.php                    # Webhooks
├── settings.php                    # Settings (8 tabs)
├── permissions.php                 # Roles and permissions
├── profile.php                     # Own profile, password and two-step verification
├── two-factor.php                  # Sign-in step: 6-digit code or recovery code
├── two-factor-setup.php            # Two-step verification setup (QR) and recovery codes
├── logout.php
├── translations.php                # UI strings
├── style.css                       # Styles (CSS variables)
├── main.js                         # Sidebar, quick search, tables
├── favicon.ico
│
├── controllers/                    # Form handlers (POST only, except quick search)
│   ├── authenticate.php            # Login
│   ├── createuser.php              # Create staff account
│   ├── data-controller.php         # Player data edits
│   ├── editpass-controller.php     # Password change
│   ├── money-controller.php        # Account edits
│   ├── notes-controller.php        # Player notes and tags
│   ├── remove-license-controller.php
│   ├── remove-staff-controller.php
│   ├── remove-veh-controller.php   # Delete vehicle(s)
│   ├── search-global.php           # Quick search (GET, JSON)
│   ├── search-veh-controller.php   # Vehicle search by plate
│   ├── send-veh-controller.php     # Send vehicle to garage
│   ├── settings-controller.php     # Settings, logo and item uploads
│   ├── two-factor-controller.php   # Turn 2FA on/off, recovery codes, reset by a Superadmin
│   ├── verify-two-factor.php       # Sign-in code check
│   └── swap-controller.php         # Swap
│
├── includes/
│   ├── bootstrap.php               # Loaded by config.php: roles, default access, helpers
│   ├── security.php                # Sessions, headers, CSRF, DB connection, CK and swap
│   ├── framework.php               # Framework adapter and schema detection
│   ├── fw_players.php              # Adapter: per-player helpers
│   ├── fw_world.php                # Adapter: economy, housing, vehicles, items, live API
│   ├── settings_helper.php         # Settings store, appearance helpers
│   ├── two_factor.php              # TOTP, encrypted secrets, recovery codes
│   ├── login_guard.php             # Login rate limit and session start after sign-in
│   ├── permissions.php             # Granular permissions engine
│   ├── webhooks.php                # Webhook delivery
│   ├── layout.php                  # Menu definition and page titles
│   ├── header.php                  # <head> assets (CDN with SRI)
│   ├── sidebar.php                 # Sidebar shell
│   ├── topbar.php                  # Top bar shell
│   ├── menu.php                    # Sidebar links filtered by access and detected data
│   └── chart.php                   # Chart.js loader and defaults
│
├── install/
│   └── index.php                   # Installer (6 steps)
│
├── setup/
│   ├── schema.sql                  # Panel tables
│   ├── cronjob_money_analytics.php # Analytics snapshots
│   └── reset-2fa.php               # Turn off 2FA for an admin (command line)
│
├── assets/
│   ├── js/qrcode.min.js            # QR code drawing for the 2FA setup (MIT, qrcode.LICENSE)
│   ├── data/                       # items.json (created by the item catalogue upload)
│   └── img/                        # custom-logo.* (created by the logo upload)
│
└── cache/                          # Runtime files
    ├── schema.json                 # Detected tables (~2 min)
    ├── users_<framework>.json      # Player list cache
    ├── cacheAnalytics.txt          # Analytics cache
    ├── login_attempts.json         # Login rate limiting
    └── totp-key.php                # 2FA encryption key (keep it when updating)
```

---

## Solución de problemas

| Problema | Causa | Solución |
| ----- | ----- | -------- |
| **"Database connection error"** | Credenciales incorrectas, puerto incorrecto o base de datos caída | Comprueba `$DDBB_HOST` (usa `host:port` para un puerto distinto del predeterminado), `$DDBB_USER`, `$DDBB_PASSWORD`, `$DATABASE_NAME`. |
| **Página en blanco** | Error de PHP oculto en modo producción | Establece `$MODE = "development"` temporalmente y revisa el registro de errores de PHP. |
| **Errores de tabla del panel inexistente** | Tablas del panel no creadas | Ejecuta el instalador o importa `setup/schema.sql`. |
| **"Invalid security token"** | Sesión expirada o formulario abierto en otra sesión | Vuelve a iniciar sesión; aumenta el tiempo de expiración de sesión en Settings si hace falta. |
| **Falta una entrada de menú o una sección de página** | El recurso no se detectó | Revisa **Settings → System → Detected resources**, pulsa **Rescan** o define el nombre de la tabla en `$DB_TABLES`. |
| **Framework incorrecto** | La detección eligió otra estructura | Define `$FRAMEWORK` en `config.php` (`esx`, `qbcore`, `qbox`, `custom`). |
| **Los objetos muestran nombres internos** | No hay catálogo de objetos | Sube `ox_inventory/data/items.lua` o `qb-core/shared/items.lua` en **Settings → Game Config → Item catalogue**. |
| **Falla la subida del logo** | Archivo demasiado grande o carpeta sin permisos de escritura | Usa PNG/JPG/WebP de hasta 512 KB; da permisos de escritura a `assets/img/`. |
| **Página Analytics vacía** | Todavía no hay instantáneas | Configura la [tarea cron](#tarea-cron-de-analítica-opcional). |
| **Página Live vacía** | URL de API ausente, incorrecta o servidor inaccesible | Configura **Settings → General → FiveM API URL**. La página muestra el error recibido (conexión, estado HTTP o JSON no válido). |
| **La búsqueda rápida no devuelve nada (Apache)** | Un `.htaccess` antiguo bloquea las peticiones GET a los controladores | Usa el `.htaccess` de 2.2, que permite GET a `controllers/search-global.php`. |
| **Redirección a HTTPS en un servidor sin certificado** | `.htaccess` antiguo | El `.htaccess` de 2.2 omite la redirección para `localhost`, `127.0.0.1` y `[::1]`. Para otros hosts, instala un certificado o elimina el bloque de redirección. |
| **Instalador bloqueado** | Ya instalado | Borra `install/installed.lock`. |
| **Los permisos no se guardan** | Faltan privilegios en la BD | El usuario de MySQL necesita `INSERT`/`UPDATE` en `panel_roles`. |
| **El código 2FA siempre es incorrecto** | El reloj del móvil o el del servidor no está en hora | Pon el móvil en fecha y hora automáticas; comprueba la hora del servidor. |
| **Un admin perdió el móvil** | Sin app de autenticación | Inicia sesión con un código de recuperación o [reiníciala](#un-admin-perdió-el-móvil-y-los-códigos-de-recuperación). |
| **"Two-step verification is unavailable"** | `cache/` sin permisos de escritura o `cache/totp-key.php` sustituido | Da permisos de escritura a `cache/`; restaura el archivo de clave anterior o reinicia la 2FA de cada admin. |

### Archivos de registro

- **Errores de PHP:** tu registro de errores de PHP (XAMPP: `C:\xampp\php\logs\php_error_log`)
- **Entregas de webhooks:** página Webhooks o `panel_webhook_logs`
- **Intentos de inicio de sesión:** `cache/login_attempts.json`
- **Acciones del staff:** página Audit Log o `panel_audit_log`

---

## Seguridad

### Autenticación y sesiones

- Contraseñas con hash mediante `password_hash()` (`PASSWORD_DEFAULT`), recalculado al iniciar sesión cuando hace falta
- Política de contraseñas para cuentas nuevas y cambios: 8+ caracteres con mayúscula, minúscula y un número
- Las cuentas marcadas con `force_password_change` deben cambiar su contraseña antes de usar el panel
- ID de sesión regenerado al iniciar sesión
- Cookie de sesión con `HttpOnly`, `SameSite=Strict` y `Secure` cuando la petición es HTTPS, también en la petición de inicio de sesión
- Tiempo de expiración de sesión (1 hora por defecto)
- Limitación de intentos de inicio de sesión por IP, guardada en disco; los códigos 2FA erróneos cuentan para el mismo límite
- Verificación en dos pasos (TOTP) opcional por admin u obligatoria para todos; secretos cifrados con AES-256-GCM y códigos de recuperación guardados como hashes
- El error de inicio de sesión no revela si un nombre de usuario existe

### Protección de peticiones

- Tokens CSRF en los formularios (incluida la búsqueda de objetos), rotados tras cada comprobación correcta
- Las operaciones que cambian estado usan POST
- Sentencias preparadas de PDO con la emulación desactivada; valores como umbrales y nombres de trabajo se vinculan como parámetros
- Los nombres de tablas y columnas de la configuración se validan antes de usarse
- Salida escapada con `e()` / `attr()`; los datos pasados a JavaScript se codifican como JSON

### Cabeceras HTTP

Enviadas por `includes/security.php` (y por `.htaccess` en Apache):

- `X-Frame-Options: DENY`
- `X-Content-Type-Options: nosniff`
- `X-XSS-Protection: 1; mode=block`
- `Referrer-Policy: strict-origin-when-cross-origin`
- `Permissions-Policy: camera=(), microphone=(), geolocation=()`
- `Strict-Transport-Security` (solo en peticiones HTTPS)

### Dependencias del front-end

Cargadas desde CDN con hashes de Subresource Integrity: jQuery 3.7.1, DataTables core 1.13.7, Font Awesome 6.5.1, Chart.js 4.4.1. Las fuentes vienen de Google Fonts. La librería de códigos QR de la verificación en dos pasos (qrcode.js, MIT) va incluida en `assets/js/` y se sirve desde tu propio hosting.

### Protección de archivos

`.htaccess` (Apache):
- Redirige HTTP a HTTPS, excepto para `localhost`, `127.0.0.1` y `[::1]`
- Bloquea las peticiones que no sean POST a `controllers/*.php`, excepto `controllers/search-global.php` (búsqueda rápida)
- Bloquea `includes/*.php`, `setup/` y `cache/`
- Deniega los archivos `.sql`, `.log`, `.txt`, `.md`, `.json`, `.bak`, `.old`, `.orig`, `.save` y `config.php`
- Desactiva el listado de directorios

En Nginx, añade reglas equivalentes a tu bloque de servidor.

### Lista de comprobación para producción

1. Sirve el panel por HTTPS
2. Restringe el acceso (firewall, VPN o lista de IP permitidas)
3. Mantén `$MODE = "production"`
4. Borra o bloquea `install/` tras la instalación
5. Activa la verificación en dos pasos (**Settings → Staff**), al menos para los Superadmins
6. Revisa el registro de auditoría con regularidad
7. Mantén PHP y MySQL/MariaDB actualizados
8. Haz copias de seguridad de la base de datos, incluidas las tablas del panel, y de `cache/totp-key.php`

---

## Registro de cambios

### v2.3.0

**Seguridad**
- Verificación en dos pasos con códigos de 6 dígitos de Google Authenticator, Authy, Microsoft Authenticator o cualquier app TOTP. Desactivada por defecto: tras actualizar, todo el mundo inicia sesión como antes
- **Settings → Staff** define el modo: Off, Optional (cada admin la activa en su perfil) o Required (cada admin la configura antes de usar el panel)
- Configuración con un código QR dibujado en el navegador por una librería incluida (sin servicios externos) y un primer código para confirmar
- 10 códigos de recuperación de un solo uso por admin, guardados como hashes; se pueden crear códigos nuevos desde el perfil
- Los códigos erróneos cuentan para el mismo límite de inicio de sesión por IP que las contraseñas erróneas; tras 5 códigos erróneos se vuelve a pedir la contraseña
- Cada código funciona una sola vez y el secreto se guarda cifrado (AES-256-GCM)
- Un Superadmin puede reiniciar la verificación en dos pasos de otro admin desde **Settings → Staff**; sin acceso al panel, lo hace `php setup/reset-2fa.php <username>` o una consulta SQL
- Entradas en el registro de auditoría al activarla y desactivarla, en los reinicios, los códigos de recuperación nuevos, los inicios de sesión con código de recuperación y los códigos erróneos

**Base de datos**
- Nueva tabla `panel_admin_2fa`, creada por el instalador o la primera vez que un admin configura la verificación en dos pasos. No se modifica ninguna tabla existente

**Correcciones y cambios menores**
- **Max login attempts** y **Login lockout time** de Settings → General ahora se aplican al inicio de sesión (antes solo lo hacían `$MAX_LOGIN_ATTEMPTS` / `$LOGIN_LOCKOUT_TIME` de `config.php`)
- Al eliminar una cuenta de staff también se eliminan sus datos de verificación en dos pasos

### v2.2.1 (2026-10-10)

**Seguridad**
- El instalador ahora queda bloqueado tras una instalación manual: se niega a ejecutarse si existe `config.php` o `install/installed.lock`
- El instalador valida el nombre de la base de datos antes de usarlo
- El script cron de analítica solo se puede ejecutar desde la línea de comandos
- Los flags reforzados de la cookie de sesión ahora también se aplican en la petición de inicio de sesión

**Novedades**
- Comprobación de actualizaciones en **Settings → System**: muestra **Up to date** o **Version X available** (se comprueba como mucho cada 12 horas y se puede desactivar con `$UPDATE_CHECK = false`)

**Correcciones y cambios menores**
- Los webhooks de Discord usan el avatar del propio webhook salvo que se defina `$WEBHOOK_AVATAR_URL`
- Limpieza interna del nombre de la moneda extra en la página del jugador
- Los pasos de instalación manual ahora incluyen bloquear el instalador

### v2.2.0

**Novedades**
- Exportación de la lista de jugadores a CSV
- Modo demo de solo lectura (`$DEMO_MODE`)
- Analytics muestra una gráfica por cuenta con su propia escala y la variación a 30 días
- `export_audit`, `purge_audit` y `manage_webhooks` ahora se aplican y se pueden conceder a roles personalizados

**Frameworks**
- ESX Legacy, QBCore y Qbox son compatibles de forma nativa mediante un nuevo adaptador (`includes/framework.php`, `includes/fw_players.php`, `includes/fw_world.php`)
- Las columnas JSON de QBCore/Qbox (`charinfo`, `job`, `gang`, `money`, `metadata.licences`) se leen con `JSON_EXTRACT` y se escriben con `JSON_SET`
- `player_groups` de Qbox se mantiene sincronizada al cambiar de trabajo
- El instalador detecta ESX, QBCore y Qbox y tiene una opción Qbox

**Configuración**
- `config.php` solo contiene valores y termina con `require_once includes/bootstrap.php`; los valores por defecto de cada framework se han movido a `includes/framework.php`
- `$DB_TABLES` ahora es solo para sobrescrituras
- El host de la base de datos puede incluir un puerto (`127.0.0.1:3307`)
- Las configuraciones generadas por 2.1 siguen funcionando

**Recursos y datos**
- Los recursos opcionales se detectan automáticamente; sus páginas y entradas de menú se ocultan cuando no existen
- Nuevo **Settings → System → Detected resources** con **Rescan**
- Housing: loaf_housing, esx_property, ps-housing, qbx_properties, qb-houses
- Fondos de negocios: cuentas addon de ESX, qb-management, qb-banking, Renewed-Banking
- Facturación: `billing` de ESX, `phone_invoices` de qb-phone
- Las cuentas siguen al framework; el crypto de QBCore/Qbox se muestra como la moneda extra. Se puede definir una moneda personalizada con `account_coin`
- La subida del catálogo de objetos (`items.lua` de ox_inventory o qb-core, o JSON) sustituye a la lista de objetos incluida
- Character kill y swap tienen en cuenta el framework; el swap de QBCore/Qbox mueve un personaje a otra licencia de Rockstar; el swap de ESX rechaza hacer un swap de un identifier sobre sí mismo
- Enviar al garaje y borrar por matrícula funcionan en todos los frameworks; borrar vehículos de trabajo es solo para ESX
- El cron de analítica registra solo las cuentas que existen

**Interfaz**
- Nueva interfaz oscura con barra lateral agrupada y contraíble y barra superior
- Búsqueda rápida (`Ctrl+K` / `Cmd+K`) de jugadores, matrículas y páginas, sin distinguir mayúsculas en todos los frameworks
- **Settings → Appearance**: color de acento y subida de logo
- Bootstrap 3 eliminado; DataTables core 1.13.7 y Chart.js 4.4.1 fijados con SRI
- Estructura de página compartida: `includes/sidebar.php`, `includes/topbar.php`, `includes/layout.php`, `includes/header.php`

**Seguridad**
- Los flags reforzados de la cookie de sesión ahora se aplican de verdad (`HttpOnly`, `SameSite=Strict`, `Secure` en HTTPS)
- El inicio de sesión ya no revela si un nombre de usuario existe
- `.htaccess` ya no fuerza HTTPS en localhost y permite GET solo al endpoint de búsqueda rápida
- Comprobación CSRF añadida a la búsqueda de objetos
- Correcciones de escape de salida en varias páginas
- Umbrales SQL vinculados como parámetros

**Eliminado**
- Las imágenes incluidas en `assets/img/` y la lista de objetos incluida en `assets/data/`

### v2.1.0

- **Intelligence Suite** — Economy Dashboard, Business Analytics, Anomaly Detection, Staff Activity
- **Ajustes dinámicos** — Configuración completa desde el panel (sin editar archivos para la mayoría de los ajustes)
- **Permisos granulares** — Motor de permisos por rol respaldado por la BD con creación de roles personalizados
- **Sistema de webhooks** — Webhooks multi-endpoint compatibles con Discord, Slack y JSON genérico (13 eventos)
- **Notas de jugador** — Notas entre miembros del staff en los perfiles de jugador
- **Registro de auditoría avanzado** — 7 filtros, exportación CSV, tarjetas de estadísticas, purga automática
- **Tramos de riqueza** — Rangos configurables de distribución de riqueza
- **Seguimiento de actividad del staff** — Mapas de calor, gráficas de tendencia, ranking, desglose por categoría

### v2.0.0

- **Compatibilidad multi-framework** — ESX Legacy, QBCore y mapeo de tablas para frameworks personalizados
- **Control de acceso basado en roles** — 4 roles integrados con permisos de página y de acción configurables
- **Protección CSRF** — Todos los formularios y peticiones que cambian estado
- **Protección XSS** — Escape de salida en todos los datos generados por usuarios
- **Caché segura** — Caché basada en JSON que sustituye a la serialización PHP insegura
- **Limitación de intentos** — Limitación de intentos de inicio de sesión con bloqueo configurable
- **Interfaz modernizada** — Tema oscuro con la familia tipográfica Inter, variables CSS, diseño adaptable
- **Dependencias actualizadas** — jQuery 3.7, DataTables 1.13, Font Awesome 6.5
- **Refuerzo de seguridad** — Eliminados los hashes de contraseña expuestos, controladores solo POST, protección contra autoborrado, limpieza de código de depuración

---


## Licencia

Este es un producto comercial. Queda prohibida la redistribución, reventa o modificación para reventa sin autorización.

© 2024–2026 XeX Game Management. Todos los derechos reservados.
