FinancialTransaction (Transacao Financeira)

A FinancialTransaction representa uma movimentacao financeira (receita ou despesa) no sistema.

Descricao

Transacoes financeiras registram todas as entradas e saidas de dinheiro do petshop. Podem ser unicas, parceladas ou recorrentes, e se integram com vendas, faturas de cartao e conciliacao bancaria.

Dados

Informacoes Basicas

Campo	Tipo	Obrigatorio	Descricao
name	Texto	Sim	Nome/descricao da transacao
value	Monetario	Sim	Valor da transacao
type	Selecao	Sim	"expense" (despesa) ou "revenue" (receita)
status	Selecao	Sim	"pending" ou "paid"
date	Data	Sim	Data de vencimento
competence_date	Data	Sim	Data de competencia contabil

Valores de Pagamento

Campo	Tipo	Obrigatorio	Descricao
paid_date	Data	Condicional	Data do pagamento (se pago)
paid_value	Monetario	Condicional	Valor efetivamente pago
discount_value	Monetario	Calculado	Desconto obtido (value - paid_value)
tax_value	Monetario	Calculado	Juros/multa (paid_value - value)
signal_value	Monetario	Calculado	Valor com sinal (+ receita, - despesa)
final_date	Data	Calculado	paid_date ou date

Conta de Pagamento

Campo	Tipo	Obrigatorio	Descricao
payment_account	Selecao	Sim	"financial_account", "credit", "payment_method"
financial_account_id	Referencia	Condicional	Conta financeira
credit_card_id	Referencia	Condicional	Cartao de credito
payment_method_id	Referencia	Condicional	Metodo de pagamento
method_type	Selecao	Condicional	"debit", "credit_card", "pix"

Recorrencia

Campo	Tipo	Descricao
payment_frequency	Selecao	"one_time", "fixed", "installment"
frequency	Selecao	Intervalo de recorrencia
frequency_end_date	Data	Data final (se fixed)
installments	Numero	Numero de parcelas
current_installment	Numero	Parcela atual
financial_parent_reference	Texto	ID da transacao pai
frequency_update	Selecao	Escopo de edicao da serie

Categorizacao

Campo	Tipo	Obrigatorio	Descricao
financial_category_id	Referencia	Sim	Categoria financeira
parent_financial_category_id	Referencia	Auto	Categoria pai
financial_cost_center_id	Referencia	Nao	Centro de custo unico
use_cost_center_allocation	Booleano	Nao	Usar rateio de custos
cost_center_allocations	Array	Condicional	Rateio por centro de custo

Flags Especiais

Campo	Tipo	Descricao
is_invoice	Booleano	Se e fatura consolidada
is_transfer	Booleano	Se e transferencia entre contas
is_voucher	Booleano	Se e voucher/vale
initial_balance	Booleano	Se e saldo inicial da conta
salary	Booleano	Se e salario
benefit	Booleano	Se e beneficio
commission	Booleano	Se e comissao

Conciliacao Bancaria

Campo	Tipo	Descricao
reconciliated	Booleano	Se foi conciliado
bank_reconciliation_transaction_id	Referencia	Transacao do extrato
before_reconciliate_status	Texto	Status antes da conciliacao
created_from_bank_reconciliation	Booleano	Se criado via conciliacao

Relacionamentos

Pertence a

Entidade	Obrigatorio	Descricao
Account	Sim	Conta do petshop
Store	Nao	Filial
FinancialAccount	Condicional	Conta bancaria
CreditCard	Condicional	Cartao de credito
PaymentMethod	Condicional	Metodo de pagamento
FinancialCategory	Sim	Categoria
FinancialCostCenter	Nao	Centro de custo
Customer	Nao	Cliente (receitas)
Provider	Nao	Fornecedor (despesas)
Sale	Nao	Venda associada
Checkout	Nao	Checkout associado
Payment	Nao	Pagamento associado
FinancialInvoice	Nao	Fatura associada
FinancialTransfer	Nao	Transferencia associada

Possui

Entidade	Descricao
CostCenterAllocations	Rateio por centro de custo
TransactionInvoice	Transacao de fatura espelhada

Tipos de Transacao

Expense (Despesa)

• Saida de dinheiro
• signal_value negativo
• Exemplos: compras, salarios, contas

Revenue (Receita)

• Entrada de dinheiro
• signal_value positivo
• Exemplos: vendas, recebimentos

Ciclo de Vida (Status)

Transicao Automatica para Paid

Quando payment_account e:

• credit: Status automaticamente vira "paid"
• payment_method: Status automaticamente vira "paid"

Frequencia de Pagamento

one_time (Unico)

• Transacao unica
• Sem recorrencia

fixed (Recorrente)

installment (Parcelado)

Frequencias Disponiveis

Frequencia	Descricao
daily	Diario
weekly	Semanal
biweekly	Quinzenal
monthly	Mensal
bimonthly	Bimestral
quarterly	Trimestral
half_yearly	Semestral
yearly	Anual

Atualizacao de Series

Opcoes (frequency_update)

Opcao	Descricao
update_only	Atualiza apenas esta transacao
update_next	Atualiza esta e futuras
update_all	Atualiza toda a serie

Campos Propagados

• name, value, type
• payment_account, financial_account_id, etc.
• financial_category_id
• cost_center_allocations
• Datas (recalculadas)

Conta de Pagamento

financial_account (Conta Bancaria)

• Status editavel (pending/paid)
• Suporta conciliacao bancaria
• Afeta saldo da conta

credit (Cartao de Credito)

• Status automaticamente "paid"
• Gera ou vincula FinancialInvoice
• Calculado na fatura do cartao

payment_method (Metodo de Pagamento)

• Status automaticamente "paid"
• Aplica taxas do metodo
• Gera fatura do metodo

Geracao de Faturas

Cartao de Credito

Metodo de Pagamento

Rateio de Centros de Custo

Modo Simples

• Um financial_cost_center_id por transacao
• 100% para um centro de custo

Modo Rateio (use_cost_center_allocation)

Validacao

• Soma dos percentuais deve ser exatamente 100%
• Valores calculados automaticamente

Conciliacao Bancaria

Processo

1. Importar extrato bancario
2. Sistema cria BankReconciliationTransaction
3. Vincular transacao existente ou criar nova
4. Transacao marcada como "paid" e "reconciliated"

Desfazer Conciliacao

• Se criada via conciliacao: transacao e destruida
• Se existia antes: volta para status anterior

Transferencias

Caracteristicas

• Marcada com is_transfer = true
• Vinculada a FinancialTransfer
• Status sincronizado entre as transacoes da transferencia

Tipos

Transacao	Tipo	Conta
Saida	expense	Conta origem
Entrada	revenue	Conta destino

Calculos Automaticos

signal_value

Se type = "expense": signal_value = value * -1
Se type = "revenue": signal_value = value

discount_value

Se status = "paid" e paid_value < value:
  discount_value = (value - paid_value) * -1

tax_value

Se status = "paid" e paid_value > value:
  tax_value = paid_value - value

final_date

Se status = "paid": final_date = paid_date
Senao: final_date = date

Validacoes

Campo	Regra
name	Obrigatorio
value	Obrigatorio, diferente de zero
type	Deve ser "expense" ou "revenue"
status	Deve ser "pending" ou "paid"
paid_date	Obrigatorio se status = "paid"
paid_value	Obrigatorio se status = "paid"
financial_account	Obrigatorio se payment_account = "financial_account"
credit_card	Obrigatorio se payment_account = "credit"
payment_method	Obrigatorio se payment_account = "payment_method"
frequency_end_date	Maximo 5 anos apos date
cost_center_allocations	Soma = 100%

Automacoes

Ao Criar

1. Define financial_parent_reference (se recorrente)
2. Gera parcelas/recorrencias
3. Vincula conciliacao bancaria (se aplicavel)
4. Resolve divergencia de caixa (se aplicavel)

Ao Atualizar

1. Propaga alteracoes para serie (se frequency_update != "update_only")
2. Sincroniza status de transferencia
3. Atualiza voucher/pagamento
4. Recalcula fatura

Ao Salvar

1. Calcula signal_value, discount_value, tax_value
2. Atualiza saldo da conta
3. Atualiza valor da fatura

Escopos

Escopo	Descricao
only_accounts	Apenas payment_account = "financial_account"
expenses	Apenas type = "expense"
revenues	Apenas type = "revenue"
pending	Apenas status = "pending"
paid	Apenas status = "paid"
not_reconciliated	Nao conciliadas
only_invoices	Apenas faturas
not_invoices	Exceto faturas

Restricoes de Edicao

Tipo	Restricao
initial_balance	Nao pode editar/excluir
is_transfer	Nao pode editar/excluir individualmente
is_voucher	Nao pode excluir
is_invoice	Nao pode editar (somente leitura)
frequency	Nao pode alterar apos criacao

Permissoes

Acao	Descricao
Criar	Criar nova transacao
Editar	Alterar transacao (com restricoes)
Excluir	Excluir transacao (com restricoes)
Pagar	Marcar como pago
Desfazer pagamento	Voltar para pendente
Reconciliar	Vincular ao extrato