--- 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: "") - Se alguma despesa tem reference_no IGUAL → DUPLICADO → PARAR Camada 1 — Fornecedor + Valor + Data: - get_expenses(search: "") - Mesmo fornecedor + valor (±0.05) + data (±3 dias) = duplicado Camada 2 — Expense name: - get_expenses(search: " - ") - 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/ 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