NEPHE TIGER EVOLUTION — NEPHE TIGER PAY ETAPA 2 — MOTOR FINANCEIRO E COBRANÇAS Continuando o módulo NEPHE TIGER PAY criado na etapa anterior, agora quero implementar o segundo estágio: o MOTOR FINANCEIRO E DE COBRANÇAS. IMPORTANTE: - NÃO reconstruir o Nephe Tiger Evolution. - NÃO apagar funcionalidades existentes. - NÃO duplicar cadastro de clientes, estoque ou financeiro. - NÃO criar banco, gateway ou instituição financeira fictícia. - NÃO considerar pagamentos fictícios como reais. - NÃO implementar ainda bloqueio do aparelho. - Criar a arquitetura preparada para integração com um provedor financeiro real posteriormente. Antes de modificar qualquer coisa, analise o que foi criado na etapa anterior e reutilize toda a estrutura existente. --- 1. MOTOR DE PARCELAS Cada contrato ativo deverá possuir um cronograma financeiro completo. Para cada parcela armazenar: - ID; - Contrato; - Número da parcela; - Data de vencimento; - Valor original; - Desconto; - Juros; - Multa; - Encargos; - Valor atualizado; - Status; - Data de pagamento; - Forma de pagamento; - ID da transação externa; - Data de criação; - Data de atualização. Status: - PENDENTE - VENCENDO - PAGA - ATRASADA - NEGOCIADA - CANCELADA O status deve ser atualizado automaticamente de acordo com as datas e pagamentos confirmados. --- 2. CÁLCULO DE ATRASO Criar uma camada de cálculo financeiro configurável. Não deixar valores de multa e juros fixos diretamente no frontend. Criar configurações para: - Multa; - Juros por dia; - Juros mensal; - Dias de tolerância; - Regras de atualização; - Desconto para pagamento antecipado. As regras deverão poder ser alteradas por administrador autorizado. Registrar no histórico quando uma parcela tiver seu valor atualizado. --- 3. CENTRAL DE PAGAMENTOS Criar uma tela: PAGAMENTOS Filtros: - Todos; - Pendentes; - Pagos; - Atrasados; - Cancelados; - Hoje; - Este mês; - Período personalizado. Colunas: - Contrato; - Cliente; - Parcela; - Vencimento; - Valor; - Status; - Forma de pagamento; - Data de pagamento; - ID da transação. Criar busca por: - Nome; - CPF; - Número do contrato; - IMEI; - ID da transação. --- 4. ESTRUTURA PARA PIX Criar uma camada de abstração para cobrança Pix. Cada cobrança deverá poder armazenar: - Provider; - External Charge ID; - TXID; - Valor; - Expiração; - QR Code; - Pix Copia e Cola; - Status; - Data de criação; - Data de pagamento; - Data de expiração. Status: - CREATED - PENDING - PAID - EXPIRED - CANCELLED - FAILED IMPORTANTE: Ainda NÃO conectar a um banco específico. Criar uma interface de serviço semelhante a: PaymentProvider com métodos preparados para: - createPixCharge() - getPixCharge() - cancelPixCharge() - createBoleto() - getBoleto() - cancelBoleto() A implementação real do provedor será adicionada posteriormente. --- 5. ESTRUTURA PARA BOLETO Preparar o sistema para boleto bancário. Cada boleto deverá possuir: - ID interno; - Provider; - ID externo; - Nosso número; - Código de barras; - Linha digitável; - PDF/URL; - Valor; - Data de emissão; - Data de vencimento; - Status; - Data de pagamento. Status: - CREATED - REGISTERED - PENDING - PAID - EXPIRED - CANCELLED - FAILED NÃO gerar códigos de barras fictícios. Enquanto não existir provedor configurado, mostrar: "Provedor de pagamento não configurado." --- 6. WEBHOOKS Criar estrutura segura para receber eventos de pagamento de um provedor externo. Criar endpoint preparado para: PAYMENT_CREATED PAYMENT_UPDATED PAYMENT_PAID PAYMENT_FAILED PAYMENT_EXPIRED PAYMENT_CANCELLED O webhook deverá: 1. Receber evento; 2. Validar autenticação/assinatura quando o provedor fornecer; 3. Identificar a transação; 4. Localizar a parcela; 5. Verificar idempotência; 6. Atualizar o pagamento; 7. Atualizar a parcela; 8. Atualizar o contrato; 9. Registrar auditoria. IMPORTANTE: O mesmo webhook enviado duas vezes NÃO pode gerar dois pagamentos. Implementar controle de idempotência. --- 7. CONFIRMAÇÃO DE PAGAMENTO Apenas um evento financeiro validado deve alterar: PENDENTE → PAGA Nunca permitir que o frontend simplesmente envie: "marcar como paga" para uma parcela. Para pagamentos manuais autorizados pelo administrador, exigir: - Motivo; - Usuário; - Data; - Observação; - Registro de auditoria. --- 8. CENTRAL DE COBRANÇA Criar uma nova tela: COBRANÇAS Mostrar: - Cliente; - Contrato; - Parcela; - Vencimento; - Dias em atraso; - Valor original; - Valor atualizado; - Status; - Última cobrança; - Próxima ação. Filtros: - Vence hoje; - Vence amanhã; - Vence em 3 dias; - Vence em 7 dias; - Vencidas; - 1–7 dias atrasadas; - 8–15 dias; - 16–30 dias; - Mais de 30 dias. --- 9. LINHA DO TEMPO DO CLIENTE Dentro do contrato criar uma timeline: Exemplo: 24/08 — Contrato criado 24/08 — Parcela 01 gerada 24/08 — Pix criado 25/08 — Cliente recebeu cobrança 05/09 — Parcela venceu 06/09 — Parcela entrou em atraso 07/09 — Cliente recebeu aviso 10/09 — Pagamento confirmado 10/09 — Parcela regularizada Todas essas ações devem ficar registradas. --- 10. NOTIFICAÇÕES Criar estrutura para futuramente enviar: - E-mail; - WhatsApp; - SMS; - Push notification. Criar templates configuráveis. Tipos: PRÉ-VENCIMENTO "Olá, {cliente}. Sua parcela do Nephe Tiger Pay vence em {data}." VENCIMENTO "Sua parcela vence hoje." ATRASO "Identificamos uma parcela em atraso." PAGAMENTO CONFIRMADO "Pagamento confirmado." Não conectar WhatsApp ou SMS ainda. Criar somente a arquitetura. --- 11. SEGUNDA VIA Dentro da parcela: Se boleto estiver disponível: [ GERAR SEGUNDA VIA ] Se Pix estiver disponível: [ GERAR NOVO PIX ] Se já estiver pago: mostrar: "Parcela paga." Não permitir gerar nova cobrança para uma parcela já quitada sem uma regra explícita. --- 12. NEGOCIAÇÃO Preparar estrutura para negociação. Criar opção: NEGOCIAR PARCELA Futuramente poderá permitir: - Nova data; - Desconto; - Juros; - Multa; - Parcelamento do atraso; - Entrada; - Novo cronograma. Criar entidade/histórico de negociação. Não permitir alteração silenciosa da dívida. Toda negociação deve gerar: - ID; - Usuário; - Data; - Valores anteriores; - Novos valores; - Motivo; - Status. --- 13. CONCILIAÇÃO Criar tela: CONCILIAÇÃO FINANCEIRA Preparar estrutura para comparar: TRANSAÇÕES DO PROVEDOR versus PARCELAS DO NEPHE TIGER PAY Mostrar: - Conciliado; - Pendente; - Divergente; - Sem correspondência. Isso será importante quando conectarmos o primeiro provedor real. --- 14. DASHBOARD FINANCEIRO Atualizar o dashboard do Nephe Tiger Pay com: RECEBIMENTOS Hoje Semana Mês Período personalizado A RECEBER Próximos 7 dias Próximos 30 dias Total da carteira INADIMPLÊNCIA Valor em atraso Quantidade de parcelas Quantidade de clientes Percentual da carteira PAGAMENTOS Pix Boleto Outros --- 15. AUDITORIA Toda operação financeira crítica deve gerar log. Registrar: - Usuário; - Data/hora; - IP quando disponível; - Ação; - Contrato; - Parcela; - Valor anterior; - Valor novo; - Origem da ação; - Resultado. Exemplos: PAYMENT_CREATED PAYMENT_CONFIRMED PAYMENT_CANCELLED INSTALLMENT_UPDATED INSTALLMENT_PAID CONTRACT_UPDATED NEGOTIATION_CREATED MANUAL_PAYMENT_REGISTERED --- 16. SEGURANÇA Toda operação financeira deverá ocorrer no backend. Não confiar em valores enviados pelo frontend. Validar no servidor: - Usuário; - Permissão; - Contrato; - Parcela; - Valores; - Status; - Transação; - Idempotência. Nunca armazenar segredo de API no frontend. As credenciais de futuros provedores deverão ficar somente em ambiente seguro/server-side. --- 17. PREPARAÇÃO PARA O FUTURO DEVICE CONTROL NÃO implementar bloqueio nesta etapa. Porém, manter a relação: CONTRATO ↓ CONTRACT_DEVICE ↓ IMEI ↓ DEVICE_ID Quando uma parcela entrar em atraso, o sistema deverá apenas atualizar o status financeiro. Exemplo: CONTRACT_STATUS = EM_ATRASO Não executar nenhuma ação no aparelho. O módulo Device Control será desenvolvido em uma etapa posterior e independente. --- 18. REGRAS DE INTEGRIDADE Criar regras para impedir: - Dois pagamentos para a mesma parcela; - Dois contratos ativos para o mesmo IMEI; - Parcela paga duas vezes; - Alteração de contrato quitado sem autorização; - Exclusão de transações financeiras; - Exclusão de logs de auditoria; - Alteração de valores sem histórico. Preferir: CANCELAMENTO / ESTORNO / INATIVAÇÃO em vez de exclusão definitiva de dados financeiros. --- 19. RESULTADO ESPERADO Ao terminar esta etapa, quero conseguir: 1. Criar uma contratação; 2. Gerar automaticamente as parcelas; 3. Visualizar vencimentos; 4. Identificar atrasos; 5. Visualizar o valor atualizado; 6. Criar uma cobrança Pix preparada; 7. Criar um boleto preparado; 8. Receber futuramente confirmação por webhook; 9. Dar baixa automaticamente; 10. Registrar toda a operação; 11. Visualizar a carteira financeira; 12. Visualizar a inadimplência; 13. Preparar negociação; 14. Preparar conciliação. NÃO criar pagamentos fictícios. NÃO conectar banco fictício. NÃO implementar bloqueio de aparelho ainda. Ao terminar, apresente: - Estrutura do banco; - Novas tabelas; - APIs/endpoints; - Serviços criados; - Regras de negócio; - Permissões; - Webhooks; - Status financeiros; - O que está pronto; - O que depende do provedor financeiro real; - O que ficará para a próxima etapa.