Monitorando Entregas

Monitorando Entregas

Skill para consultar status de entregas, canhotos, devoluções e agendamentos.

Índice

1. Quando NÃO Usar Esta Skill
2. DECISION TREE - Qual Script Usar?
3. Regras de Negócio (Anti-Alucinação)
4. Scripts Disponíveis
5. Referência Cruzada
6. References

Quando NÃO Usar Esta Skill

DECISION TREE - Qual Script Usar?

Mapeamento Rápido

Regras de Decisão (em ordem de prioridade)

1. Se pergunta sobre STATUS de entrega: → Use consultando_status_entrega.py → Exemplo: "NF 12345 foi entregue?" → --nf 12345

2. Se pergunta sobre CANHOTO: → Use consultando_canhotos.py → Exemplo: "tem canhoto da NF?" → --nf 12345

3. Se pergunta sobre DEVOLUÇÃO: → Use consultando_devolucoes.py → Exemplo: "houve devolução?" → --nf 12345

4. Se pergunta sobre AGENDAMENTO: → Use consultando_agendamentos.py → Exemplo: "quando está agendada?" → --nf 12345

5. Se pergunta sobre PROBLEMAS genéricos: → Use consultando_status_entrega.py --problemas → Inclui: nf_cd=True OU reagendar=True

Regras de Negócio (Anti-Alucinação)

status_finalizacao - Valores Válidos

Fórmulas CORRETAS (O que o agente DEVE usar)

O Agente PODE Afirmar:

• Status atual da entrega (baseado em status_finalizacao)
• Se tem canhoto (baseado em canhoto_arquivo IS NOT NULL)
• Data de entrega (baseado em data_hora_entrega_realizada)
• Se está no CD (baseado em nf_cd = True)
• Se precisa reagendar (baseado em reagendar = True)

O Agente NÃO PODE Inventar:

• Lead time se não calculado pelo script
• Motivo de devolução sem consultar ocorrencia_devolucao
• Status de agendamento sem consultar agendamentos_entrega
• Previsão de entrega sem dados no sistema

Campos Importantes

Scripts Disponíveis

1. consultando_status_entrega.py

Consulta status de entregas com vários filtros.

source .venv/bin/activate && python .claude/skills/monitorando-entregas/scripts/consultando_status_entrega.py [opções]

Parâmetros:

Retorno esperado:

{
  "sucesso": true,
  "total": 15,
  "entregas": [
    {
      "id": 1234,
      "numero_nf": "144533",
      "cliente": "ATACADAO SA",
      "status_finalizacao": null,
      "entregue": false,
      "nf_cd": false,
      "reagendar": false,
      "data_faturamento": "2025-01-15",
      "data_embarque": "2025-01-16",
      "data_entrega_prevista": "2025-01-20",
      "transportadora": "BRASPRESS",
      "municipio": "SAO PAULO",
      "uf": "SP"
    }
  ]
}

2. consultando_canhotos.py

Consulta canhotos de entregas.

source .venv/bin/activate && python .claude/skills/monitorando-entregas/scripts/consultando_canhotos.py [opções]

Parâmetros:

3. consultando_devolucoes.py

Consulta devoluções e ocorrências.

source .venv/bin/activate && python .claude/skills/monitorando-entregas/scripts/consultando_devolucoes.py [opções]

Parâmetros:

4. consultando_agendamentos.py

Consulta agendamentos de entrega.

source .venv/bin/activate && python .claude/skills/monitorando-entregas/scripts/consultando_agendamentos.py [opções]

Parâmetros:

5. consultando_devolucoes_detalhadas.py

Consulta devoluções detalhadas com entity resolution e análises agregadas.

source .venv/bin/activate && python .claude/skills/monitorando-entregas/scripts/consultando_devolucoes_detalhadas.py [opções]

Parâmetros (modos mutuamente exclusivos):

*Um dos 4 modos deve ser especificado.

Retorno esperado (modo --cliente):

{
  "sucesso": true,
  "modo": "cliente",
  "resumo": {
    "mensagem": "Historico de devolucoes de 12 NFDs do cliente 'Sendas'",
    "total_nfds": 12,
    "exibindo": 10,
    "valor_total_devolucoes": 45678.90,
    "custo_total": 3456.78,
    "cliente": "Sendas",
    "periodo": {"de": "2025-01-01", "ate": "2025-12-31"}
  },
  "nfds": [
    {
      "id": 123,
      "numero_nfd": "12345",
      "nome_emitente": "Sendas Distribuidora SA",
      "cnpj_emitente": "12.345.678/0001-99",
      "data_registro": "2025-01-15",
      "valor_total": 4567.89,
      "status": "REGISTRADA",
      "motivo": "AVARIA",
      "total_linhas": 3
    }
  ]
}

Retorno esperado (modo --ranking):

{
  "sucesso": true,
  "modo": "ranking",
  "resumo": {
    "mensagem": "Top 10 produtos mais devolvidos (ordenado por ocorrencias)",
    "criterio": "ocorrencias",
    "total_produtos": 10
  },
  "ranking": [
    {
      "produto_referencia": "PALMITO-400G",
      "descricao_produto_interno": "Palmito Inteiro 400g",
      "total_ocorrencias": 45,
      "qtd_total": 234.0,
      "total_nfds": 38,
      "total_clientes": 12
    }
  ]
}

Exemplos de Uso

Cenário 1: Status de NF específica

Pergunta: "NF 144533 foi entregue?"
Raciocínio: Pergunta sobre STATUS de NF → consultando_status_entrega.py
Comando: --nf 144533
Resultado: "A NF 144533 está pendente (em andamento). Data de embarque: 16/01/2025."

Cenário 2: Entregas pendentes do Atacadão

Pergunta: "tem entrega pendente do Atacadão?"
Raciocínio: STATUS + CLIENTE → consultando_status_entrega.py
Comando: --cliente atacadao --pendentes
Resultado: "Encontrei 5 entregas pendentes do Atacadão: [lista com NFs]"

Cenário 3: Canhotos pendentes

Pergunta: "quais entregas não têm canhoto?"
Raciocínio: CANHOTO + pendentes → consultando_canhotos.py
Comando: --pendentes --limite 20
Resultado: "20 entregas sem canhoto registrado: [lista]"

Cenário 4: Devoluções abertas

Pergunta: "tem devolução aberta?"
Raciocínio: DEVOLUÇÃO + abertas → consultando_devolucoes.py
Comando: --abertas
Resultado: "3 ocorrências de devolução abertas: [detalhes]"

Cenário 5: Data de embarque

Pergunta: "que dia saiu a NF 144533?"
Raciocínio: Pergunta sobre DATA DE EMBARQUE → consultando_status_entrega.py
Comando: --nf 144533
Resultado: "A NF 144533 saiu (embarcou) em 16/01/2025."

Cenário 6: Data de faturamento

Pergunta: "quando faturou a NF do Atacadão loja 183?"
Raciocínio: DATA DE FATURAMENTO + CLIENTE → resolver grupo primeiro, depois consultando_status_entrega.py
Comando: --cliente "Atacadao 183"
Resultado: "Encontrei 3 NFs do Atacadão 183. Faturamento: NF 144533 em 15/01/2025, NF 144534 em 16/01/2025..."

Cenário 7: Data de entrega realizada

Pergunta: "quando chegou a NF 144533?"
Raciocínio: DATA DE ENTREGA REALIZADA → consultando_status_entrega.py
Comando: --nf 144533
Resultado: "A NF 144533 foi entregue em 20/01/2025 às 14:32."

Referência Cruzada

References (sob demanda)

Tabelas do Domínio