monitorando-entregas

name: monitorando-entregas description: >- Pos-faturamento: status de entregas, canhotos, devolucoes e datas de embarque. Gatilhos: "NF 12345 foi entregue?", "que dia embarcou?", "tem canhoto?", "houve devolucao?", "entregas pendentes", "NFs no CD". Anti: pedido nao faturado -> gerindo-expedicao; rastrear NF/PO Odoo -> rastreando-odoo. allowed-tools: Read, Bash, Glob, Grep

Monitorando Entregas

Skill para consultar status de entregas, canhotos, devoluções e agendamentos pós-faturamento.

Índice

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

Quando NÃO Usar Esta Skill

DECISION TREE - Qual Script Usar?

Scripts EXISTENTES (apenas estes 3)

⚠️ IMPORTANTE: Esta skill possui EXATAMENTE 3 scripts. NÃO tente executar scripts que não estão listados abaixo.

Mapeamento Rápido

Regras de Decisão (em ordem de prioridade)

1. Se pergunta sobre STATUS de entrega ou DATAS (embarque/faturamento/entrega): → Use consultando_status_entrega.py

2. Se pergunta sobre CANHOTO: → Use consultando_status_entrega.py (campo canhoto_arquivo no retorno) → Se canhoto_arquivo é null → "sem canhoto registrado" → Se canhoto_arquivo tem valor → "canhoto disponível"

3. Se pergunta sobre DEVOLUÇÃO (ocorrência/status/NFD): → Use consultando_devolucoes.py

4. Se pergunta sobre ANÁLISE de devoluções (ranking, custo, histórico por cliente/produto): → Use consultando_devolucoes_detalhadas.py com o modo adequado

5. Se pergunta sobre AGENDAMENTO: → Dados de agendamento estão em consultando_status_entrega.py (campos data_agenda, reagendar, motivo_reagendamento) → Para agendamentos detalhados, usar consultando-sql com tabela agendamentos_entrega

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

Regras CRÍTICAS (Anti-Alucinação)

R1: FIDELIDADE AO OUTPUT DOS SCRIPTS

OBRIGATÓRIO:
- Reportar EXATAMENTE os valores retornados pelo script
- Usar EXATAMENTE os nomes de campos do JSON de retorno
- Citar numeros (total, valores) do campo "resumo" quando disponivel
- Formatar datas como DD/MM/YYYY (converter de YYYY-MM-DD do script)
- Formatar valores monetarios como R$ X.XXX,XX

PROIBIDO:
- Inventar dados que NAO estao no output do script
- Inferir status a partir de campos booleanos isolados (usar status_finalizacao)
- Arredondar ou estimar valores — usar exatamente o que o script retorna
- Adicionar contexto ou explicacao que nao tem base nos dados retornados

R2: status_finalizacao — Valores Válidos

R3: Fórmulas CORRETAS

R4: 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)
• Ranking de produtos devolvidos (baseado no output de --ranking)
• Custo de devoluções (baseado no output de --custo)

R5: O Agente NÃO PODE Inventar

• Lead time ou prazo de entrega se não calculado pelo script
• Motivo de devolução sem consultar ocorrencia_devolucao (usar consultando_devolucoes.py)
• Previsão de entrega sem dados no campo data_entrega_prevista
• Custo de devolução sem executar consultando_devolucoes_detalhadas.py --custo
• Status de agendamento detalhado sem consultar tabela agendamentos_entrega

R6: Campos com Semântica Especial

Scripts Disponíveis

1. consultando_status_entrega.py

Consulta status de entregas com vários filtros. Script principal — cobre status, datas, canhotos e agendamentos básicos.

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

Parâmetros:

Retorno esperado:

{
  "sucesso": true,
  "total": 15,
  "exibindo": 50,
  "filtros_aplicados": {"pendentes": true},
  "entregas": [
    {
      "id": 1234,
      "numero_nf": "144533",
      "cliente": "ATACADAO SA",
      "cnpj_cliente": "45.543.915/0039-00",
      "transportadora": "BRASPRESS",
      "municipio": "SAO PAULO",
      "uf": "SP",
      "valor_nf": 12345.67,
      "data_faturamento": "2025-01-15",
      "data_embarque": "2025-01-16",
      "data_entrega_prevista": "2025-01-20",
      "data_hora_entrega_realizada": null,
      "status_finalizacao": null,
      "entregue": false,
      "nf_cd": false,
      "reagendar": false,
      "motivo_reagendamento": null,
      "data_agenda": null,
      "teve_devolucao": false,
      "canhoto_arquivo": null,
      "nova_nf": null
    }
  ]
}

2. consultando_devolucoes.py

Consulta devoluções (NFDs) com ocorrências relacionadas.

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

Parâmetros:

Retorno esperado:

{
  "sucesso": true,
  "total": 30,
  "exibindo": 30,
  "devolucoes": [
    {
      "id": 456,
      "numero_nfd": "67890",
      "numero_nf_venda": "12345",
      "motivo": "AVARIA",
      "valor_total": 1234.56,
      "nome_emitente": "ATACADAO SA",
      "status_nfd": "REGISTRADA",
      "status_ocorrencia": "ABERTA",
      "categoria": "QUALIDADE",
      "responsavel": "QUALIDADE"
    }
  ]
}

3. consultando_devolucoes_detalhadas.py

Consulta devoluções detalhadas com 4 modos mutuamente exclusivos.

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

Parâmetros de modo (UM obrigatório, mutuamente exclusivos):

Parâmetros gerais:

Retorno por modo:

Tratamento de Resultados

Quando o Script Retorna "sucesso": false

1. Reportar o erro ao usuario: "Nao consegui consultar: {erro}"
2. NAO inventar dados alternativos
3. Sugerir: "Verifique se o numero da NF/nome do cliente esta correto"

Quando o Script Retorna "total": 0 (sem resultados)

1. Dizer claramente: "Nao encontrei entregas com os filtros aplicados"
2. Sugerir filtros alternativos:
   - Se buscou por NF → "Verifique o numero da NF"
   - Se buscou por cliente → "O nome exato pode ser diferente. Tente parte do nome"
   - Se buscou pendentes → "Nao ha entregas pendentes no momento"
3. NAO inventar dados ou resultados aproximados

Quando total > exibindo (resultados truncados)

1. Informar: "Encontrei {total} entregas, mostrando as {exibindo} mais recentes"
2. Sugerir refinar filtros (período, NF específica) se total for muito grande

Formatação de Resposta

- Datas: converter YYYY-MM-DD → DD/MM/YYYY (padrão brasileiro)
- Valores: R$ com separador de milhar (.) e decimal (,)
- Status null: dizer "pendente" ou "em andamento" (NÃO dizer "null")
- Canhoto null: dizer "sem canhoto registrado" (NÃO dizer "null")
- Listas: numerar NFs quando houver múltiplas

Exemplos de Uso

Cenário 1: Status de NF específica

Pergunta: "NF 144533 foi entregue?"
Script: consultando_status_entrega.py --nf 144533
Resposta: "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?"
Script: consultando_status_entrega.py --cliente atacadao --pendentes
Resposta: "Encontrei 5 entregas pendentes do Atacadão: [lista com NFs]"

Cenário 3: Canhoto de NF

Pergunta: "tem canhoto da NF 144533?"
Script: consultando_status_entrega.py --nf 144533
Resposta (se canhoto_arquivo != null): "Sim, canhoto registrado para a NF 144533."
Resposta (se canhoto_arquivo == null): "Não, NF 144533 não tem canhoto registrado."

Cenário 4: Devoluções abertas

Pergunta: "tem devolução aberta?"
Script: consultando_devolucoes.py --abertas
Resposta: "3 ocorrências de devolução abertas: [detalhes com NFD, cliente, categoria]"

Cenário 5: Ranking de produtos devolvidos

Pergunta: "quais produtos são mais devolvidos?"
Script: consultando_devolucoes_detalhadas.py --ranking --limite 10
Resposta: "Top 10 produtos mais devolvidos: 1. Palmito 400g (45 ocorrências)..."

Cenário 6: Custo de devoluções em período

Pergunta: "quanto custaram as devoluções em janeiro?"
Script: consultando_devolucoes_detalhadas.py --custo --de 2025-01-01 --ate 2025-01-31
Resposta: "Custo total de devoluções em janeiro: R$ 12.345,67 (15 despesas, 8 NFDs)"

Cenário 7: Data de embarque

Pergunta: "que dia saiu a NF 144533?"
Script: consultando_status_entrega.py --nf 144533
Resposta: "A NF 144533 saiu (embarcou) em 16/01/2025."

Referência Cruzada

References (sob demanda)

Tabelas do Domínio