claude-plugins/crm-ops/skills/crm-ops/SKILL.md

name, description, disable-model-invocation

name	description	disable-model-invocation
crm-ops	Operações CRM seguras com verificação obrigatória de duplicados e confirmações. Distinção Lead vs Customer, Proposal vs Estimate. Criação de entidades CRM.	true

/crm-ops - Operações CRM Seguras

Skill para operações CRM com verificações obrigatórias de duplicados e confirmações.

Metadata

• Version: 1.2.0
• Author: Descomplicar
• Date: 2026-01-28
• Status: Active

---

Quando Usar

• Criar lead, customer, proposal, estimate
• Pesquisar entidades CRM
• Converter lead para customer
• Operações que envolvem orçamentos/propostas
• Qualquer operação que pode criar duplicados

Quando NÃO Usar

• Para desenvolvimento WordPress (usar /wp-dev)
• Para criar orçamentos completos (usar /orcamento)
• Para análise de leads (usar /lead-approach)

---

DEFINIÇÕES CRÍTICAS

Lead vs Customer

Aspecto	LEAD	CUSTOMER
O que é	Contacto inicial, prospect	Cliente com relação comercial
Quando usar	Primeiro contacto, ainda a avaliar	Após qualificação, vai comprar
Tabela	tblleads	tblclients + tblcontacts
Recebe	Proposals (orçamentos)	Estimates, Invoices
Conversão	Pode virar Customer	Já é cliente

REGRA: Novos contactos são SEMPRE leads primeiro. Só se tornam customers após qualificação.

Proposal vs Estimate

Aspecto	PROPOSAL (Orçamento)	ESTIMATE
Para quem	LEADS (prospects)	CUSTOMERS (clientes)
Quando usar	Utilizador pede "orçamento"	Cliente existente, pedido formal
Tabela	tblproposals	tblestimates
Converte para	Nada (lead vira customer primeiro)	Invoice directamente
Termo PT	Orçamento, Proposta	Estimativa

IMPORTANTE: Quando o utilizador pede um "orçamento", usar PROPOSAL (para leads). Estimates são para clientes já existentes com pedidos formais.

Fluxo Comercial Correcto

┌─────────────────────────────────────────────────────────────────────┐
│                     FLUXO COMERCIAL PERFEX                          │
└─────────────────────────────────────────────────────────────────────┘

     LEAD                              CUSTOMER
       │                                   │
       ▼                                   ▼
   PROPOSAL ──────────────────────▶   ESTIMATE
  (orçamento)    converter lead       (formal)
       │          para customer           │
       │               │                  ▼
       │               │              INVOICE
       │               │                  │
       └───────────────┴──────────────────┘
                       │
                       ▼
                   PAYMENT

Resumo:

• Lead + Orçamento = Proposal
• Customer + Orçamento formal = Estimate
• Estimate aceite = Invoice

---

Protocolo

REGRA 0: NUNCA CRIAR SEM VERIFICAR (CRÍTICA)

PROIBIDO criar Lead ou Customer sem verificar se já existe.

Esta regra é INVIOLÁVEL. Mesmo que o utilizador peça para criar, PRIMEIRO:

1. Pesquisar em LEADS: get_leads() + filtrar por nome/email/empresa
2. Pesquisar em CUSTOMERS: search_customers(termo)
3. SE encontrar match:
   - MOSTRAR resultados ao utilizador
   - PERGUNTAR: "Encontrei [X]. É este ou criar novo?"
4. SE não encontrar:
   - PERGUNTAR: "Não encontrei [Nome]. Confirmas criação?"
5. SÓ CRIAR após confirmação explícita

Violação desta regra causa duplicados que prejudicam operações comerciais.

REGRA 1: VERIFICAR DUPLICADOS (Detalhado)

ANTES de criar QUALQUER entidade (Lead, Customer, Proposal, Estimate):

1. Pesquisar por nome/email/empresa:
   • search_customers para clientes
   • get_leads com filtro search para leads
2. Se match encontrado: MOSTRAR ao utilizador
3. Se match parcial: PERGUNTAR se é o mesmo
4. Se sem match: PERGUNTAR confirmação antes de criar

REGRA 2: CONFIRMAR ANTES DE CRIAR

NUNCA criar entidade sem confirmação EXPLÍCITA:

• Lead: "Não encontrei este contacto. Criar lead [Nome] com email [Email]?"
• Customer: "Criar cliente [Empresa]? (ACÇÃO IRREVERSÍVEL - só para clientes qualificados)"
• Proposal: "Criar orçamento para lead [Nome] no valor de [X]?"
• Estimate: "Criar estimativa formal para cliente [Empresa] no valor de [X]?"

REGRA 3: MODELO DE DADOS PERFEX

Regra	Descrição
Email em tblcontacts	Email do cliente está em tblcontacts, NÃO em tblclients
userid é o ID	Usar userid para clientes, não customer_id
Contacto principal	is_primary = 1 para contacto principal
Source obrigatório	Leads precisam de source_id (buscar default)
Itens em tblitemable	Todos os itens (estimate, invoice, proposal) usam tblitemable com rel_type
rel_type para items	'estimate', 'invoice', 'proposal', 'credit_note'

Comandos

Comando	Descrição
/crm-ops search <termo>	Pesquisa unificada em leads + customers
/crm-ops lead create	Criar lead COM verificação de duplicados
/crm-ops lead convert <id>	Converter lead em customer
/crm-ops customer create	Criar customer COM confirmação obrigatória
/crm-ops estimate create	Criar estimate COM validação cliente
/crm-ops status	Mostrar códigos de status

Fluxos Detalhados

Criar Lead

1. Receber dados do lead (nome, email, empresa)
2. search_customers(email/nome)
3. get_leads(search=email/nome)
4. SE match encontrado:
   - Mostrar resultados
   - Perguntar: "Usar existente ou criar novo?"
5. SE criar novo:
   - Buscar source default se não fornecido
   - create_lead
6. Retornar ID do lead criado

Converter Lead para Customer

1. Verificar lead existe: get_lead(lead_id)
2. Mostrar dados do lead ao utilizador
3. Perguntar: "Converter lead X para cliente?"
4. SE confirmado:
   - convert_lead_to_customer
   - Notas são transferidas automaticamente
5. Retornar ID do novo cliente

Criar Customer (SEM lead)

1. SEMPRE perguntar confirmação ao utilizador
2. Verificar se existe lead para converter
   - SE existe: usar convert_lead_to_customer
3. SE não existe lead:
   - search_customers para verificar duplicados
   - Confirmar criação
   - create_customer

Criar Estimate

1. Identificar cliente (perguntar se não especificado)
2. get_customer para verificar se existe
   - SE não existe: PARAR, NÃO criar customer automaticamente
   - Perguntar se deve criar customer primeiro
3. Confirmar itens e valores com utilizador
4. create_estimate
5. Perguntar se deve enviar: send_estimate

Criar Proposal (Suporta Lead OU Customer)

CORRIGIDO v3.5.3: Proposals agora suportam leads directamente.

1. Identificar se é Lead ou Customer
2. Usar o parâmetro correcto:
   - Lead: create_proposal(lead_id=204, subject="...")
   - Customer: create_proposal(client_id=42, subject="...")
3. NÃO usar ambos parâmetros (um OU outro)

Editar Proposal

1. Obter proposal_id
2. update_proposal(proposal_id=X, subject="...", status=2)

Status de Proposal:

• 1 = Draft
• 2 = Sent
• 3 = Open
• 4 = Revised
• 5 = Declined
• 6 = Accepted

Adicionar Itens a Proposal (v3.5.4)

1. Preparar array de itens com: description, qty, rate, unit, long_description
2. Chamar add_proposal_items:
   add_proposal_items(
     proposal_id=78,
     clear_existing=true,  // opcional: limpar itens anteriores
     items=[
       { description: "Serviço X", qty: 1, rate: 500, unit: "un" },
       { description: "Horas Dev", qty: 10, rate: 60, unit: "hora" }
     ]
   )
3. Total da proposta é actualizado automaticamente

Listar Itens de Proposal

get_proposal_items(proposal_id=78)

Retorna lista de itens com quantidade, valor e total calculado.

Converter Estimate para Invoice

1. get_estimate para verificar status
2. SE status != 4 (Aceite): PARAR e informar
3. Confirmar com utilizador
4. convert_estimate_to_invoice
5. Retornar ID da nova factura

Status Codes

Estimates

• 1 = Rascunho
• 2 = Enviado
• 3 = Visto
• 4 = Aceite (pode converter)
• 5 = Recusado
• 6 = Expirado

Proposals

• 1 = Draft
• 2 = Sent
• 3 = Open
• 4 = Revised
• 5 = Declined
• 6 = Accepted

Invoices

• 1 = Unpaid
• 2 = Paid
• 3 = Partially Paid
• 4 = Overdue

MCP Tools

Leads

• get_leads - Listar leads com filtros
• create_lead - Criar lead
• update_lead - Actualizar lead
• convert_lead_to_customer - Converter para cliente
• lead_scoring - Pontuar lead
• lead_analytics - Métricas

Customers

• get_customers - Listar clientes
• get_customer - Detalhes cliente
• create_customer - Criar cliente
• search_customers - Pesquisa multi-campo
• update_customer - Actualizar
• delete_customer - Eliminar
• manage_customer_contacts - Gerir contactos
• create/get/update/delete_customer_note - Notas

Estimates

• get_estimates - Listar orçamentos
• get_estimate - Detalhes
• create_estimate - Criar orçamento
• update_estimate - Actualizar
• send_estimate - Marcar como enviado
• convert_estimate_to_invoice - Converter para factura
• estimate_analytics - Métricas

Proposals

• get_proposals - Listar propostas
• create_proposal - Criar proposta (suporta lead_id OU client_id)
• update_proposal - Editar proposta existente
• add_proposal_items - Adicionar itens/linhas a proposta
• get_proposal_items - Listar itens de uma proposta
• proposal_builder - Construtor interactivo
• proposal_analytics - Métricas

Anti-Patterns (NUNCA fazer)

Criação sem Verificação (CRÍTICO)

1. NUNCA criar lead sem pesquisar se já existe
2. NUNCA criar customer sem pesquisar se já existe
3. NUNCA assumir que entidade não existe - verificar SEMPRE

Confusão de Entidades

4. Criar customer quando devia ser lead (novos contactos = leads)
5. Usar estimate para leads (usar proposal)
6. Usar proposal para customers qualificados (usar estimate)
7. Criar customer automaticamente para associar estimate

Erros Técnicos

8. Converter estimate não-aceite para invoice
9. Aceder a email directamente em tblclients (usar JOIN com tblcontacts)
10. Usar tabelas inventadas (ex: tblitems_in) - verificar schema real primeiro

Terminologia

• Utilizador diz "orçamento" para lead → usar PROPOSAL
• Utilizador diz "orçamento" para cliente existente → usar ESTIMATE

Exemplos

Exemplo 1: Criar lead com verificação

User: /crm-ops lead create nome="João Silva" email="joao@example.com"
→ Pesquisa em leads e customers
→ Não encontra duplicado
→ Pergunta: "Não encontrei João Silva. Confirmas criação?"
→ User: Sim
→ Cria lead #215
→ Confirma: "Lead #215 criado com sucesso"

Exemplo 2: Detectar duplicado

User: /crm-ops customer create empresa="TechStart Lda"
→ Pesquisa customers
→ Encontra match: TechStart Lda (#42)
→ Mostra: "Encontrei TechStart Lda (#42). É este ou criar novo?"
→ User: É esse
→ Retorna dados do cliente existente

Exemplo 3: Proposal para lead

User: Criar orçamento para lead João Silva
→ Verifica que é lead (não customer)
→ Usa create_proposal(lead_id=215)
→ Adiciona itens via add_proposal_items
→ Confirma: "Proposal #78 criada para lead #215"

Checklist Pré-Operação

• Verificar duplicados
• Confirmar com utilizador
• Validar campos obrigatórios
• Usar source/status default se não fornecido
• Mostrar resultado da operação

Integração

• MCP: desk-crm-v3
• Procedimento: PROC-CRM-Operacoes
• CLAUDE.md: Secção "CRM (Perfex/DeskCRM)"

Changelog

v1.2.0 (2026-01-28)

• REGRA 0 adicionada: NUNCA criar lead/customer sem verificar existência
• Secção "DEFINIÇÕES CRÍTICAS" com distinção clara:
  • Lead vs Customer (tabela comparativa)
  • Proposal vs Estimate (tabela comparativa)
• Diagrama de fluxo comercial actualizado
• "Orçamento" = Proposal (para leads), não Estimate
• Anti-patterns reorganizados por categoria
• Terminologia PT clarificada

v1.1.0 (2026-01-28)

• Adicionadas ferramentas de itens: add_proposal_items, get_proposal_items
• Documentado padrão tblitemable para itens de documentos
• Adicionados novos anti-patterns (tabelas inventadas, proposals vs estimates)
• Fluxo completo para adicionar itens a proposals
• Actualizada lista de MCP tools para proposals

v1.0.0 (2026-01-28)

• Versão inicial completa
• Fluxo comercial documentado
• Regras de verificação
• Status codes
• Integração com MCP desk-crm-v3

v0.1.0 (2026-01-28)

• Estrutura inicial da skill
• Definição de comandos e fluxos

---

Criado: 2026-01-28 Actualizado: 2026-01-28 Motivo: Prevenção de erros CRM após incidente de duplicação

---

Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

{"date":"","issue":"","fix":"","source":"user|auto"}

Adicionar nova linha após cada erro corrigido.