R-008 — Resumo financeiro do cliente

TLDR: como são calculados os números do cliente: valor original das parcelas dos débitos em andamento, com defaulted contando como vencida. A listagem (GET /api/v1/customers) e o detalhe (GET /api/v1/customers/:id) devolvem o mesmo payload, com summary.

Regras

Regra Decisão
Valor usado Valor original da parcela (amount_cents). Juros e desconto não entram.
Débitos considerados Só os em andamento: pending, no_forecast, no_response, bureau_report, negativated. cancelled e negotiated ficam de fora.
Vencidas Parcelas overdue e defaulted.
Pagas Parcelas paid.
A vencer Parcelas upcoming.
Total de parcelas Vencidas + pagas + a vencer.
Dívida total (total_debt_amount_cents) Soma do valor de todas as parcelas consideradas.
Total pago Valor das pagas.
Em aberto (unpaid_debt_amount_cents) Dívida total − Total pago (= vencidas + a vencer). Sai só fora do summary.
Próx. vencimento (next_due_installment) A parcela upcoming de menor due_on: data e valor original. Se mais de uma vence nessa data, o valor é a soma delas. Sem parcela a vencer, null.

Sem débitos em andamento, todas as contagens e valores são 0 e next_due_installment é null.

Campos do cliente (GET /api/v1/customers e GET /api/v1/customers/:id)

Coluna do front Campo Regra
Sit. financeira financial_status Derivada dos débitos e parcelas do cliente pela tabela abaixo.
Responsável collaborator Nome do user ligado ao cliente; null se não houver.
Cursos/Produtos products product_name dos produtos de todos os débitos do cliente, sem repetir, em ordem alfabética.
Em aberto unpaid_debt_amount_cents Mesma regra de “Em aberto” acima.

financial_status — a primeira linha que bater vale:

Ordem Valor Rótulo no front Quando
1 negativated NEGATIVADO Algum débito negativated.
2 overdue EM ATRASO Alguma parcela overdue ou defaulted em débito ativo (pending, no_forecast, no_response, bureau_report).
3 cancelled CANCELADO Tem débitos e todos estão cancelled.
4 up_to_date EM DIA Qualquer outro caso, inclusive cliente sem débitos e cliente com débito em cobrança sem parcela vencida.

Onde está no código

  • modules/backend/app/serializers/customer_serializer.rb (financial_status, products, collaborator, unpaid_debt_amount_cents, summary; mesmo payload na listagem e no detalhe)
  • Testes: modules/backend/test/serializers/customer_serializer_test.rb e modules/backend/test/controllers/api/v1/customers_controller_test.rb