Pular para conteúdo

Análise de Crédito

O que é

A avaliação de crédito de um contato pelo analista da mesa — decidir aprovar, recusar ou enviar direto para CCB com base no Open Finance, score e demais dados do contato. Não é uma rota própria: é a aba ?tab=analise-credito&analise_id=… da ficha-do-contato (/contatos/:id), alcançada pelos atalhos ▶ (iniciar análise), 👁 (ver análise) e ＋ (criar proposta) do card da Mesa no kanban-comercial — todos abrem essa mesma aba em nova aba do navegador.

A aba mostra os relatórios de Open Finance do contato (rendas, contas, transações, débitos concorrentes, despesas recorrentes, risk insights) quando o provedor é Belvo; para Klavi (ou contato sem Open Finance) mostra um estado vazio apontando para o console Klavi — ver AnaliseCreditoSection.tsx. É sobre esses dados, mais o histórico/score do contato, que o analista decide.

O ciclo

  1. Mesa aberta — GarantirMesaAbertaUseCase garante que existe 1 análise ativa para o contato (contatos_mesa), criando ou reabrindo conforme o status anterior. Ver detalhe em mesa.
  2. Iniciar análise (▶, botão "Iniciar análise" no card sticky StickyAcoesAnalise) — IniciarAnaliseUseCase move a mesa para Analisando, grava analista_atual/ analista_atual_id (o analista que clicou vira o responsável) e emite analise.iniciada → o negocio espelha a etapa (Mesa → Em Análise). "Trava" o contato: só quem iniciou pode decidir (outro analista vê banner informativo, sem ação).
  3. Decidir (com a análise em Analisando e o analista logado = analista atual, o card sticky mostra 3 ações mutuamente exclusivas):
  4. Aprovar — abre o dialog EditPropostaDialog em modo criação (modoFinalizarAnalise) para criar a(s) proposta(s); "Salvar e Adicionar Nova" permite criar mais de uma proposta na mesma aprovação, mantendo o dialog aberto. Ao salvar, AprovarAnaliseUseCase registra a decisão (status = 'Aprovado', analista/analista_decisao) e emite analise.aprovada → o negócio vai para Comercial/Aguardando Apresentação. Ver proposta para o que acontece a partir daí no Kanban.
  5. Recusar — abre DialogRegistrarRecusa; RecusarAnaliseUseCase registra a recusa (motivo, analista) em recusados, muda a mesa para Negado e emite contatos-mesa.recusado → o negócio é arquivado no kanban-comercial. Como side-effect isolado (BullMQ, não bloqueia a recusa em si), agenda o envio de uma mensagem de recusa ao cliente via Chatwoot (com delay configurável — recusa manual é imediata; recusas automáticas costumam ter uma janela de revisão antes de notificar).
  6. Enviar para CCB — rota alternativa que pula a criação de proposta: EnviarParaCcbUseCase muda a mesa direto para Envio da CCB e emite analise.ccb → o negócio vai direto para Mesa F2/Cadastrar CCB. Usado quando a formalização já está decidida sem precisar do ciclo normal de proposta no Comercial.
  7. Um caso derivado do fluxo de aprovação: se o convênio escolhido na criação da proposta está inativo, ou os parâmetros de endividamento/comprometimento do convênio excedem o limite, o próprio dialog de proposta oferece recusar por esse motivo específico (Convênio inativo / Endividamento acima do limite / Comprometimento acima do limite), reaproveitando o mesmo RecusarAnaliseUseCase.
  8. Depois de decidir — a aba tenta fechar a própria janela (assumindo que foi aberta via window.open pelo board ou pela fila da Mesa); se o navegador não deixar, navega de volta para /credito/analise/em-analise.

O card sticky (StickyAcoesAnalise) decide qual dos 6 estados mostrar puramente a partir de contatos_mesa.status + analista_atual/analista_atual_id: sem análise válida (erro), Em análise (não iniciada), Analisando + sou eu (ações), Analisando + outro analista (banner), Aprovado/Negado (banner com decisão) e demais status (Pendência, Aguardando aceite, Envio da CCB — banner neutro).

Como se relaciona

  • negocio — o negócio referencia a análise por negocio.analise_id → contatos_mesa.id; cada evento do ciclo acima (analise.iniciada, analise.aprovada, contatos-mesa.recusado, analise.ccb) é o que move o negócio no kanban-comercial (ver mapa completo de eventos lá e em mesa).
  • proposta — N propostas nascem da mesma análise (analise_id compartilhado); a aprovação e a criação de proposta acontecem no mesmo dialog, mas são passos distintos (dá pra aprovar sem nunca ter passado por "Enviar para CCB", e vice-versa).
  • kanban-comercial — os atalhos ▶/👁/＋ do card da Mesa nesse board são a porta de entrada para esta aba; ver também pipe-e-etapa para as etapas de Mesa F1/F2 que os eventos acima destravam.

Regras de negócio

⚠️ A documentar. Esta tela ainda não tem as regras de negócio levantadas do código.

O que entra aqui: invariante (o que nunca pode acontecer), permissão (quem pode fazer o quê), bloqueio (o que impede a ação e a mensagem que o usuário vê), cálculo (fórmula e arredondamento) e efeito colateral (o que mais muda quando isso acontece).

Regra só entra aqui com origem no código — arquivo e linha. Regra que alguém "acha que é assim" é pior que seção vazia, porque vira decisão de produto baseada em memória.

Onde vive no código

  • API: apps/api-menos-juros/src/v2/mesa-analise/application/use-cases/
  • garantir-mesa-aberta.use-case.ts, iniciar-analise.use-case.ts, aprovar-analise.use-case.ts, recusar-analise.use-case.ts, enviar-para-ccb.use-case.ts, criar-proposta.use-case.ts.
  • Eventos: domain/events/{analise-iniciada,analise-aprovada,analise-ccb,contatos-mesa-recusado,contatos-mesa-criado,contatos-mesa-reaberta}.event.ts.
  • Controller: presentation/controllers/analise-transicao.controller.ts.
  • CRM: apps/crm-menos-juros/client/src/pages/contatos/central/components/AnaliseCreditoSection.tsx (relatórios de Open Finance) + analise-credito/StickyAcoesAnalise.tsx (as 6 branches de ação/estado) + components/EditPropostaDialog.tsx (criação de proposta em modo aprovação) + components/analises/DialogRegistrarRecusa.tsx + domains/mesa-analise/analises/hooks/{use-iniciar-analise,use-aprovar-analise,use-enviar-para-ccb,use-registrar-recusa}.ts.
  • DB: supabase/migrations/ — tabela contatos_mesa (status, analista_atual, analista_atual_id, data_inicio_analise, data_decisao, analista_decisao) e recusados.

Relacionado

mesa · ficha-do-contato · kanban-comercial · negocio · proposta · pipe-e-etapa

Histórico

  • 2026-07-10: primeira ingestão desta funcionalidade no wiki, aprofundando o ciclo de decisão da análise (iniciar/aprovar/recusar/enviar para CCB) já citado en passant em ficha-do-contato e kanban-comercial.