Name: Monitorando Entregas
Author: Rafael-2109

스킬 검색.../

Situação	Usar em vez desta
Pedido ainda não faturado	gerindo-expedicao
Rastrear NF/PO/pagamento no Odoo	rastreando-odoo
Criar separação de pedido	gerindo-expedicao
Análise completa da carteira (P1-P7)	analista-carteira (subagente)
Consultas SQL analíticas complexas	consultando-sql

Script	Arquivo	Função
Status de entregas	`consultando_status_entrega.py`	Status, datas, canhotos, filtros por NF/cliente/período
Devoluções básicas	`consultando_devolucoes.py`	NFDs com ocorrências (abertas, por NF/cliente)
Devoluções detalhadas	`consultando_devolucoes_detalhadas.py`	4 modos: por cliente, produto, ranking, custo

Se a pergunta menciona...	Use este script	Com estes parâmetros
Status de NF específica	`consultando_status_entrega.py`	`--nf 12345`
Status por cliente/CNPJ	`consultando_status_entrega.py`	`--cliente "Atacadao"` ou `--cnpj 123...`
Data de embarque ("que dia saiu?", "quando embarcou?")	`consultando_status_entrega.py`	`--nf 12345` → campo `data_embarque`
Data de faturamento ("quando faturou?", "data da NF")	`consultando_status_entrega.py`	`--nf 12345` → campo `data_faturamento`
Data de entrega ("quando chegou?", "foi entregue quando?")	`consultando_status_entrega.py`	`--nf 12345` → campo `data_hora_entrega_realizada`
Entregas pendentes	`consultando_status_entrega.py`	`--pendentes`
Entregas no CD	`consultando_status_entrega.py`	`--no-cd`
Entregas reagendadas	`consultando_status_entrega.py`	`--reagendadas`
Entregas entregues (período)	`consultando_status_entrega.py`	`--entregues --de 2025-01-01 --ate 2025-01-31`
Canhoto de NF	`consultando_status_entrega.py`	`--nf 12345` → campo `canhoto_arquivo`
Canhotos pendentes	`consultando_status_entrega.py`	`--entregues` → filtrar onde `canhoto_arquivo` é null
Entregas com problema	`consultando_status_entrega.py`	`--problemas`
Devoluções abertas

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

Valor	Significado
`NULL`	Em andamento/pendente - NF ainda não finalizada
`Entregue`	NF entregue com sucesso ao cliente
`Cancelada`	Entrega cancelada (NF não será entregue)
`Devolvida`	Cliente devolveu a mercadoria
`Troca de NF`	NF substituída por outra (ver campo `nova_nf`)
`Sinistro`	Perda/extravio da mercadoria
`nao_finalizado`	NF saiu do monitoramento sem conclusão

Consulta	Fórmula	Flag no script
Entregas pendentes	`status_finalizacao IS NULL`	`--pendentes`
Entregas entregues	`status_finalizacao = 'Entregue'`	`--entregues`
Entregas devolvidas	`status_finalizacao = 'Devolvida' OR teve_devolucao = True`	—
Entregas com problema	`nf_cd = True OR reagendar = True`	`--problemas`
Com canhoto	`canhoto_arquivo IS NOT NULL`	—

Campo	Descrição	⚠️ Cuidado
`entregue`	Boolean - True quando `status_finalizacao='Entregue'`	NÃO usar isoladamente para filtrar pendentes
`nf_cd`	Boolean - NF fisicamente no CD	Pode ser NF que nunca saiu OU que voltou
`reagendar`	Boolean - cliente solicitou reagendamento	—
`teve_devolucao`	Boolean - houve devolução (mesmo parcial)	—
`nova_nf`	NF substituta	Só presente quando `status_finalizacao='Troca de NF'`
`canhoto_arquivo`	Caminho do arquivo do canhoto	null = sem canhoto, valor = tem canhoto

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

Param	Obrig	Descrição
`--nf`	Não	Número da NF (busca parcial ILIKE)
`--cliente`	Não	Nome do cliente (busca parcial ILIKE)
`--cnpj`	Não	CNPJ do cliente
`--transportadora`	Não	Transportadora
`--pendentes`	Não	Apenas entregas pendentes (status_finalizacao IS NULL)
`--entregues`	Não	Apenas entregas entregues
`--no-cd`	Não	Apenas NFs no CD (nf_cd=True)
`--reagendadas`	Não	Apenas reagendadas (reagendar=True)
`--problemas`	Não	Com problema (nf_cd=True OR reagendar=True)
`--de`	Não	Data inicial (YYYY-MM-DD)
`--ate`	Não	Data final (YYYY-MM-DD)
`--limite`	Não	Máximo de registros (default: 50)
`--formato`	Não	json ou tabela (default: json)

{
  "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
    }
  ]
}

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

Param	Obrig	Descrição
`--nf`	Não	Número da NF original
`--nfd`	Não	Número da NF de devolução
`--abertas`	Não	Apenas ocorrências abertas (ABERTA, EM_ANALISE, AGUARDANDO_RETORNO)
`--cliente`	Não	Nome do cliente/emitente
`--de`	Não	Data inicial (YYYY-MM-DD)
`--ate`	Não	Data final (YYYY-MM-DD)
`--limite`	Não	Máximo de registros (default: 50)

{
  "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"
    }
  ]
}

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

Param	Descrição
`--cliente "Nome"`	Histórico de devoluções por cliente
`--produto "nome"`	Produtos devolvidos (ILIKE)
`--ranking`	Top N produtos mais devolvidos
`--custo`	Custo total de devoluções (via despesas_extras)

Param	Descrição
`--de`	Data início (YYYY-MM-DD)
`--ate`	Data fim (YYYY-MM-DD)
`--limite`	Max resultados (default: 50)
`--incluir-custo`	Incluir custo (apenas com --cliente)
`--ordenar-por`	'ocorrencias' ou 'quantidade' (apenas com --ranking)

Modo	Campo principal	Conteúdo
`--cliente`	`nfds`	Lista de NFDs + resumo com total/valor
`--produto`	`linhas`	Linhas de devolução + resumo com qtd/clientes
`--ranking`	`ranking`	Top N com total_ocorrencias, qtd_total, total_clientes
`--custo`	`breakdown_mensal`	Custo total + breakdown por mês

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"

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

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

- 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

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."

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]"

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."

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

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)..."

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)"

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

Skill	Quando usar em vez desta
gerindo-expedicao	Pedidos antes de faturar, estoque, separação
rastreando-odoo	Rastrear NF/PO/pagamento no Odoo
consultando-sql	Consultas analíticas complexas (agregações, rankings avançados)
analista-carteira	Análise completa da carteira com decisões P1-P7

Gatilho na Pergunta	Reference a Ler	Motivo
"status de devolução"	`references/devolucoes.md`	Fluxo completo de devolução, status NFD/ocorrência
"categorias de ocorrência"	`references/devolucoes.md`	Valores válidos de categoria/subcategoria
"tabelas relacionadas"	`references/tables.md`	Relacionamentos entre tabelas do domínio

Tabela	Descrição	FK principal
`entregas_monitoradas`	Status principal de cada NF	-
`agendamentos_entrega`	Histórico de agendamentos	`entrega_id → entregas_monitoradas.id`
`nf_devolucao`	NFs de devolução recebidas	`entrega_monitorada_id → entregas_monitoradas.id`
`nf_devolucao_linha`	Linhas/produtos da NFD	`nf_devolucao_id → nf_devolucao.id`
`ocorrencia_devolucao`	Ocorrências/tratativa	`nf_devolucao_id → nf_devolucao.id`

Monitorando Entregas | Skills Pool

Monitorando Entregas

Monitorando Entregas

Índice

Quando NÃO Usar Esta Skill

DECISION TREE - Qual Script Usar?

Scripts EXISTENTES (apenas estes 3)

Mapeamento Rápido

Regras de Decisão (em ordem de prioridade)

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

R1: FIDELIDADE AO OUTPUT DOS SCRIPTS

R2: status_finalizacao — Valores Válidos

R3: Fórmulas CORRETAS

R4: O Agente PODE Afirmar

R5: O Agente NÃO PODE Inventar

R6: Campos com Semântica Especial

Scripts Disponíveis

1. consultando_status_entrega.py

2. consultando_devolucoes.py

3. consultando_devolucoes_detalhadas.py

Tratamento de Resultados

Quando o Script Retorna "sucesso": false

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

Quando total > exibindo (resultados truncados)

Formatação de Resposta

Exemplos de Uso

Cenário 1: Status de NF específica

Cenário 2: Entregas pendentes do Atacadão

Cenário 3: Canhoto de NF

Cenário 4: Devoluções abertas

Cenário 5: Ranking de produtos devolvidos

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

Cenário 7: Data de embarque

Referência Cruzada

References (sob demanda)

Tabelas do Domínio

Feishu Perm

Discord

Coding Agent (bash-first)

Apple Notes

Feishu Wiki

Bear Notes

Quando o Script Retorna `"sucesso": false`

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

Quando `total` > `exibindo` (resultados truncados)