Transações

Visão Geral

As Transações são o coração do módulo financeiro. Elas representam qualquer movimentação de dinheiro no sistema, seja uma receita, uma despesa ou uma transferência entre contas. Uma transação pode estar vinculada diretamente a uma Conta Financeira ou indiretamente via uma Fatura de Cartão de Crédito.

Tabelas

`financial_transactions`

Coluna	Tipo	Descrição
`id`	bigint	Chave primária.
`financial_account_id`	foreignId	(Opcional) A conta bancária onde a transação ocorreu.
`financial_credit_card_invoice_id`	foreignId	(Opcional) A fatura de cartão de crédito à qual esta compra pertence.
`financial_recurrence_id`	foreignId	(Opcional) A recorrência que gerou esta transação.
`transfer_pair_id`	bigint	(Opcional) ID da transação correspondente (par) em caso de transferência.
`type`	enum	`income` (receita) ou `expense` (despesa).
`amount`	decimal	Valor total da transação.
`description`	string	Descrição/Título da movimentação.
`date`	date	Data em que a transação ocorreu.
`status`	string	Enum `TransactionStatus` (`draft`, `pending`, `posted`).
`installment_current`	integer	(Opcional) Qual parcela é esta (ex: 1).
`installment_total`	integer	(Opcional) Total de parcelas (ex: 12).

`financial_transaction_items`

Permite a divisão de uma única transação em múltiplos itens para categorização mais granular.

Coluna	Tipo	Descrição
`id`	bigint	Chave primária.
`financial_transaction_id`	foreignId	Transação pai.
`description`	string	Descrição do item específico.
`quantity`	decimal	Quantidade.
`unit_price`	decimal	Preço unitário.
`total`	decimal	Total calculado a partir da quantidade e do preço unitário.

Diagrama Relacional (ER)

Renderizando diagrama declarativo…

Modelo relacional de transações

Transações podem vir de contas, faturas ou recorrências; possuem itens e tags, e duas transações podem formar o par de uma transferência.

Leitura semântica

Transações podem vir de contas, faturas ou recorrências; possuem itens e tags, e duas transações podem formar o par de uma transferência.

Fonte declarativa: diagrams/sources/transactions-model.mmd

Regras de Negócio e Comportamento

Ciclo de Vida e Status (`TransactionStatus`)

O status da transação é gerenciado pelo Enum App\Enums\TransactionStatus:

Rascunho (TransactionStatus::Draft / 'draft'): Utilizado para lançamentos parciais, rascunhos de conciliação ou importações pendentes de revisão.
Pendente (TransactionStatus::Pending / 'pending'): Indica que a transação está prevista para acontecer (compras futuras, despesas não pagas, compras em faturas de cartão ainda abertas).
Efetivada (TransactionStatus::Posted / 'posted'): O fluxo de caixa real aconteceu. Transações efetivadas impactam diretamente o saldo real consolidado da conta.
Ao criar compras parceladas ou transferências, o sistema avalia automaticamente se a data da transação é hoje ou no passado para defini-la como efetivada (posted). Caso a data seja futura, ela nasce como pendente (pending).

Anexos e Comprovantes (Spatie MediaLibrary)

O modelo FinancialTransaction implementa a interface HasMedia com a coleção privada attachments. É possível anexar comprovantes de pagamento, recibos fiscais em PDF ou imagens diretamente na tela de criação/edição. Os arquivos são armazenados no disco privado (attachments), garantindo privacidade total.

Itens da Transação

Os itens são opcionais e detalham a transação para permitir classificação por tags e relatórios mais precisos. A quantidade deve ser maior que zero; o preço unitário não pode ser zero e pode ser negativo, por exemplo para registrar um desconto, estorno ou ajuste dentro da composição da transação. O total da transação é recalculado a partir dos itens enquanto eles estão sendo editados.

Ao salvar uma edição, os itens existentes são atualizados preservando sua identidade e seu histórico. Um item removido do formulário é excluído definitivamente junto com os seus vínculos de tags, e a auditoria mantém o registro dos dados que foram removidos.

Parcelamentos

A criação de compras parceladas (via método createInstallmentsOnAccount) gera automaticamente as N transações futuras no banco de dados. Cada transação recebe a data deslocada mensalmente, e possui metadados de controle (installment_current e installment_total) para facilitar a identificação visual ("1/12", "2/12", etc.). O valor total é dividido, e eventuais centavos de arredondamento são somados à última parcela.

Transferências

As transferências não possuem uma entidade própria; elas são representadas por duas transações vinculadas entre si:

Uma transação do tipo expense na conta de Origem.
Uma transação do tipo income na conta de Destino.
Ambas compartilham o mesmo transfer_pair_id apontando para o ID da despesa geradora.
Automaticamente recebem a tag protegida de "Transferência" (FinancialTag::TRANSFERENCIA_ID) para que relatórios financeiros possam ignorá-las sem distorcer o fluxo de caixa líquido.
Em caso de taxa bancária associada à transferência, uma 3ª transação (despesa) é gerada na conta de origem separadamente.

Soft Deletes e Proteção em Cascata

Se uma das pernas de uma transferência for excluída, o sistema intercepta o evento de deleting e apaga automaticamente a transação correspondente (par) para manter a coerência financeira. Deleções definitivas (forceDelete) também forçam a purga da contraparte.