Documentación de Gobierno 360

Gobierno 360

Núcleo de gobierno para servidores de rol: un Estado completo con 26 organizaciones, rangos con escala salarial, departamentos, personal, tesorería por organización con libro mayor, nóminas por minutos conectado, partidas presupuestarias con topes por rango y solicitudes internas, todo con auditoría y dos paneles: uno para los cargos RP y otro para el staff.

Que hace

sbr-presidentes monta la estructura institucional de tu ciudad y la mantiene sincronizada con la base de datos a partir de un archivo de configuración.

• 26 organizaciones de serie: el Estado (raíz), el Congreso, el Tribunal Supremo, 15 ministerios (Presidencia, Interior y Seguridad, Hacienda y Finanzas, Justicia, Sanidad, Educación, Obras Públicas, Transportes, Trabajo y Empleo, Economía y Comercio, Vivienda y Urbanismo, Cultura y Deportes, Medioambiente, Bienestar Social y Administración Pública), 5 organismos independientes (Comisión Electoral, Tribunal de Cuentas, Defensor del Ciudadano, Oficina de Transparencia y Autoridad de Protección de Datos) y 3 ayuntamientos (Los Santos, Sandy Shores y Paleto Bay). Cada una tiene sus departamentos; los municipios comparten además una plantilla de departamentos municipales.
• Escala de rangos global con salario: 15 rangos desde Aprendiz (nivel 5) hasta Presidente de la República (nivel 100), cada uno con su salario por ciclo y su grupo de permisos. Las organizaciones pueden tener cargos con nombre propio (alcalde, concejal, diputado, magistrado, juez, fiscal, profesor, conserje...) que heredan nivel y salario de un rango base.
• Permisos institucionales por rango: un catálogo de permisos del tipo ambito.accion (ver plantilla, contratar, ascender, gastar, transferir, asignar partidas, gestionar nóminas, aprobar gastos de otros, ver auditoría...) agrupado en 7 grupos (presidencia, gabinete, ministerio, dirección, jefatura, trabajador y aprendiz). La Presidencia no puede gastar ni asignar partidas a propósito: eso corresponde a Hacienda.
• Personal: fichas por ciudadano y organización con rango, departamento, estado (active, suspended, dismissed), cargo principal e historial de altas, ceses, ascensos y traslados.
• Tesorería por organización: cada organización tiene su caja con saldo, libro mayor (asientos con saldo resultante, categoría y concepto) y balance por días. Ingresos, gastos, transferencias entre cajas, pagos a ciudadanos y cobros a ciudadanos son operaciones atómicas en base de datos con clave de idempotencia: una orden repetida no se ejecuta dos veces.
• Nóminas por minutos conectado: el personal acumula minutos de servicio mientras está en línea y cobra su salario cada ciclo (30 minutos por defecto) desde la caja de su organización, con tope de seguridad por ciclo. La nómina se activa o para por organización.
• Partidas presupuestarias y topes por rango: el gasto de cada organización se reparte en partidas por categoría (asignado, gastado, disponible), se puede cerrar el ejercicio y conservar el histórico, y cada rango puede tener tope por operación, tope por periodo y un umbral a partir del cual hace falta la autorización de otro cargo.
• Solicitudes internas: desde el panel institucional cualquier miembro crea solicitudes de 6 tipos (gasto o presupuesto, contratación, ascenso, traslado, permiso o baja y trámite interno) que ven y resuelven los cargos con el permiso correspondiente; nadie se aprueba a sí mismo.
• Dos paneles: /panelgob (tecla F6 por defecto) para los cargos RP, con pestañas Mi cargo, Personal, Presupuesto y Solicitudes; y /gov_staff para el staff, con panel principal, gestión de personal, tesorería, presupuestos y nóminas, ministerios y departamentos, municipios, permisos y administración e historial general. Las operaciones de dinero piden confirmación.
• Comandos de consola y exports: más de 40 comandos /gov_* para consultar o administrar todo desde la consola o el chat, y una API de exports de lectura (abierta) y de escritura (solo recursos autorizados) para integrar otros scripts.
• Auditoría y migraciones automáticas: cada acción relevante queda en el registro de auditoría con su actor, y las tablas se crean y actualizan solas al arrancar.

Requisitos

• FiveM (FXServer reciente) y Lua 5.4.
• QBCore (qb-core; también detecta qbx_core y es_extended, ver "Configuración").
• ox_lib (menús de contexto, callbacks y avisos).
• oxmysql y una base de datos MariaDB o MySQL 8. Las migraciones comprueban qué existe antes de cada cambio, así que funcionan en ambos motores.
• Opcional: reydi_economy para mover el dinero de los jugadores. Si no está, el recurso usa el dinero directo del framework detectado (QBCore) sin cambiar nada más.

Instalacion

1. Descarga el recurso desde tu Portal de Cfx.re con la cuenta con la que lo compraste y copia la carpeta sbr-presidentes en resources.
2. Añade en server.cfg, después de qb-core, ox_lib y oxmysql (y de reydi_economy si lo usas):

   ensure sbr-presidentes

1. Da el permiso de staff a tu grupo de administración. Es un ACE, no un cargo RP: ni el presidente administra el recurso.

   add_ace group.admin gov.admin allow

1. Revisa config/config_server.lua. La lista Config.Admin.owners viene vacía: si quieres licencias con acceso garantizado aunque el ACL falle, ponlas ahí o usa la convar set sbr_gov_owners "licencia1,licencia2" en server.cfg (se suma a la lista; 40 caracteres hexadecimales, con o sin el prefijo license:).
2. Arranca el servidor. Con Config.Database.autoMigrate = true el recurso aplica solas las migraciones 001 a 006 de la carpeta sql/ que falten (estructura, personal, tesorería, partidas, solicitudes e índices) y sincroniza config_gobierno.lua con la base de datos. No hay que importar ningún .sql a mano.
3. Decide dos cosas antes de abrir al público:
4. Config.Economy.requireBudget (por defecto true): un gasto exige una partida activa para su categoría. Crea las partidas con /gov_partida o desde el panel de staff, o ponlo en false para gastar sin partidas.
5. Config.Api.allowedResources: lista de recursos que pueden usar los exports de escritura (contratar, mover dinero, asignar partidas). Añade ahí tus scripts.
6. Comprueba con /gov_info desde la consola que el núcleo está LISTO y qué framework y economía detectó.

Protección y edición. El recurso viene protegido con Asset Escrow de Cfx.re: se descarga desde tu Portal y solo funciona en servidores de tu cuenta. Según el escrow_ignore del fxmanifest.lua quedan sin cifrar: web/** (toda la interfaz de los dos paneles), config/.lua (los cuatro archivos de configuración), sql/.sql (las migraciones), shared/sh_util.lua, bridge/*.lua (la integración con framework, economía y avisos) y docs/**. Así puedes adaptar el framework, la economía, la estructura del Estado, los textos y el aspecto sin tocar el código cifrado, que es solo el de server/ y client/.

Configuracion

Toda la configuración vive en la carpeta config/. Ningún archivo de server/ o client/ nombra un recurso externo.

config/config.lua (compartido con el cliente)

config/config_server.lua (solo servidor, nunca llega al cliente)

config/config_bridge.lua (integración con tu servidor)

config/config_gobierno.lua (estructura del Estado)

Es la fuente de verdad de la estructura: Config.Gobierno.rangos (escala global con slug, label, level, salary y perms), Config.Gobierno.departamentosBase (8 departamentos comunes: dirección, administración, recepción, seguridad, limpieza, mantenimiento, conserjería y almacén), Config.Gobierno.organizaciones (las 26, con slug, type, parent, label, description y sus departamentos), Config.Gobierno.departamentosMunicipales (14 para los ayuntamientos), Config.Gobierno.municipios (centro y radio de cada municipio para enrutar por coordenadas) y Config.Gobierno.rangosEspecificos (cargos con nombre propio por organización). Añadir un ministerio, un municipio o un departamento es añadir una entrada y reiniciar el recurso; el slug no se cambia nunca, el label sí.

config/config_permisos.lua (permisos institucionales)

Config.Permisos es el catálogo de permisos con su descripción y Config.GruposPermisos asigna permisos a cada grupo de rango (presidencia, gabinete, ministerio, direccion, jefatura, trabajador, aprendiz). El comodín concede un ámbito completo (finance.).

Comandos y permisos

Todos los comandos /gov_* del servidor exigen el ACE gov.admin (o cualquiera de Config.Admin.aces, o una licencia de owners) y también funcionan desde la consola del servidor. Ningún cargo RP, ni siquiera el presidente, puede usarlos. Donde dice <idJugador|citizenid> vale el ID de servidor de un jugador conectado o su citizenid.

Paneles y menús

Diagnóstico y estructura

Personal

Tesorería y nóminas

Partidas y topes

Exports. Lectura, abiertos a cualquier recurso: Ready, GetStatus, GetOrganization(s), GetDepartments, GetMunicipalities, GetMunicipalityAt, GetRanks, GetRank, RankHasPermission, GetSalary, IsGovAdmin, GetMemberships, GetMember, GetPrimaryMember, IsMember, GetRoster, HasPermission, PlayerHasPermission, GetOrgBalance, GetTreasuryAccount, GetOrgLedger, GetOrgStatement, GetServiceTime, GetPayrollLog, GetOrgBudgets, GetBudgetSummary, GetRankSpendLimits, CheckSpendLimit, entre otros. Escritura, solo desde Config.Api.allowedResources: HireMember, SetMemberRank, TransferMember, SetMemberStatus, FireMember, SetPrimaryMember, DepositFunds, SpendFunds, TransferFunds, PayCitizen, CollectFromCitizen, SetPayrollEnabled, FlushPendingPayroll, AllocateBudget, AdjustBudget, SetBudgetActive, ResetBudget, SetRankSpendLimit, PurgeIdempotencyKeys. Un recurso no autorizado recibe false, 'recurso_no_autorizado'.

Como se usa

1. El staff da de alta al primer cargo con /gov_contratar o desde la pestaña Gestión de personal de /gov_staff, eligiendo jugador conectado, organismo, cargo y departamento en desplegables.
2. El staff ingresa fondos en las cajas (/gov_ingresar o Tesorería), crea las partidas por categoría (Presupuestos y nóminas o /gov_partida) y activa la nómina de cada organización (/gov_nomina ... on). La activación de la nómina pide confirmación porque empieza a mover dinero real.
3. Un cargo abre /panelgob (F6) y ve en Mi cargo su institución, rango, departamento, salario y permisos efectivos; si tiene varios cargos, cambia de organización en el desplegable superior.
4. En Personal contrata, asciende o traslada según sus permisos; en Presupuesto consulta partidas, saldo y libro mayor; en Solicitudes crea una solicitud (tipo, importe, partida, asunto y detalle) o aprueba y rechaza las de su bandeja (el rechazo exige motivo).
5. Mientras el personal está conectado acumula minutos; cada ciclo cobra su salario desde la caja de su organización y el pago queda en el historial de nóminas.
6. Cualquier jugador puede ver su expediente con /gov.

Para administradores

• Quién administra: solo quien tenga el ACE gov.admin (o group.admin), o una licencia en Config.Admin.owners o en la convar sbr_gov_owners. Los cargos RP, incluido el presidente, nunca administran el recurso.
• Un gasto dice partida_inexistente, categoria_requerida o partida_desactivada: con requireBudget = true hace falta una partida activa para esa categoría. Créala con /gov_partida o pon Config.Economy.requireBudget = false.
• Un script tuyo recibe recurso_no_autorizado: añádelo a Config.Api.allowedResources en config_server.lua.
• Una contratación falla: Hire rechaza fichas suspendidas (ficha_suspendida), citizenid que no existen (ciudadano_inexistente) y organizaciones inactivas (organizacion_inactiva).
• Cambiar la estructura: edita config_gobierno.lua y reinicia el recurso (o /gov_reload). Lo que desaparece de la configuración no se borra de la base de datos; se desactiva a mano.
• Economía: /gov_info muestra qué recurso de economía detectó. Si reydi_economy no está, el bridge avisa en consola y usa el dinero directo del framework. Si ese recurso arranca más tarde, el bridge lo vuelve a detectar solo.
• Ver por qué se deniega un acceso: Config.Admin.debug = true imprime el motivo de cada denegación en la consola del servidor (escribe la licencia; vuelve a false después).
• Auditoría: todo queda en la tabla gov_audit_log con actor, acción y objetivo; también la Operaciones recientes del panel de staff. Con Config.Audit.retentionDays > 0 se purga cada purgeEveryHours.
• Mantenimiento: /gov_idem_purgar limpia claves de idempotencia antiguas; las colgadas se liberan solas tras idemPendingMinutes.
• Al cambiar el prefijo de tablas: hazlo antes del primer arranque; las migraciones crean las tablas con ese prefijo.

Preguntas frecuentes

¿Funciona sin reydi_economy? Sí. Si el recurso no existe, el bridge cae al dinero directo del framework detectado y lo avisa en consola. También puedes dejar Config.Bridge.economy.resource = nil.

¿Funciona con ESX o Qbox? El bridge detecta qb-core, qbx_core y es_extended, y config_bridge.lua permite un adaptador propio. En esta versión solo se ha validado la integración con QBCore.

¿Tengo que importar los .sql a mano? No. Con autoMigrate = true el recurso aplica al arrancar las migraciones que falten y las registra en gov_migrations. Las migraciones están sin cifrar por si quieres revisarlas.

¿Por qué el presidente no puede gastar? Es deliberado: el grupo presidencia no tiene finance.spend ni finance.budget; gastar y asignar partidas corresponde a Hacienda (grupo ministerio). Puedes cambiarlo en config_permisos.lua.

¿Qué pasa si el servidor se cae a mitad de una operación de dinero? Cargos, abonos y traspasos son una sola transacción en base de datos con clave de idempotencia: o se aplica todo o nada, y un reintento devuelve lo ya hecho. El único límite es el dinero del jugador, que vive en el framework: ahí una caída entre el cargo a la caja y el abono al jugador no la cubre SQL.

¿Puedo añadir un ministerio o un municipio nuevo? Sí: una entrada más en Config.Gobierno.organizaciones (y en Config.Gobierno.municipios si tiene zona geográfica) y reinicio del recurso.

¿Está probado en juego? Esta versión 1.0.0 ha pasado pruebas automatizadas de la lógica de servidor (personal, tesorería, partidas, nóminas, solicitudes e idempotencia) y las migraciones se han aplicado en una base de datos real, pero no se ha probado de principio a fin dentro del juego. Prueba los paneles y las nóminas en tu servidor antes de abrirlo al público.

Actualizaciones y soporte

Las versiones nuevas aparecen en tu Portal de Cfx.re y en la tienda. Antes de actualizar, guarda una copia de la carpeta config/ y de web/ si cambiaste la interfaz; las migraciones nuevas se aplican solas al arrancar y nunca borran datos. Soporte: [enlace de soporte].