Gerindo Expedicao

Gerindo Expedicao

Skill para consultas e operacoes logisticas da Nacom Goya.

---

Indice

1. Quando Usar Esta Skill
2. DECISION TREE - Qual Script Usar?
   • Mapeamento Rapido
   • Regras de Decisao
   • Como Decidir (Raciocinio)
   • Termos Ambiguos
   • Exemplos
3. Scripts Disponiveis
   • analisando_disponibilidade_estoque.py
   • consultando_situacao_pedidos.py
   • consultando_produtos_estoque.py
   • calculando_leadtime_entrega.py
   • criando_separacao_pedidos.py
   • consultando_programacao_producao.py
4. Fluxo de Criacao de Separacao
5. Referencias (tables, business, glossary, synonyms, products, examples)

---

Quando Usar Esta Skill

USE para:

• Consultas de pedidos: "tem pedido do Atacadao?", "pedido VCD123 esta em separacao?"
• Consultas de estoque: "quanto tem de palmito?", "chegou cogumelo?"
• Analise de disponibilidade: "quando VCD123 fica disponivel?", "o que vai dar falta?"
• Calculo de prazo: "se embarcar amanha, quando chega?"
• Criacao de separacao: "crie separacao do VCD123 pra amanha"
• Resolucao de entidades: identificar pedido, produto, cliente por termos parciais

NAO USE para:

• Analise COMPLETA da carteira com decisoes (use o Agent analista-carteira)
• Comunicacao com PCP ou Comercial (use o Agent)
• Decisoes de priorizacao P1-P7 (use o Agent)

---

DECISION TREE - Qual Script Usar?

<decision_tree> SEMPRE consulte esta secao ANTES de executar qualquer script. A escolha correta evita resultados errados e retrabalho. </​decision_tree>

Mapeamento Rapido

<mapeamento>

</​mapeamento>

Regras de Decisao (em ordem de prioridade)

<regras_decisao>

1. Se pergunta tem PRODUTO + CLIENTE/​GRUPO juntos: → Use consultando_situacao_pedidos.py --grupo X --produto Y ou --cliente X --produto Y → Exemplo: "quantas caixas de ketchup tem pro atacadao?" → --grupo atacadao --produto ketchup

2. Se pergunta e sobre PEDIDOS de um cliente/​grupo (sem produto): → Use consultando_situacao_pedidos.py --grupo X ou --cliente X → Exemplo: "tem pedido do assai?" → --grupo assai

3. Se pergunta e sobre ESTOQUE de produto (sem cliente): → Use consultando_produtos_estoque.py --produto X --completo → Exemplo: "quanto tem de palmito?" → --produto palmito --completo

4. Se pergunta e sobre DISPONIBILIDADE de pedido: → Use analisando_disponibilidade_estoque.py --pedido X → Exemplo: "quando VCD123 fica disponivel?" → --pedido VCD123

5. Se pergunta e sobre PRAZO de entrega: → Use calculando_leadtime_entrega.py → Exemplo: "se embarcar amanha, quando chega?" → --pedido X --data-embarque amanha

6. Se for ACAO de criar separacao: → Use criando_separacao_pedidos.py (SEMPRE simular antes de executar!) → Exemplo: "crie separacao do VCD123" → --pedido VCD123 --expedicao [data] (SEM --executar)

</​regras_decisao>

Como Decidir (Raciocinio Obrigatorio)

<instrucao_raciocinio> ANTES de escolher qualquer script, faca este raciocinio mentalmente:

PASSO 1 - IDENTIFICAR: O que o usuario quer saber?

• E sobre PEDIDOS? (quem comprou, quanto, quando entregar)
• E sobre ESTOQUE? (tem, vai faltar, chegou, quanto sobra)
• E sobre DISPONIBILIDADE? (quando pedido fica pronto)
• E sobre PRAZO? (quando chega se embarcar dia X)
• E uma ACAO? (criar separacao)

PASSO 2 - VERIFICAR: Tem cliente/​grupo mencionado?

• SIM + produto → consultando_situacao_pedidos --grupo/​--cliente + --produto
• SIM sem produto → consultando_situacao_pedidos --grupo/​--cliente
• NAO → provavelmente consultando_produtos_estoque

PASSO 3 - CONFIRMAR: A escolha faz sentido?

• Se escolhi ESTOQUE mas usuario perguntou "pro atacadao" → ERRADO (use PEDIDOS)
• Se escolhi PEDIDOS mas usuario perguntou "quanto tem em estoque" → ERRADO (use ESTOQUE)
• Se escolhi DISPONIBILIDADE mas usuario perguntou "quando chega" → ERRADO (use LEADTIME)

PASSO 4 - PERGUNTAR: Se ainda em duvida apos os 3 passos → pergunte ao usuario! </​instrucao_raciocinio>

---

Leitura de References (Sob Demanda)

<filosofia_50_50> FILOSOFIA: 50% Regra / 50% IA

Esta skill implementa um equilibrio entre scripts e IA:

SCRIPTS fazem:

• Resolver entidades (cliente, grupo, produto)
• Buscar dados no banco
• Retornar TODOS os candidatos (sem truncar)

IA decide:

• Como agrupar/​apresentar resultados
• Se precisa perguntar algo ao usuario
• Quando usar references para contexto </​filosofia_50_50>

<leitura_references> ANTES de executar scripts, o agente DEVE ler os references relevantes baseado na pergunta:

<exemplo_fluxo_50_50> Exemplo de Fluxo Completo

Pergunta: "quanto tem de palmito pro atacadao 183"

1. IA le references/​glossary.md → "pendente" = qtd_saldo > 0
2. IA le references/​business.md → atacadao = grupo com prefixos CNPJ
3. IA executa: python consultando_situacao_pedidos.py --grupo atacadao --produto palmito
4. Script encontra 18 candidatos de palmito
5. Script busca TODOS na carteira do cliente (nao para por multiplos)
6. Script retorna 2 SKUs com saldo: Tolete 15x300g (2.592 un), Rodela 15x300g (1.053 un)
7. IA apresenta tabela consolidada ao usuario

IMPORTANTE: Quando script retorna ia_decide: true, a IA DEVE processar os dados e decidir a melhor forma de apresentar. </​exemplo_fluxo_50_50>

---

Termos Ambiguos - PERGUNTE antes de agir!

<termos_ambiguos>

Se o usuario usar estes termos, PARE e PERGUNTE antes de executar.

"programacao de entrega" (CRITICO - 4 interpretacoes)

PERGUNTAR: "Voce quer saber: A) data que o cliente solicitou, B) data de expedicao programada, C) data de chegada no cliente, ou D) protocolo de agendamento?"

"quantidade pendente"

ACAO PADRAO: Mostrar AMBOS e explicar: "Na carteira: X un | Em separacao: Y un | Total pendente: Z un"

"itens" vs "unidades"

NUNCA usar "itens" sozinho. SEMPRE especificar:

• "X linhas de produto" (SKUs diferentes)
• "X unidades" ou "X caixas" (quantidade)

Multiplas lojas do mesmo grupo

Se resultado tiver mais de 1 loja do mesmo grupo (ex: Atacadao): PERGUNTAR: "Encontrei pedidos em X lojas do [grupo]. Qual loja especificamente, ou quer ver todas?"

Outros termos ambiguos

</​termos_ambiguos>

Exemplos de Boas e Mas Escolhas

<exemplo_bom> Pergunta: "quantas caixas de ketchup tem pendentes pro atacadao 183" Escolha: consultando_situacao_pedidos.py --grupo atacadao --produto ketchup Motivo: Combina PRODUTO + GRUPO, que e o caso 1 das regras de decisao. </​exemplo_bom>

<exemplo_ruim> Pergunta: "quantas caixas de ketchup tem pendentes pro atacadao 183" Escolha ERRADA: consultando_produtos_estoque.py --produto ketchup Problema: Mostra catalogo de produtos, NAO pedidos do cliente. O usuario quer saber qtd pendente para o atacadao, nao estoque geral. </​exemplo_ruim>

<exemplo_bom> Pergunta: "quanto tem de palmito?" Escolha: consultando_produtos_estoque.py --produto palmito --completo Motivo: Pergunta sobre ESTOQUE de produto, sem mencionar cliente. </​exemplo_bom>

<exemplo_ruim> Pergunta: "quanto tem de palmito?" Escolha ERRADA: consultando_situacao_pedidos.py --produto palmito Problema: Mostra pedidos com palmito, NAO estoque. O usuario quer saber quantidade em estoque. </​exemplo_ruim>

<exemplo_bom> Pergunta: "quando o pedido VCD123 fica disponivel?" Escolha: analisando_disponibilidade_estoque.py --pedido VCD123 Motivo: Pergunta sobre DISPONIBILIDADE de pedido especifico. Analisa estoque vs demanda. </​exemplo_bom>

<exemplo_ruim> Pergunta: "quando o pedido VCD123 fica disponivel?" Escolha ERRADA: consultando_situacao_pedidos.py --pedido VCD123 --status Problema: Mostra status atual do pedido, NAO projeta quando tera estoque disponivel. </​exemplo_ruim>

<exemplo_bom> Pergunta: "se embarcar amanha, quando chega em Manaus?" Escolha: calculando_leadtime_entrega.py --pedido X --data-embarque amanha Motivo: Calculo de PRAZO de entrega com data de embarque fornecida. </​exemplo_bom>

<exemplo_ruim> Pergunta: "se embarcar amanha, quando chega em Manaus?" Escolha ERRADA: analisando_disponibilidade_estoque.py --pedido X Problema: Analisa disponibilidade de estoque, NAO calcula prazo de transporte. </​exemplo_ruim>

<exemplo_bom> Pergunta: "crie separacao do VCD123 pra segunda" Escolha: criando_separacao_pedidos.py --pedido VCD123 --expedicao segunda Motivo: ACAO de criar separacao com data informada. SEMPRE simular primeiro (SEM --executar). </​exemplo_bom>

<exemplo_ruim> Pergunta: "crie separacao do VCD123 pra segunda" Escolha ERRADA: criando_separacao_pedidos.py --pedido VCD123 --expedicao segunda --executar Problema: NUNCA usar --executar sem simular primeiro e confirmar com usuario! </​exemplo_ruim>

<exemplo_bom> Pergunta: "o que vai ser produzido essa semana?" Escolha: consultando_programacao_producao.py --listar --dias 7 --por-dia Motivo: Consulta de PROGRAMACAO de producao futura com agrupamento por dia. </​exemplo_bom>

<exemplo_ruim> Pergunta: "o que vai ser produzido essa semana?" Escolha ERRADA: consultando_produtos_estoque.py --entradas Problema: Mostra entradas de estoque (producao JA realizada), NAO programacao futura. </​exemplo_ruim>

---

Scripts Disponiveis

Ambiente Virtual

Sempre ativar antes de executar:

source .venv/​bin/​activate

---

1. analisando_disponibilidade_estoque.py

Proposito: Analisa disponibilidade de estoque para pedidos ou grupos de clientes.

Queries cobertas: Q1, Q2, Q3, Q4, Q5, Q6, Q9, Q11, Q12

source .venv/​bin/​activate && \
python .claude/​skills/​gerindo-expedicao/​scripts/​analisando_disponibilidade_estoque.py [parametros]

---

2. consultando_situacao_pedidos.py

Proposito: Consulta pedidos por diversos filtros e perspectivas.

Queries cobertas: Q8, Q10, Q14, Q16, Q19

source .venv/​bin/​activate && \
python .claude/​skills/​gerindo-expedicao/​scripts/​consultando_situacao_pedidos.py [parametros]

Combinacoes suportadas:

• --grupo atacadao --produto ketchup → Pedidos do Atacadao com ketchup
• --cliente Carrefour --produto palmito → Pedidos do Carrefour com palmito
• --cliente "45.543.915" → Busca por CNPJ

---

3. consultando_produtos_estoque.py

Proposito: Consulta estoque atual, movimentacoes, pendencias, projecoes e SITUACAO COMPLETA.

Queries cobertas: Q13, Q17, Q18, Q20 + SITUACAO COMPLETA

source .venv/​bin/​activate && \
python .claude/​skills/​gerindo-expedicao/​scripts/​consultando_produtos_estoque.py [parametros]

Opcao --completo retorna:

• Estoque atual e menor estoque nos proximos 7 dias
• Separacoes por data de expedicao (detalhado com pedidos)
• Demanda total (Carteira bruta/​liquida + Separacoes)
• Programacao de producao (proximos 14 dias)
• Projecao dia a dia (estoque projetado)
• Indicadores: sobra, cobertura em dias, % disponivel, previsao de ruptura

---

4. calculando_leadtime_entrega.py

Proposito: Calcula data de entrega OU data de expedicao sugerida (calculo reverso).

Queries cobertas: Q7 + CALCULO REVERSO

source .venv/​bin/​activate && \
python .claude/​skills/​gerindo-expedicao/​scripts/​calculando_leadtime_entrega.py [parametros]

Modos de operacao:

---

5. criando_separacao_pedidos.py

Proposito: Cria separacoes de pedidos via linguagem natural.

IMPORTANTE: Sempre executar primeiro SEM --executar para simular!

source .venv/​bin/​activate && \
python .claude/​skills/​gerindo-expedicao/​scripts/​criando_separacao_pedidos.py [parametros]

Modos de operacao:

Tipos de separacao:

---

6. consultando_programacao_producao.py

Proposito: Lista programacao de producao e simula alteracoes para resolver ruptura.

Queries cobertas: Q15 + LISTAGEM COMPLETA

source .venv/​bin/​activate && \
python .claude/​skills/​gerindo-expedicao/​scripts/​consultando_programacao_producao.py [parametros]

Modos de operacao:

Exemplo de listagem completa:

python .claude/​skills/​gerindo-expedicao/​scripts/​consultando_programacao_producao.py --listar --dias 7 --por-dia

---

7. resolver_entidades.py

Proposito: Modulo utilitario para resolver entidades do dominio.

Uso interno pelos outros scripts. Resolve:

• Pedidos por numero parcial ou termo
• Produtos por nome ou abreviacoes
• Grupos empresariais por nome
• Cidades por nome (normalizado)

---

Fluxo de Criacao de Separacao

Checklist Obrigatorio

Sequencia

1. SIMULAR primeiro (sem --executar)
2. Verificar alertas de estoque
3. Mostrar resultado ao usuario
4. Solicitar confirmacao
5. EXECUTAR (com --executar)

---

Nivel de Detalhes (Progressive Disclosure)

1. Resposta inicial: Resumo com 3-5 itens principais
2. Se pedir mais: Mostrar mais itens do mesmo JSON
3. Se pedir "todos": Lista completa

---

Referencias

<progressive_disclosure> Os arquivos em references/ sao carregados sob demanda. NAO leia todos de uma vez - consulte apenas quando necessario. </​progressive_disclosure>

Grupos Empresariais: --grupo atacadao, --grupo assai, --grupo tenda