---
name: crm-ops
description: 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.
disable-model-invocation: 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.

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

*Adicionar nova linha após cada erro corrigido.*