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

> Sistema bancário completo em NUI (React) para vRP: conta pessoal, contas conjuntas, transferências, faturas, multas e investimentos (CDB).

O **five-bank** é o recurso de banco do servidor. Ele fornece uma interface NUI moderna (React + Vite, já compilada em `web/build/`) acessível em pontos de atendimento (caixas eletrônicos) espalhados pelo mapa via `ox_target`.

## Funcionalidades

<CardGroup cols={2}>
  <Card title="Conta pessoal" icon="wallet">
    Depósito e saque do saldo bancário do vRP usando o item `dollar`.
  </Card>

  <Card title="Contas conjuntas" icon="users">
    Contas compartilhadas dos tipos `casal`, `familia`, `empresarial` e `conjunto`, com convites (aceitar/recusar) e limite de participantes configurável.
  </Card>

  <Card title="Transferências" icon="arrow-right-arrow-left">
    Entre jogadores (por chave de transferência: usuário ou passaporte) e para contas conjuntas (chave no formato `j{id}`).
  </Card>

  <Card title="Faturas e impostos" icon="file-invoice-dollar">
    Faturas (`bank_invoices`) e impostos legados (`taxes`): consulta e pagamento.
  </Card>

  <Card title="Multas" icon="gavel">
    Leitura e pagamento de multas pendentes da tabela `mdt_creative_fines`.
  </Card>

  <Card title="Investimentos (CDB)" icon="chart-line">
    Aplicação e resgate com rendimento diário fixo de 1,15% (CDB 115%).
  </Card>

  <Card title="Histórico de saldo" icon="clock-rotate-left">
    Gravação semanal e mensal para alimentar os gráficos da dashboard.
  </Card>

  <Card title="Personalização da conta" icon="user-pen">
    Foto de perfil, nome, apelido, username, gênero, tipo de chave de transferência e PIN de segurança.
  </Card>
</CardGroup>

<Info>
  Integração opcional de logs via `five_logs` (depósito, saque e transferência).
</Info>

<Note>
  O recurso cria automaticamente todas as suas tabelas no MySQL ao iniciar. Não é necessário rodar SQL manualmente.
</Note>

***

## Dependências

Declaradas/usadas no `fxmanifest.lua` e no código.

<CardGroup cols={2}>
  <Card title="vrp" icon="layer-group">
    Framework base (`@vrp/lib/utils.lua`, `@vrp/config/Global.lua`, `@vrp/config/Item.lua`, além de `lib/Tunnel` e `lib/Proxy`).
  </Card>

  <Card title="oxmysql" icon="database">
    Acesso ao banco de dados (`@oxmysql/lib/MySQL.lua`).
  </Card>

  <Card title="ox_target" icon="bullseye">
    Cria as zonas de interação dos caixas (`exports.ox_target:addSphereZone`). **Obrigatório** para abrir o banco pelo mundo.
  </Card>

  <Card title="five_logs (opcional)" icon="file-lines">
    Se estiver iniciado, registra logs das operações. O recurso funciona normalmente sem ele.
  </Card>
</CardGroup>

<Info>
  Dependências de itens/sistema vRP usadas em runtime:

  * Item **`dollar`** – usado em depósitos e saques (`vRP.TakeItem` / `vRP.GenerateItem`).
  * Tabelas externas **`taxes`**, **`invoices`** e **`mdt_creative_fines`** – consultadas para impostos, faturas legadas e multas (geradas por outros recursos, como o MDT).
</Info>

***

## Configuração

Todo o ajuste do recurso fica em `config/config.lua`. O arquivo `config/functions.lua` contém apenas a criação de tabelas e funções auxiliares internas (não precisa ser editado).

<AccordionGroup>
  <Accordion title="config/config.lua — Cor do tema" icon="palette">
    ```lua theme={null}
    Bank.ThemeColor = "#0143bb"
    -- Cor principal (hex) usada na UI do banco.
    -- Atenção: Theme.main, definido em vrp/config/Global.lua, tem PRIORIDADE.
    -- Se Theme.main estiver definido e não for vazio, ele sobrescreve esta opção.
    -- Para usar a cor do five-bank, deixe Theme.main vazio no Global.lua.
    ```
  </Accordion>

  <Accordion title="config/config.lua — Limite de participantes por tipo de conta conjunta" icon="users">
    ```lua theme={null}
    Bank.MaxParticipants = {
        casal       = 2,   -- conta de casal: no máximo 2 pessoas
        familia     = 6,   -- conta familiar: no máximo 6 pessoas
        empresarial = 10,  -- conta empresarial: no máximo 10 pessoas
        conjunto    = 4,   -- conta conjunta genérica: no máximo 4 pessoas
    }
    -- O limite INCLUI o criador da conta.
    -- Ex.: familia = 6 → criador + 5 convidados.
    ```

    <Note>
      Para contas `casal` e `familia` o servidor exige no mínimo 2 participantes. Se você adicionar um novo tipo aqui, precisará também incluí-lo na lista `validTypes` em `server-side/core.lua`.
    </Note>
  </Accordion>

  <Accordion title="config/config.lua — Locais de acesso (caixas eletrônicos)" icon="map-pin">
    ```lua theme={null}
    Bank.Locations = {
        vec3(149.64, -1041.36, 29.59),
        vec3(313.95, -279.74, 54.39),
        vec3(-351.2, -50.57, 49.26),
        vec3(-2961.85, 482.87, 15.92),
        vec3(1175.09, 2707.53, 38.31),
        vec3(-1212.37, -331.37, 38.0),
        vec3(-112.86, 6470.46, 31.85),
    }
    -- Lista de coordenadas onde aparece a opção "Abrir Banco" (via ox_target).
    -- Cada coordenada vira uma sphere zone de raio 1.75.
    -- Adicione/remova linhas vec3(x, y, z) para criar ou tirar pontos de banco.
    ```
  </Accordion>

  <Accordion title="config/config.lua — Impostos (taxas)" icon="percent">
    ```lua theme={null}
    Bank.Tax = {
        Rate = 0.10,  -- Taxa base sobre o valor (10%)
        VipDiscounts = {
            { permission = "Ouro",   multiplier = 0.65 },
            { permission = "Prata",  multiplier = 0.75 },
            { permission = "Bronze", multiplier = 0.85 },
        },
    }
    ```

    * `Bank.Tax.Rate` – percentual base do imposto aplicado pelo export `AddTaxes`. Com `0.10`, um valor base de `1000` gera imposto de `100`.
    * `Bank.Tax.VipDiscounts` – descontos por permissão vRP (`vRP.HasService`). O primeiro item correspondente da lista é aplicado (ordem importa) e seu `multiplier` multiplica o imposto. Ex.: jogador **Ouro** paga `100 * 0.65 = 65`. Quanto menor o `multiplier`, maior o desconto.

    <Note>
      O imposto final é arredondado para baixo (`math.floor`) e, se ficar menor que `1`, não é gerado.
    </Note>
  </Accordion>
</AccordionGroup>

***

## Localizações

Pontos de acesso ao banco definidos em `Bank.Locations` (`config/config.lua`). Cada coordenada vira uma `addSphereZone` do `ox_target` (raio 1.75) com a opção "Abrir Banco".

| Local   | Coordenadas                   | Tipo                    |
| ------- | ----------------------------- | ----------------------- |
| Caixa 1 | vec3(149.64, -1041.36, 29.59) | Zona ox\_target (banco) |
| Caixa 2 | vec3(313.95, -279.74, 54.39)  | Zona ox\_target (banco) |
| Caixa 3 | vec3(-351.2, -50.57, 49.26)   | Zona ox\_target (banco) |
| Caixa 4 | vec3(-2961.85, 482.87, 15.92) | Zona ox\_target (banco) |
| Caixa 5 | vec3(1175.09, 2707.53, 38.31) | Zona ox\_target (banco) |
| Caixa 6 | vec3(-1212.37, -331.37, 38.0) | Zona ox\_target (banco) |
| Caixa 7 | vec3(-112.86, 6470.46, 31.85) | Zona ox\_target (banco) |

***

## Comandos

**Nenhum.** O recurso não registra comandos de chat. O banco é aberto pela interação `ox_target` nos `Bank.Locations`, ou disparando o evento `five-bank:open` a partir de outro recurso.

***

## Exports

### Servidor (`server-side/core.lua`)

Exports compatíveis (substituem o antigo `exports.bank:*`). `passport` corresponde ao `user_id` do vRP.

| Export            | Assinatura                                 | Descrição                                                                                                                                                  |
| ----------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AddTransactions` | `(passport, ttype, price, reference)`      | Insere uma transação na conta pessoal do jogador (`bank_transactions`).                                                                                    |
| `AddTaxes`        | `(passport, name, valuation, description)` | Cria um imposto na tabela `taxes` aplicando `Bank.Tax.Rate` e o desconto VIP. Retorna `false` se `valuation <= 0` ou se o imposto final for menor que `1`. |
| `CheckTaxes`      | `(passport)`                               | Retorna `true` (e notifica) se houver impostos pendentes há mais de 24h.                                                                                   |
| `CheckFines`      | `(passport)`                               | Retorna `true` (e notifica) se houver multas não pagas há mais de 24h.                                                                                     |
| `Taxs`            | `(passport)`                               | Retorna a lista de impostos do jogador.                                                                                                                    |
| `Fines`           | `(passport)`                               | Retorna a lista de multas não pagas formatada.                                                                                                             |
| `Invoices`        | `(passport)`                               | Retorna faturas legadas (`invoices`).                                                                                                                      |
| `Transactions`    | `(passport, limit)`                        | Retorna as últimas transações pessoais. `limit` padrão = `6`.                                                                                              |

Exemplo de uso a partir de outro recurso:

```lua theme={null}
exports["five-bank"]:AddTaxes(passport, "Imposto de Garagem", 5000, "Cobrança mensal")
local pendentes = exports["five-bank"]:CheckFines(passport)
```

### Cliente

**Nenhum** export é exposto no client-side.

***

## Eventos

| Evento           | Direção                      | Descrição                                                                                             |
| ---------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| `five-bank:open` | Cliente (`RegisterNetEvent`) | Abre a interface do banco. Pode ser disparado por outro recurso com `TriggerEvent("five-bank:open")`. |

<Note>
  Notificações são enviadas via evento vRP `Notify` no formato `("Banco", mensagem, cor, duração)`.
</Note>

***

## Banco de Dados

Tabelas criadas automaticamente (`CREATE TABLE IF NOT EXISTS`) na inicialização.

| Tabela                 | Função                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| `bank_accounts`        | Dados da conta: foto, nome, apelido, username, gênero, tipo de chave e PIN (padrão `0000`). |
| `bank_transactions`    | Histórico de transações (depósito, saque, transferência, fatura, imposto, investimento).    |
| `bank_balance_history` | Snapshots de saldo por período (gráficos).                                                  |
| `bank_invoices`        | Faturas modernas do jogador (`pending`/`paid`).                                             |
| `bank_joint_accounts`  | Contas conjuntas: nome, tipo, membros (JSON), saldo e criador.                              |
| `bank_investments`     | Saldo investido em CDB por jogador.                                                         |
| `bank_joint_invites`   | Convites para contas conjuntas.                                                             |

<Info>
  Tabelas **externas** apenas lidas/atualizadas: `taxes`, `invoices`, `mdt_creative_fines`.
</Info>

***

## Customização

### Locais dos caixas

* Adicione/remova pontos em `Bank.Locations`. Para mudar raio/ícone/texto, edite o bloco `addSphereZone` em `client-side/core.lua`.

### Contas conjuntas

* Ajuste a capacidade em `Bank.MaxParticipants` (inclui o criador). Para criar um tipo novo, adicione a chave aqui **e** na tabela `validTypes` em `server-side/core.lua`.

### Impostos e descontos VIP

* `Bank.Tax.Rate` controla o percentual base. Em `Bank.Tax.VipDiscounts`, mapeie as permissões do seu servidor para multiplicadores (a ordem importa).

### Valores fixos no código (não estão no config)

Para alterá-los edite `server-side/core.lua`:

* **Taxa diária do CDB**: `CDB_DAILY_RATE = 0.0115` (1,15% ao dia).
* **PIN padrão**: `"0000"` (4 dígitos numéricos).
* **Item de depósito/saque**: `"dollar"`.