> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fivenetwork.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# five-admin

> Painel administrativo (NUI em React) com gerenciamento de jogadores, veículos, itens, organizações, staff, salários, propriedades, baús, avisos e chat de staff. Acessível pelo comando `/admin`.

O **five-admin** fornece um painel administrativo completo via NUI. A comunicação NUI → Lua é feita por `RegisterNUICallback`, que repassa as ações ao servidor via eventos. O recurso cria suas próprias tabelas e integra com `five-vehicles`, `propertys`, `five_logs` e `PL_PROTECT`.

## Funcionalidades

<CardGroup cols={2}>
  <Card title="Gerenciamento de jogadores" icon="users">
    Lista e busca de jogadores online e offline, com ações de teleporte, reviver, god, colete, kick, dar dinheiro e espectar.
  </Card>

  <Card title="Whitelist" icon="user-check">
    Controle de acesso de jogadores diretamente pelo painel.
  </Card>

  <Card title="Veículos" icon="car">
    Spawnar, dar/remover, reparar e tunar veículos, com integração ao `five-vehicles`.
  </Card>

  <Card title="Itens" icon="box">
    Gere e gerencie itens do inventário dos jogadores.
  </Card>

  <Card title="Organizações e staff" icon="sitemap">
    Gerencie organizações e a equipe de staff (promover, demitir), com hierarquia configurável.
  </Card>

  <Card title="Salários" icon="money-bill">
    Grupos de salário com pagamento automático a cada 30 minutos.
  </Card>

  <Card title="Propriedades e baús" icon="house">
    Edite propriedades e crie/gerencie baús diretamente pelo painel.
  </Card>

  <Card title="Avisos e chat de staff" icon="bell">
    Avisos, anúncios e um chat exclusivo da staff (histórico das últimas 50 mensagens).
  </Card>
</CardGroup>

***

## Dependências

<CardGroup cols={2}>
  <Card title="vrp" icon="layer-group">
    Framework base (`@vrp/lib/utils.lua`, `@vrp/config/Global.lua`, `Item.lua`, `Vehicle.lua`).
  </Card>

  <Card title="oxmysql" icon="database">
    Acesso ao banco de dados.
  </Card>
</CardGroup>

<Info>
  Integrações via exports (opcionais): `five-vehicles`, `propertys`, `five_logs` (logs), `PL_PROTECT` (anti-cheat) e `engine`.
</Info>

***

## Configuração

Todo o ajuste do recurso fica em `config/config.lua`.

<AccordionGroup>
  <Accordion title="config/config.lua — Configurações principais" icon="sliders">
    ```lua theme={null}
    Config.ImagesProvider = {
        Items    = ItemsURL,                                  -- imagem de item: Items .. <img> .. ".png"
        Vehicles = "https://cdn.blacknetwork.com.br/conce/",  -- imagem de veículo: Vehicles .. <spawn> .. ".png"
    }

    Config.Permission = "Admin"   -- grupo/permissão usado em TODAS as checagens de acesso

    Config.ThemeColor = "#0143bb" -- cor da UI (Theme.main em Global.lua tem prioridade)

    Config.Cache = {
        Organizations = { Duration = 30000, Enabled = true },  -- cache da lista de grupos (ms)
    }
    ```
  </Accordion>

  <Accordion title="config/config.lua — Cargos de staff" icon="user-shield">
    ```lua theme={null}
    Config.StaffGroups = {
        ["Owner"]     = { Level = 4, Color = "#FFD700", CanPromote = true,  CanDemote = true,  CanManage = true },
        ["Admin"]     = { Level = 3, Color = "#FF4444", CanPromote = true,  CanDemote = true,  CanManage = true },
        ["Moderador"] = { Level = 2, Color = "#3C8EDC", CanPromote = false, CanDemote = false, CanManage = false },
        ["Suporte"]   = { Level = 1, Color = "#10B981", CanPromote = false, CanDemote = false, CanManage = false },
    }
    -- A chave é o nome do grupo/permissão vRP. Level = peso hierárquico interno (ordena a lista).

    Config.StaffHierarchy = { "Suporte", "Moderador", "Admin", "Owner" }
    -- Ordem (do menor ao maior) para calcular promoção/rebaixamento.
    ```

    <Tip>
      Para adicionar um cargo, crie a entrada em `StaffGroups` (chave = permissão vRP exata) e inclua o nome em `StaffHierarchy`.
    </Tip>
  </Accordion>
</AccordionGroup>

***

## Comandos

O recurso registra um único comando de chat; as demais ações partem da UI.

| Comando  | Permissão (nível) | Descrição                     |
| -------- | ----------------- | ----------------------------- |
| `/admin` | `Admin` nível 4   | Abre o painel administrativo. |

<Note>
  As demais ações são acionadas pela UI, cada uma com sua checagem de nível no servidor (`HasAdminLevel(user_id, nível)`). Lembre da semântica vRP: **nível menor = mais privilégio**; `nil` aceita qualquer nível. Exemplos de níveis exigidos: matar jogador (2), dar dinheiro (1), kick (5), gerar item (3), spawnar veículo (2), promover/demitir staff (1), editar propriedade (2), criar/editar baú (2).
</Note>

***

## Localizações

O **five-admin** não possui locais fixos no mapa: é um painel via NUI aberto por comando. As únicas coordenadas envolvidas são dinâmicas: a posição do admin/alvo gravada nos logs (`LogCoords`/`GetEntityCoords`) e teleportes para coordenadas digitadas na UI. Os baús criados pelo painel (tabela `five_admin_chests`) guardam suas próprias coordenadas, definidas pelo staff em tempo de uso (não há valores fixos no config).

***

## Exports

**Nenhum.** O recurso não publica exports; apenas consome de outros.

***

## Eventos

A interface se comunica com o servidor por uma série de net events, validados por nível.

| Evento                             | Direção             | Descrição                                                                                                                                             |
| ---------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `five-admin:openPanel`             | Comando → Cliente   | Abre a UI após `/admin`.                                                                                                                              |
| `five-admin:*`                     | Cliente ↔ Servidor  | Dezenas de net events (um por ação: jogadores, veículos, itens, staff, salários, propriedades, baús, avisos, chat). Cada um valida nível no servidor. |
| `Notify`                           | Externo disparado   | Notificações.                                                                                                                                         |
| `engine:tryFuel` / `plateEveryone` | Externos disparados | Após spawn de veículo.                                                                                                                                |

<Note>
  O bloco de garagens dinâmicas está comentado, pois essa função migrou para o `/gmanager` do `five-vehicles`.
</Note>

***

## Banco de Dados

As tabelas abaixo são criadas automaticamente (`InitDatabase`).

| Tabela              | Conteúdo                                                           |
| ------------------- | ------------------------------------------------------------------ |
| `five_admin_notify` | Avisos criados pelo painel.                                        |
| `five_admin_chat`   | Histórico do chat de staff (últimas 50).                           |
| `five_admin_salary` | Grupos de salário (`name`, `group`, `amount`).                     |
| `five_admin_chests` | Baús gerenciados pelo painel (modos 1–4; `distance` = 0.5 a 10.0). |

<Info>
  Tabelas de terceiros lidas/escritas: `characters`, `accounts` (whitelist), `propertys`, `chests` (vRP), `five_characters_vehicles`.
</Info>

***

## Customização

* **Permissão de acesso:** ajuste `Config.Permission`. Os níveis por ação estão fixos em `server-side/core.lua` (chamadas `HasAdminLevel(user_id, <nível>)`).
* **Aparência:** prefira `Theme.main` em `Global.lua` (tem prioridade); `Config.ThemeColor` é fallback.
* **Imagens (CDN):** troque `Config.ImagesProvider.Vehicles` e a `ItemsURL` do vRP.
* **Cargos de staff:** edite `Config.StaffGroups` (chave = permissão vRP) e mantenha `StaffHierarchy` coerente.
* **Salários:** geridos pela UI (tabela `five_admin_salary`); pagamento automático a cada 30 min (fixo no código).
* **Logs:** ações registradas via `five_logs` (`AddLog`) por categoria (`KICK`, `MONEY`, `SPAWNCAR`, etc.). Sem `five_logs` iniciado, são ignorados.