Credit Lifecycle

O ciclo de crédito usa quatro conceitos:

• CompanyCreditPurchase registra a compra de crédito feita pela Company para uma Cooperative.
• CompanyCreditAccount guarda o saldo corporativo disponível para distribuição.
• CreditGrant guarda o estado consolidado do crédito concedido ao Customer.
• CreditLedgerEntry guarda cada movimento de forma append-only.

​

Compra de saldo corporativo

A compra de saldo é feita pela Company para uma Cooperative escolhida. Ela usa a configuração ativa de billing dessa Cooperative e não cria Ticket.

​

Concessão e uso do crédito

​

Movimentos

​

Regras

• payment.status = PAID com CompanyCreditPurchase.creditedAt = null é a única origem de aumento de saldo comprado da Company.
• CompanyCreditAccount é posição consolidada; histórico de compra fica em CompanyCreditPurchase.
• CreditGrant só pode ser criado quando CompanyCreditAccount possui availableAmount suficiente.
• customerId é obrigatório.
• O crédito pode ser usado em tickets de qualquer cooperativa.
• O uso definitivo do crédito é sempre por ticketId.
• CAPTURE e REFUND devem preencher ticketId.
• cooperativeId e transportOperatorId entram no ledger como contexto do Ticket usado.
• O valor nunca pode ficar negativo.
• availableAmount + reservedAmount + usedAmount não pode ultrapassar amount.
• Retry de movimentos críticos deve usar idempotência.
• Ledger não é editado nem removido.
• Estorno retorna para o mesmo CreditGrant, Customer e Company que concedeu o crédito.

​

Compra e distribuição pela Company

1. Company lista e escolhe uma Cooperative disponível.
2. OPS resolve a configuração ativa de billing da Cooperative.
3. OPS cria a cobrança no gateway e persiste Payment + CompanyCreditPurchase.
4. O frontend acompanha payment.status pelo detalhe da compra.
5. Quando o Payment fica PAID, o valor entra em CompanyCreditAccount e creditedAt é preenchido.
6. Company seleciona um usuário elegível.
7. O sistema resolve ou cria automaticamente o Customer desse usuário.
8. Company cria CreditGrant para o Customer.
9. CompanyCreditAccount reduz availableAmount e aumenta allocatedAmount.
10. O Customer usa o crédito em tickets.

​

Compra com crédito

1. Customer inicia checkout.
2. System encontra créditos ativos do Customer.
3. Customer informa quanto de crédito quer usar.
4. System reserva o valor no checkout.
5. Ao confirmar a compra, System distribui a captura nos tickets elegíveis.
6. Cada captura gera CreditLedgerEntry com ticketId.
7. Se o checkout falha, System libera a reserva.
8. Se um ticket é cancelado depois, System registra estorno para aquele ticket.

​

Checkout QR com crédito

No Checkout QR, o canal de venda pode selecionar paymentMethod = CREDIT_GRANT, mas a autorização do crédito pertence ao Customer no app do cliente.

1. Canal de venda cria CheckoutSession para uma Trip.
2. Customer autenticado escaneia o QR Code.
3. Customer app valida créditos ativos do Customer.
4. Customer autoriza o valor de crédito a usar.
5. System reserva o crédito para o checkout.
6. Ao confirmar a sessão, Sales cria Checkout, Order e Ticket.
7. Credit Grant captura o valor por Ticket em CreditLedgerEntry.
8. Se a sessão expira, cancela ou falha antes da confirmação, a reserva é liberada.

​

Relatórios e comprovantes

Departamento (Employee.department) pode ser usado como agrupamento de relatório quando a Company opera departamento como centro de custo. Centro de custo formal e independente ainda exigiria modelagem própria. Veja a modelagem em CreditGrant.