Instalación

Guía de instalación

Esta guía describe una instalación nueva, una actualización y las verificaciones mínimas antes de abrir el servidor a jugadores.

1. Requisitos

Obligatorios

Componente	Uso
FiveM server	Ejecución del recurso Lua y de la NUI.
ESX, QBCore o Qbox	Datos de personaje, trabajo y dinero.
ox_lib	Localización y utilidades compartidas.
oxmysql	Consultas y transacciones con MySQL/MariaDB.
MySQL/MariaDB	Persistencia de facturas, pagos y auditoría.

Solo para facturas de empresa

Framework	Recurso esperado
ESX	esx_addonaccount
QBCore	qb-management o qb-banking
Qbox	Una capa compatible con qb-management o qb-banking

El terminal POS y las facturas personales pueden operar sin sociedad. Una factura empresarial requiere que el bridge pueda ingresar y, en caso de rollback, retirar fondos de la cuenta indicada.

2. Preparar la carpeta

La carpeta debe llamarse exactamente rc-billing:

resources/
└── [realcitydev]/
    └── rc-billing/
        ├── fxmanifest.lua
        ├── config.lua
        ├── bridge/
        ├── client/
        ├── server/
        ├── locales/
        ├── sql/
        └── web/public/

Evita nombres como rc-billing-main, rc-billing-v1 o una carpeta duplicada rc-billing/rc-billing. El nombre se utiliza en exports, callbacks NUI y ejemplos de integración.

3. Instalar la base de datos

La base de datos se instala sola por defecto, pero en caso de que sea necesario puede instalarla ejecutando estos dos archivos:

Haz una copia de seguridad antes de importar SQL en una base existente.

Ejecuta los archivos en este orden:

1. sql/invoices.sql

2. sql/payment_requests.sql

4. Orden de inicio

Las dependencias y el framework deben estar iniciados antes de rc-billing.

QBCore

ensure oxmysql
ensure ox_lib
ensure qb-core
ensure qb-management
ensure rc-billing

Si utilizas qb-banking, reemplaza qb-management por el nombre correspondiente y confirma que expone AddMoney y RemoveMoney.

ESX

ensure oxmysql
ensure ox_lib
ensure es_extended
ensure esx_addonaccount
ensure rc-billing

Las cuentas compartidas configuradas, por ejemplo society_police, deben existir antes del primer pago empresarial.

Qbox

ensure oxmysql
ensure ox_lib
ensure qbx_core

# Inicia aquí la capa bancaria compatible de tu servidor.
ensure rc-billing

La detección utiliza el nombre oficial qbx_core. El bridge consume la capa de compatibilidad QB que Qbox publica mediante el export qb-core.

5. Configuración inicial

Abre config.lua y revisa obligatoriamente:

1. Config.Locale.

2. Config.AllowPersonalInvoices y Config.RequireAceForPersonalInvoices.

3. Config.CompanyJobs.

4. Config.PaymentAccount.

5. Config.MaxInvoiceAmount y límites por empresa.

6. Config.DefaultCommission y comisiones específicas.

7. Config.DiscordWebhook.

8. Comandos y teclas predeterminadas.

No publiques un webhook real dentro de un repositorio público o paquete de demostración.

6. Permisos ACE

La creación personal puede quedar abierta o restringida:

Config.AllowPersonalInvoices = true
Config.RequireAceForPersonalInvoices = true
Config.CreateInvoicePermission = 'rc-billing.create'

Ejemplo de permisos:

add_ace group.admin rc-billing.admin allow
add_ace group.admin rc-billing.create allow
add_ace group.moderator rc-billing.create allow

Si RequireAceForPersonalInvoices es false, el ACE de creación no se consulta. Si AllowPersonalInvoices es false, ninguna persona puede emitir facturas personales aunque tenga ACE.

7. Primera prueba

Reinicia el recurso desde consola:

restart rc-billing

Conecta dos personajes y ejecuta esta prueba completa:

1. Abre /openinvoice con el emisor.

2. Crea una factura personal de importe pequeño.

3. Confirma que el receptor ve la solicitud.

4. Recházala y comprueba que queda cancelada.

5. Crea otra factura y acéptala.

6. Realiza un pago parcial.

7. Completa el importe y verifica el saldo de ambos.

8. Abre /openpos, crea una solicitud y acéptala.

9. Repite con una factura empresarial y verifica la comisión y la sociedad.

10. Revisa invoice_payments e invoice_audit_logs.

8. Actualizar una instalación

1. Detén rc-billing.

2. Copia config.lua y exporta las tablas del recurso.

3. Lee CHANGELOG.md y compara las nuevas opciones de configuración.

4. Sustituye los archivos del recurso.

5. Fusiona manualmente tu configuración anterior con la nueva.

6. Ejecuta ambos archivos SQL. Sus bloques de migración comprueban columnas e índices existentes.

7. Inicia el recurso.

8. Repite la prueba funcional básica.

No elimines las tablas para actualizar: perderías historial, pagos y auditoría.

9. Desinstalación

1. Elimina o comenta ensure rc-billing.

2. Reinicia el servidor.

3. Conserva las tablas si necesitas histórico.

4. Si quieres borrar todos los datos de manera irreversible, hazlo manualmente después de una copia de seguridad.

El recurso no elimina datos automáticamente al detenerse o desinstalarse.

10. Instalación validada

La instalación está lista cuando se cumplen todos estos puntos:

• No aparece No supported framework detected.

• No hay errores de columnas o tablas en oxmysql.

• /openinvoice y /openpos abren y cierran correctamente.

• Un destinatario solo puede pagar sus propias facturas.

• Una empresa recibe el importe esperado.

• Una comisión llega al empleado configurado.

• Los estados cambian en el orden documentado.

• El build NUI servido coincide con el código de la versión.

Continúa con Configuración y Solución de problemas.