> ## 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-roubos

> Sistema de roubos com painel administrativo (NUI), killfeed, votação de rendição, fluxo bandidos × policiais × reféns, histórico em banco e logs via webhook.

O **five-roubos** adiciona pontos de roubo interativos ao mapa, cada um vinculado a um **preset** (recompensa, cooldown, itens necessários, animação, permissão, projeção bandidos×policiais), com painel administrativo em NUI, killfeed, histórico em banco e logs via webhook.

## Funcionalidades

<CardGroup cols={2}>
  <Card title="Pontos por preset" icon="map-pin">
    Cada ponto de roubo é vinculado a um preset com recompensa, cooldown, itens necessários, animação, permissão e projeção bandidos×policiais.
  </Card>

  <Card title="Painel administrativo" icon="sliders">
    Gerenciamento de presets e pontos em runtime via NUI (`/bk roubos`).
  </Card>

  <Card title="Killfeed e scoreboard" icon="list">
    HUD de partida com scoreboard; as mortes alimentam o killfeed em tempo real.
  </Card>

  <Card title="Histórico em banco" icon="database">
    Cada roubo concluído é gravado no histórico (preset, vencedor, duração, killfeed).
  </Card>
</CardGroup>

***

## Como funciona

<Steps>
  <Step title="Interação no ponto">
    O jogador pressiona `E` no ponto de roubo.
  </Step>

  <Step title="Validação do servidor">
    O servidor valida preset, permissão, cooldown, mínimo de policiais e itens.
  </Step>

  <Step title="Montagem dos times">
    O "pusher" escolhe bandidos/reféns e um policial monta o time policial.
  </Step>

  <Step title="Início do roubo">
    Ao entrarem no perímetro o roubo inicia (HUD + scoreboard) e as mortes alimentam o killfeed.
  </Step>

  <Step title="Recompensa e histórico">
    O time vencedor recebe a recompensa e o roubo é gravado no histórico.
  </Step>
</Steps>

***

## Dependências

<CardGroup cols={2}>
  <Card title="vRP" icon="cube">
    Framework base (Proxy/Tunnel; `Passport`, `HasGroup`, `HasService`, `GiveItem`, `Query`, `Request`).
  </Card>

  <Card title="MySQL" icon="database">
    Persistência via `vRP.Query`/`Prepare`.
  </Card>
</CardGroup>

<Info>
  **Opcional:** `five_logs` — logs `ROUBO-INICIOU` e `ROUBO`.
</Info>

***

## Configuração

<AccordionGroup>
  <Accordion title="shared/config.lua — opções gerais e permissões" icon="sliders">
    ```lua theme={null}
    Config.Roubos = {
        openScoreboardKey      = 'INSERT',     -- tecla do scoreboard (remapeável)
        NeedAdminAuthorization = false,        -- (ramo true vazio/TODO no código)
        disableCooldown        = false,        -- só para testes
        blipCooldown           = 100,          -- duração (s) do blip de rota policial
        cmdPermission          = 'AdminCommand',-- permissão p/ abrir o painel admin
        LogWebhook             = '',           -- webhook de eventos de roubo
        ThemeColor             = '#0143bb',    -- copie de vrp/config/Global.lua → Theme.main
    }

    Config.Permissions = {
        AdminCommand  = { Groups = { 'Admin', 'admin' }, MinHierarchy = 1 },
        ManagePresets = { Groups = { 'Admin', 'admin' }, MinHierarchy = 1 },
        ViewHistoric  = { Groups = { 'Admin', 'admin' }, MinHierarchy = 1 },
        Police        = { Groups = { 'Pc','Gcm','Coe','Rota','Baep','Federal','Policia' }, MinHierarchy = nil },
    }
    -- A checagem usa Groups (com variações de hierarquia) + fallback HasPermission. MinHierarchy não é avaliado no código atual.

    Config.Hierarquia = { 'Coronel','Tenente-Coronel','Major', ... }  -- cargos policiais
    ```
  </Accordion>

  <Accordion title="Config.DeathEvent — killfeed" icon="skull">
    O killfeed é configurável em `Config.DeathEvent` (ícones por classe de arma e nomes via `add('classe', { WEAPON_X = 'Nome' })`).
  </Accordion>
</AccordionGroup>

<Note>
  `Config.Roubos.AdminWebhook` e `Config.Roubos.hitMarker` são lidos pelo código mas **não vêm definidos**; adicione em `Config.Roubos` se quiser usá-los (AdminWebhook cai em LogWebhook se vazio).
</Note>

***

## Comandos

Comandos disponíveis nos lados client e server.

| Comando                | Lado   | Permissão       | Descrição                     |
| ---------------------- | ------ | --------------- | ----------------------------- |
| `/bk roubos`           | client | `AdminCommand`  | Abre o painel administrativo. |
| `/roubos listar`       | server | `AdminCommand`  | Lista roubos em andamento.    |
| `/roubos deletar [ID]` | server | `AdminCommand`  | Cancela/deleta um roubo.      |
| `/placar`              | client | (durante roubo) | Abre o scoreboard.            |

***

## Exports

<Info>
  Não publica exports próprios. Consome `exports["five_logs"]:AddLog(...)` (opcional).
</Info>

***

## Banco de Dados

O schema fica em `install.sql` (idempotente, com migração das tabelas antigas `lotus_*`). Rode uma vez.

| Tabela                | Descrição                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| `five_roubos_points`  | Pontos no mapa (preset + coords JSON).                                                                        |
| `five_roubos_presets` | Config por tipo (recompensa, cooldown, itens, projeção, permissão).                                           |
| `five_roubos_history` | Histórico (preset, vencedor, duração, killfeed, timestamp). O cooldown usa o último registro de mesmo preset. |

***

## Localizações

Não há coordenadas fixas no `shared/config.lua`. Os pontos de roubo são criados em runtime pelo painel admin (`/bk roubos`) e gravados na tabela `five_roubos_points` (coluna de coords em JSON), sendo lidos do banco a cada boot. Os blips em volta de cada ponto (`AddBlipForRadius`, raio 50.0) e o blip de rota policial (`AddBlipForCoord`, sprite 1, cor 27) usam as coordenadas vindas do banco, definidas ao cadastrar o ponto.

***

## Customização

* **Permissões/cargos:** `Config.Permissions` e `Config.Hierarquia`.
* **Tema:** `Config.Roubos.ThemeColor` (copie de `Theme.main`).
* **Logs:** `Config.Roubos.LogWebhook` (+ opcional `AdminWebhook`).
* **Killfeed:** listas `add('classe', {...})` e `Config.DeathEvent.WeaponClassIcons`.
* **Presets e pontos:** criados em runtime pelo painel `/bk roubos` (não em config).

<Note>
  Constantes do fluxo (raios, timeouts, vida "down") estão hardcoded em `server/functions.lua` e `client/`. A UI fica em `ui/` (artefatos compilados; sem `src` no recurso, edite pelo projeto-fonte original).
</Note>