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

---
name: expense
description: Gestao de despesas Desk CRM com PDF obrigatorio. Registar, categorizar e analisar despesas com verificacao de duplicados por reference_no, upload SFTP e arquivo mensal automatico.
---

# /expense - Gestao de Despesas

Skill para gestao de despesas com verificacao obrigatoria de categorias existentes.

## Quando Usar

- Registar nova despesa
- Criar/gerir categorias de despesas
- Consultar despesas por periodo/categoria
- Associar despesas a projectos/clientes
- Analise e relatorios de despesas
- Processar despesas de tickets de contabilidade (departamento 3)
- Importar recibos de servicos (Anthropic, Hetzner, etc.)

## Quando NAO Usar

- Para facturas a clientes (usar /invoice)
- Para orcamentos (usar /orcamento)
- Para pagamentos recebidos (usar /crm)

---

## REGRA CRITICA: CATEGORIAS

> **PROIBIDO criar categoria sem verificar se ja existe.**

```
1. Listar categorias: get_expense_categories(with_stats=true)
2. Pesquisar por nome similar na lista
3. SE encontrar match ou similar: USAR a categoria existente
4. SE realmente nao existe: PERGUNTAR "Nao encontrei categoria para X. Criar nova?"
5. SO CRIAR apos confirmacao explicita
```

**Violacao desta regra causa duplicados que prejudicam relatorios financeiros.**

Para mapeamento completo de fornecedores, emails e padroes PDF para categorias: ver `references/category-mapping.md`

---

## Protocolo: Registar Despesa

> **Gate PDF obrigatorio:** Sem documento, nao regista. Unica excepcao: bypass explicito do utilizador (AT/Salario sem recibo).

```
1. GATE PDF: Verificar que existe ficheiro PDF
   - SE utilizador forneceu PDF: prosseguir
   - SE nao forneceu: PEDIR o ficheiro
   - SE nao tem e pede bypass: PERGUNTAR "Confirmas despesa sem documento?"
   - Bypass valido apenas para: AT, Salarios, transferencias bancarias
2. LER O PDF: Extrair dados reais do documento
   - NUNCA copiar valor de um PDF para outro
   - EXTRAIR reference_no (numero factura) — OBRIGATORIO para dedup
3. OBRIGATORIO: get_expense_categories(with_stats=true)
4. Identificar categoria correcta na lista
5. VERIFICAR DUPLICADOS (3 camadas — OBRIGATORIO):
   Camada 0 — Referencia de factura (PRIMARIA):
   - get_expenses(search: "<reference_no>")
   - Se alguma despesa tem reference_no IGUAL → DUPLICADO → PARAR
   Camada 1 — Fornecedor + Valor + Data:
   - get_expenses(search: "<fornecedor>")
   - Mesmo fornecedor + valor (±0.05) + data (±3 dias) = duplicado
   Camada 2 — Expense name:
   - get_expenses(search: "<fornecedor> - <reference_no>")
   - Se match exacto → duplicado
   Se QUALQUER camada detecta duplicado → NAO criar, informar utilizador
6. Recolher dados:
   - category_id, amount, currency (EUR=3, USD=2), date (YYYY-MM-DD)
   - reference_no (numero factura — OBRIGATORIO)
   - note (incluir numero factura), send_invoice_to_customer = 0
   - Opcionais: client_id, project_id, billable, tax
7. CONFIRMAR com utilizador (mostrar resumo)
8. create_expense (INCLUIR reference_no no payload)
9. UPLOAD PDF ao Desk via SFTP:
   a. mkdir -p no servidor: /home/ealmeida/desk.descomplicar.pt/uploads/expenses/<id>
   b. mcp__ssh-unified__sftp_upload(server:"desk", local_path, remote_path)
   c. chown -R ealmeida:ealmeida
   d. INSERT INTO tblfiles (rel_id, rel_type='expense', ...)
10. ARQUIVO MENSAL: Mover PDF para Contabilidade/YYYY/NN-NomeMes/
11. Confirmar criacao ao utilizador
```

## Protocolo: Criar Categoria

```
1. get_expense_categories() - listar todas
2. Verificar se existe categoria similar
3. SE existe similar: USAR ESSA, nao criar
4. SE nao existe: perguntar confirmacao ao utilizador
5. SO APOS confirmacao: criar
```

## Protocolo: Consultar Despesas

```
1. get_expenses com filtros: category, date_from/date_to, client_id, project_id, limit
2. Apresentar resumo ao utilizador
```

## Protocolo: Analise de Despesas

```
1. expense_analytics: period ("month"/"quarter"/"year"), breakdown_by ("category"/"client"/"project")
2. Apresentar insights: total por categoria, tendencias, categorias mais usadas
```

## Processar Despesas de Tickets

Para protocolo completo de processamento de tickets de contabilidade: ver `references/ticket-processing.md`

**Resumo:** Obter ticket -> verificar anexos -> verificar duplicados (3 camadas) -> extrair dados -> confirmar -> criar despesa -> upload PDF -> arquivo mensal.

---

## Comandos

| Comando | Descricao |
|---------|-----------|
| `/expense create` | Registar nova despesa |
| `/expense list` | Listar despesas recentes |
| `/expense categories` | Listar categorias disponiveis |
| `/expense report [periodo]` | Relatorio de despesas |
| `/expense search [termo]` | Pesquisar despesas |

## MCP Tools

**Despesas:** `get_expenses`, `create_expense`, `update_expense`, `delete_expense`, `bill_expense_to_customer`
**Categorias:** `get_expense_categories` (usar with_stats=true)
**Analise:** `expense_analytics`

---

## Anti-Patterns (NUNCA fazer)

**Categorias:**
1. Criar categoria sem listar existentes primeiro
2. Assumir que categoria nao existe
3. Criar categoria com nome similar a existente

**Despesas:**
4. Criar despesa sem category_id
5. Nao validar data (formato YYYY-MM-DD)
6. Criar despesa sem verificar duplicados primeiro (3 camadas obrigatorias)
7. Criar despesa sem reference_no (chave primaria de dedup)

**Valores de PDFs:**
8. Assumir que ficheiros com nomes semelhantes tem o mesmo valor
9. SEMPRE ler CADA PDF individualmente para extrair o valor real

**Tickets:**
10. Processar ticket sem verificar anexos PDF
11. Assumir que ticket com recibo = despesa nao lancada

---

## Checklist Pre-Operacao

- [ ] Listar categorias existentes
- [ ] Validar categoria correcta
- [ ] Extrair reference_no do PDF/factura
- [ ] Verificar duplicados (3 camadas)
- [ ] Confirmar dados com utilizador
- [ ] Usar formato data YYYY-MM-DD
- [ ] Incluir reference_no no create_expense
- [ ] Incluir nota descritiva

---

## Referencias

- `references/category-mapping.md` - Mapeamento fornecedores, emails, padroes PDF, campos, moedas, SQL
- `references/ticket-processing.md` - Protocolo completo de processamento de tickets
- `references/changelog.md` - Historico de alteracoes



---

## Self-Healing

Antes de executar, ler `~/.claude-work/healing/expense.jsonl` (se existir). Cada linha é um padrão de erro conhecido:

```json
{"date":"YYYY-MM-DD","issue":"descrição do problema","fix":"como evitar","source":"user|auto"}
```

Se encontrares um padrão relevante ao contexto actual, aplica o fix preventivamente. Após cada erro ou correcção do utilizador nesta skill, **adicionar nova linha** ao healing log com o padrão aprendido.

---

**Criado:** 2026-02-05 | **Actualizado:** 2026-03-30 | Fix: dedup 3 camadas com reference_no (DES-137)


## Healing Log
<!-- Registo automático de erros e correcções nesta skill -->