Pular para o conteúdo principal

Mapeamento de Banco de Dados — API Keys

Pilar: 04 — Banco de Dados / Tabelas
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server (app/models.py, app/api/web/apiKey.py)

1. Visão Geral da Modelagem​

Diferente de sistemas que utilizam uma tabela dedicada N:1 para API Keys, a arquitetura do Gatein armazena os pares de chaves de integração diretamente como atributos na tabela companies. Essa decisão simplifica a consulta de middleware e garante acesso em tempo constante O(1) sem JOINs desnecessários nas requisições operacionais de alta frequência.

2. Atributos Físicos de API Keys na Tabela companies​

Nome da ColunaTipo SQLConstraintsDescrição / Regra
api_key_prefixVARCHAR(16)NULLABLE, INDEXPrefixo visual de 8 caracteres da chave primária (ex: gt_a1b2c345)
api_key_hashVARCHAR(255)NULLABLEHash seguro (bcrypt) da chave primária em texto claro
api_key_secondary_prefixVARCHAR(16)NULLABLE, INDEXPrefixo visual de 8 caracteres da chave secundária
api_key_secondary_hashVARCHAR(255)NULLABLEHash seguro (bcrypt) da chave secundária em texto claro

3. Índices e Performance​

  • idx_companies_api_key_prefix: Índice B-Tree na coluna api_key_prefix para busca acelerada durante a autenticação por chave primária.
  • idx_companies_api_key_secondary_prefix: Índice B-Tree na coluna api_key_secondary_prefix para busca por chave secundária.

4. Diagrama ER de Relacionamento de Tenant​

erDiagram
    COMPANIES ||--o{ APPOINTMENTS : "gerencia"
    COMPANIES ||--o{ DRIVERS : "cadastra"
    COMPANIES {
        uuid id PK
        string name
        string cnpj
        string api_key_prefix "Indexado"
        string api_key_hash "Secret Hash"
        string api_key_secondary_prefix "Indexado"
        string api_key_secondary_hash "Secret Hash"
    }

5. Regras de Integridade de Banco de Dados​

  1. Limpeza Simultânea de Par: Ao revogar uma chave, as colunas api_key_prefix e api_key_hash (ou o par secundário) são obrigatoriamente setadas para NULL em uma única transação atômica (db.commit()).
  2. Imutabilidade Direta do Hash: O hash gravado no banco de dados não pode ser editado manualmente; toda alteração deve ser intermediada pelo método APIKeyManager.generate_key_pair().