Bug na projeção de saldo: agregados inconsistentes e possível dupla contagem

Identifiquei inconsistências entre os valores exibidos na projeção de saldo e os dados retornados pelos componentes usados para construí-la.

Não estou incluindo valores reais porque este ticket é público, mas consigo fornecer dados específicos de forma privada se necessário.

1. Recorrências: summary diverge dos itens retornados

Ao consultar as recorrências de um mês futuro, a resposta contém:

summary.total_expected = X
sum(patterns[].amount) = Y

Porém:

X != Y

A diferença é material, não apenas arredondamento.

Curiosamente, a interface de projeção parece utilizar um valor próximo de sum(patterns[].amount), enquanto outros consumidores do endpoint podem utilizar summary.total_expected.

Isso pode gerar projeções significativamente diferentes dependendo de qual campo é utilizado.

Comportamento esperado

O seguinte invariante deveria sempre ser verdadeiro, salvo se o summary incluir explicitamente componentes adicionais documentados:

summary.total_expected == sum(patterns[].amount)

Caso existam valores adicionais no summary, eles deveriam ser retornados separadamente e documentados.

2. Fatura com vencimento no mês projetado

Existe uma fatura de cartão:

due_date = mês projetado
remaining > 0

Essa fatura contém componentes como:

installments_total
recurring_total
onetime_total
credits_total

Compras realizadas no mês anterior, mas presentes nessa fatura, só afetam o caixa no mês em que a fatura será paga.

Portanto, uma projeção de saldo bancário futuro deveria considerar o vencimento da fatura, e não apenas a data original das compras.

Exemplo conceitual

Uma compra à vista no crédito feita em agosto:

purchase_date = agosto
bill_due_date = setembro

deveria afetar:

cashflow setembro

e não:

cashflow agosto

3. Possível dupla contagem entre fatura, recorrências e parcelamentos

Parte das recorrências e parcelas já está embutida na própria fatura.

Portanto, esta lógica seria incorreta:

saldo
+ receitas
- fatura inteira
- todas as recorrências
- todas as parcelas

porque parcelas e recorrências presentes na fatura seriam descontadas duas vezes.

A lógica esperada para fluxo de caixa seria aproximadamente:

saldo bancário atual
+ receitas que entram no mês
- faturas com vencimento no mês
- recorrências pagas fora dessas faturas
- outros compromissos que efetivamente saem da conta no mês

4. Parcelamentos apresentam totais diferentes dependendo da fonte

Para o mesmo mês, existem diferenças entre:

valor de "Parcelamentos" exibido na projeção
summary.total_monthly_cost dos installment plans
installments_total da fatura que vence naquele mês

Entendo que esses valores possam representar conceitos diferentes.

Porém, seria importante documentar claramente:

• qual valor é usado na projeção;

• como uma parcela é associada ao mês de pagamento;

• como parcelas já incluídas em uma fatura são deduplicadas;

• se o cálculo considera a data da transação, data da parcela ou vencimento da fatura.

5. Bucket "A confirmar"

A projeção possui um bucket chamado:

A confirmar

Não ficou claro quais transações entram nesse valor.

Em particular, seria importante esclarecer se compras à vista no cartão que:

já foram sincronizadas
já pertencem a uma fatura aberta
e possuem vencimento no mês projetado

ainda entram em A confirmar ou são contabilizadas de outra forma.

Comportamento esperado

Para uma projeção cujo objetivo seja responder:

"Quanto dinheiro haverá nas minhas contas bancárias ao final deste mês?"

eu esperaria uma lógica baseada em cash flow / data efetiva de pagamento:

projected_balance =
    current_bank_balance
    + inflows_due_in_period
    - credit_card_bills_due_in_period
    - non-card recurring_outflows_due_in_period
    - other_cash_outflows_due_in_period

Com as seguintes garantias:

• compras no cartão entram no mês de pagamento da fatura;

• somente a parcela correspondente ao mês é considerada;

• parcelas futuras não afetam o mês atual;

• recorrências já contidas em uma fatura não são descontadas novamente;

• compras à vista já contidas na fatura não são somadas novamente;

• agregados são reconciliáveis com seus componentes;

• qualquer valor "estimado" ou "a confirmar" possui composição auditável.

Sugestão

Seria útil existir um breakdown/debug da projeção mostrando, para cada componente:

source
transaction/pattern/bill id
amount
effective_cashflow_date
classification
included_in_bill
projection_bucket

Isso facilitaria bastante validar a projeção e identificar dupla contagem ou itens ausentes.