Financeiro

Visão Geral

O módulo financeiro gerencia transações (receitas e despesas), contas bancárias, categorias configuráveis, e relatórios em PDF. Implementa um workflow de status: pendente → efetivada ou cancelada.

Models

Transaction

Namespace: App\Domain\Finance\Models\Transaction

Campo	Tipo	Descrição
ulid	string	Identificador público
tipo	enum	receita ou despesa
status	enum	pendente, efetivada, cancelada
valor	decimal(10,2)	Valor da transação
transaction_category_id	FK	Categoria (Dízimo, Aluguel, etc.)
congregation_id	FK nullable	Congregação
bank_account_id	FK nullable	Conta bancária
member_id	FK nullable	Membro (para dízimos/ofertas nominais)
forma_pagamento	enum nullable	dinheiro, pix, cartao_credito, cartao_debito, transferencia, boleto, cheque
data_transacao	date	Data do lançamento
data_vencimento	date nullable	Vencimento (despesas)
data_pagamento	date nullable	Data da efetivação
descricao	text nullable	Descrição livre
nota_fiscal	string nullable	Número NF/recibo
cancelamento_motivo	text nullable	Motivo do cancelamento

Workflow de Status

pendente ──→ efetivada (via ConfirmTransactionAction)
    │
    └──→ cancelada (via CancelTransactionAction, com motivo)

• Pendente: pode ser editada, efetivada ou cancelada
• Efetivada: imutável (não pode ser editada ou cancelada)
• Cancelada: imutável, mantém registro visível com motivo

TransactionCategory

Categorias configuráveis por tipo.

Campo	Tipo
nome	string
tipo	enum (receita/despesa)
is_active	boolean
sort_order	integer

Categorias padrão (seeder):

• Receita: Dízimo, Oferta, Campanha, Doação
• Despesa: Aluguel, Água, Luz, Internet, Salário, Manutenção, Material de Limpeza, Material de Escritório

BankAccount

Contas bancárias opcionais (igrejas no plano Semente podem não usar).

Campo	Tipo
nome	string
banco	string nullable
agencia / conta	string nullable
tipo	enum (corrente/poupanca) nullable
chave_pix	string nullable
congregation_id	FK nullable

Actions

Action	Descrição
CreateTransactionAction	Cria transação, dispara TransactionCreated
UpdateTransactionAction	Atualiza (apenas pendentes), dispara TransactionUpdated
ConfirmTransactionAction	Muda para efetivada + data_pagamento
CancelTransactionAction	Muda para cancelada + motivo

Endpoints

Transações

Método	Rota	Descrição
GET	/transactions	Lista com filtros (tipo, status, categoria, período)
POST	/transactions	Criar transação
GET	/transactions/	Detalhes
PUT	/transactions/	Atualizar (só pendentes)
DELETE	/transactions/	Soft delete
PATCH	/transactions/{ulid}/confirm	Efetivar transação
PATCH	/transactions/{ulid}/cancel	Cancelar com motivo

Contas Bancárias

Método	Rota	Descrição
GET/POST/PUT/DELETE	/bank-accounts	CRUD completo

Categorias

Método	Rota	Descrição
GET/POST/PUT/DELETE	/transaction-categories	CRUD com filtro por tipo

Relatórios (PDF)

Método	Rota	Descrição
GET	/reports	Página de geração de relatórios
GET	/reports/financial	PDF do relatório de período
GET	/reports/receipt/	PDF do recibo individual

Dashboard

O dashboard (/dashboard) exibe KPIs financeiros e de membros:

KPIs: Membros ativos, Receitas/Despesas do mês (com variação %), Saldo, Dízimos, Membros por situação

Gráficos (Chart.js):

• Barras: Receitas vs Despesas (últimos 6 meses)
• Donut: Top 5 categorias de despesa do mês

Permissões

Permissão	admin-igreja	tesoureiro	secretario
finance.view	✅	✅	✅
finance.create	✅	✅	❌
finance.edit	✅	✅	❌
finance.delete	✅	❌	❌
finance.confirm	✅	✅	❌
bank-account.view	✅	✅	❌
bank-account.manage	✅	❌	❌