Relatório — KPIs e Métricas para Tela de Dashboard

Projeto: tmc-records — gestão de processos jurídicos previdenciários/INSS Stack: Next.js 16 · React 19 · HeroUI v3 · Tailwind v4 · Prisma 7 / MySQL Data: 2026-06-23 Autor: análise automatizada do código e do schema do banco

1. Sumário executivo

O sistema acompanha o ciclo de vida completo de processos (administrativos e judiciais), desde o protocolo até o resultado final, registrando cada mudança de estado como uma movimentação (trilha de auditoria). O modelo de dados é rico em dimensões categóricas (tipo, subtipo, estado, resultado, perícia médica, avaliação social, judicial/administrativo) e rico em dados temporais (dataProtocolo, createdAt, ultimaMovimentacaoAt, Movimentacao.createdAt).

Isso permite um dashboard forte em três frentes:

• Volume e tendência — quantos processos entram, em que estados estão, ritmo de movimentações.
• Performance / conversão — taxa de sucesso, conversão de perícia, performance por captador/perito.
• Operação e gargalos — processos parados, tempo de tramitação, distribuição de carga.

Hoje não existe nenhuma tela de dashboard e nenhuma biblioteca de gráficos está instalada. Este relatório lista 31 KPIs (acima do mínimo de 20 pedido), agrupados por importância, cada um já com o tipo de gráfico recomendado (linha, barra ou pizza) e a fonte de dados no schema.

2. Contexto técnico e limitações dos dados

Pontos importantes que condicionam o desenho do dashboard — leia antes dos KPIs:

Convenção de "resultado favorável" usada neste relatório (favorável = ganho para o cliente): PROCEDENTE, CONCEDIDO_ADM, CONCLUIU_ADM. Desfavorável/perda: IMPROCEDENTE, EXTINTO_SEM_MERITO, FALTA_CUMPRIMENTO_EXIGENCIA, PENDENCIA_NAO_RESOLVIDA. Abandono/sem mérito: DESISTIU, CANCELOU, SEM_CONTATO, FALECEU. Essa classificação deve ser confirmada com o negócio.

3. KPIs por nível de importância

Legenda de gráfico: 🟦 Card (número único) · 📈 Linha · 📊 Barra · 🥧 Pizza/Donut · 🔻 Funil.

🔴 Crítica — visão de topo (cards + gráficos principais)

São os indicadores que respondem "como o escritório está agora?". Devem ocupar o topo da tela.

🟠 Alta — indicadores operacionais

Respondem "onde melhorar a operação e quem performa melhor?".

🟡 Média — analítica e drill-down

Para análise mais profunda, normalmente em uma segunda dobra da tela ou em telas de detalhe.

🟢 Baixa — saúde de dados, governança e crescimento

Indicadores de qualidade e administração; baixa frequência de consulta, mas importantes para confiança nos dados.

Total: 31 KPIs — 8 críticos, 10 de alta, 8 de média e 5 de baixa importância. Os três tipos de gráfico pedidos (linha, barra, pizza) estão amplamente cobertos, além de cards e funil.

4. Mapa visual sugerido da tela

• Filtros globais sugeridos: período (data de protocolo / movimentação), tipo, subtipo, competencia/UF, captador, foiJudicial. Reaproveitar os filtros já existentes no feed() (clienteNome, from, to) como ponto de partida.

5. Recomendações de implementação

1. Biblioteca de gráficos — não há nenhuma instalada. Opções compatíveis com React 19/Next 16:

   • Recharts (mais simples, declarativo, cobre linha/barra/pizza com facilidade);
   • visx ou ECharts (mais poder, inclui funil para o KPI #22). Verificar primeiro se o HeroUI v3 já oferece componentes de chart antes de adicionar dependência (consultar a doc HeroUI via MCP).

2. Camada de agregação no repositório — adicionar métodos ao ProcessoRepository / MovimentacaoRepository usando prisma.processo.groupBy(...), count e aggregate. Sugestão de assinaturas:

   • countByEstado(), countByResultado(), countByTipo(), countBySubtipo();
   • countByCaptador(), countByPerito(), countByCompetencia();
   • novosPorMes(from, to), movimentacoesPorDia(from, to);
   • estagnados(diasSemMovimentacao: number). Encapsular tudo num use case GetDashboardMetricsUseCase que monta o payload da tela, seguindo o padrão de camadas (domain/application/infrastructure/presentation) já usado nos módulos existentes.

3. Definir regra única de status — criar um helper de domínio (ex.: isAtivo(processo) / classificarResultado(resultado)) para que "ativo", "favorável" e "abandono" tenham uma única fonte de verdade reutilizada por todos os KPIs.

4. Considerar um campo monetário (evolução futura) — adicionar valorCausa e/ou valorAcordo em Processo habilitaria uma categoria inteira de KPIs financeiros de alto valor: faturamento estimado, ticket médio por tipo, valor em RPV, valor recuperado por captador. Hoje impossível por ausência do dado.

5. Performance — para dashboards com muitos groupBy, avaliar índices adicionais (ex.: em Processo.estado, Processo.resultado, Processo.tipo) e/ou cache leve do payload de métricas, já que esses dados mudam com baixa frequência relativa.

6. Apêndice — dimensões disponíveis no schema

Campos ausentes (oportunidades futuras): valores monetários, flag de status ativo/encerrado, data de encerramento explícita, prazos/SLA formais.