Configuração da Tabela 'systems'

Documentação da Tabela systems

Introdução

A tabela systems no backend do CSBBenk é um componente crítico que armazena configurações globais em formato de chave-valor, onde o valor é um campo JSON. Essas configurações permitem controlar dinamicamente diversos aspectos da aplicação sem a necessidade de fazer um novo deploy do código.

As configurações podem abranger desde expirações de tokens e chaves de segurança até elementos de branding, como estilos visuais e contas bancárias vinculadas. As alterações podem ser realizadas de duas formas principais: diretamente via consultas SQL ou através do painel administrativo.

Geralmente, nas seeds da API do CSBBenk, uma estrutura base já é criada para servir de exemplo e facilitar a configuração inicial.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição
id	INTEGER	Identificador único auto-incrementado (Chave Primária).
key	VARCHAR	O nome (chave) único do parâmetro de sistema (ex: ‘whitelist’).
value	JSONB ou TEXT	O valor da configuração, armazenado em formato JSON para flexibilidade.
status	VARCHAR	O status do parâmetro (ex: ‘ACTIVE’ ou ‘INACTIVE’).
created_at	TIMESTAMP WITH TIME ZONE	Data e hora de criação do registro.
updated_at	TIMESTAMP WITH TIME ZONE	Data e hora da última atualização do registro.

Exemplo de consulta SQL para visualizar todas as configurações:

SELECT * FROM systems ORDER BY id;

---

Operacionalização via Painel Administrativo

No painel de administração, as configurações da tabela systems são abstraídas em diferentes seções para facilitar a edição:

1. Limites e Taxas: Ajustes em taxas de transação ou limites (ex: saque diário) são feitos na seção “Fees e Limites”. Ao salvar, o sistema atualiza o objeto JSON dentro da chave 'configurations'.
2. Conta Vinculada: A definição da conta que recebe as taxas de serviço é configurada em uma seção específica, que atualiza as chaves 'bank_account' ou 'configurations'. O painel valida a estrutura do JSON antes de salvar.
3. Outras Configurações: Permissões de interface ('permissions'), botões personalizados ('personal_buttons') ou versões de componentes ('versions') são editados através de formulários dedicados.

Qualquer alteração feita através do painel administrativo atualiza automaticamente o campo updated_at.

---

Operacionalização via SQL

Atualizar uma Configuração Existente

Para modificar um valor JSON existente, use a função jsonb_set.

Exemplo: Alterar a taxa (fee_rate) dentro da chave 'configurations' (supondo id = 2).

UPDATE systems
SET value = jsonb_set(value::jsonb, '{fees_rate}', '0.015'::jsonb),
    updated_at = CURRENT_TIMESTAMP AT TIME ZONE 'America/Sao_Paulo'
WHERE id = 2 AND key = 'configurations';

Deletar uma Configuração

Para remover um parâmetro obsoleto:

DELETE FROM systems WHERE key = 'old_key' AND status = 'ACTIVE';

---

Exemplos de Configurações (Chaves)

Abaixo estão detalhadas as principais chaves utilizadas na tabela systems:

1. Chave: whitelist

• Propósito: Controla listas de permissões, como IPs autorizados.
• JSON: {"active": boolean}
• Exemplo: {"active": false}
• Operação: Editável via painel admin (“Segurança”) ou SQL.

2. Chave: token_expirations

• Propósito: Define os tempos de expiração (em segundos) para tokens de autenticação e OTPs.
• JSON: {"otp": int, "auth": int, "refresh": int}
• Exemplo: {"otp": 180, "auth": 1800, "refresh": 3600}
• Operação: Ajustável via painel admin (“Autenticação”).

3. Chave: permissions

• Propósito: Gerencia a visibilidade de elementos na UI, como botões e seções.
• JSON: {"pages": {"onboarding": {"button_pf": boolean, "button_pj": boolean}}}
• Exemplo: {"pages": {"onboarding": {"button_pf": true, "button_pj": true}}}
• Operação: Editável via painel admin.

4. Chave: block_login

• Propósito: Permite bloquear o login por canal (ex: mobile, web).
• JSON: {"mobile": boolean, "administrator": boolean}
• Exemplo: {"mobile": false, "administrator": false}
• Operação: Geralmente via SQL para manutenções emergenciais.

5. Chave: secrets

• Propósito: Armazena chaves criptográficas, como pares de chaves pública/privada.
• JSON: {"public_key": string, "private_key": string}
• Exemplo: Chaves no formato PEM.
• Operação: Edição cuidadosa via painel admin.

6. Chave: personal_buttons

• Propósito: Define botões personalizados no dashboard do cliente.
• JSON: [{"type": string, "label": string, "value": URL}, ...]
• Exemplo: Botões para download de extratos CNAB ou acesso a um portal externo.
• Operação: Editável via painel admin ou SQL.

7. Chave: bank_account

• Propósito: Define a conta bancária vinculada para recebimento de taxas.
• JSON: {"body": {"owners": [...], "businessName": string, ...}}
• Exemplo: Dados completos da conta da CSB Crie Seu Banco Digital.
• Operação: Editável via painel admin.

8. Chave: company

• Propósito: Armazena informações corporativas e de branding.
• JSON: {"cors": string, "logo": URL, ...}
• Exemplo: Dados da CSBBenk, incluindo domínios permitidos (CORS) e logos.
• Operação: Editável via painel admin.

9. Chave: versions

• Propósito: Rastreia as versões de componentes da plataforma (API, mobile, etc.).
• JSON: {"api": string, "mobile": string, ...}
• Exemplo: {"api": "2.5.0", "mobile": "1.7.0"}
• Operação: Atualizado via painel admin após cada deploy.

10. Chave: configurations

• Propósito: Agrupa configurações gerais, como ativação de taxas e integrações.
• JSON: {"fees": boolean, "castle": boolean, ...}
• Exemplo: Ativa ou desativa a cobrança de taxas ou a integração com o Castle.
• Operação: Editável via painel admin.

11. Chave: bypass_otp

• Propósito: Lista de documentos (CPFs/CNPJs) que podem ignorar a verificação OTP.
• JSON: [string, ...]
• Exemplo: ["54769222000100"]
• Operação: Editável via painel admin para fins de teste ou suporte.

12. Chave: system_styles

• Propósito: Define os estilos visuais da plataforma (whitelabel).
• JSON: {"style": {"colors": {...}, "images": {...}}, ...}
• Exemplo: Paleta de cores, logos e imagens de fundo.
• Operação: Editável via painel admin para customização de temas.