BK-248 - Carteira de creditos do cliente com saldo blue e saldo red

Objetivo

Documentar a regra de negocio, arquitetura e trilha de implementacao da nova carteira de creditos do cliente final do Rio no Teatro.

Esta frente e diferente do modulo ja existente de creditos de divulgacao para cliente-produtor.

Escopo desta rodada

• consolidar a nomenclatura saldo blue e saldo red
• registrar o que o cliente ve e o que o admin ve
• fechar a semantica de consumo, credito e estorno
• atualizar os docs canonicos (BACKLOG, SISTEMA_CREDITOS, ARCHITECTURE, sitemap)
• criar um doc tecnico detalhado proprio da carteira do cliente
• deixar a trilha pronta para futura implementacao sem fingir que a estrutura de banco ja existe

Decisoes de negocio validadas

Visibilidade por perfil

• cliente final ve apenas saldo total
• admin ve:
• saldo total
• saldo blue
• saldo red
• extrato detalhado por movimentacao, origem e regra de estorno

Semantica dos saldos

• saldo blue
• credito estornavel em 100%
• nasce quando o credito existe por responsabilidade da producao/plataforma, e nao por vontade do cliente

• saldo red
• credito usavel normalmente para comprar ingressos no site
• se o cliente pedir estorno, sofre taxa de 20% sobre o saldo red remanescente no momento do saque
• nasce sempre que o valor foi parar na carteira por iniciativa, escolha ou responsabilidade economica do proprio cliente

Regras de origem

• compra direta de credito pelo cliente:
• entra como saldo red

• cancelamento do pedido por iniciativa do cliente, dentro do prazo:
• o valor convertido para carteira entra todo como saldo red

• cancelamento da peca/sessao por culpa da producao:
• se o cliente aceitar credito em vez de estorno imediato, esse valor entra como saldo blue

Regras de consumo

• toda compra futura consome primeiro saldo blue
• depois consome saldo red
• dentro de cada natureza, consome o lote mais antigo primeiro
• a carteira pode ser usada parcialmente:
• se o pedido custa mais que o saldo disponivel, o cliente usa o saldo e complementa a diferenca no checkout

Regras de estorno

• estorno de saldo blue:
• devolucao integral de 100%

• estorno de saldo red:
• desconto de 20% sobre o valor red remanescente que o cliente estiver sacando naquele momento
• a taxa nao continua presa ao valor historico original se parte do saldo ja foi consumida
• a taxa incide sobre o valor pedido para saque naquele momento

Regra operacional de cancelamento e validacao

• o cliente nao cancela a compra sozinho em definitivo
• o cliente apenas solicita o cancelamento
• essa solicitacao continua condicionada a janela operacional valida, hoje ate 3 horas antes da sessao comprada
• o admin e quem valida o desfecho do caso
• antes de concluir estorno em dinheiro, o admin deve confirmar com o cliente que ele esta ciente da taxa de 20% quando houver saldo red
• so depois dessa confirmacao o admin decide se o caso vira:
• estorno financeiro
• manutencao do valor como credito
• por isso, o ledger da carteira nao deve assumir estorno automatico apenas porque o cliente solicitou cancelamento
• na visao do cliente, o extrato nao deve mostrar admin validou
• para o cliente, o item do extrato deve refletir o momento em que ele clicou para solicitar o cancelamento
• formato alvo desse item no extrato do cliente:
• {data do clique} {hora do clique} - {nome do evento} - {sessao do evento} - {quantidade de ingressos} x {valor do ingresso} | {valor total do cancelamento}

Exemplos validados

Exemplo 1 - cancelamento do cliente

• pedido original: R$100
• cliente opta por manter como credito
• carteira resultante:
• saldo blue = 0
• saldo red = 100

Se depois gastar R$25:

• carteira resultante:
• saldo blue = 0
• saldo red = 75

Se depois pedir estorno desses R$75:

• taxa de 20% sobre R$75

Exemplo 2 - mistura de saldos

• cliente tem:
• saldo blue = 50
• saldo red = 10

• compra de R$25

Consumo correto:

• primeiro sai R$25 do saldo blue
• carteira fica:
• saldo blue = 25
• saldo red = 10

Exemplo 3 - cancelamento da producao apos compra com saldo misto

• cliente tinha saldo blue = 50 e saldo red = 10
• compra ingresso de R$20
• depois a peca e cancelada pela producao

Regra:

• o valor devolvido por esse cancelamento volta como saldo blue
• a natureza do novo credito depende da origem do evento de devolucao, nao do saldo historico usado na compra anterior

Estrutura funcional alvo

Tela do cliente

• pagina Meus Creditos
• mostra apenas:
• saldo total
• extrato amigavel com origem e movimentacoes
• nao exibe a classificacao blue/red

Tela/admin

• extrato do cliente com:
• saldo total
• saldo blue
• saldo red
• origem de cada entrada
• consumo por pedido
• estornos executados
• estornos ainda possiveis
• observacao operacional para atendimento

Modelo de dados alvo

O sistema nao deve depender de um unico campo de saldo.

A arquitetura alvo precisa de ledger/extrato transacional para guardar, no minimo:

• id do cliente
• tipo da movimentacao
• origem da movimentacao
• natureza do saldo gerado (blue ou red)
• valor de entrada
• valor consumido
• valor remanescente por lote/origem
• referencia ao pedido/cancelamento/acao administrativa
• elegibilidade de estorno
• taxa aplicavel no saque
• timestamps operacionais

Documento tecnico detalhado desta rodada

• docs/documentacao_tecnica/creditos/CARTEIRA_CREDITOS_CLIENTE.md
• docs/documentacao_tecnica/creditos/MODELO_DADOS_CARTEIRA_CLIENTE.md
• docs/documentacao_tecnica/creditos/TELA_CLIENTE_MEUS_CREDITOS.md
• docs/documentacao_tecnica/creditos/FLUXO_ADMIN_EXTRATO_ATENDIMENTO.md

Esses documentos passam a concentrar:

• arquitetura detalhada da carteira
• modelo de dados alvo com ledger, consumo e estorno
• tela do cliente Meus Creditos
• visao admin de extrato, atendimento e simulacao de estorno

Lacunas ainda abertas

• expiracao da carteira do cliente: ainda sem regra final
• tratamento de chargeback e rollback de estorno: ainda sem regra final
• estorno direto pelo cliente vs atendimento/admin: ainda sem regra final
• estorno parcial vs integral como fluxo padrao do admin: ainda sem regra final

Observacao operacional para atendimento

• por padrao comercial, o time deve sempre priorizar a opcao de manter o valor como credito para novas compras
• a opcao de estorno deve continuar disponivel quando o cliente preferir sacar ou quando o contexto operacional exigir
• no fluxo atual, o cliente solicita o cancelamento e o admin valida a conclusao apos confirmar a ciencia da taxa quando houver saldo red
• internamente, saldo blue e saldo red servem para orientar o admin; para o cliente, a experiencia continua centrada em saldo total

Primeiro recorte de codigo implementado em 2026-04-09

Escopo real desta primeira entrega tecnica:

• arquivo SQL novo SQL/V2026/20260409_bk248_cliente_carteira_base.sql
• schema inicial para:
• tb_cliente_credito_ledger
• tb_cliente_credito_consumo
• tb_cliente_carteira_resumo
• helper novo config/functions_cliente_carteira.php para leitura segura de:
• resumo da carteira do cliente
• extrato simplificado
• fallback para saldo 0 quando a base ainda nao estiver aplicada
• modulo novo painel/modulos/carteira/
• tela Meus Creditos para o cliente final
• exibicao apenas de saldo total
• extrato simplificado com linguagem amigavel
• integracao inicial no painel:
• card Meus Creditos no dashboard do cliente
• item Meus Creditos no menu lateral

Este recorte NAO mexe ainda no checkout nem no cancelamento operacional. Ele estabelece a base real de leitura sem colidir com o modulo antigo painel/modulos/creditos, que continua sendo credito de divulgacao do cliente-produtor.

Segundo recorte de codigo implementado em 2026-04-09

Escopo real desta segunda entrega tecnica:

• o helper config/functions_cliente_carteira.php passou a ter trilha real de escrita e manutencao de saldo:
• rnt_cliente_carteira_registrar_credito(...)
• rnt_cliente_carteira_recalcular_resumo(...)
• idempotencia basica por tipo_movimentacao + referencia_tipo + referencia_id + id_cliente
• o admin do cliente agora consegue auditar a carteira em:
• admin/modulos/clientes/detalhe.php
• a nova aba Carteira Cliente mostra:
• saldo total
• saldo blue
• saldo red
• extrato tecnico das ultimas movimentacoes
• o bootstrap do admin de clientes passou a incluir o helper da carteira

Este recorte ainda NAO liga a escrita do ledger aos fluxos vivos de cancelamento e compra. Ele prepara a camada transacional e a auditoria admin antes de acoplar a carteira aos pedidos, respeitando a regra de que o cliente apenas solicita cancelamento e o admin valida o desfecho.

Terceiro recorte de codigo implementado em 2026-04-09

Escopo real desta terceira entrega tecnica:

• o clique de solicitacao de cancelamento no cliente agora pode ser persistido em metadado canonico do pedido
• config/functions_new.php ganhou rnt_order_capture_cancel_request_meta(...)
• esse snapshot guarda:
• data e hora do clique da solicitacao
• nome do evento
• sessao do evento
• quantidade de ingressos
• valor unitario
• valor total do cancelamento
• config/functions_cliente_carteira.php passou a reutilizar esse snapshot para renderizar a descricao amigavel do extrato do cliente quando a linha da carteira nascer de cancelamento
• painel/modulos/pedidos/action.php passou a salvar esse snapshot no momento da solicitacao do cliente

Este recorte ainda nao escreve o ledger automaticamente no cancelamento. Ele prepara a fonte de verdade do texto que o cliente devera enxergar no extrato, ancorada no momento do clique da solicitacao e nao na validacao admin.

Proximos passos sugeridos

1. ligar a geracao de linhas em tb_cliente_credito_ledger aos fluxos vivos somente depois da validacao admin do desfecho do cancelamento
2. implementar o consumo em compra respeitando blue antes de red e FIFO por lote
3. ligar tb_cliente_credito_consumo ao fechamento do pedido quando a carteira for usada
4. abrir a visao admin de simulacao de estorno em cima do saldo atual do cliente
5. decidir como a tela do cliente vai expor pedido de estorno, ou se isso ficara apenas no atendimento/admin

Handoff operacional em 2026-04-10

O que ficou concluido nesta rodada

• saldo do cliente e saldo do produtor foram unificados na trilha operacional viva
• checkout checkout_pix.php passou a aceitar:
• SALDO RNT
• saldo + PIX
• saldo + cartao
• compra 100% com saldo fecha como status_transacao = 3 e grava uso da carteira
• cancelamento com escolha credito passou a virar saldo direto para o cliente, sem depender de aprovacao admin
• cancelamento com escolha estorno passou a marcar o pedido como pedido_cancelar = 1 com preferencia de estorno
• painel de pedidos passou a exibir:
• Virou credito
• Estorno Solicitado
• ids visiveis nos cards
• ordenacao por id decrescente
• extrato e carteira do cliente passaram a refletir corretamente os valores totais de pedidos com qtd > 1
• historicos antigos errados da cliente 50877 foram corrigidos no banco para os pedidos:
• 73716
• 73718
• 73720
• admin de clientes passou a ter simulacao operacional de estorno sobre o saldo atual
• menu mobile publico/logado ganhou:
• mais links
• drawer dark
• largura full screen

O que ainda falta fazer amanha

• fechar o fluxo admin de estorno ponta a ponta:
• acao administrativa apos Estorno Solicitado
• status final do pedido depois do estorno real
• trilha transacional correspondente no ledger quando o caso nao virar saldo
• revisar se o admin deve conseguir executar devolvida diretamente da carteira do cliente ou apenas de pedidos_2
• consolidar a regra de loop de cancelamento recompra para bloquear cancelou -> recomprou -> tentou cancelar de novo em seguida
• revisar se os docs de creditos ainda falam em pontos desatualizados da fase blue/red que ja foram simplificados na operacao viva
• decidir se vale publicar changelog detalhado do BK-248 ja nesta rodada ou somente quando o fluxo admin de estorno estiver fechado