Finance Library - Estrutura de Banco de Dados

Este documento explica, de forma didática e técnica, como funciona a estrutura de dados do módulo financeiro em libraries/finance.

1) Objetivo do módulo

O módulo financeiro foi modelado para cobrir o ciclo completo de gestão financeira:

• cadastro base (filiais, categorias, centros de custo, contas bancárias, meios de pagamento);
• planejamento (título e parcelas);
• execução financeira (liquidação/baixa real);
• conciliação bancária (extrato x liquidação);
• governança (auditoria e fechamento de período);
• projeções futuras (cenários, fluxo projetado e agenda de recebíveis).

2) Convenções gerais

2.1 Escopo atual (sem tenant)

Nesta versão, o módulo não usa separação por tenant nas tabelas novas. Ou seja, não existem colunas company_person_id ou person_company_id nas tabelas do módulo financeiro.

2.2 Tabelas já existentes usadas pelo módulo

O módulo reutiliza tabelas de outras libraries:

• person: contraparte de títulos e liquidações (cliente/fornecedor).
• user: autoria e rastreabilidade (created_by, matched_by, closed_by, etc.).
• tag: classificação analítica de parcelas.
• file: anexos de títulos.

2.3 Padrões recomendados de domínio

• Valores monetários em centavos (*_cents) para evitar erro de precisão.
• Datas de competência e vencimento separadas para análises corretas.
• Histórico imutável de eventos financeiros: não apagar histórico; corrigir por estorno/ajuste.

3) Visão macro das relações

Fluxo principal de operação:

1. Cadastra financial_title (documento pai).
2. Gera financial_installment (parcelas).
3. Registra settlement (dinheiro real).
4. Liga settlement às parcelas em settlement_allocation.
5. Importa extrato (bank_statement e bank_statement_line).
6. Concilia extrato x settlement em bank_reconciliation.

Relações de suporte:

• financial_installment_tag: N:N entre parcela e tag.
• installment_allocation: rateio de parcela por centro de custo.
• financial_title_attachment: documentos anexos.
• audit_log: trilha de auditoria de ações.
• period_close: bloqueio operacional por período.

4) Dicionário de tabelas (objetivo, colunas e uso)

4.1 company_profile

Objetivo: guardar configurações globais do contexto financeiro (status, moeda e timezone).

Colunas:

• id: chave primária.
• code: identificador curto/estável para integração e referência.
• status: active|inactive.
• default_currency: moeda padrão (ex.: BRL).
• timezone: timezone padrão (ex.: America/Sao_Paulo).
• created_at, updated_at: auditoria temporal.

Uso comum: inicialização de regras de data/moeda em UI, API e relatórios.

4.2 branch

Objetivo: representar filiais/unidades operacionais.

Colunas:

• id: chave primária.
• code: código único da filial.
• name: nome exibível da filial.
• status: active|inactive.
• created_at, updated_at.

Relações:

• Referenciada por financial_title.branch_id.
• Referenciada por bank_account.branch_id.
• Referenciada por settlement.branch_id.

4.3 finance_category

Objetivo: plano de categorias financeiras para classificação analítica.

Colunas:

• id: chave primária.
• parent_id: auto-relacionamento para hierarquia (nullable).
• code: código da categoria.
• name: nome da categoria.
• kind: revenue|expense|transfer|adjustment|other.
• status: active|inactive.
• created_at, updated_at.

Relações:

• Auto-relacionamento por parent_id.
• Referenciada por financial_title.finance_category_id.

4.4 cost_center

Objetivo: centro de custo/projeto para rateio gerencial.

Colunas:

• id: chave primária.
• code: código do centro de custo.
• name: nome exibível.
• status: active|inactive.
• created_at, updated_at.

Relações:

• Referenciada por installment_allocation.cost_center_id.

4.5 payment_method

Objetivo: catálogo configurável de meios de pagamento/recebimento.

Colunas:

• id: chave primária.
• code: identificador do método.
• name: nome exibível.
• type: pix|boleto|ted|doc|card|cash|other.
• status: active|inactive.
• created_at, updated_at.

Relações:

• Referenciada por settlement.payment_method_id.

4.6 bank_account

Objetivo: contas bancárias/caixa usadas nos movimentos reais.

Colunas:

• id: chave primária.
• branch_id: FK para branch.id (nullable).
• code: código da conta.
• name: nome exibível.
• bank_name, bank_code: metadados bancários (nullable).
• agency, account_number: metadados bancários (nullable).
• account_type: checking|savings|investment|cash|other.
• status: active|inactive.
• created_at, updated_at.

Relações:

• Referenciada por bank_statement.bank_account_id.
• Referenciada por bank_statement_line.bank_account_id.
• Referenciada por settlement.bank_account_id.

4.7 financial_title

Objetivo: documento pai de contas a pagar/receber.

Colunas:

• id: chave primária.
• branch_id: FK para filial (nullable).
• person_id: FK para contraparte (person.id).
• title_type: payable|receivable.
• status: draft|approved|open|partial|settled|canceled|overdue.
• document_number: número do documento (nullable).
• description: histórico/observações (nullable).
• competence_date: competência macro (nullable).
• issue_date: emissão (nullable).
• total_amount_cents: total previsto no título.
• finance_category_id: FK para categoria (nullable).
• created_by_user_id: FK para user.id (nullable).
• created_at, updated_at.

Relações:

• 1:N com financial_installment.
• 1:N com financial_title_attachment.

4.8 financial_installment

Objetivo: parcelas planejadas de cada título.

Colunas:

• id: chave primária.
• title_id: FK para financial_title.id.
• installment_number: número sequencial da parcela por título.
• competence_date: competência contábil/gerencial.
• due_date: vencimento.
• amount_cents: valor original da parcela.
• open_amount_cents: saldo em aberto.
• status: open|partial|settled|canceled|overdue.
• notes: observações (nullable).
• created_at, updated_at.

Relações:

• N:1 com financial_title.
• N:N com tag via financial_installment_tag.
• 1:N com installment_allocation.
• 1:N com settlement_allocation.

4.9 financial_title_attachment

Objetivo: anexar arquivos ao título sem armazenar binário na tabela.

Colunas:

• id: chave primária.
• title_id: FK para financial_title.id.
• file_id: FK para file.id.
• uploaded_by_user_id: FK para user.id (nullable).
• created_at, updated_at.

4.10 financial_installment_tag

Objetivo: classificação por tags em nível de parcela.

Colunas:

• id: chave primária.
• installment_id: FK para financial_installment.id.
• tag_id: FK para tag.id.
• created_at, updated_at.

Observação: possui unicidade (installment_id, tag_id) para evitar duplicidade.

4.11 installment_allocation

Objetivo: ratear uma parcela entre centros de custo.

Colunas:

• id: chave primária.
• installment_id: FK para financial_installment.id.
• cost_center_id: FK para cost_center.id.
• allocated_amount_cents: valor alocado.
• created_at, updated_at.

Observação: possui unicidade (installment_id, cost_center_id).

4.12 settlement

Objetivo: representar o evento financeiro real (pagamento/recebimento/transferência/ajuste).

Colunas:

• id: chave primária.
• branch_id: FK para branch.id (nullable).
• person_id: FK para person.id (nullable).
• bank_account_id: FK para bank_account.id (nullable).
• payment_method_id: FK para payment_method.id (nullable).
• settlement_type: payable|receivable|transfer|adjustment.
• status: pending|confirmed|reversed.
• settled_at: data/hora do evento financeiro.
• amount_cents: valor do evento.
• description: histórico (nullable).
• external_reference: referência externa (nullable).
• created_by_user_id: FK para user.id (nullable).
• created_at, updated_at.

Relações:

• 1:N com settlement_allocation.
• 1:1 com bank_reconciliation (por restrição de unicidade).

4.13 settlement_allocation

Objetivo: distribuir um settlement em uma ou várias parcelas.

Colunas:

• id: chave primária.
• settlement_id: FK para settlement.id.
• installment_id: FK para financial_installment.id.
• allocated_amount_cents: valor aplicado na parcela.
• discount_cents: desconto aplicado.
• interest_cents: juros aplicado.
• penalty_cents: multa aplicada.
• created_at, updated_at.

Observação: possui unicidade (settlement_id, installment_id).

4.14 bank_statement

Objetivo: lote de importação de extrato bancário.

Colunas:

• id: chave primária.
• bank_account_id: FK para bank_account.id.
• source_type: ofx|csv|manual.
• idempotency_key: evita reimportação do mesmo lote (nullable).
• period_start, period_end: intervalo coberto no extrato (nullable).
• imported_at: data/hora da importação.
• imported_by_user_id: FK para user.id (nullable).
• created_at, updated_at.

Relações:

• 1:N com bank_statement_line.

4.15 bank_statement_line

Objetivo: transações individuais do extrato (a prova bancária).

Colunas:

• id: chave primária.
• bank_statement_id: FK para bank_statement.id.
• bank_account_id: FK para bank_account.id.
• external_id: identificador externo do banco (nullable).
• posted_date: data efetiva.
• amount_cents: valor da linha.
• description: histórico do banco.
• status: imported|pending|reconciled|reversed|adjusted.
• dedupe_key: chave de deduplicação (única).
• created_at, updated_at.

Relações:

• 1:1 com bank_reconciliation (por restrição de unicidade).

4.16 bank_reconciliation

Objetivo: vínculo auditável entre linha de extrato e settlement.

Colunas:

• id: chave primária.
• bank_statement_line_id: FK para bank_statement_line.id (único).
• settlement_id: FK para settlement.id (único).
• status: pending|reconciled|reversed|adjusted.
• matched_at: data/hora da conciliação (nullable).
• matched_by_user_id: FK para user.id (nullable).
• created_at, updated_at.

Observação: modelado como 1:1 para simplificar conciliação de eventos.

4.17 audit_log

Objetivo: trilha de auditoria funcional do módulo.

Colunas:

• id: chave primária.
• actor_user_id: FK para user.id (nullable).
• action: ação executada (ex.: SETTLEMENT_CREATE).
• entity_table: tabela afetada.
• entity_id: id da entidade afetada (string).
• summary: resumo legível (nullable).
• before_data: snapshot anterior (nullable).
• after_data: snapshot posterior (nullable).
• ip_address: origem da ação (nullable).
• created_at, updated_at.

4.18 period_close

Objetivo: controlar fechamento operacional de período.

Colunas:

• id: chave primária.
• period_start: início do período.
• period_end: fim do período.
• status: open|closed.
• closed_at: data/hora do fechamento (nullable).
• closed_by_user_id: FK para user.id (nullable).
• notes: observações (nullable).
• created_at, updated_at.

Uso comum: bloquear operações diretas em períodos fechados e permitir apenas estornos sob regra.

4.19 forecast_scenario

Objetivo: cenários de planejamento financeiro futuro.

Colunas:

• id: chave primária.
• name: nome do cenário (ex.: Base, Conservador).
• status: active|inactive.
• is_default: cenário padrão.
• created_at, updated_at.

Relações:

• 1:N com cashflow_projection.
• 1:N com receivable_schedule.

4.20 cashflow_projection

Objetivo: linhas de projeção de fluxo por data e tipo.

Colunas:

• id: chave primária.
• scenario_id: FK para forecast_scenario.id.
• projection_date: data projetada.
• projection_type: inflow|outflow|net.
• amount_cents: valor projetado.
• notes: observações (nullable).
• created_at, updated_at.

4.21 receivable_schedule

Objetivo: agenda de recebíveis previstos quando ainda não há título lançado.

Colunas:

• id: chave primária.
• scenario_id: FK para forecast_scenario.id.
• person_id: FK para person.id (nullable).
• expected_date: data esperada.
• amount_cents: valor esperado.
• description: descrição (nullable).
• created_at, updated_at.

5) Fluxos operacionais essenciais

5.1 Contas a pagar/receber

1. Criar financial_title.
2. Criar parcelas em financial_installment.
3. Registrar liquidação em settlement.
4. Alocar liquidação em settlement_allocation.
5. Atualizar saldo em aberto e status da parcela/título na regra de negócio.

5.2 Conciliação bancária

1. Importar lote em bank_statement.
2. Inserir linhas em bank_statement_line com dedupe_key.
3. Associar linha e settlement em bank_reconciliation.
4. Atualizar status de conciliação e registrar auditoria.

5.3 Estorno

1. Não apagar dados históricos.
2. Marcar settlement.status = reversed.
3. Reprocessar saldo em aberto das parcelas relacionadas.
4. Registrar no audit_log.

5.4 Fechamento de período

1. Definir janela em period_close.
2. Marcar status = closed.
3. Bloquear lançamentos/alterações do período fechado via regra da aplicação.

6) Invariantes recomendados de regra de negócio

Para manter consistência financeira, o ideal é garantir (na aplicação e, quando possível, no banco):

• financial_installment.open_amount_cents >= 0.
• financial_installment.open_amount_cents <= financial_installment.amount_cents.
• soma de settlement_allocation.allocated_amount_cents por parcela não excede o valor permitido pela política da parcela.
• soma de installment_allocation.allocated_amount_cents coerente com a política de rateio da parcela.
• period_end >= period_start em period_close.
• unicidade respeitada em tabelas de vínculo N:N para evitar duplicidades.

7) Diretrizes para novos desenvolvedores

• Trate financial_title como agregador de documento e financial_installment como unidade operacional de cobrança/baixa.
• Considere settlement como evento imutável de dinheiro real; prefira estorno/ajuste em vez de edição destrutiva.
• Use audit_log sempre que houver alteração relevante de estado.
• Ao importar extrato, monte dedupe_key estável para evitar duplicidade.
• Ao evoluir schema, preserve compatibilidade de índices e FKs com os fluxos descritos neste documento.

8) Resumo rápido da arquitetura

• Cadastro: company_profile, branch, finance_category, cost_center, payment_method, bank_account.
• Operação: financial_title, financial_installment, settlement, settlement_allocation.
• Conciliação: bank_statement, bank_statement_line, bank_reconciliation.
• Governança: audit_log, period_close.
• Planejamento: forecast_scenario, cashflow_projection, receivable_schedule.

Com essa estrutura, o módulo cobre planejamento, execução, rastreabilidade e projeção financeira de forma consistente e extensível.