Resolvendo Entidades

Resolvendo Entidades

Skill dedicada a resolver termos humanos para identificadores do sistema.

Indice

1. CRITICO: Quando Usar Esta Skill
2. Fluxo Obrigatorio
3. Mapeamento: Qual Script Usar?
4. Scripts Disponiveis
5. Regras de Negocio
6. Referencias Cruzadas
7. References

CRITICO: Quando Usar Esta Skill

OBRIGATORIO usar ANTES de qualquer skill que aceite entidades do dominio.

As entidades transitam por MULTIPLAS tabelas do sistema:

Sem resolver primeiro, o agente alucina ou falha em consultas.

Fluxo Obrigatorio

1. Usuario: "entregas do Assai de SP"
            ↓
2. RESOLVER PRIMEIRO:
   resolver_grupo.py --grupo assai --uf SP
   → {"sucesso": true, "prefixos_cnpj": ["06.057.22"], "total": 15}
            ↓
3. ENTAO CONSULTAR:
   consultando_status_entrega.py --cnpj "06.057.22"

Quando NAO Resolver

NAO usar esta skill se usuario ja forneceu:

• CNPJ completo: 06.057.22/0001-XX
• cod_produto exato: AZ001
• num_pedido exato: VCD2565291

Mapeamento: Qual Script Usar?

Tabela de Decisao Rapida

Regras de Decisao

1. Se menciona grupo empresarial conhecido: → resolver_grupo.py

2. Se menciona cliente desconhecido ou CNPJ parcial: → resolver_cliente.py

3. Se menciona produto por nome/abreviacao: → resolver_produto.py

4. Se menciona pedido por numero parcial: → resolver_pedido.py

5. Se menciona cidade ou UF: → resolver_cidade.py ou resolver_uf.py

Scripts Disponiveis

1. resolver_grupo.py

Resolve grupos empresariais para lista de CNPJs.

source .venv/bin/activate && python .claude/skills/resolvendo-entidades/scripts/resolver_grupo.py [opcoes]

Parametros:

Retorno:

{
  "sucesso": true,
  "grupo": "assai",
  "prefixos_cnpj": ["06.057.22"],
  "filtros": {"uf": "SP"},
  "cnpjs": ["06.057.22/0001-XX", "06.057.22/0002-YY"],
  "total": 15
}

2. resolver_cliente.py

Resolve cliente nao-grupo por CNPJ parcial ou nome.

source .venv/bin/activate && python .claude/skills/resolvendo-entidades/scripts/resolver_cliente.py --termo "Carrefour"

Parametros:

Retorno:

{
  "sucesso": true,
  "termo": "Carrefour",
  "estrategia": "NOME_PARCIAL",
  "clientes": [
    {"cnpj": "45.543.915/0001-XX", "nome": "CARREFOUR CENTRO", "cidade": "SAO PAULO", "uf": "SP"}
  ],
  "total": 3
}

3. resolver_produto.py

Resolve produto por termo ou abreviacao.

source .venv/bin/activate && python .claude/skills/resolvendo-entidades/scripts/resolver_produto.py --termo "palmito"

Parametros:

Retorno:

{
  "sucesso": true,
  "termo": "palmito",
  "produtos": [
    {"cod_produto": "PAL001", "nome_produto": "PALMITO PUPUNHA 300G", "score": 8}
  ],
  "total": 15
}

4. resolver_pedido.py

Resolve pedido por numero parcial ou termo.

source .venv/bin/activate && python .claude/skills/resolvendo-entidades/scripts/resolver_pedido.py --termo "VCD123"

Parametros:

Retorno:

{
  "sucesso": true,
  "termo": "VCD123",
  "estrategia": "NUMERO_PARCIAL",
  "pedidos": [
    {"num_pedido": "VCD1234567", "cliente": "ATACADAO 183", "cnpj": "93.209.76/0001-XX"}
  ],
  "multiplos": true,
  "total": 5
}

5. resolver_cidade.py

Resolve cidade com normalizacao de acentos.

source .venv/bin/activate && python .claude/skills/resolvendo-entidades/scripts/resolver_cidade.py --cidade "itanhaem"

Parametros:

6. resolver_uf.py

Resolve UF para lista de CNPJs/pedidos.

source .venv/bin/activate && python .claude/skills/resolvendo-entidades/scripts/resolver_uf.py --uf SP

Regras de Negocio

Grupos Empresariais Mapeados

Abreviacoes de Produto

O Agente PODE Afirmar

• CNPJs de um grupo empresarial
• Produtos que casam com termo de busca
• Pedidos que casam com numero parcial
• Clientes encontrados por nome/CNPJ

O Agente NAO PODE Inventar

• CNPJs de grupos nao mapeados
• Produtos sem match no CadastroPalletizacao
• Pedidos inexistentes
• Abreviacoes nao documentadas

Referencias Cruzadas

Skills que PRECISAM de Resolucao

Quando Delegar para Outra Skill

References

Exemplos de Uso

Cenario 1: Resolver grupo antes de consultar entregas

Pergunta: "entregas pendentes do Assai de SP"

Passo 1 - Resolver:
   resolver_grupo.py --grupo assai --uf SP --fonte entregas
   → {"prefixos_cnpj": ["06.057.22"], "total": 15}

Passo 2 - Consultar:
   consultando_status_entrega.py --cnpj "06.057.22" --pendentes
   → {"total": 8, "entregas": [...]}

Resposta: "Encontrei 8 entregas pendentes do Assai em SP"

Cenario 2: Resolver produto por abreviacao

Pergunta: "tem AZ VF na carteira do Atacadao?"

Passo 1 - Resolver produto:
   resolver_produto.py --termo "AZ VF"
   → {"produtos": [{"cod_produto": "AZ001", "nome": "AZEITONA VERDE FATIADA"}]}

Passo 2 - Resolver grupo:
   resolver_grupo.py --grupo atacadao
   → {"prefixos_cnpj": ["93.209.76", "75.315.33", "00.063.96"]}

Passo 3 - Consultar:
   (usar gerindo-expedicao com filtros resolvidos)

Cenario 3: Multiplos resultados

Pergunta: "pedido 123"

Passo 1 - Resolver:
   resolver_pedido.py --termo 123
   → {"multiplos": true, "pedidos": ["VCD1234", "VCD5123", "VFB123"]}

Resposta: "Encontrei 3 pedidos com '123'. Qual voce quer?
   - VCD1234 (Atacadao 183)
   - VCD5123 (Assai Guarulhos)
   - VFB123 (Tenda Centro)"