Documentação do Banco de Dados - CSBBenk

Tabela: aggregated_transaction_info

Descrição

Esta tabela armazena dados agregados de transações diárias para cada conta corrente (checking_account). O objetivo é fornecer um resumo rápido do volume e da quantidade de transações de entrada (cash-in) e saída (cash-out), tanto criadas quanto pagas, para otimizar consultas que necessitam desses totais diários.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de agregação.	Chave Primária
checkingAccountId	integer	Chave estrangeira que referencia a tabela checking_accounts.	Não Nulo, FK
date	date	A data para a qual os dados de transação foram agregados.	Não Nulo
referenceEndTime	time	A hora final da janela de agregação para o dia. Indica até que ponto do dia as transações foram incluídas.	Não Nulo
cashinPayedAmountSum	float	Soma dos valores de transações de entrada (crédito) que foram pagas no dia.	Não Nulo
cashoutPayedAmountSum	float	Soma dos valores de transações de saída (débito) que foram pagas no dia.	Não Nulo
cashinCreatedAmountSum	float	Soma dos valores de transações de entrada (crédito) que foram criadas no dia.	Não Nulo
cashoutCreatedAmountSum	float	Soma dos valores de transações de saída (débito) que foram criadas no dia.	Não Nulo
cashinPayedCount	integer	Número de transações de entrada (crédito) que foram pagas no dia.	Não Nulo
cashoutPayedCount	integer	Número de transações de saída (débito) que foram pagas no dia.	Não Nulo
cashinCreatedCount	integer	Número de transações de entrada (crédito) que foram criadas no dia.	Não Nulo
cashoutCreatedCount	integer	Número de transações de saída (débito) que foram criadas no dia.	Não Nulo

Relacionamentos

• checking_accounts: (n:1) Cada registro de agregação pertence a uma única conta corrente. A coluna checkingAccountId é a chave estrangeira.

Índices

• IDX_checkingAccount_date: Índice único composto pelas colunas checkingAccountId e date. Garante que haverá apenas um registro de agregação por conta corrente por dia.

Métodos Importantes da Entidade

• update(): Atualiza o registro de agregação com as transações mais recentes que ocorreram desde a última referenceEndTime.
• createRegister(...): Método estático para inicializar um novo registro de agregação para uma conta em uma data específica, geralmente com valores zerados.
• getAllWithinTimeWindow(...): Método estático que busca todos os registros de agregação para uma conta dentro de um intervalo de datas.
• getTransactionAggregationUpdate(...): Executa uma consulta SQL bruta para calcular os novos totais de transações a serem adicionados ao registro agregado.

---

Tabela: allow_list

Descrição

A tabela allow_list funciona como uma lista de permissões (whitelist) para funcionalidades específicas. Ela permite que um cliente (customer) restrinja o acesso a certas operações com base em um valor específico, como um endereço IP, um documento, etc.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro na lista de permissões.	Chave Primária
listName	varchar(100)	O nome da lista de permissões (ex: ip-allow-list, document-allow-list).	Não Nulo
value	varchar(100)	O valor que está sendo permitido (ex: um endereço IP, um número de documento).	Não Nulo
customerId	integer	Chave estrangeira que referencia a tabela customers.	FK

Relacionamentos

• customers: (n:1) Cada registro na lista de permissões pertence a um cliente. A coluna customerId é a chave estrangeira.

Índices

• IDX_listName_customer: Índice composto pelas colunas listName e customerId. Otimiza a busca por todos os valores permitidos para uma determinada lista de um cliente.

Métodos Importantes da Entidade

• isAllowed(listName, value, customer): Método estático que verifica duas coisas:
  1. Se a funcionalidade de “allow list” está ativa para o cliente através de uma FeatureFlag.
  2. Se o value fornecido está presente na lista de permissões (listName) para o customer especificado. Retorna true se a funcionalidade estiver desativada ou se o valor for encontrado, e false caso contrário.

---

Tabela: banks

Descrição

A tabela banks armazena uma lista de instituições financeiras que operam no Brasil. Ela serve como um repositório central de informações sobre bancos, incluindo seus nomes e códigos de identificação (ISPB e COMPE).

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único para cada banco.	Chave Primária
name	varchar(100)	O nome oficial do banco.	Não Nulo
ispb	varchar(100)	O Identificador do Sistema de Pagamentos Brasileiro (ISPB) do banco. É um código único de 8 dígitos.	Não Nulo
compe	varchar(20)	O Código de Compensação (COMPE) do banco. É um código de 3 dígitos usado para a compensação de cheques e outras transações.	Pode ser Nulo
createdAt	timestamp	Data e hora em que o registro do banco foi criado.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro do banco.	Gerado Automaticamente

Relacionamentos

Esta tabela é referenciada por outras tabelas que precisam associar informações a um banco específico, como checking_accounts e favorite_ted.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: batched_fee_charge

Descrição

A tabela batched_fee_charge é usada para registrar cobranças de taxas que são processadas em lote. Em vez de cobrar uma taxa a cada transação, o sistema pode agregar várias taxas e cobrá-las de uma só vez. Esta tabela armazena os detalhes de cada cobrança em lote.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da cobrança de taxa em lote.	Chave Primária
customerId	integer	Chave estrangeira que referencia o cliente (customer) que está sendo cobrado.	FK
feeType	enum	O tipo de taxa que está sendo cobrada (ex: percentage, fixed).	Não Nulo
fee	double precision	O valor ou percentual da taxa aplicada.	Não Nulo
baseValue	double precision	O valor base sobre o qual a taxa foi calculada.	Não Nulo
totalFee	double precision	O valor total da taxa cobrada.	Não Nulo
referenceStartDate	timestamp	A data de início do período de referência para o qual as taxas foram agregadas.	Não Nulo
referenceEndDate	timestamp	A data de fim do período de referência.	Não Nulo
conciliationId	varchar(100)	Um identificador de conciliação para esta cobrança em lote.	Não Nulo
description	varchar(250)	Uma descrição opcional para a cobrança.	Pode ser Nulo
concluded	boolean	Um booleano que indica se a cobrança da taxa foi concluída com sucesso.	default: false
operation_charged	varchar(10)	A operação (CREDIT ou DEBIT) que foi cobrada.	Pode ser Nulo
endToEndId	varchar(100)	O End-to-End ID da transação que efetivou a cobrança da taxa.	Pode ser Nulo

Relacionamentos

• customers: (n:1) Cada registro de cobrança de taxa em lote pertence a um cliente. A coluna customerId é a chave estrangeira.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: bb_batch_cashout

Descrição

Esta tabela armazena informações sobre lotes de transações de “cash-out” (saída de dinheiro) processados através do Banco do Brasil (BB). Ela agrupa múltiplas transações de retirada em um único lote para processamento.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do lote de cash-out.	Chave Primária
total_amount	float	O valor total de todas as transações incluídas no lote.	default: 0.0
status	integer	O status atual do processamento do lote. O valor numérico corresponde a um status definido em TransactionStatusNumber.	default: 0
request_number	integer	Um número de requisição associado ao lote, provavelmente fornecido pelo Banco do Brasil.	Não Nulo
checkingAccountId	integer	Chave estrangeira que referencia a conta corrente (checking_account) de onde os fundos foram retirados.	FK
createdAt	timestamp	Data e hora em que o registro do lote foi criado.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro do lote.	Gerado Automaticamente

Relacionamentos

• checking_accounts: (n:1) Cada lote de cash-out está associado a uma conta corrente. A coluna checkingAccountId é a chave estrangeira.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: billets

Descrição

A tabela billets armazena todos os dados relacionados a boletos bancários gerados no sistema. Isso inclui boletos de depósito, cobrança, e todos os seus detalhes, desde a criação até o pagamento.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do boleto.	Chave Primária
type	varchar(20)	Tipo do boleto (ex: deposit).	default: 'deposit'
dueDate	date	Data de vencimento do boleto.	Não Nulo
closePayment	date	Data limite para pagamento do boleto.	Não Nulo
amount	decimal	Valor principal do boleto.	Não Nulo, default: 0.0
checkingAccountId	integer	Chave estrangeira para a conta corrente (checking_account) que emitiu o boleto.	FK
payerId	integer	Chave estrangeira para o pagador (payer) do boleto.	FK
interest	json	Objeto JSON com as configurações de juros por atraso.	Pode ser Nulo
fine	json	Objeto JSON com as configurações de multa por atraso.	Pode ser Nulo
discounts	json	Objeto JSON com as configurações de descontos.	Pode ser Nulo
authenticationCode	varchar(100)	Código de autenticação do boleto, se aplicável.	Pode ser Nulo
ourNumber	varchar(60)	”Nosso Número”, o identificador do boleto no banco emissor.	Pode ser Nulo
singlePath	varchar(500)	Caminho para o arquivo do boleto individual (ex: PDF).	Pode ser Nulo
multiplePath	varchar(500)	Caminho para um arquivo com múltiplos boletos (carnê).	Pode ser Nulo
notes	varchar(200)	Instruções ou observações no corpo do boleto.	Pode ser Nulo
status	integer	Código numérico que representa o status do boleto (ex: 0 para pendente, 1 para pago).	default: 0
statusDescription	varchar(60)	Descrição textual do status (ex: ‘Processed’, ‘Paid’).	default: 'Processed'
meta	json	Campo para metadados diversos relacionados à criação do boleto.	Pode ser Nulo
digitable	varchar(200)	A linha digitável do boleto.	Pode ser Nulo
document	varchar(200)	Número do documento associado ao boleto.	Pode ser Nulo
paymentDate	date	Data em que o boleto foi efetivamente pago.	Pode ser Nulo
paymentMeta	json	Campo para metadados diversos relacionados ao pagamento.	Pode ser Nulo
paymentAmount	decimal	Valor total pago, incluindo juros, multas e descontos.	Pode ser Nulo
fineAmount	decimal	Valor da multa pago.	Pode ser Nulo
interestAmount	decimal	Valor dos juros pago.	Pode ser Nulo
discountAmount	decimal	Valor do desconto aplicado no pagamento.	Pode ser Nulo
installment	integer	Número da parcela atual (para carnês).	default: 1
installments	integer	Número total de parcelas (para carnês).	default: 1
reference	varchar(60)	Uma referência interna para o boleto.	Pode ser Nulo
externalReference	varchar(100)	Uma referência externa para o boleto.	Pode ser Nulo
items	json	Objeto JSON com a lista de itens da cobrança.	Pode ser Nulo
shipping	json	Objeto JSON com informações de frete.	Pode ser Nulo
splits	json	Objeto JSON com regras de divisão de pagamento (split).	Pode ser Nulo
ipAddress	varchar(60)	Endereço IP do solicitante que gerou o boleto.	Pode ser Nulo
postbackUrl	varchar(500)	URL para notificação (webhook) de eventos do boleto.	Pode ser Nulo
traceable	boolean	Indica se o boleto é rastreável.	default: false
sendEmail	boolean	Indica se um e-mail deve ser enviado ao pagador.	default: false
metadata	varchar(120)	Campo genérico para metadados adicionais.	Pode ser Nulo
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• checking_accounts: (n:1) Cada boleto é emitido por uma conta corrente.
• payers: (n:1) Cada boleto tem um pagador associado.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: blocked_payer

Descrição

A tabela blocked_payer é uma lista de bloqueio (blacklist) para pagadores. Ela armazena os documentos de pagadores que, por algum motivo, foram impedidos de realizar transações no sistema.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de bloqueio.	Chave Primária
document	varchar(100)	O número do documento (CPF/CNPJ) do pagador que está bloqueado.	Não Nulo, Único
owner	varchar(100)	Identificação de quem ou qual sistema realizou o bloqueio.	Não Nulo

Relacionamentos

Esta tabela não possui relacionamentos diretos (chaves estrangeiras) com outras tabelas, mas o campo document é usado para verificar se um pagador está na lista de bloqueio antes de processar uma transação.

Índices

• IDX_document: Índice único na coluna document. Garante que não haverá documentos duplicados na lista de bloqueio e otimiza a consulta de verificação.

Métodos Importantes da Entidade

• checkIsBlockedPayer(document): Método estático que recebe um número de documento e verifica se ele existe na tabela blocked_payer. Retorna true se o pagador estiver bloqueado e false caso contrário.

---

Tabela: blocked_pix_keys

Descrição

Similar à blocked_payer, a tabela blocked_pix_keys funciona como uma lista de bloqueio (blacklist), mas especificamente para chaves PIX. Ela impede que transações sejam realizadas utilizando as chaves PIX que estão registradas nesta tabela.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de bloqueio da chave PIX.	Chave Primária
key	varchar(100)	A chave PIX que está bloqueada (ex: e-mail, CPF, telefone, chave aleatória).	Não Nulo
owner	varchar(100)	Identificação de quem ou qual sistema realizou o bloqueio.	Não Nulo

Relacionamentos

Esta tabela não possui relacionamentos diretos (chaves estrangeiras). Ela é consultada durante o processo de validação de transações PIX.

Índices

Não há índices customizados definidos na entidade, além da chave primária. A consulta é feita diretamente pelo valor da coluna key.

Métodos Importantes da Entidade

• checkIsBlockedPixKey(pixKey): Método estático que recebe um objeto PixKey e verifica se o valor da chave (pixKey.key) existe na tabela blocked_pix_keys. Retorna true se a chave estiver bloqueada e false caso contrário.

---

Tabela: check_phone_numbers

Descrição

Esta tabela é responsável por gerenciar o processo de verificação de números de telefone dos usuários. Ela armazena tokens de verificação, controla seu status e prazo de validade, e associa o número de telefone a um usuário.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de verificação.	Chave Primária
phone_number	varchar(60)	O número de telefone que está sendo verificado.	Não Nulo
token	varchar(60)	O token único enviado ao usuário para verificação.	Não Nulo, Único
is_verified	boolean	Indica se o número de telefone foi verificado com sucesso.	default: false
verified_at	timestamp	Data e hora em que a verificação foi concluída.	Pode ser Nulo
expires_at	timestamp	Data e hora em que o token de verificação expira.	default: CURRENT_TIMESTAMP
imei	varchar(255)	IMEI do dispositivo móvel que solicitou a verificação.	Pode ser Nulo
platform	varchar(60)	Plataforma do dispositivo (ex: ‘iOS’, ‘Android’).	Pode ser Nulo
version	varchar(60)	Versão do aplicativo ou sistema operacional.	Pode ser Nulo
isActive	boolean	Indica se este registro de verificação está ativo.	default: true
sId	varchar(60)	Um ID de sessão ou serviço externo relacionado à verificação.	Pode ser Nulo
attempts	integer	Número de tentativas de verificação.	default: 1
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente
user_id	integer	Chave estrangeira que referencia o usuário (user) associado a esta verificação.	FK

Relacionamentos

• users: (n:1) Cada registro de verificação de telefone está associado a um usuário.

Índices

• A coluna token possui um índice único para garantir que não haja tokens duplicados.

---

Tabela: checking_account_custom_attributes

Descrição

Esta tabela permite armazenar atributos (metadados) personalizados no formato chave-valor para contas correntes (checking_accounts). É uma forma flexível de estender as informações de uma conta corrente sem precisar alterar a estrutura da tabela principal.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do atributo personalizado.	Chave Primária
checkingAccountId	integer	Chave estrangeira que referencia a conta corrente (checking_account) à qual este atributo pertence.	FK
key	varchar	A chave (nome) do atributo personalizado.	Não Nulo
value	varchar	O valor do atributo personalizado.	Não Nulo
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• checking_accounts: (n:1) Cada atributo personalizado está associado a uma única conta corrente.

Índices

• IDX_checkingAccount_key: Índice único composto pelas colunas checkingAccountId e key. Garante que cada chave de atributo seja única para uma determinada conta corrente.

---

Tabela: checking_accounts

Descrição

A tabela checking_accounts é central para o sistema, representando as contas correntes dos clientes. Ela armazena os detalhes bancários essenciais, como agência, número da conta e o banco associado.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da conta corrente.	Chave Primária
bankId	integer	Chave estrangeira que referencia o banco (banks) ao qual a conta pertence.	FK
type	varchar(100)	O tipo de conta (ex: PAYMENT_ACCOUNT, CHECKING_ACCOUNT).	default: 'PAYMENT_ACCOUNT'
agency	varchar(100)	O número da agência da conta.	Não Nulo
accountNumber	varchar(100)	O número da conta corrente.	Não Nulo
meta	json	Campo para metadados diversos relacionados à conta.	Pode ser Nulo
isActive	boolean	Indica se a conta corrente está ativa.	default: true
statusReason	varchar(100)	Motivo para o status atual da conta (ex: motivo de inativação).	Pode ser Nulo
createdAt	timestamp	Data e hora de criação do registro da conta.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• banks: (n:1) Cada conta corrente pertence a um banco.
• customers: (1:1) Cada conta corrente está diretamente associada a um cliente (customer).
• Outras Tabelas: É referenciada por muitas outras tabelas que lidam com transações e configurações financeiras, como transactions, billets, aggregated_transaction_info, etc.

Índices

Não há índices customizados definidos na entidade, além da chave primária e das chaves estrangeiras.

---

Tabela: claimed_pix_keys

Descrição

Esta tabela gerencia o processo de reivindicação de chaves PIX. Quando um usuário tenta registrar uma chave PIX que já pertence a outra pessoa, um processo de reivindicação é iniciado. Esta tabela rastreia o status dessas reivindicações.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de reivindicação.	Chave Primária
claimId	varchar(40)	O ID da reivindicação, geralmente fornecido pelo provedor de serviços PIX (PSP).	Não Nulo
status	enum	O status atual da reivindicação (ex: OPEN, CONFIRMED, CANCELLED).	Não Nulo, default: 'OPEN'
createdAt	timestamp	Data e hora em que o registro de reivindicação foi criado.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente
customerId	integer	Chave estrangeira que referencia o cliente (customer) que iniciou a reivindicação.	FK

Relacionamentos

• customers: (n:1) Cada reivindicação de chave PIX é iniciada por um cliente.

Índices

• IDX_status_customer: Índice composto nas colunas status e customerId. Otimiza a busca por reivindicações de um cliente com um status específico.

---

Tabela: client_credentials

Descrição

A tabela client_credentials armazena as credenciais de cliente (Client ID e Client Secret) usadas para autenticação de API, seguindo o fluxo de Client Credentials do OAuth 2.0. Essas credenciais são associadas a um cliente (customer) e permitem que sistemas externos se autentiquem para interagir com a API em nome desse cliente.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da credencial.	Chave Primária
client_id	varchar	O Client ID, um identificador público para a aplicação cliente.	Não Nulo
client_secret	varchar	O Client Secret, uma senha confidencial usada para autenticar a aplicação cliente.	Não Nulo
customerId	integer	Chave estrangeira que referencia o cliente (customer) ao qual estas credenciais pertencem.	Não Nulo, FK
expirationDate	timestamp	Data e hora em que as credenciais expiram.	Pode ser Nulo
isActive	boolean	Indica se as credenciais estão ativas e podem ser usadas para autenticação.	default: true
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente

Relacionamentos

• customers: (n:1) Cada par de credenciais de cliente está associado a um único cliente.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: compound_customers

Descrição

A tabela compound_customers é usada para criar uma relação entre dois clientes (customers) distintos, tratando-os como uma única entidade composta para fins específicos. Geralmente, um cliente é designado para operações de “cash-in” (entrada de dinheiro) e o outro para operações de “cash-out” (saída de dinheiro).

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de cliente composto.	Chave Primária
cashin_customer_id	integer	Chave estrangeira que referencia o cliente (customer) responsável pelas operações de cash-in.	Não Nulo, FK
cashout_customer_id	integer	Chave estrangeira que referencia o cliente (customer) responsável pelas operações de cash-out.	Não Nulo, FK

Relacionamentos

• customers (como cashin_customer_id): (1:1) Aponta para o cliente que lida com as entradas de fundos.
• customers (como cashout_customer_id): (1:1) Aponta para o cliente que lida com as saídas de fundos.

Índices

Não há índices customizados definidos na entidade, além da chave primária e das chaves estrangeiras.

---

Classe: CustomBaseEntity

Descrição

CustomBaseEntity não é uma tabela do banco de dados, mas sim uma classe base abstrata da qual muitas outras entidades do sistema herdam. Ela estende a BaseEntity do TypeORM e adiciona métodos utilitários estáticos que simplificam operações comuns de banco de dados.

Métodos Utilitários

createInstance<T>(obj)

• Descrição: Um método estático genérico que cria uma nova instância da entidade que o chama. Ele funciona como um atalho para new Entity() e Object.assign(), ou mais diretamente, para o método .create() do repositório do TypeORM.
• Parâmetros:
  • obj: Um objeto contendo as propriedades para inicializar a nova instância da entidade.
• Retorno: Uma nova instância da entidade, pronta para ser salva no banco de dados.
• Uso: const newUser = User.createInstance({ name: 'John Doe', email: 'john@example.com' });

findOneWhere<T>(where)

• Descrição: Um método estático genérico que busca o primeiro registro que corresponde a um conjunto de condições. É um atalho para o método .find() com as opções { where, take: 1 }.
• Parâmetros:
  • where: Um objeto de condição do TypeORM para filtrar a busca.
• Retorno: Uma promessa (Promise) que resolve para a primeira entidade encontrada que corresponde às condições, ou undefined se nenhum registro for encontrado.
• Uso: const user = await User.findOneWhere({ email: 'john@example.com' });

Propósito

O objetivo principal desta classe é fornecer uma API mais limpa e consistente para criar e buscar instâncias de entidades, promovendo a reutilização de código e simplificando a lógica nos serviços e repositórios.

---

Tabela: customer_aggregates

Descrição

A tabela customer_aggregates é usada para criar um relacionamento de agregação entre clientes. Ela permite que um cliente (customer) seja agrupado sob outro cliente (aggregate). Isso é útil em cenários de marketplace ou grupos de empresas, onde uma conta principal (agregadora) pode ter várias contas secundárias (agregadas) vinculadas a ela.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de agregação.	Chave Primária
customerId	integer	Chave estrangeira para o cliente principal/pai (customer).	FK
aggregateId	integer	Chave estrangeira para o cliente que está sendo agregado/filho (customer).	FK
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• customers (como customer): (n:1) Aponta para o cliente principal que agrega outros.
• customers (como aggregate): (n:1) Aponta para o cliente que é agregado.

Índices

• IDX_customer_aggregate: Índice composto nas colunas customerId e aggregateId.
• IDX_aggregate: Índice na coluna aggregateId para otimizar buscas por clientes agregados.

Métodos Importantes da Entidade

• set(customer, aggregate, manager?): Método estático para criar uma nova relação de agregação entre um customer e um aggregate. Permite o uso de um EntityManager para transações.
• checkIsAggregate(customer, aggregate): Método estático que verifica se um cliente (aggregate) já está agregado a outro (customer). Retorna true ou false.
• findCustomerByAggregate(aggregate): Método estático que encontra o cliente principal (customer) ao qual um determinado cliente agregado (aggregate) pertence.

---

Tabela: customer-custom-attributes

Descrição

Assim como a checking_account_custom_attributes, esta tabela permite armazenar atributos (metadados) personalizados no formato chave-valor, mas desta vez para a entidade Customer. É uma forma flexível de estender as informações de um cliente, frequentemente usada para armazenar identificadores customizados para fins de conciliação ou integração com sistemas externos.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do atributo personalizado.	Chave Primária
key	varchar(100)	A chave (nome) do atributo personalizado.	Não Nulo
value	varchar(100)	O valor do atributo personalizado.	Não Nulo
customerId	integer	Chave estrangeira que referencia o cliente (customer) ao qual este atributo pertence.	FK
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• customers: (n:1) Cada atributo personalizado está associado a um único cliente.

Índices

• IDX_customer_key: Índice único composto pelas colunas customerId e key. Garante que cada chave de atributo seja única para um determinado cliente.

Métodos Importantes da Entidade

• set(customIdentifier): Método estático para criar ou atualizar um atributo personalizado para um cliente.
• getCustomer(key, value): Método estático que busca e retorna o cliente (Customer) associado a um par específico de chave e valor.
• getValueFromKey(customer, key): Método estático que busca o valor de um atributo específico (key) para um determinado cliente (customer).

---

Tabela: customer_documents

Descrição

A tabela customer_documents armazena informações sobre os documentos enviados pelos clientes durante o processo de cadastro e verificação (KYC - Know Your Customer). Ela guarda as URLs dos arquivos de documento, bem como metadados sobre eles.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do documento.	Chave Primária
url	varchar(500)	A URL (geralmente de um serviço de armazenamento como S3) onde o arquivo do documento está localizado.	Não Nulo
fileName	varchar(200)	O nome original do arquivo do documento.	Pode ser Nulo
mimeType	varchar(60)	O tipo MIME do arquivo (ex: image/jpeg, application/pdf).	Pode ser Nulo
publicUrl	varchar(500)	Uma URL pública para acessar o documento, se aplicável.	Pode ser Nulo
documentType	varchar(20)	O tipo de documento enviado (ex: SELFIE, ID_CARD, PASSPORT).	default: 'SELFIE'
documentSide	varchar(20)	O lado do documento, se aplicável (ex: FRONT, BACK).	default: 'FRONT'
customerId	integer	Chave estrangeira que referencia o cliente (customer) que enviou o documento.	FK
token	varchar(60)	Um token associado ao upload do documento, para segurança ou rastreamento.	Pode ser Nulo
status	integer	Um código numérico que representa o status de verificação do documento.	default: 0
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• customers: (n:1) Cada documento pertence a um cliente. A coluna customerId é a chave estrangeira.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: customer_subscriptions

Descrição

A tabela customer_subscriptions gerencia as assinaturas de planos dos clientes. Ela vincula um cliente (customer) a um plano de assinatura (subscription_plan) e controla o ciclo de vida dessa assinatura, incluindo datas, pagamentos e renovação.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da assinatura do cliente.	Chave Primária
customerId	integer	Chave estrangeira para o cliente (customer) que possui a assinatura.	Não Nulo, FK
planId	integer	Chave estrangeira para o plano (subscription_plan) assinado.	Não Nulo, FK
startDate	timestamp	Data de início da vigência da assinatura.	Não Nulo
endDate	timestamp	Data de término da vigência da assinatura.	Não Nulo
paymentDay	integer	O dia do mês em que o pagamento da assinatura é devido.	Não Nulo
nextPaymentDate	timestamp	A data do próximo pagamento agendado.	Pode ser Nulo
autoRenew	boolean	Indica se a assinatura deve ser renovada automaticamente ao final do período.	Não Nulo, default: true
paymentPending	boolean	Indica se há um pagamento pendente para a assinatura.	default: true
paymentAmount	float	O valor do pagamento da assinatura.	default: 0
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• customers: (n:1) Cada registro de assinatura pertence a um cliente.
• subscription_plans: (n:1) Cada registro de assinatura está vinculado a um plano específico.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: customers

Descrição

A tabela customers é uma das entidades centrais do sistema, contendo todas as informações cadastrais dos clientes, sejam eles pessoas físicas ou jurídicas. Ela armazena desde dados pessoais e de contato até informações de segurança, configurações de PIX e relacionamentos com outras entidades.

Estrutura da Tabela

Informações Pessoais e de Contato

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do cliente.	Chave Primária
name	varchar(100)	Nome completo ou razão social do cliente.	Não Nulo
tradingName	varchar(100)	Nome fantasia (para pessoas jurídicas).	Pode ser Nulo
email	varchar(100)	Endereço de e-mail principal do cliente.	Não Nulo
phoneNumber	varchar(30)	Número de telefone de contato.	Pode ser Nulo
website	varchar(60)	Website do cliente.	Pode ser Nulo
document	varchar(14)	CPF ou CNPJ do cliente.	Pode ser Nulo
type	varchar(1)	Tipo de pessoa: ‘F’ para Física, ‘J’ para Jurídica.	default: 'F'
logo	varchar(500)	URL para a logomarca do cliente.	Pode ser Nulo

Endereço

Coluna	Tipo de Dados	Descrição
addressLine1	varchar(100)	Logradouro e número.
addressLine2	varchar(14)	Complemento.
neighborhood	varchar(100)	Bairro.
city	varchar(100)	Cidade.
state	varchar(20)	Estado.
postalCode	varchar(10)	CEP.
countryCode	varchar(2)	Código do país (ISO 3166-1 alpha-2). default: 'BR'

Status e Configurações da Conta

Coluna	Tipo de Dados	Descrição
isActive	boolean	Indica se o cliente está ativo no sistema. default: true
status	integer	Código numérico que representa o status do cadastro do cliente (ex: PROPOSTA_CRIADA, APROVADO).
statusDescription	varchar(200)	Descrição textual do status do cadastro.
isTransactionsAllowed	boolean	Indica se o cliente tem permissão para realizar transações. default: true
isInQueue	boolean	Flag para controle de processamento em fila.
inQueueAt	date	Data em que o cliente entrou na fila de processamento.

Relacionamentos e Chaves Estrangeiras

Coluna	Tipo de Dados	Descrição
checkingAccountId	integer	FK para a conta corrente principal do cliente em checking_accounts.
withdrawCheckingAccountId	integer	FK para a conta corrente de saque do cliente em checking_accounts.
userId	integer	FK para o usuário master (users) associado a este cliente.
pixSettingsId	integer	FK para as configurações de PIX do cliente em pix_settings.

Segurança e Chaves

Coluna	Tipo de Dados	Descrição
transactionPassword	varchar(255)	Hash da senha transacional do cliente. (Não selecionável por padrão)
privateKey	varchar(500)	Chave privada do cliente para assinaturas. (Não selecionável por padrão)
publicKey	varchar(500)	Chave pública do cliente.
hashPrivateKey	varchar	Hash da chave privada para validação. (Não selecionável por padrão)
webhookKey	varchar	Chave secreta para validação de webhooks. (Não selecionável por padrão)

Configurações de PIX e Transacionais

Coluna	Tipo de Dados	Descrição
pixKeyType	varchar(20)	Tipo da chave PIX principal do cliente (ex: CPF, EMAIL).
pixKeyValue	varchar(60)	Valor da chave PIX principal do cliente.
pixCashInKey	varchar(60)	Chave PIX específica para operações de cash-in.
billetLimitAmount	float	Limite de valor para emissão de boletos.

Metadados e Outros

Coluna	Tipo de Dados	Descrição
meta	json	Campo genérico para metadados.
deviceInfo	json	Informações do dispositivo usado no cadastro. (Não selecionável por padrão)
imei	varchar	IMEI do dispositivo. (Não selecionável por padrão)
marketPlaceId	varchar(100)	ID do marketplace ao qual o cliente pertence, se aplicável.
isMarketPlace	boolean	Indica se o cliente é um marketplace.
fallbackWebhookUrl	varchar(100)	URL de webhook de fallback.
createdAt	timestamp	Data de criação do registro.
updatedAt	timestamp	Data da última atualização.

Relacionamentos

• checking_accounts: (1:1) Um cliente possui uma conta corrente principal e pode ter uma conta de saque.
• users: (1:1) Um cliente tem um usuário “master” associado.
• customer_documents: (1:n) Um cliente pode ter vários documentos.
• customer_aggregates: (1:n) Um cliente pode agregar vários outros clientes.
• webhooks: (1:n) Um cliente pode ter várias configurações de webhook.
• pix_settings: (n:1) Um cliente possui um conjunto de configurações de PIX.

Métodos Importantes da Entidade

• getOneByDocumentAndAccountNumber(...): Busca um cliente pelo documento e número da conta.
• getTransactionPassword(...): Busca a senha transacional de um cliente de forma segura.
• validateTransactionPassword(...): Compara uma senha fornecida com o hash armazenado no banco.
• getStatusDescription(...): Retorna a descrição textual de um status numérico.

Índices

• idx_name_status_document: Índice composto para otimizar buscas por nome, status e documento.

---

Tabela: customer_txs_monthly_usage

Descrição

Esta tabela rastreia o uso mensal de transações por tipo para cada cliente. Ela armazena a contagem de transações PIX, TED e de Boleto que um cliente realizou em um determinado mês/ano. É útil para relatórios, faturamento e análise de uso.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de uso mensal.	Chave Primária
customerId	integer	Chave estrangeira para o cliente (customer).	FK
monthYear	date	O mês e ano de referência para a contagem de transações (o dia é irrelevante).	Não Nulo
countPix	integer	Número total de transações PIX realizadas no mês.	default: 0
countTed	integer	Número total de transações TED realizadas no mês.	default: 0
countBillet	integer	Número total de transações de Boleto realizadas no mês.	default: 0
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• customers: (n:1) Cada registro de uso mensal pertence a um cliente.

Índices

• IDX_customer_monthYear: Índice único composto nas colunas customerId e monthYear. Garante que haverá apenas um registro de contagem por cliente para cada mês/ano.

---

Tabela: dda_billets

Descrição

A tabela dda_billets armazena informações sobre boletos eletrônicos gerenciados através do DDA (Débito Direto Autorizado). Ela contém os detalhes dos boletos que são apresentados eletronicamente para os clientes pagadores.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do boleto DDA.	Chave Primária
code	varchar(20)	Código do boleto.	Não Nulo
ispb	varchar(20)	ISPB do banco emissor.	Não Nulo
assignor	varchar(20)	Identificador do cedente (emissor do boleto).	Pode ser Nulo
name	varchar(100)	Nome do cedente.	Não Nulo
fantasyName	varchar(100)	Nome fantasia do cedente.	Pode ser Nulo
personType	varchar(1)	Tipo de pessoa do cedente (‘F’ ou ‘J’).	default: 'J'
documentNumber	varchar(14)	CPF/CNPJ do cedente.	Não Nulo
dueDate	date	Data de vencimento do boleto.	Não Nulo
dueDateRegister	date	Data de registro do vencimento.	Pode ser Nulo
hasDiscount	boolean	Indica se o boleto possui desconto.	default: false
hasInterest	boolean	Indica se o boleto possui juros.	default: false
description	varchar(100)	Descrição do boleto.	Pode ser Nulo
originalValue	float	Valor original do boleto.	default: 0.0
digitable	varchar(100)	Linha digitável do boleto.	Não Nulo
barCode	varchar(100)	Código de barras do boleto.	Não Nulo
status	enum	Status do pagamento do boleto (Aberto, Pago, Cancelado, Estornado).	default: 'Aberto'
paymentSituation	varchar(200)	Descrição da situação do pagamento.	Pode ser Nulo
externalTransactionId	varchar(100)	ID da transação no sistema externo.	Não Nulo
customer_id	integer	FK para o cliente (customer) que é o sacado (pagador).	FK
transaction_id	integer	FK para a transação (transaction) que liquidou este boleto.	FK, Pode ser Nulo
isScheduledForPayment	boolean	Indica se o boleto está agendado para pagamento.	default: false
isHidden	boolean	Indica se o boleto deve ser ocultado da visualização do usuário.	default: false
createdAt	timestamp	Data de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data da última atualização.	Gerado Automaticamente

Relacionamentos

• customers: (n:1) Cada boleto DDA pertence a um cliente (pagador).
• transactions: (1:1) Um boleto DDA pago está associado a uma transação de pagamento.

Métodos Importantes da Entidade

• getScheduledDdaBillets(dueDate): Método estático que busca todos os boletos DDA agendados para pagamento em uma data específica (dueDate), incluindo uma lógica para buscar boletos de fim de semana na sexta-feira anterior.

---

Tabela: dda_customer

Descrição

A tabela dda_customer gerencia a adesão e o status de um cliente ao serviço de DDA (Débito Direto Autorizado). Ela registra se um cliente está ativo, em processamento ou se ocorreu algum erro em sua adesão ao DDA.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de adesão ao DDA.	Chave Primária
status	enum	O status atual da adesão do cliente ao DDA (processing, created, inactive, error).	default: 'processing'
customerId	integer	Chave estrangeira que referencia o cliente (customer) que aderiu ao DDA.	FK, Relação 1:1
createdAt	timestamp	Data de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• customers: (1:1) Cada registro de dda_customer está associado a um único cliente, representando a adesão daquele cliente ao serviço.

Métodos Importantes da Entidade

• checkDdaCustomerStatus(customer): Método estático que verifica e retorna o status da adesão ao DDA para um determinado cliente.
• setDdaCustomerStatus(customer, status): Método estático que cria ou atualiza o status da adesão ao DDA para um cliente.
• deleteCustomerDDA(customer): Método estático que remove o registro de adesão ao DDA de um cliente, efetivamente cancelando sua participação no serviço.

---

Tabela: faqs

Descrição

A tabela faqs armazena as Perguntas Frequentes (FAQ) que podem ser exibidas em uma seção de ajuda do aplicativo ou site. Ela contém a pergunta, a resposta, uma categoria opcional e um indicador de status.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	uuid	Identificador único universal (UUID) para cada FAQ.	Chave Primária
question	varchar	O texto da pergunta.	Não Nulo
answer	text	O texto da resposta.	Não Nulo
category	varchar	Uma categoria opcional para agrupar as FAQs (ex: ‘PIX’, ‘Cadastro’).	Pode ser Nulo
isActive	boolean	Indica se a FAQ está ativa e deve ser exibida.	default: true
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

Esta tabela geralmente não possui relacionamentos diretos com outras tabelas. Ela serve como uma fonte de conteúdo para a interface do usuário.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: favorite_pix

Descrição

A tabela favorite_pix armazena os contatos PIX que um usuário marcou como favoritos. Isso permite que o usuário acesse rapidamente os detalhes de um destinatário frequente sem precisar digitar a chave PIX toda vez.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do favorito.	Chave Primária
alias	varchar(100)	Um apelido ou nome personalizado para o favorito (ex: “Aluguel”, “Mãe”).	Pode ser Nulo
name	varchar(100)	O nome do titular da chave PIX.	Não Nulo
pix_type	varchar(100)	O tipo da chave PIX (ex: CPF, EMAIL, PHONE).	Não Nulo
pix_key	varchar(100)	O valor da chave PIX.	Não Nulo
user_id	integer	Chave estrangeira que referencia o usuário (user) que salvou este favorito.	FK

Relacionamentos

• users: (n:1) Cada favorito PIX pertence a um único usuário.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: favorite_ted

Descrição

A tabela favorite_ted armazena os contatos de destinatários de TED (Transferência Eletrônica Disponível) que um usuário marcou como favoritos. Ela serve para facilitar o preenchimento de dados bancários para transferências recorrentes.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do favorito.	Chave Primária
alias	varchar(100)	Um apelido ou nome personalizado para o favorito.	Pode ser Nulo
name	varchar(100)	O nome do titular da conta de destino.	Não Nulo
bank_id	integer	Chave estrangeira que referencia o banco (banks) da conta de destino.	FK
agency	varchar(100)	O número da agência da conta de destino.	Não Nulo
account_number	varchar(100)	O número da conta de destino.	Não Nulo
document	varchar(14)	O CPF/CNPJ do titular da conta de destino.	Pode ser Nulo
user_id	integer	Chave estrangeira que referencia o usuário (user) que salvou este favorito.	FK

Relacionamentos

• users: (n:1) Cada favorito de TED pertence a um único usuário.
• banks: (n:1) Cada favorito de TED está associado a um banco.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: favorite_tef

Descrição

A tabela favorite_tef armazena os contatos de destinatários de TEF (Transferência Eletrônica de Fundos) que um usuário marcou como favoritos. Assim como a favorite_ted, ela serve para facilitar o preenchimento de dados bancários para transferências recorrentes dentro do mesmo banco ou entre bancos parceiros.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do favorito.	Chave Primária
alias	varchar(100)	Um apelido ou nome personalizado para o favorito.	Pode ser Nulo
name	varchar(100)	O nome do titular da conta de destino.	Não Nulo
bank_id	integer	Chave estrangeira que referencia o banco (banks) da conta de destino.	FK
agency	varchar(100)	O número da agência da conta de destino.	Não Nulo
account_number	varchar(100)	O número da conta de destino.	Não Nulo
document	varchar(14)	O CPF/CNPJ do titular da conta de destino.	Pode ser Nulo
user_id	integer	Chave estrangeira que referencia o usuário (user) que salvou este favorito.	FK

Relacionamentos

• users: (n:1) Cada favorito de TEF pertence a um único usuário.
• banks: (n:1) Cada favorito de TEF está associado a um banco.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: feature_flag

Descrição

A tabela feature_flag implementa um sistema de “Feature Flags” (ou “Feature Toggles”), que permite ativar ou desativar funcionalidades específicas do sistema de forma dinâmica, sem a necessidade de um novo deploy de código. As flags podem ser aplicadas a todos os clientes ou a clientes específicos.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da feature flag.	Chave Primária
name	varchar(100)	O nome único da funcionalidade que está sendo controlada (ex: pix-refund-v2).	Não Nulo
customerId	integer	Chave estrangeira para o cliente (customer) ao qual esta regra se aplica. Se for nulo, a regra pode ser global.	FK
isActive	boolean	Indica se a funcionalidade está ativa (true) ou inativa (false).	default: false
all_customers	boolean	Se true, esta regra se aplica a todos os clientes, e o customerId é ignorado.	default: false

Relacionamentos

• customers: (n:1) Uma feature flag pode estar associada a um cliente específico.

Índices

• IDX_customer_name: Índice composto nas colunas customerId e name para otimizar a busca de flags para um cliente específico.
• IDX_name: Índice na coluna name para otimizar a busca de flags pelo nome.

Métodos Importantes da Entidade

• isFeatureEnabledForAll(name): Verifica se uma funcionalidade está ativa globalmente para todos os clientes.
• isFeatureEnabledForCustomer(customer, name): Verifica se uma funcionalidade está ativa especificamente para um determinado cliente.
• isFeatureEnabled(customer, name): Método combinado que primeiro verifica a flag específica do cliente e, se não houver, poderia (embora a implementação atual não mostre) verificar a flag global como fallback.
• getEnabledCustomers(name): Retorna uma lista de todos os clientes para os quais uma determinada funcionalidade está ativa (excluindo a regra all_customers).

---

Tabela: fee_settings_history

Descrição

A tabela fee_settings_history funciona como um log de auditoria para todas as alterações feitas nas configurações de taxas (fee_settings). Cada vez que uma configuração de taxa é criada, ativada, desativada ou modificada, um registro é criado nesta tabela para manter um histórico completo das mudanças.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de histórico.	Chave Primária
action	enum	A ação que foi realizada (ex: CREATED, ACTIVATED, DEACTIVATED).	Não Nulo
activedById	integer	Chave estrangeira para o administrador (user_admin) que realizou a ação.	FK
setting	jsonb	Um snapshot (cópia) em JSON da configuração de taxa (FeeSetting) no momento da ação.	Não Nulo
modifiedAt	timestamp	Data e hora em que a modificação ocorreu.	Gerado Automaticamente

Relacionamentos

• user_admin: (n:1) Cada registro de histórico é associado a um usuário administrador que realizou a alteração.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: fee_settings

Descrição

A tabela fee_settings armazena diferentes conjuntos de configurações de taxas. Cada registro representa um “pacote” de regras de taxação que pode ser aplicado aos clientes. O sistema garante que apenas um conjunto de configurações de taxas possa estar ativo por vez.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do conjunto de configurações de taxa.	Chave Primária
description	varchar	Uma descrição para identificar o conjunto de taxas (ex: “Plano Padrão 2024”).	Não Nulo, Único
isActive	boolean	Indica se este conjunto de configurações de taxa é o que está atualmente em vigor.	Não Nulo, default: false
createdById	integer	Chave estrangeira para o administrador (user_admin) que criou este conjunto de taxas.	FK
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• user_admin: (n:1) Cada conjunto de taxas é criado por um usuário administrador.
• fee_transaction_settings: (1:n) Cada conjunto de taxas (FeeSetting) possui várias regras de taxação específicas por tipo de transação (FeeTransactionSetting).

Índices

• unique_is_active: Índice único na coluna isActive com a condição WHERE is_active = true. Isso garante em nível de banco de dados que apenas um único registro pode ter isActive como true, prevenindo a ativação de múltiplos conjuntos de taxas simultaneamente.
• unique_description: Índice único na coluna description para garantir que cada conjunto de taxas tenha um nome exclusivo.

---

Tabela: fee_transaction_settings

Descrição

A tabela fee_transaction_settings detalha as regras de taxação para transações específicas. Cada registro define o valor da taxa e a isenção mensal para uma combinação única de operação (crédito/débito), tipo de transação (PIX, TED, etc.) e o conjunto de taxas (fee_setting) ao qual pertence.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da regra de taxa.	Chave Primária
operation	Operation	A operação da transação (CREDIT ou DEBIT).	Não Nulo
transactionType	TRANSACTION_TYPE_ENUM	O tipo da transação (ex: PIX, TED, BILLET).	Não Nulo
feeAmountType	FEE_AMOUNT_TYPE_ENUM	O tipo de cálculo da taxa (FIXED ou PERCENTAGE).	Não Nulo, default: 'FIXED'
feeAmount	float	O valor (fixo ou percentual) da taxa a ser aplicada.	Não Nulo
monthlyFree	integer	O número de transações deste tipo que são isentas de taxa por mês.	Não Nulo
feeSettingId	integer	Chave estrangeira que referencia o conjunto de taxas (fee_settings) ao qual esta regra pertence.	FK

Relacionamentos

• fee_settings: (n:1) Cada regra de taxa pertence a um conjunto de configurações de taxa.

Índices

• unique_fee_transaction_setting: Índice único composto pelas colunas operation, transactionType e feeSettingId. Isso garante que não exista mais de uma regra de taxa para a mesma combinação de operação e tipo de transação dentro do mesmo conjunto de configurações de taxa.

---

Tabela: ip_allow_list

Descrição

A tabela ip_allow_list é uma lista de permissões (whitelist) específica para endereços IP. Ela permite que um cliente (customer) restrinja o acesso a determinadas funcionalidades ou APIs apenas aos endereços IP listados.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro.	Chave Primária
listName	varchar(100)	O nome da lista de permissões à qual este IP pertence (ex: api-access, dashboard-login).	Não Nulo
ip	varchar(100)	O endereço IP que está sendo permitido.	Não Nulo
customerId	integer	Chave estrangeira que referencia o cliente (customer) dono desta regra.	FK

Relacionamentos

• customers: (n:1) Cada registro de IP permitido pertence a um cliente.

Métodos Importantes da Entidade

• isIpAllowed(customer, ip, listName): Método estático que verifica se um determinado endereço ip está na lista de permissões (listName) para um customer específico. Retorna true se o IP for encontrado, e false caso contrário.

---

Tabela: notifications

Descrição

A tabela notifications armazena as notificações que são enviadas aos clientes. Ela é usada para comunicação dentro da plataforma, como avisos, alertas ou mensagens informativas.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da notificação.	Chave Primária
customer_id	integer	Chave estrangeira que referencia o cliente (customer) que receberá a notificação.	Não Nulo, FK
read	boolean	Indica se a notificação já foi lida pelo cliente.	default: false
title	varchar	O título da notificação.	Não Nulo
message	text	O conteúdo da mensagem da notificação.	Não Nulo
createdAt	timestamp	Data e hora de criação da notificação.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização (ex: quando foi lida).	Gerado Automaticamente

Relacionamentos

• customers: (n:1) Cada notificação pertence a um único cliente.

Índices

• notifications_idx_user: Índice composto nas colunas customer_id, createdAt e read. Otimiza a busca por notificações de um cliente, permitindo filtrar por lidas/não lidas e ordenar por data de forma eficiente.

---

Tabela: payers

Descrição

A tabela payers armazena informações sobre os pagadores (sacados) de transações, especialmente em contextos como a emissão de boletos. Ela contém os dados cadastrais da pessoa ou empresa que deve realizar o pagamento.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do pagador.	Chave Primária
name	varchar(200)	Nome completo ou razão social do pagador.	Não Nulo
tradeName	varchar(200)	Nome fantasia do pagador.	Pode ser Nulo
email	varchar(100)	Endereço de e-mail do pagador.	Pode ser Nulo
phoneNumber	varchar(100)	Número de telefone do pagador.	Pode ser Nulo
document	varchar(14)	CPF ou CNPJ do pagador.	Não Nulo
addressLine1	varchar(100)	Endereço principal do pagador.	Pode ser Nulo
city	varchar(100)	Cidade do pagador.	Pode ser Nulo
state	varchar(20)	Estado do pagador.	Pode ser Nulo
zipCode	varchar(10)	CEP do pagador.	Pode ser Nulo
customerId	integer	Chave estrangeira que referencia o cliente (customer) que cadastrou este pagador.	FK
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• customers: (n:1) Cada registro de pagador é associado a um cliente que o cadastrou.
• billets: A tabela payers é referenciada pela tabela billets para identificar quem é o pagador de um boleto.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: permission_admin

Descrição

A tabela permission_admin define as permissões individuais que podem ser concedidas a usuários administradores. Cada registro representa uma ação ou acesso específico no painel de administração (ex: “visualizar usuários”, “editar configurações”). Essas permissões são então agrupadas em papéis (roles).

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da permissão.	Chave Primária
name	varchar(255)	O nome de código da permissão (ex: users:read, settings:write).	Pode ser Nulo
title	varchar(255)	Um título amigável para a permissão (ex: “Visualizar Usuários”).	Pode ser Nulo
description	varchar(255)	Uma descrição detalhada do que a permissão concede.	Pode ser Nulo
visualization	boolean	Flag que pode ser usada para controlar a visibilidade da permissão na interface.	default: false
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• role_admin: (n:m) Uma permissão pode ser atribuída a múltiplos papéis, e um papel pode ter múltiplas permissões. A relação é gerenciada por uma tabela de junção (roles_permissions_admin).

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: pix_key_info

Descrição

A tabela pix_key_info funciona como um cache para os dados de chaves PIX consultadas. Quando uma chave PIX é validada, os dados do destinatário (nome, documento, dados bancários) são armazenados aqui para acelerar consultas futuras e reduzir a necessidade de consultar repetidamente o DICT (Diretório de Identificadores de Contas Transacionais).

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de cache.	Chave Primária
type	varchar(100)	O tipo da chave PIX (ex: CPF, EMAIL).	Não Nulo
key	varchar(100)	O valor da chave PIX.	Não Nulo
bankIspb	varchar(100)	ISPB do banco do destinatário.	Não Nulo
agency	varchar(100)	Agência da conta do destinatário.	Não Nulo
accountNumber	varchar(100)	Número da conta do destinatário.	Não Nulo
accountType	varchar(100)	Tipo da conta do destinatário (ex: CACC para Conta Corrente).	Não Nulo
document	varchar(100)	Documento (CPF/CNPJ) do titular da chave.	Não Nulo
name	varchar(100)	Nome do titular da chave.	Não Nulo

Relacionamentos

Esta tabela não possui relacionamentos diretos com outras tabelas do sistema, mas é fundamental para o funcionamento das transações PIX.

Métodos Importantes da Entidade

• getCreditParty(pixKey): Método estático que busca os dados de um destinatário (credit party) no cache a partir de uma chave PIX.
• setOne(pixKey, pixKeyInfo): Método estático que salva no cache os dados de um destinatário (pixKeyInfo) associados a uma chave PIX (pixKey).

---

Tabela: pix_profit_distribution_item

Descrição

A tabela pix_profit_distribution_item armazena os itens individuais de uma distribuição de lucros via PIX. Cada registro representa uma parcela da distribuição, detalhando para quem o lucro foi enviado, os custos associados e o status da transação de pagamento.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do item de distribuição.	Chave Primária
pixProfitDistributionId	integer	Chave estrangeira que referencia o lote de distribuição de lucros (pix_profit_distribution) ao qual este item pertence.	FK
name	varchar	Nome do participante ou da finalidade deste item de distribuição.	Não Nulo
data	json	Dados adicionais sobre o participante ou a distribuição (ex: chave PIX, dados bancários).	Pode ser Nulo
costs	double precision	Custos associados a este item da distribuição.	default: 0.0
profit	double precision	Valor do lucro a ser distribuído neste item.	default: 0.0
status	integer	Status da transação de pagamento deste item (ex: 0 para pendente, 2 para pago).	default: 0
responseMeta	json	Metadados da resposta da transação de pagamento.	Pode ser Nulo
endToEndId	varchar	End-to-End ID da transação PIX que efetivou o pagamento deste item.	Pode ser Nulo
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• pix_profit_distribution: (n:1) Cada item pertence a um lote de distribuição de lucros.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: pix_profit_distribution

Descrição

A tabela pix_profit_distribution representa um lote de distribuição de lucros. Ela serve como um registro mestre que agrupa vários itens de distribuição (pix_profit_distribution_item), totalizando os valores de cash-in, cash-out, custos e lucros para um período de referência (baseDate).

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do lote de distribuição.	Chave Primária
checkingAccountId	integer	Chave estrangeira para a conta corrente (checking_account) de onde os lucros estão sendo distribuídos.	FK
baseDate	date	A data de referência para o cálculo e a distribuição dos lucros.	Não Nulo
totalCashIn	double precision	Soma total do cash-in no período de referência.	default: 0.0
totalCashOut	double precision	Soma total do cash-out no período de referência.	default: 0.0
totalCosts	double precision	Soma total dos custos associados à operação.	default: 0.0
totalProfit	double precision	Lucro total a ser distribuído neste lote.	default: 0.0
cashInCount	integer	Número de transações de cash-in no período.	default: 0
cashOutCount	integer	Número de transações de cash-out no período.	default: 0
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• checking_accounts: (n:1) Cada lote de distribuição está associado a uma conta corrente.
• pix_profit_distribution_item: (1:n) Um lote de distribuição (PixProfitDistribution) contém múltiplos itens de distribuição (PixProfitDistributionItem).

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: pix_profit_participant

Descrição

A tabela pix_profit_participant define os participantes em um modelo de compartilhamento de lucros (profit sharing) via PIX. Cada registro especifica um participante, sua chave PIX de destino e a regra de como sua parcela do lucro deve ser calculada.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do participante.	Chave Primária
name	varchar(100)	Nome para identificar o participante.	Não Nulo
pixKeyId	integer	Chave estrangeira para pix_key_info, indicando a chave PIX para onde o lucro será enviado.	Não Nulo, FK
profitShareType	enum	O tipo de cálculo da parcela do lucro (percentage ou fixed).	default: 'percentage'
profitShare	double precision	O valor (percentual ou fixo) da parcela do lucro.	default: 0.0
isProfitOverGrossAmount	boolean	Se true, a parcela é calculada sobre o valor bruto da transação, não sobre o lucro líquido.	default: false
pixSettingsId	integer	Chave estrangeira que referencia o conjunto de configurações (pix_settings) ao qual este participante pertence.	Pode ser Nulo, FK

Relacionamentos

• pix_key_info: (n:1) Cada participante tem uma chave PIX de destino para receber os pagamentos.
• pix_settings: (n:1) Cada participante está associado a um conjunto de configurações de PIX, definindo um modelo de compartilhamento de lucros.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: pix_settings

Descrição

A tabela pix_settings armazena as configurações de transações PIX para os clientes. Ela define as taxas, limites de valor, horários de operação noturna e as contas para cobrança de taxas. Cada cliente (customer) pode ter um conjunto de configurações PIX associado.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do conjunto de configurações.	Chave Primária
description	varchar	Descrição do conjunto de configurações (ex: “TARIFA PADRÃO”).	default: 'TARIFA PADRÃO'
profitPercentage	double precision	Percentual de lucro retido pela plataforma.	default: 0.0
feeType	enum	Tipo de taxa aplicada (percentage ou fixed).	default: 'percentage'
cashInFee	double precision	Taxa para transações de entrada (crédito).	default: 0.0
cashOutFee	double precision	Taxa para transações de saída (débito).	default: 0.0
cashInMaxAmount	double precision	Valor máximo para transações de cash-in.	default: 0.0
cashOutMaxAmount	double precision	Valor máximo para transações de cash-out durante o dia.	default: 0.0
cashOutNightMaxAmount	double precision	Valor máximo para transações de cash-out durante o período noturno.	default: 0.0
nightTimeStart	integer	Hora de início do período noturno (ex: 20 para 20:00).
nightTimeEnd	integer	Hora de fim do período noturno (ex: 6 para 06:00).
createPixTransactions	boolean	Flag que habilita ou desabilita a criação de transações PIX.	default: true
participants	json	Campo JSON para armazenar regras de participantes em modelos de split.	Pode ser Nulo
cashOutDailyAmount	double precision	Limite de valor diário para cash-out.	default: 0.0
feeChargePixKeyId	integer	FK para pix_key_info, indicando a chave PIX para onde as taxas cobradas devem ser enviadas.	FK
feeChargeCheckingAccountId	integer	FK para checking_accounts, indicando a conta de onde as taxas devem ser debitadas.	FK
createdAt	timestamp	Data de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data da última atualização.	Gerado Automaticamente

Relacionamentos

• customers: (1:n) Um conjunto de configurações pode ser aplicado a múltiplos clientes.
• pix_key_info: (n:1) Aponta para a chave PIX usada para centralizar a cobrança de taxas.
• checking_accounts: (n:1) Aponta para a conta corrente usada para debitar as taxas.

Métodos Importantes da Entidade

• getFeeSum(baseValue, operation, monetaryFraction): Calcula o valor total da taxa para uma transação com base no valor (baseValue) e na operação (CREDIT ou DEBIT). Pode retornar o valor em centavos ou reais.

---

Tabela: plan_transaction_settings

Descrição

A tabela plan_transaction_settings define as regras de isenção de transações para planos de assinatura (subscription_plans). Cada registro especifica a quantidade de transações mensais gratuitas que um cliente tem direito para uma combinação de operação e tipo de transação, como parte de seu plano.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da regra do plano.	Chave Primária
operation	Operation	A operação da transação (CREDIT ou DEBIT).	Não Nulo
transactionType	TRANSACTION_TYPE_ENUM	O tipo da transação (ex: PIX, TED, BILLET).	Não Nulo
monthlyFree	integer	O número de transações deste tipo que são isentas de taxa por mês, conforme o plano.	Não Nulo
planId	integer	Chave estrangeira que referencia o plano de assinatura (subscription_plans) ao qual esta regra pertence.	FK

Relacionamentos

• subscription_plans: (n:1) Cada regra de isenção pertence a um plano de assinatura.

Índices

• unique_plan_transaction_setting: Índice único composto pelas colunas operation, transactionType e planId. Garante que não exista mais de uma regra de isenção para a mesma combinação de operação e tipo de transação dentro do mesmo plano.

---

Tabela: qrcode_bank

Descrição

A tabela qrcode_bank funciona como um “pool” ou banco de QR Codes PIX pré-gerados para valores específicos. O objetivo é otimizar o tempo de resposta em operações que necessitam de um QR Code, fornecendo um que já foi gerado e está pronto para uso, em vez de gerar um novo a cada requisição.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro do QR Code.	Chave Primária
amount	float	O valor monetário associado a este QR Code.	default: 0.0
qrCodeId	varchar	O ID do QR Code, que contém os dados para o pagamento PIX.	Não Nulo
checkingAccountId	integer	Chave estrangeira para a conta corrente (checking_account) que receberá o pagamento.	FK
conciliationId	varchar(100)	Um ID de conciliação associado a este QR Code.	Não Nulo
expirationDate	timestamp	Data e hora em que o QR Code expira e não pode mais ser usado.	Pode ser Nulo

Relacionamentos

• checking_accounts: (n:1) Cada QR Code está associado a uma conta corrente de destino.

Índices

• IDX_checkingAccount_amount: Índice nas colunas checkingAccountId e amount para otimizar a busca por um QR Code disponível para um valor e conta específicos.
• IDX_expirationDate: Índice na coluna expirationDate para otimizar a busca por QR Codes expirados.

Métodos Importantes da Entidade

• createQrCode(qrcode): Método estático para adicionar um novo QR Code pré-gerado ao banco.
• getExpiredQrcodes(): Método estático que busca todos os QR Codes que já expiraram.
• getQrcodeByAmount(amount, checkingAccount): Método estático crucial que busca um QR Code disponível para um amount e checkingAccount específicos. Importante: Esta operação é atômica e deleta o registro do banco de dados ao mesmo tempo que o retorna, garantindo que o mesmo QR Code não seja usado mais de uma vez.

---

Tabela: question_checks

Descrição

A tabela question_checks gerencia um processo de verificação de identidade baseado em questionário (provavelmente como parte de um fluxo de KYC - Know Your Customer). Ela armazena os dados do usuário, as perguntas feitas, as respostas fornecidas e o resultado da verificação.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da verificação.	Chave Primária
cpf	varchar(60)	CPF do usuário que está sendo verificado.	Não Nulo
name	varchar(255)	Nome do usuário.	Pode ser Nulo
phone	varchar(60)	Telefone do usuário.	Pode ser Nulo
email	varchar(255)	E-mail do usuário.	Pode ser Nulo
birth_date	date	Data de nascimento do usuário.	Pode ser Nulo
ticket_id	varchar(60)	ID único do “ticket” ou sessão de verificação, provavelmente de um serviço externo.	Não Nulo, Único
result_code	integer	Código numérico do resultado da verificação.	default: 0
result_message	varchar	Mensagem textual descrevendo o resultado.	Pode ser Nulo
verified_at	timestamp	Data e hora em que a verificação foi concluída.	Pode ser Nulo
questions	json	Objeto JSON contendo as perguntas que foram feitas ao usuário.	Pode ser Nulo
answers	json	Objeto JSON contendo as respostas fornecidas pelo usuário.	Pode ser Nulo
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente
user_id	integer	Chave estrangeira que referencia o usuário (user) associado a esta verificação.	FK

Relacionamentos

• users: (n:1) Cada verificação por questionário está associada a um usuário.

Índices

• A coluna ticket_id possui um índice único para garantir a unicidade de cada sessão de verificação.

---

Tabela: refresh_tokens

Descrição

A tabela refresh_tokens armazena os “refresh tokens” utilizados no fluxo de autenticação OAuth 2.0. Um refresh token é um token de longa duração que pode ser usado para obter um novo “access token” (de curta duração) sem que o usuário precise se autenticar novamente.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do refresh token.	Chave Primária
token	varchar(255)	O valor do refresh token.	Não Nulo
accessToken	varchar(255)	O último access token que foi gerado por este refresh token.	Pode ser Nulo
expiresAt	timestamp	Data e hora em que o refresh token expira e se torna inválido.	Não Nulo
accessTokenExpiresAt	timestamp	Data e hora de expiração do access token associado.	Pode ser Nulo
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

Esta tabela não possui chaves estrangeiras diretas, mas está logicamente ligada à sessão de um usuário. A validação e o uso do token são feitos na camada de aplicação.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: role_admin

Descrição

A tabela role_admin define os papéis (funções) que podem ser atribuídos a usuários administradores. Cada papel agrupa um conjunto de permissões (permission_admin) que determinam o que um usuário com aquele papel pode fazer no painel de administração.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do papel.	Chave Primária
name	varchar(255)	O nome do papel (ex: “Administrador”, “Suporte Nível 1”).	Pode ser Nulo
createdBy	varchar(100)	Identificação de quem criou o papel.	Pode ser Nulo
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• user_admin: (1:n) Um papel pode ser atribuído a múltiplos usuários administradores.
• permission_admin: (n:m) Um papel pode ter múltiplas permissões, e uma permissão pode pertencer a múltiplos papéis. A relação é gerenciada por uma tabela de junção chamada roles_permissions_admin.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: subscription_plan_config

Descrição

A tabela subscription_plan_config armazena configurações globais para o sistema de planos de assinatura. Atualmente, ela define a lista de dias de pagamento permitidos que os clientes podem escolher ao assinar um plano.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da configuração.	Chave Primária
paymentDays	json	Um array de números representando os dias do mês que estão disponíveis para serem escolhidos como dia de pagamento da assinatura.	Não Nulo, default: '[]'
isActive	boolean	Indica se esta configuração está ativa.	Não Nulo, default: true
createdById	integer	Chave estrangeira para o administrador (user_admin) que criou a configuração.	FK
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• user_admin: (n:1) Cada configuração é criada por um usuário administrador.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Módulo: SubscriptionPlanEntitiesModule

Descrição

SubscriptionPlanEntitiesModule não é uma tabela do banco de dados, mas sim um módulo do NestJS. Sua função é agrupar e exportar todas as entidades do TypeORM que são relacionadas à funcionalidade de planos de assinatura.

Propósito

O objetivo deste módulo é simplificar a importação de dependências. Em vez de importar cada entidade (SubscriptionPlan, CustomerSubscription, etc.) individualmente em outros módulos que precisam delas, pode-se importar apenas o SubscriptionPlanEntitiesModule. Isso melhora a organização e a manutenibilidade do código.

Entidades Incluídas

O módulo importa e reexporta o TypeOrmModule.forFeature() com as seguintes entidades:

• SubscriptionPlan: Define os planos de assinatura disponíveis.
• CustomerSubscription: Vincula um cliente a um plano de assinatura.
• Transaction: Usada para registrar os pagamentos das assinaturas.
• PlanTransactionSetting: Define as regras de isenção de transações para cada plano.

Uso

Qualquer outro módulo do NestJS que precise interagir com as tabelas de planos de assinatura pode simplesmente adicionar SubscriptionPlanEntitiesModule à sua lista de imports.

---

Tabela: subscription_plans

Descrição

A tabela subscription_plans define os diferentes planos de assinatura que podem ser oferecidos aos clientes. Cada registro representa um plano com seu nome, descrição, preço e as regras de transação associadas.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do plano.	Chave Primária
name	varchar	Nome do plano de assinatura (ex: “Plano Básico”, “Plano Premium”).	Não Nulo
description	varchar	Descrição detalhada dos benefícios e características do plano.	Não Nulo
pricePerMonth	float	O preço mensal do plano.	default: 0
customerType	varchar(1)	O tipo de cliente ao qual o plano se destina (‘F’ para Pessoa Física, ‘J’ para Pessoa Jurídica).	Pode ser Nulo
publishedAt	timestamp	Data em que o plano foi publicado e se tornou disponível para assinatura.	Pode ser Nulo
createdById	integer	Chave estrangeira para o administrador (user_admin) que criou o plano.	FK
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• user_admin: (n:1) Cada plano é criado por um usuário administrador.
• plan_transaction_settings: (1:n) Um plano de assinatura contém várias regras de isenção de taxas para diferentes tipos de transação.
• customer_subscriptions: A tabela subscription_plans é referenciada por customer_subscriptions para indicar qual plano um cliente assinou.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: systems

Descrição

A tabela systems funciona como um sistema de configuração de parâmetros para toda a aplicação. É um repositório genérico de chave-valor que permite armazenar e gerenciar configurações diversas do sistema (ex: limites globais, chaves de API de serviços de terceiros, etc.) sem a necessidade de alterar o código-fonte.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do parâmetro.	Chave Primária
parameter	varchar(255)	O nome (chave) único do parâmetro de sistema.	Único
value	jsonb	O valor do parâmetro, armazenado como JSON para flexibilidade.	Não Nulo
status	enum	O status do parâmetro (ACTIVE ou INACTIVE).	default: 'ACTIVE'
created_at	timestamp with time zone	Data e hora de criação do registro.	Gerado Automaticamente
updated_at	timestamp with time zone	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

Esta tabela não possui relacionamentos diretos com outras tabelas. Ela é consultada pela lógica de negócios em vários pontos da aplicação para obter valores de configuração.

Índices

• A coluna parameter possui um índice único para garantir que cada parâmetro de sistema tenha um nome exclusivo.

---

Tabela: terms_acceptance_versions

Descrição

A tabela terms_acceptance_versions é uma tabela de lookup que armazena as diferentes versões dos Termos de Serviço da plataforma. Cada registro representa uma versão única dos termos que foi publicada.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da versão.	Chave Primária
version	varchar	O identificador da versão (ex: “v1.0.0”, “2024-09-23”).	Único
createdAt	timestamp	Data e hora de criação do registro da versão.	Gerado Automaticamente

Relacionamentos

• terms_acceptance: (1:n) Uma versão dos termos pode ser aceita por múltiplos usuários, e cada registro de aceite (terms_acceptance) aponta para uma única versão.

Índices

• A coluna version possui um índice único para garantir que não haja identificadores de versão duplicados.

---

Tabela: terms_acceptance

Descrição

A tabela terms_acceptance registra o aceite dos Termos de Serviço por parte dos usuários. Cada registro representa o momento em que um usuário específico (userId) aceitou uma determinada versão dos termos (termsAcceptanceVersion).

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de aceite.	Chave Primária
userId	integer	O ID do usuário que aceitou os termos.	Pode ser Nulo
termsVersion	varchar	O identificador da versão dos termos que foi aceita.	Pode ser Nulo
acceptedAt	timestamp	Data e hora em que os termos foram aceitos.	Pode ser Nulo
termsAcceptanceVersionId	integer	Chave estrangeira que referencia a versão (terms_acceptance_versions) que foi aceita.	FK

Relacionamentos

• terms_acceptance_versions: (n:1) Cada registro de aceite está vinculado a uma versão específica dos Termos de Serviço.
• users: Embora userId não seja uma chave estrangeira formal na entidade, ele representa a ligação lógica com a tabela users.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: tokens

Descrição

A tabela tokens é um repositório genérico para armazenar diferentes tipos de tokens de uso único ou de curta duração. Eles são usados para processos como verificação de e-mail, redefinição de senha, ou outras operações que exigem uma confirmação segura.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do token.	Chave Primária
token	varchar(500)	O valor do token, que deve ser único.	Não Nulo, Único
type	varchar(60)	O tipo do token, que define sua finalidade (ex: EMAIL_VERIFICATION, PASSWORD_RESET).	Não Nulo
isActive	boolean	Indica se o token ainda pode ser usado.	default: true
expires_in	timestamp	Data e hora em que o token expira.	default: CURRENT_TIMESTAMP
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente
user_id	integer	Chave estrangeira que referencia o usuário (user) ao qual o token está associado.	FK

Relacionamentos

• users: (n:1) Cada token é gerado para e pertence a um único usuário.

Índices

• A coluna token possui um índice único para garantir que cada token seja exclusivo e para otimizar as buscas.

---

Tabela: transaction_bank_conciliation

Descrição

A tabela transaction_bank_conciliation é usada para mapear uma transação interna do sistema a um identificador de conciliação externo, geralmente fornecido por um banco ou outro parceiro financeiro. Isso é essencial para reconciliar registros entre os sistemas.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de conciliação.	Chave Primária
transactionId	integer	Chave estrangeira que referencia a transação (transactions) interna.	FK, Relação 1:1
externalConciliation	varchar(100)	O identificador de conciliação fornecido pelo sistema externo (banco).	Não Nulo
checkingAccountId	integer	Chave estrangeira que referencia a conta corrente (checking_accounts) envolvida.	FK

Relacionamentos

• transactions: (1:1) Cada registro de conciliação está ligado a uma única transação interna.
• checking_accounts: (n:1) Cada registro de conciliação está associado a uma conta corrente.

Índices

• IDX_checkingAccount_externalConciliation: Índice único composto pelas colunas checkingAccountId e externalConciliation. Garante que um ID de conciliação externo seja único para cada conta.
• IDX_transactionId: Índice na coluna transactionId.
• IDX_externalConciliation: Índice na coluna externalConciliation.

Métodos Importantes da Entidade

• set(bankConciliation): Método estático para criar um novo registro de conciliação, vinculando uma transação interna a um ID externo.

---

Tabela: transaction_custom_conciliation

Descrição

A tabela transaction_custom_conciliation oferece um mecanismo flexível para conciliação de transações usando identificadores customizados. Ela permite que um conciliationId (que pode ser usado na transação principal) seja mapeado para um ou mais pares de chave-valor (name, value) específicos de um cliente.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro.	Chave Primária
customerId	integer	Chave estrangeira que referencia o cliente (customer) dono deste mapeamento.	FK
conciliationId	varchar(100)	O ID de conciliação principal, que será usado na transação.	Não Nulo
name	varchar(100)	O nome (chave) do identificador customizado (ex: “pedido_id”, “fatura_id”).	Não Nulo
value	varchar(100)	O valor do identificador customizado.	Não Nulo

Relacionamentos

• customers: (n:1) Cada registro de conciliação customizada pertence a um cliente.

Índices

• IDX_customer_conciliationId_name_value: Índice único composto por todas as colunas principais. Garante que a combinação de cliente, ID de conciliação e par chave-valor seja única.
• IDX_name_value: Índice nas colunas name e value para otimizar a busca pelo conciliationId a partir de um identificador customizado.

Métodos Importantes da Entidade

• set(customIdentifier): Método estático para criar um novo registro de mapeamento de conciliação.
• getConciliationId(name, value): Método estático que busca o conciliationId principal a partir de um par de name e value de um identificador customizado.
• getTransactionIdentification(conciliationId): Método estático que busca o valor de um identificador customizado específico (com name igual a ‘transactionIdentification’) a partir do conciliationId principal.

---

Tabela: transaction_fee_settings

Descrição

A tabela transaction_fee_settings define as regras de taxação para transações, associando um valor de taxa e uma franquia mensal a uma combinação de operação, tipo de transação e um conjunto de taxas (fee_setting).

Nota: Esta entidade parece ter uma funcionalidade muito similar ou sobreposta à fee_transaction_settings. A principal diferença é a ausência da coluna feeAmountType nesta entidade.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da regra de taxa.	Chave Primária
operation	Operation	A operação da transação (CREDIT ou DEBIT).	Não Nulo
transactionType	TRANSACTION_TYPE_ENUM	O tipo da transação (ex: PIX, TED, BILLET).	Não Nulo
feeAmount	float	O valor fixo da taxa a ser aplicada.	Não Nulo
monthlyFree	integer	O número de transações deste tipo que são isentas de taxa por mês.	Não Nulo
feeSettingId	integer	Chave estrangeira que referencia o conjunto de taxas (fee_settings) ao qual esta regra pertence.	FK

Relacionamentos

• fee_settings: (n:1) Cada regra de taxa pertence a um conjunto de configurações de taxa.

Índices

• unique_transaction_fee_setting: Índice único composto pelas colunas operation, transactionType e feeSettingId. Garante que não exista mais de uma regra de taxa para a mesma combinação de operação e tipo de transação dentro do mesmo conjunto de configurações de taxa.

---

Tabela: transaction_fees

Descrição

A tabela transaction_fees é uma tabela de associação que vincula uma transação original (a transação que incorreu na taxa) a uma segunda transação que representa a cobrança da taxa em si. Isso permite rastrear qual taxa foi gerada por qual operação.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de taxa de transação.	Chave Primária
parentTransactionId	integer	Chave estrangeira para a transação (transactions) que originou a cobrança da taxa.	Não Nulo, FK
feeTransactionId	integer	Chave estrangeira para a transação (transactions) que representa a cobrança da taxa.	Não Nulo, FK, Único

Relacionamentos

• transactions (como parentTransaction): (n:1) Aponta para a transação principal.
• transactions (como feeTransaction): (1:1) Aponta para a transação que é a própria taxa.

Índices

• A coluna feeTransactionId possui uma restrição UNIQUE, garantindo que uma transação de taxa não possa ser associada a mais de uma transação principal.

---

Tabela: transaction_limit_requests

Descrição

A tabela transaction_limit_requests gerencia as solicitações de alteração de limites de transação feitas pelos clientes. Cada registro representa uma solicitação para aumentar ou diminuir um limite específico, rastreando seu valor e status.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da solicitação.	Chave Primária
transactionLimitId	integer	Chave estrangeira para o limite (transactions_limit) que está sendo solicitado para alteração.	FK
value	float	O novo valor de limite que está sendo solicitado.	Não Nulo
status	enum	O status atual da solicitação (pending, completed, failed, recused, canceled).	default: 'pending'
scheduledFor	timestamp	Data e hora para quando a alteração do limite está agendada para entrar em vigor, se aplicável.	Pode ser Nulo
createdAt	timestamp	Data e hora de criação da solicitação.	Gerado Automaticamente

Relacionamentos

• transactions_limit: (n:1) Cada solicitação de alteração refere-se a um limite de transação específico (ex: limite diurno de PIX para um cliente).

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: transaction_reprocess

Descrição

A tabela transaction_reprocess é usada para gerenciar e rastrear o reprocessamento de transações que falharam ou precisam de uma nova tentativa por algum motivo. Cada registro contém uma referência à transação original e armazena metadados sobre as tentativas de reprocessamento.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de reprocessamento.	Chave Primária
transactionId	integer	Chave estrangeira para a transação (transactions) que está sendo reprocessada.	FK
responseMeta	json	Metadados da resposta da última tentativa de reprocessamento. (Não selecionável por padrão)	Pode ser Nulo
authenticationCode	varchar(100)	Código de autenticação usado na tentativa de reprocessamento. (Não selecionável por padrão)	Pode ser Nulo
idempotencyKey	varchar(100)	Chave de idempotência usada na tentativa de reprocessamento. (Não selecionável por padrão)	Pode ser Nulo
xCorrelationId	varchar(100)	ID de correlação usado na tentativa de reprocessamento. (Não selecionável por padrão)	Pode ser Nulo
refundMeta	json	Metadados específicos para reprocessamento de estornos. (Não selecionável por padrão)	Pode ser Nulo
cancelMeta	json	Metadados específicos para reprocessamento de cancelamentos. (Não selecionável por padrão)	Pode ser Nulo
status	integer	Código de status da tentativa de reprocessamento.	default: 0
paymentAmount	float	Valor do pagamento na tentativa de reprocessamento.	Pode ser Nulo
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• transactions: (n:1) Cada registro de reprocessamento está associado a uma transação original.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: transaction_request

Descrição

A tabela transaction_request gerencia um fluxo de aprovação para transações. Ela permite que um usuário solicite a criação de uma transação que, dependendo das regras de negócio, pode precisar da aprovação de outro usuário antes de ser efetivamente processada e se tornar uma transação real na tabela transactions.

Estrutura da Tabela

Informações Gerais

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da solicitação.	Chave Primária
type	enum	O tipo de transação solicitada (ex: KEY, TED, BILLET).	Não Nulo
amount	float	O valor da transação solicitada.	default: 0.0
status	enum	O status atual da solicitação (PENDENTE, APROVADO, REPROVADO).	default: 'PENDENTE'
description	varchar(200)	Descrição ou justificativa para a transação.	Pode ser Nulo
checkingAccountId	integer	FK para a conta (checking_account) de origem da transação.	FK
requested_by	integer	FK para o usuário (user) que fez a solicitação.	Não Nulo, FK
approvedOrRepprovedBy	integer	FK para o usuário (user) que aprovou ou reprovou.	Pode ser Nulo, FK
transactionId	integer	FK para a transação (transaction) criada após a aprovação.	Pode ser Nulo, FK

Dados Específicos por Tipo de Transação

Coluna	Tipo de Dados	Descrição
pixKeyType	varchar(20)	Tipo da chave PIX (para type='KEY').
pixKeyValue	varchar(60)	Valor da chave PIX (para type='KEY').
accountNumber	varchar(20)	Número da conta (para type='TED' ou 'TEF').
bankIspb	varchar(20)	ISPB do banco (para type='TED' ou 'TEF').
agency	varchar(20)	Agência (para type='TED' ou 'TEF').
document	varchar(20)	Documento do destinatário (para type='TED' ou 'TEF').
accountType	varchar(20)	Tipo da conta do destinatário (para type='TED' ou 'TEF').
name	varchar(60)	Nome do destinatário (para type='TED' ou 'TEF').
digitable	varchar(100)	Linha digitável (para type='BILLET').
barCode	varchar(100)	Código de barras (para type='BILLET').
emv	varchar(600)	Payload do QR Code (para type='QRCODE').
dueDate	date	Data de vencimento (para type='BILLET').

Timestamps

Coluna	Tipo de Dados	Descrição
createdAt	timestamp	Data e hora de criação da solicitação.
updatedAt	timestamp	Data e hora da última atualização.

Relacionamentos

• users (como requestedBy): (n:1) Cada solicitação é feita por um usuário.
• users (como approvedOrRepprovedBy): (n:1) Cada solicitação pode ser aprovada/reprovada por um usuário.
• checking_accounts: (n:1) Cada solicitação está associada a uma conta de origem.
• transactions: (1:1) Uma solicitação aprovada resulta em uma transação.

---

Tabela: transactions

Descrição

A tabela transactions é o coração do sistema financeiro, registrando todas as movimentações de fundos. Cada registro representa uma transação única, seja ela um PIX, TED, TEF, pagamento de boleto, ou uma operação interna. Ela contém todos os detalhes da transação, desde o valor e as partes envolvidas até o status e metadados de resposta.

Estrutura da Tabela

Informações Principais

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da transação.	Chave Primária
checkingAccountId	integer	FK para a conta corrente (checking_account) associada à transação.	FK
type	varchar(10)	O tipo da transação (ex: PIX, TED, BILLET).	default: 'TED'
operation	varchar(10)	A natureza da operação: CREDIT (entrada) ou DEBIT (saída).	default: 'DEBIT'
amount	float	O valor principal da transação.	default: 0.0
description	varchar(200)	Descrição da transação.	Pode ser Nulo
initializationType	varchar(20)	Como a transação foi iniciada (ex: manual, key, fee).	default: 'manual'

Partes Envolvidas (Sender/Recipient)

Coluna	Tipo de Dados	Descrição
recipient	json	Objeto JSON com os dados do destinatário (quem recebe).
sender	json	Objeto JSON com os dados do remetente (quem envia).

Status e Pagamento

Coluna	Tipo de Dados	Descrição
status	integer	Código numérico do status da transação (0: PENDING, 2: CLOSED, 3: REVERTED, 4: CANCELED).
paymentAmount	float	O valor efetivamente pago, que pode incluir taxas ou juros.
paymentDate	timestamp	Data e hora em que a transação foi liquidada.
isConfirmed	boolean	Indica se a transação foi confirmada.

Identificadores e Chaves

Coluna	Tipo de Dados	Descrição
endToEndId	varchar(100)	Identificador de ponta a ponta da transação (padrão PIX).
endToEndIdOriginal	varchar(100)	endToEndId da transação original (usado em estornos).
conciliationId	varchar(100)	ID de conciliação interno.
authenticationCode	varchar(100)	Código de autenticação da transação.
idempotencyKey	varchar(100)	Chave de idempotência para evitar processamento duplicado. (Não selecionável por padrão)
qrCodeId	varchar	ID do QR Code usado para iniciar a transação.

Metadados e Estornos

Coluna	Tipo de Dados	Descrição
meta	json	Metadados gerais da transação. (Não selecionável por padrão)
responseMeta	json	Metadados da resposta do provedor de serviços de pagamento.
cancelMeta	json	Metadados relacionados ao cancelamento da transação.
refundMeta	json	Metadados relacionados ao estorno da transação. (Não selecionável por padrão)
refundAmount	float	Valor do estorno, se aplicável.
refundConciliationId	varchar(100)	ID de conciliação para a transação de estorno.

Timestamps

Coluna	Tipo de Dados	Descrição
createdAt	timestamp	Data e hora de criação do registro.
updatedAt	timestamp	Data e hora da última atualização.

Relacionamentos

• checking_accounts: (n:1) Cada transação pertence a uma conta corrente.
• billets: (n:1) Uma transação pode ser o pagamento de um boleto.
• É referenciada por várias outras tabelas, como transaction_reprocess, transaction_fee, transaction_bank_conciliation.

Métodos Importantes da Entidade

• getOne(...): Busca uma única transação com base em um critério.
• updateCashout(...) / updateRefunded(...): Métodos estáticos para atualizar o status de transações de cash-out e estorno.
• generateConciliationId(): Gera um ID de conciliação único.
• getByConciliationId(...): Busca uma transação pelo seu ID de conciliação.
• getFee(...): Calcula a taxa aplicável a uma transação com base nas PixSettings.
• getNetAmount(...): Calcula o valor líquido de uma transação após a dedução da taxa.
• populateRefundTransaction(...): Cria uma nova instância de transação populada com os dados para um estorno.

Índices

• Múltiplos índices para otimizar consultas por checkingAccount, createdAt, status, operation, conciliationId, e qrCodeId.
• transaction_textsearch_idx: Um índice tsvector para buscas full-text em campos como endToEndId, nome do remetente, conciliationId, etc.

---

Tabela: transactions_limits_ranges

Descrição

A tabela transactions_limits_ranges serve como um gabarito ou modelo para os limites de transação padrão. Ela define os valores de limite com base no tipo de cliente (‘F’ para Físico, ‘J’ para Jurídico), no período (diurno ou noturno) e no tipo de transação (PIX, TEF, etc.).

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	varchar	Identificador único do registro de faixa de limite.	Chave Primária
customerType	varchar(1)	O tipo de cliente ao qual esta faixa de limite se aplica (‘F’ ou ‘J’).	Não Nulo
period	enum	O período do dia ao qual o limite se aplica (day ou night).	Não Nulo
transactionsType	enum	O tipo de transação (ex: PIX, TEF, BILLET).	Não Nulo
value	float	O valor padrão do limite para esta combinação de fatores.	Não Nulo
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

Esta tabela não possui relacionamentos diretos. Ela é usada como uma fonte de dados pela lógica de negócios, por exemplo, ao criar um novo cliente, para popular os limites iniciais na tabela transactions_limit.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: transactions_limit

Descrição

A tabela transactions_limit armazena os limites de transação específicos para cada cliente. Diferente da transactions_limits_ranges (que é um modelo), esta tabela contém os valores de limite que estão efetivamente em vigor para um cliente, para um tipo de transação e período (diurno/noturno).

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do limite.	Chave Primária
customerId	integer	Chave estrangeira para o cliente (customer) ao qual este limite se aplica.	FK
value	float	O valor monetário do limite.	default: 5000.0
transactionsType	enum	O tipo de transação ao qual este limite se aplica (ex: PIX, TEF, BILLET).	Não Nulo
period	enum	O período do dia ao qual o limite se aplica (day ou night).	Não Nulo

Relacionamentos

• customers: (n:1) Cada registro de limite pertence a um cliente específico.
• transaction_limit_requests: É referenciada por esta tabela quando um cliente solicita uma alteração de limite.

Métodos Importantes da Entidade

• createAllLimitsForCustomer(customer, manager?): Método estático que cria todos os limites padrão para um novo cliente com base em seu tipo (‘F’ ou ‘J’), usando os valores definidos em LIMITS_RANGES. Permite o uso de um EntityManager para operações transacionais.
• getLimitForCustomer(customerType, period, transactionsType): Método estático que busca o valor de limite padrão para uma combinação de tipo de cliente, período e tipo de transação a partir da constante LIMITS_RANGES.

Índices

• A coluna customerId é indexada para otimizar a busca de todos os limites de um cliente.

---

Tabela: transactions_monthly_usage

Descrição

A tabela transactions_monthly_usage rastreia o uso mensal de transações por cliente de forma granular. Diferente da customer_txs_monthly_usage, esta tabela separa a contagem por operation (crédito/débito) e transactionType. Isso é fundamental para lógicas de negócio como a aplicação de taxas após um certo número de transações gratuitas por mês, conforme definido em fee_transaction_settings ou plan_transaction_settings.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de uso.	Chave Primária
customerId	integer	Chave estrangeira para o cliente (customer).	FK
monthYear	date	O mês e ano de referência para a contagem.	Não Nulo
operation	Operation	A operação da transação (CREDIT ou DEBIT).	Não Nulo
transactionType	TRANSACTION_TYPE_ENUM	O tipo da transação (ex: PIX, TED).	Não Nulo
count	integer	Número de transações realizadas para esta combinação específica no mês.	default: 0
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• customers: (n:1) Cada registro de uso mensal pertence a um cliente.

Índices

• IDX_customer_monthYear_operation_transactionType: Índice único composto que garante a unicidade de cada registro de contagem. Não pode haver mais de um registro para o mesmo cliente, mês/ano, operação e tipo de transação.

---

Tabela: user_account_audit_logs

Descrição

A tabela user_account_audit_logs serve como um log de auditoria para registrar todas as alterações significativas feitas nos dados das contas de usuários (users) e clientes (customers). Cada registro captura o que foi alterado, os valores antes e depois da mudança, e o contexto da alteração (quem, quando e de onde).

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro de log.	Chave Primária
user_id	integer	FK para o usuário (user) que realizou a alteração.	Não Nulo, FK
customer_id	integer	FK para o cliente (customer) cuja conta foi alterada.	Não Nulo, FK
changedFields	text	String JSON contendo os nomes dos campos que foram modificados.	Não Nulo
oldValues	text	String JSON contendo os valores dos campos antes da alteração.	Pode ser Nulo
newValues	text	String JSON contendo os valores dos campos depois da alteração.	Pode ser Nulo
ipAddress	varchar(45)	Endereço IP de onde a alteração foi originada.	Pode ser Nulo
userAgent	varchar(500)	User-Agent do navegador ou dispositivo que realizou a alteração.	Pode ser Nulo
created_at	timestamp	Data e hora em que o log foi criado (momento da alteração).	Gerado Automaticamente

Relacionamentos

• users: (n:1) Cada log de auditoria é gerado por um usuário.
• customers: (n:1) Cada log de auditoria refere-se a um cliente.

Índices

• idx_user_account_audit_log_user_customer: Índice composto em user_id e customer_id para otimizar a busca de logs por usuário e cliente.
• idx_user_account_audit_log_created_at: Índice em created_at para otimizar a ordenação e filtragem por data.

---

Tabela: user_account

Descrição

A tabela user_account é uma tabela de junção que estabelece uma relação muitos-para-muitos entre usuários (users) e clientes/contas (customers). Ela permite que um mesmo usuário tenha acesso a múltiplas contas de clientes e que uma conta de cliente possa ser acessada por múltiplos usuários (com diferentes papéis e permissões).

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da associação.	Chave Primária
userId	integer	Chave estrangeira para a tabela users.	FK
customerId	integer	Chave estrangeira para a tabela customers.	FK

Relacionamentos

• users: (n:1) Cada registro de user_account aponta para um usuário.
• customers: (n:1) Cada registro de user_account aponta para um cliente/conta.

Métodos Importantes da Entidade

• getUsersByCustomer(customer): Método estático que retorna todos os usuários associados a um determinado cliente.
• getUserByUserIdAndCustomerId(userId, customerId): Método estático que busca uma associação específica entre um usuário e um cliente.
• findByUser(user): Método estático que encontra a primeira associação (UserAccount) para um determinado usuário.

Índices

Não há índices customizados definidos na entidade, além das chaves estrangeiras.

---

Tabela: user_admin

Descrição

A tabela user_admin armazena os dados dos usuários administradores da plataforma. São os usuários que têm acesso ao painel de administração para gerenciar clientes, configurações, usuários e outras operações internas.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do usuário administrador.	Chave Primária
name	varchar(100)	Nome do administrador.	Não Nulo
email	varchar(100)	E-mail de login do administrador.	Não Nulo, Único
password	varchar(255)	Hash da senha do administrador.	Não Nulo
isActive	boolean	Indica se a conta do administrador está ativa.	default: true
phoneNumber	varchar(30)	Número de telefone do administrador.	Pode ser Nulo
document	varchar(14)	Documento (CPF) do administrador.	Pode ser Nulo
roleAdminId	integer	Chave estrangeira para o papel (role_admin) que define as permissões deste usuário.	FK
origin_ip	varchar	IP de origem registrado para o usuário. (Não selecionável por padrão)	Pode ser Nulo
lastPasswordUpdate	timestamp	Data da última atualização de senha.	Gerado Automaticamente
otp_secret	varchar	O segredo para a geração de códigos de autenticação de dois fatores (2FA/OTP).	Pode ser Nulo
otp_validated	boolean	Indica se o 2FA já foi validado e está ativo para o usuário.	default: false
requires_2fa	boolean	Indica se o login deste usuário exige autenticação de dois fatores.	default: true
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• role_admin: (n:1) Cada usuário administrador possui um papel que define suas permissões.

Métodos Importantes da Entidade

• getUserOriginIp(user): Método estático que busca de forma segura o IP de origem registrado para um usuário administrador.

---

Tabela: user_device

Descrição

A tabela user_device gerencia os dispositivos (celulares, tablets, etc.) que um usuário utiliza para acessar o sistema. Ela é fundamental para a segurança, permitindo rastrear sessões, gerenciar dispositivos confiáveis e enviar notificações push.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do dispositivo associado.	Chave Primária
isActive	boolean	Indica se o dispositivo está atualmente ativo e autorizado para o usuário.	default: true
deviceSecret	varchar(255)	Um segredo único gerado para o dispositivo, usado para autenticação e segurança.	Não Nulo, Único, Não Selecionável
deviceId	varchar(255)	O identificador único do dispositivo (ex: UDID, Android ID).	Pode ser Nulo
userId	integer	Chave estrangeira para o usuário (user) dono do dispositivo.	FK
deviceName	varchar(100)	Nome do dispositivo (ex: “iPhone de João”).	Pode ser Nulo
operatingSystem	varchar(50)	Sistema operacional do dispositivo (ex: “iOS”, “Android”).	Pode ser Nulo
lastIp	varchar(50)	O último endereço IP registrado para este dispositivo.	Pode ser Nulo
notification_token	varchar(50)	O token usado para enviar notificações push para o dispositivo (ex: FCM, APNS).	Pode ser Nulo
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• users: (n:1) Cada dispositivo registrado pertence a um único usuário.

Índices

• IDX_isActive_user: Índice composto nas colunas isActive e userId. Otimiza a busca por todos os dispositivos ativos de um usuário.
• IDX_user: Índice na coluna userId.

---

Tabela: users

Descrição

A tabela users armazena as contas dos usuários finais da plataforma. Um usuário pode ser um “master” de uma conta de cliente (customer) ou um usuário secundário com permissões específicas. Esta tabela contém suas credenciais de login, informações pessoais e de contato, e configurações de segurança.

Estrutura da Tabela

Informações de Login e Credenciais

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do usuário.	Chave Primária
email	varchar(100)	E-mail de login do usuário.	Não Nulo
password	varchar(255)	Hash da senha do usuário.	Não Nulo, Não Selecionável
isActive	boolean	Indica se a conta do usuário está ativa.	default: true
must_change_password	boolean	Flag que força o usuário a trocar a senha no próximo login.	default: true, Não Selecionável

Informações Pessoais

Coluna	Tipo de Dados	Descrição
name	varchar(100)	Nome completo do usuário.
document	varchar(14)	CPF do usuário.
birth_date	date	Data de nascimento do usuário.
mother_name	varchar(100)	Nome da mãe do usuário.
is_politically_exposed_person	boolean	Indica se o usuário é uma Pessoa Politicamente Exposta (PEP).

Informações de Contato e Endereço

Coluna	Tipo de Dados	Descrição
phoneNumber	varchar(30)	Número de telefone do usuário.
country_phone_code	varchar(3)	Código de país do telefone (ex: ‘55’ para Brasil).
addressLine1	varchar(100)	Logradouro e número.
addressLine2	varchar(14)	Complemento.
neighborhood	varchar(100)	Bairro.
city	varchar(100)	Cidade.
state	varchar(20)	Estado.
postalCode	varchar(10)	CEP.
countryCode	varchar(2)	Código do país (ISO 3166-1 alpha-2).

Configurações e Segurança

Coluna	Tipo de Dados	Descrição
type	integer	Código do tipo/papel do usuário (ex: 0: Administrador, 1: Consultor).
avatar	varchar(255)	URL para a foto de perfil do usuário.
eneable_2fa	boolean	Indica se a autenticação de dois fatores está habilitada.
secret_2fa	varchar	Segredo para a geração de códigos 2FA.
mutiple_mobile_access	boolean	Permite que o usuário acesse de múltiplos dispositivos móveis simultaneamente.
deviceId	varchar(255)	ID do último dispositivo usado.
origin_ip	varchar	IP de origem do cadastro. (Não selecionável por padrão)

Timestamps

Coluna	Tipo de Dados	Descrição
createdAt	timestamp	Data e hora de criação do registro.
updatedAt	timestamp	Data e hora da última atualização.

Relacionamentos

• customers: (1:1) Um usuário pode ser o “master” de uma conta de cliente.
• user_account: Através desta tabela, um usuário pode estar associado a múltiplas contas de cliente.
• tokens, check_phone_numbers, user_device, etc.: Várias tabelas se relacionam com users para gerenciar segurança e verificações.

Métodos Importantes da Entidade

• getUserPassword(user): Busca de forma segura o hash da senha de um usuário.
• getUsersByDocument(document): Busca todos os usuários ativos com um determinado documento.
• checkAllActiveUsersHaveSameEmail(users): Verifica se uma lista de usuários compartilha o mesmo e-mail.
• getMasterUserByCustomerId(customerId): Encontra o usuário “master” associado a um ID de cliente.

---

Tabela: wallet_balance

Descrição

A tabela wallet_balance rastreia o saldo de uma carteira (wallet) dentro de uma conta corrente (checking_account) específica. Isso permite que uma única carteira virtual tenha saldos segregados em diferentes contas, o que é útil para modelos de negócio com múltiplos “cofres” ou contas de liquidação.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do saldo da carteira.	Chave Primária
walletId	integer	Chave estrangeira para a carteira (wallet) à qual este saldo pertence.	Não Nulo, FK
checkingAccountId	integer	Chave estrangeira para a conta corrente (checking_account) onde este saldo está alocado.	Não Nulo, FK
balance	double precision	O valor do saldo atual.	default: 0.0

Relacionamentos

• wallets: (n:1) Cada registro de saldo pertence a uma carteira.
• checking_accounts: (n:1) Cada registro de saldo está associado a uma conta corrente.
• wallet_split_rule: (1:1) Pode haver uma regra de divisão de fundos associada a este saldo específico.

Índices

• IDX_checkingAccount_wallet: Índice único composto pelas colunas checkingAccountId e walletId. Garante que uma carteira só pode ter um registro de saldo por conta corrente.

Métodos Importantes da Entidade

• getSplitRules(): Busca a regra de divisão (WalletSplitRule) associada a este saldo.
• incrementBalance(increment): Adiciona um valor ao saldo atual e salva a alteração.
• setBalanceToZero(): Zera o saldo e salva a alteração.

---

Tabela: wallet_transaction

Descrição

A tabela wallet_transaction funciona como um extrato para uma carteira (wallet). Cada registro representa uma movimentação de fundos (crédito ou débito) na carteira, vinculada a uma transação principal do sistema. Ela registra o valor que foi efetivamente alocado na carteira, que pode ser diferente do valor original da transação devido a regras de divisão (split).

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da transação da carteira.	Chave Primária
walletId	integer	Chave estrangeira para a carteira (wallet) que foi movimentada.	Não Nulo, FK
checkingAccountId	integer	Chave estrangeira para a conta corrente (checking_account) onde a movimentação ocorreu.	Não Nulo, FK
transactionId	integer	Chave estrangeira para a transação (transactions) principal que originou esta movimentação.	Não Nulo, FK
originalAmount	double precision	O valor original da transação principal.	default: 0.0
amount	double precision	O valor que foi efetivamente creditado ou debitado da carteira.	default: 0.0
operation	enum	O tipo de operação na carteira (CREDIT ou DEBIT).	default: 'CREDIT'
paymentDate	timestamp	Data e hora da movimentação.	Pode ser Nulo
conciliationId	varchar(100)	ID de conciliação, geralmente herdado da transação principal.	Não Nulo
sender	json	Objeto JSON com nome e documento do remetente da transação original.	Não Nulo

Relacionamentos

• wallets: (n:1) Cada transação de carteira pertence a uma carteira.
• checking_accounts: (n:1) Cada transação de carteira ocorre no contexto de uma conta corrente.
• transactions: (n:1) Cada transação de carteira é originada por uma transação principal do sistema.

Índices

• IDX_wallet_conciliationId: Índice único composto em walletId e conciliationId.
• IDX_wallet_paymentDate_checkingAccount: Índice composto para otimizar a busca de transações de uma carteira por data e conta.

Métodos Importantes da Entidade

• saveWalletTransaction(amount, wallet, transaction): Método estático para criar e salvar uma nova transação de carteira, populando os dados a partir da transação principal.
• getTransactions(wallet, queryParams): Método estático para buscar o extrato de transações de uma carteira, com opções de filtro por data e paginação.

---

Tabela: wallet

Descrição

A tabela wallet define as carteiras virtuais do sistema. Cada carteira pertence a um cliente (customer), possui um código único e pode ter uma chave PIX designada para operações de cash-out. A carteira é a entidade central para funcionalidades de split de pagamentos e saldos virtuais.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da carteira.	Chave Primária
code	varchar(8)	Um código único de 8 caracteres para identificar a carteira.	Não Nulo, Único
customerId	integer	Chave estrangeira para o cliente (customer) que é o dono da carteira.	Não Nulo, FK, Relação 1:1
cashoutPixKeyId	integer	Chave estrangeira para a chave PIX (pix_key_info) padrão para operações de cash-out desta carteira.	Não Nulo, FK, Relação 1:1

Relacionamentos

• customers: (1:1) Cada carteira pertence a um único cliente.
• pix_key_info: (1:1) Cada carteira tem uma chave PIX designada para saques.
• wallet_balance: (1:n) Uma carteira pode ter múltiplos registros de saldo, um para cada conta corrente (checking_account) em que opera.

Métodos Importantes da Entidade

• splitTransaction(transaction): Método estático que implementa a lógica de divisão (split) de uma transação. Ele encontra os saldos de carteira (WalletBalance) associados à conta da transação, calcula a parcela de cada um com base nas regras (WalletSplitRule), cria a transação da carteira (WalletTransaction) e atualiza o saldo.
• getWallet(customer): Método estático para buscar a carteira de um determinado cliente.
• getBalance(wallet): Método estático que calcula e retorna o saldo total de uma carteira, somando os saldos de todos os WalletBalance associados a ela.

---

Tabela: wallet_split_rule

Descrição

A tabela wallet_split_rule define a regra de divisão (split) de fundos para um saldo de carteira (wallet_balance) específico. Ela determina qual porção de uma transação deve ser alocada naquele saldo, seja como um valor fixo ou um percentual do total.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da regra de split.	Chave Primária
walletBalanceId	integer	Chave estrangeira para o saldo de carteira (wallet_balance) ao qual esta regra se aplica.	FK, Relação 1:1, Único
share	double precision	O valor da parcela (seja fixo ou percentual).	default: 0.0
shareType	enum	O tipo de cálculo da parcela (PERCENTAGE ou FIXED).	default: 'FIXED'

Relacionamentos

• wallet_balance: (1:1) Cada regra de split está associada a um único registro de saldo de carteira, definindo como os fundos chegam até ele.

Métodos Importantes da Entidade

• getShare(amount): Calcula o valor da parcela a ser dividida com base no valor total de uma transação (amount), aplicando a regra de share e shareType.

Índices

• A coluna walletBalanceId possui um índice único, garantindo que cada saldo de carteira tenha no máximo uma regra de split associada.

---

Tabela: webhook_event_transaction

Descrição

A tabela webhook_event_transaction é uma tabela de junção que cria uma relação entre um evento de webhook (webhook_event) e uma transação (transaction). Ela é usada para registrar qual transação (ou quais transações) está associada a um determinado disparo de webhook.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da associação.	Chave Primária
transactionId	integer	Chave estrangeira para a tabela transactions.	Não Nulo, FK
webhookEventId	integer	Chave estrangeira para a tabela webhook_events.	Não Nulo, FK

Relacionamentos

• transactions: (n:1) Cada registro de associação aponta para uma transação.
• webhook_events: (n:1) Cada registro de associação aponta para um evento de webhook.

Índices

Não há índices customizados definidos na entidade, além das chaves estrangeiras.

---

Tabela: webhook_events

Descrição

A tabela webhook_events funciona como um log detalhado de todas as tentativas de envio de webhooks. Cada registro representa um disparo de um evento para um endpoint configurado, armazenando o payload, a resposta, o status e o histórico de tentativas.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do evento de webhook.	Chave Primária
eventId	varchar(100)	Um ID único para o evento específico que está sendo notificado.	Não Nulo
method	varchar(10)	O método HTTP usado para enviar o webhook (ex: POST).	Não Nulo
endpoint	varchar(255)	A URL de destino para a qual o webhook foi enviado.	Não Nulo
status	integer	O código de status HTTP retornado pelo endpoint (ex: 200, 404, 500).	default: 0
body	json	O corpo (payload) da requisição que foi enviada no webhook.	Pode ser Nulo
response	text	O corpo da resposta retornada pelo endpoint.	Pode ser Nulo
webhookId	integer	Chave estrangeira para a configuração de webhook (webhooks) que gerou este evento.	FK
retries	integer	O número de tentativas de reenvio para este evento.	default: 0
retriesMeta	json	Metadados sobre as tentativas de reenvio (ex: datas, erros).	Pode ser Nulo
authenticationCode	varchar(100)	Código de autenticação ou assinatura enviado nos headers do webhook.	Pode ser Nulo
createdAt	timestamp	Data e hora de criação do evento.	Gerado Automaticamente

Relacionamentos

• webhooks: (n:1) Cada evento de webhook é gerado a partir de uma configuração de webhook específica.
• webhook_event_transaction: (1:n) Um evento de webhook pode estar associado a uma ou mais transações.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: webhooks

Descrição

A tabela webhooks armazena as configurações de webhooks para os clientes. Cada registro define um endpoint para o qual o sistema deve enviar uma notificação HTTP quando um evento específico (eventId) ocorrer para o cliente associado.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único da configuração do webhook.	Chave Primária
method	varchar(50)	O método HTTP a ser usado na chamada do webhook (ex: POST, PUT).	default: 'post'
endpoint	varchar(255)	A URL de destino para a qual a notificação do evento será enviada.	Não Nulo
eventId	varchar(100)	O nome do evento que dispara este webhook (ex: transaction.paid, customer.updated).	Não Nulo
customerId	integer	Chave estrangeira para o cliente (customer) dono desta configuração.	FK
createdAt	timestamp	Data e hora de criação do registro.	Gerado Automaticamente
updatedAt	timestamp	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

• customers: (n:1) Cada configuração de webhook pertence a um cliente.
• webhook_events: (1:n) Uma configuração de webhook pode gerar múltiplos eventos (disparos) ao longo do tempo.

Índices

Não há índices customizados definidos na entidade, além da chave primária.

---

Tabela: whitelist

Descrição

A tabela whitelist é uma lista de permissões (whitelist) simples, baseada em documentos. Ela armazena uma lista de documentos (CPF/CNPJ) que têm permissão para realizar certas ações ou acessar funcionalidades restritas.

Estrutura da Tabela

Coluna	Tipo de Dados	Descrição	Restrições
id	integer	Identificador único do registro na whitelist.	Chave Primária
name	varchar(255)	Um nome opcional para identificar a pessoa ou empresa na lista.	Pode ser Nulo
document	varchar(255)	O número do documento (CPF/CNPJ) que está sendo permitido.	Não Nulo
allowed	boolean	Um booleano que indica se o documento está efetivamente permitido.	default: false
created_at	timestamp with time zone	Data e hora de criação do registro.	Gerado Automaticamente
updated_at	timestamp with time zone	Data e hora da última atualização do registro.	Gerado Automaticamente

Relacionamentos

Esta tabela não possui relacionamentos diretos com outras tabelas. Ela é consultada pela lógica de negócios para verificar se um determinado documento está na lista de permissões.

Índices

Não há índices customizados definidos na entidade, além da chave primária.