Voltar para Central de Manuais
# Manual de Utilizacao do ML (Gestores)
Este documento explica, em linguagem de negocio, como usar a camada de Machine Learning (ML) do Sisconnect para apoiar decisoes de Financeiro, Comercial e Operacoes.
## 1) Objetivo
A camada de ML foi criada para complementar os numeros oficiais dos relatorios.
- **Relatorio oficial** responde: "o que aconteceu".
- **ML** responde: "o que tende a acontecer".
O uso correto e sempre combinar:
- fato atual (KPI oficial),
- risco/projecao (ML),
- acao recomendada.
## 2) O que ja esta disponivel
Hoje temos duas frentes de ML em producao:
- **Risco de inadimplencia** por cliente
- Tabela: `app_ml_inadimplencia_scores`
- Saidas principais: `score_risco`, `faixa_risco`, `prob_default_30d`
- **Forecast de faturamento** por cliente e por grupo
- Tabela: `app_ml_faturamento_forecasts`
- Saidas principais: `valor_previsto_centavos`, `intervalo_inf_centavos`, `intervalo_sup_centavos`
## 3) Conceitos-chave para Gestao
### 3.1 Risco de inadimplencia
- `score_risco`: numero de 0 a 1.
- `faixa_risco`:
- `baixo`: carteira saudavel
- `medio`: monitoramento ativo
- `alto`: acao imediata de cobranca/renegociacao
- `prob_default_30d`: probabilidade estimada de inadimplencia em 30 dias.
### 3.2 Forecast de faturamento
- `valor_previsto_centavos`: valor previsto para o periodo (em centavos).
- `intervalo_inf_centavos` e `intervalo_sup_centavos`: faixa de confianca simples para leitura executiva.
- `periodo_previsto`: mes da previsao.
## 4) Regra de governanca (obrigatoria)
Para evitar erro de interpretacao:
- **Nao** usar ML como "numero oficial de fechamento".
- **Sempre** usar relatorio oficial para fechamento contabil/financeiro.
- Usar ML para:
- priorizacao de carteira,
- prevencao de risco,
- planejamento de caixa e metas.
## 4.1 Regra oficial para CTE (obrigatoria)
Para qualquer indicador baseado em CTE ("emitidos", "valor emitido", "faturamento por CTE"):
- **Padrao oficial**: considerar somente CTE **autorizada**.
- **Tipo padrao para emitido**: considerar somente `normal`; desconsiderar `complementar` e `substituto`.
- **Nao** considerar cancelados/invalidos por padrao.
- Se o gestor pedir explicitamente outro status/tipo (ex.: cancelado, incluir substituto), o agente deve mudar o filtro e informar isso na resposta.
- Toda resposta com CTE deve informar os status e tipos aplicados (incluidos e excluidos).
### 4.2 Regra de vinculacao CTE -> cliente/grupo (obrigatoria)
Para evitar divergencia entre relatorio e agente em CTE complementar/substituto:
- **Nao** vincular cliente/grupo usando apenas `ct.id_coleta`.
- Usar resolucao robusta da coleta:
- `COALESCE(ct.id_coleta, r.id_coleta, cte_pai.id_coleta)`
- `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`
- Depois da coleta resolvida, seguir fluxo oficial:
`app_coletas -> app_clientes -> app_grupos_clientes`.
- Em divergencia com relatorio, validar primeiro se a query aplicada usou essa resolucao robusta.
## 5) Fluxo recomendado (rotina executiva)
### Diario (15 min)
- Ver top clientes com `faixa_risco = alto`.
- Validar valor em aberto atual vs probabilidade de default.
- Disparar plano de acao (cobranca/contato/renegociacao).
### Semanal
- Revisar forecast de faturamento (cliente e grupo).
- Comparar previsto vs realizado da semana anterior.
- Ajustar metas e foco comercial.
### Mensal
- Consolidar tendencias: risco, churn e previsao.
- Atualizar politica de credito e acompanhamento por segmento.
## 6) Como executar (time operacional/BI/tech)
### 6.1 Treinar risco de inadimplencia
- Endpoint: `POST /api/v1/ml/inadimplencia/treinar`
- Exemplo de payload:
```json
{
"lookback_days": 180
}
```
### 6.2 Consultar scores de risco
- Endpoint: `GET /api/v1/ml/inadimplencia/scores?limit=50`
### 6.3 Treinar forecast de faturamento
- Endpoint: `POST /api/v1/ml/forecast/faturamento/treinar`
- Exemplo de payload:
```json
{
"meses_lookback": 12,
"horizonte_meses": 3
}
```
### 6.4 Consultar forecast
- Endpoint cliente: `GET /api/v1/ml/forecast/faturamento?entidade_tipo=cliente&limit=100`
- Endpoint grupo: `GET /api/v1/ml/forecast/faturamento?entidade_tipo=grupo&limit=100`
## 7) Como perguntar para os agentes (exemplos prontos)
### Logos (Financeiro)
- "Traga risco ML de inadimplencia dos 20 maiores devedores e o valor em aberto atual."
- "Mostre previsao de faturamento dos proximos 3 meses por grupo e compare com o realizado do ultimo mes."
### Odin (Executivo)
- "Me entregue visao 360 com realizado oficial + risco ML + previsao de faturamento e acoes recomendadas."
- "Quais grupos estao com maior risco financeiro e impacto potencial no caixa?"
### Vetor (Comercial)
- "Cruze forecast de faturamento com risco de inadimplencia e proponha prioridade comercial por grupo."
## 8) Interpretacao rapida de faixas (sugestao executiva)
- **Risco baixo (0.00 a 0.44)**: manutencao e monitoramento leve.
- **Risco medio (0.45 a 0.74)**: monitoramento semanal e contato preventivo.
- **Risco alto (0.75 a 1.00)**: acao imediata e plano de contingencia.
## 9) Limites e cuidados
- Modelo depende da qualidade do dado historico.
- Mudancas bruscas de politica comercial/financeira podem reduzir qualidade temporariamente.
- Sempre revisar:
- periodo usado,
- status excluidos,
- fonte do KPI (oficial vs previsao).
## 10) Checklist de implantacao para Gestao
- Tabelas ML criadas no banco.
- Treino executado com sucesso (inadimplencia + forecast).
- Gestores com roteiro de leitura semanal.
- Time financeiro/comercial alinhado sobre "oficial vs previsao".
- Rituais definidos (diario/semanal/mensal).
---
Se quiser evoluir para uma versao 2, os proximos passos recomendados sao:
- anomalias automaticas por rota/cliente,
- score de churn comercial,
- painel unico de "risco e oportunidade" para diretoria.