Voltar para Central de Manuais
# Manual Paridade de KPI (Relatorio x Agente) ## Objetivo Garantir que o número informado pelos agentes bata com o relatório oficial. ## Regra principal - Relatório oficial = fonte de verdade para fechamento. - Agente deve operar em "modo paridade de relatório" quando solicitado. - Para KPI de CTE, o padrão oficial é **somente status autorizado**. ## Causas comuns de divergência - período em campo diferente (ex.: `ct.criado_em` vs outro campo) - status aplicado de forma inconsistente - filtro por nome sem resolução de entidade por ID - join incompleto (grupo/cliente/cte/coleta) ## Procedimento de paridade 1. rodar KPI no modo oficial (mesma lógica dos serviços de relatório) 2. conferir período e timezone 3. conferir status incluídos/excluídos 4. validar entidade por ID (cliente/grupo) 5. comparar query oficial vs query alternativa ## Regra canônica de CTE para paridade - Quando a pergunta não explicitar status: - usar somente CTE autorizada. - Quando a pergunta não explicitar tipo: - considerar somente CTE `normal` por padrão. - desconsiderar `complementar` e `substituto`. - Quando a pergunta explicitar status: - usar exatamente o status solicitado (ex.: cancelado). - Quando a pergunta explicitar tipo: - usar exatamente o tipo solicitado (ex.: incluir substituto). - Sempre declarar no retorno: - status incluídos - status excluídos - tipos incluídos/excluídos ## Regra canônica de vínculo CTE (obrigatória) - Não usar apenas `ct.id_coleta` para vincular CTE ao cliente/grupo. - Resolver a coleta com fallback robusto: - `LEFT JOIN app_rastreamentos r ON r.id_cte = ct.id` - `LEFT JOIN app_ctes cte_pai ON cte_pai.id = ct.id_cte_pai` - `JOIN app_coletas co ON co.id = COALESCE(ct.id_coleta, r.id_coleta, cte_pai.id_coleta)` - Em seguida, usar: - `JOIN app_clientes c ON c.id = co.id_tomador` - `LEFT JOIN app_grupos_clientes g ON g.id = c.id_grupo_cliente` - Essa regra evita perda de CTE complementar/substituto em indicadores por cliente/grupo. ## Saída padrão obrigatória - KPI calculado - período - fonte e tabelas - status excluídos - observação: oficial ou previsão