feat: refactor 30+ skills to Anthropic progressive disclosure pattern

- All SKILL.md files now <500 lines (avg reduction 69%) - Detailed content extracted to references/ subdirectories - Frontmatter standardised: only name + description (Anthropic standard) - New skills: brand-guidelines, spec-coauthor, report-templates, skill-creator - Design skills: anti-slop guidelines, premium-proposals reference - Removed non-standard frontmatter fields (triggers, version, author, category) Plugins affected: infraestrutura, marketing, dev-tools, crm-ops, gestao, core-tools, negocio, perfex-dev, wordpress, design-media Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-12 15:05:03 +00:00
parent 9404af7ac9
commit 6b3a6f2698
397 changed files with 67154 additions and 17257 deletions
--- a/crm-ops/skills/expense/references/category-mapping.md
+++ b/crm-ops/skills/expense/references/category-mapping.md
@@ -0,0 +1,187 @@
+# /expense - Mapeamento de Categorias e Dados Técnicos
+
+## Categorias Activas (consolidacao 12-02-2026)
+
+| ID | Nome | Fornecedores típicos |
+|----|------|---------------------|
+| 1 | Telecomunicacoes | MEO |
+| 4 | Alojamento web (Hosting) | Hetzner, CWP |
+| 6 | Servicos Externos | Make/Celonis, Gamma |
+| 14 | Subscricoes e Servicos Digitais | YouTube Premium, BdThemes |
+| 28 | Licencas Software | Canva, Cursor, Descript, GitHub, Softaculous |
+| 30 | Servicos Cloud e Infraestrutura | Google One, Google Workspace, ElasticEmail |
+| 37 | Dominios | PTisp, Namecheap |
+| 38 | Servicos IA e APIs | Anthropic, OpenRouter, CapSolver, Replicate |
+
+Existem ~30 categorias na BD mas apenas 8 são usadas regularmente. SEMPRE usar `get_expense_categories()` para lista completa.
+
+---
+
+## Mapeamento Fornecedor → Categoria
+
+| Fornecedor | Categoria ID | Nome |
+|-----------|-------------|------|
+| Anthropic, OpenRouter, CapSolver, Replicate | 38 | Servicos IA e APIs |
+| Canva, Cursor, Descript, GitHub, Softaculous, CWP | 28 | Licencas Software |
+| Google One, Google Workspace, ElasticEmail | 30 | Servicos Cloud e Infraestrutura |
+| Hetzner | 4 | Alojamento web (Hosting) |
+| MEO | 1 | Telecomunicacoes |
+| PTisp, Namecheap | 37 | Dominios |
+| Make/Celonis, Gamma | 6 | Servicos Externos |
+| YouTube Premium, BdThemes | 14 | Subscricoes e Servicos Digitais |
+
+---
+
+## Mapeamento Email → Categoria
+
+| Dominio Email | Categoria ID | Fornecedor |
+|---------------|--------------|------------|
+| anthropic.com | 38 | Anthropic |
+| openrouter.ai | 38 | OpenRouter |
+| payproglobal.com | 38 | CapSolver |
+| replicate.com | 38 | Replicate |
+| cursor.com, anysphere.dev | 28 | Cursor |
+| canva.com | 28 | Canva |
+| descript.com | 28 | Descript |
+| github.com | 28 | GitHub |
+| softaculous.com | 28 | Softaculous |
+| centos-webpanel.com | 28 | CWP |
+| elasticemail.com | 30 | ElasticEmail |
+| google.com (One/Workspace) | 30 | Google Cloud |
+| hetzner.com | 4 | Hetzner |
+| meoempresas.pt | 1 | MEO |
+| namecheap.com | 37 | Namecheap |
+| ptisp.pt | 37 | PTisp |
+| make.com, celonis.com | 6 | Make/Celonis |
+| gamma.app | 6 | Gamma |
+
+> `moloni.com` NAO incluido - é plataforma de facturação.
+
+---
+
+## Mapeamento Padrão PDF → Categoria
+
+| Padrão no PDF | Fornecedor | Categoria ID |
+|---------------|-----------|--------------|
+| `Gondooffice`, `Cubic Choices` | Gondooffice | 21 Contabilidade |
+| `Autoridade Tributaria`, `emiteDoc`, `AT -` | AT | 15 Planos Prestacionais |
+| `Staples`, `STP_ECOFACTURA` | Staples | 3 Material Escritorio |
+| `MEO`, `meoempresas` | MEO | 1 Telecomunicacoes |
+| `TOConline`, `Recibo de Vencimento` | Salario | 22 Salarios |
+| `Seguranca Social` | SS | 25 Contribuicoes SS |
+| `Cursor`, `Anysphere` | Cursor | 28 Licencas Software |
+| `Anthropic` | Anthropic | 38 Servicos IA e APIs |
+| `Hetzner` | Hetzner | 4 Alojamento web |
+| `ElasticEmail` | ElasticEmail | 30 Servicos Cloud |
+
+---
+
+## Campos create_expense
+
+| Campo | Tipo | Obrigatório | Descrição |
+|-------|------|-------------|-----------|
+| category_id | number | Sim | ID da categoria |
+| amount | number | Sim | Valor da despesa |
+| date | string | Sim | Data (YYYY-MM-DD) |
+| note | string | Sim | Descrição (incluir ticket ID) |
+| reference | string | Sim | Número fatura/recibo |
+| tax | number | Sim | ID da taxa (1 = IVA 23%) |
+| currency | number | Sim | EUR = **3**, USD = 2 |
+| send_invoice_to_customer | number | Sim | Sempre **0** |
+| client_id | number | Não | Cliente associado |
+| project_id | number | Não | Projecto associado |
+| billable | boolean | Não | Facturável (default: false) |
+
+---
+
+## Moedas
+
+| ID | Nome | Símbolo | Default |
+|----|------|---------|---------|
+| 2 | USD | $ | Não |
+| 3 | EUR | € | Sim |
+
+> **CRITICO:** EUR = **3**, USD = **2**. `currency = 1` não existe e causa despesas invisíveis nos relatórios.
+
+---
+
+## Taxas de Imposto
+
+| ID | Nome | Taxa |
+|----|------|------|
+| 1 | IVA Tx Normal | 23% |
+
+---
+
+## Comandos SQL
+
+```sql
+-- 1. VERIFICAR DUPLICADOS (EXECUTAR PRIMEIRO)
+SELECT id, amount, date, note, reference_no FROM tblexpenses
+WHERE reference_no LIKE '%{receipt_number}%'
+   OR note LIKE '%ticket #{ticket_id}%'
+
+-- 2. Verificar anexos do ticket
+SELECT id, file_name, filetype FROM tblticket_attachments WHERE ticketid = {ID}
+
+-- 3. Actualizar nome fornecedor (obrigatorio apos criar)
+UPDATE tblexpenses SET expense_name = '{Fornecedor}' WHERE id = {expense_id}
+
+-- 4. Registar anexo na despesa
+INSERT INTO tblfiles (rel_id, rel_type, file_name, filetype, visible_to_customer, staffid, contact_id, dateadded)
+VALUES ({expense_id}, 'expense', '{filename}', 'application/pdf', 0, 1, 0, NOW())
+```
+
+---
+
+## Extracção de Dados de PDFs
+
+**Método 1: Script Python (recomendado)**
+```bash
+python3 /home/ealmeida/scripts/extract_invoice_data.py /path/to/invoice.pdf
+```
+Retorna JSON com: vendor, cat_id, total, date, invoice, currency, text
+
+**Método 2: pdfplumber directo**
+```bash
+python3 -c "
+import pdfplumber
+with pdfplumber.open('/path/to/file.pdf') as pdf:
+    for p in pdf.pages:
+        t = p.extract_text()
+        if t: print(t)
+" | grep -iE "total|iva|€"
+```
+
+**Método 3: pdftotext (fallback)**
+```bash
+pdftotext /path/to/file.pdf - | head -80
+```
+
+---
+
+## Paths de Ficheiros
+
+- Anexos ticket: `/uploads/ticket_attachments/{ticketid}/`
+- Anexos despesa: `/uploads/expenses/{expenseid}/`
+- Arquivo mensal: `/media/ealmeida/Dados/GDrive/Cloud/ADM_Descomplicar/Financeiro/Contabilidade/YYYY/NN-NomeMes/`
+- Credenciais BD: `/home/ealmeida/desk.descomplicar.pt/application/config/app-config.php`
+
+---
+
+## Tickets a Saltar
+
+| Tipo | Descrição | Acção |
+|------|-----------|-------|
+| Payment Receipt | Recibo de pagamento (não é fatura) | SALTAR |
+| Duplicado | Mesmo nº fatura já processado | SALTAR |
+| Sem anexo PDF | Apenas notificação por email | SALTAR |
+
+---
+
+## Campos para Rastreio de Duplicados
+
+| Campo | Conteúdo | Exemplo |
+|-------|----------|---------|
+| reference | Número do recibo | `2810-3712-9577` |
+| note | Incluir ticket ID | `Anthropic Max (ticket #9648)` |
--- a/crm-ops/skills/expense/references/changelog.md
+++ b/crm-ops/skills/expense/references/changelog.md
@@ -0,0 +1,56 @@
+# /expense - Changelog
+
+## v2.0.0 (2026-02-12) - Sistema Robusto 2026
+
+- **Gate PDF obrigatorio:** Despesa sem documento nao e registada (bypass explicito para AT/Salario)
+- **Upload SFTP:** Substituido `cp` local por `mcp__ssh-unified__sftp_upload` (Regra #41)
+- **Arquivo mensal:** PDF organizado em `Contabilidade/YYYY/NN-NomeMes/` automaticamente
+- **Campo `send_invoice_to_customer`:** Documentado como obrigatorio na BD (valor 0)
+- **Correccao currency:** EUR = **3** (nao 2), USD = **2**. Corrigido em toda a skill
+- **Categorias alinhadas com consolidacao:** 8 categorias activas com mapeamento correcto
+  - Cursor/Canva/Descript/GitHub/Softaculous/CWP -> 28 (Licencas Software)
+  - Hetzner -> 4 (Alojamento web)
+  - ElasticEmail/Google -> 30 (Servicos Cloud)
+  - PTisp/Namecheap -> 37 (Dominios)
+  - YouTube/BdThemes -> 14 (Subscricoes)
+  - Make/Gamma -> 6 (Servicos Externos)
+- **Verificacao duplicados reforcada:** Integrada no passo 5 do protocolo
+- **MCP ssh-unified adicionado** a dependencias
+- **Procedimento:** `06-Operacoes/Procedimentos/PROC-Skill-Expense.md`
+
+## v1.5.0 (2026-02-05)
+
+- Adicionado mapeamento **Cursor (Anysphere)** -> categoria 38 (Servicos IA e APIs)
+
+## v1.4.0 (2026-02-05)
+
+- **CORRECCAO CRITICA:** ID moeda EUR = **2** (nao 1)
+- Despesas com currency=1 nao aparecem em relatorios
+- Corrigidas 22 despesas existentes via `UPDATE tblexpenses SET currency = 2 WHERE currency = 1`
+
+## v1.3.0 (2026-02-05)
+
+- **Conversao USD -> EUR obrigatoria** (taxa ~0.92, $19.99 -> 18.39 EUR)
+- **Processamento em lote** quando utilizador pede "criar todas"
+- Tickets a saltar documentados (payment receipts, duplicados, sem PDF)
+- 9 despesas processadas em sessao de teste: 857.73 EUR total
+
+## v1.2.0 (2026-02-05)
+
+- Campo `expense_name` obrigatorio com nome do fornecedor (via SQL UPDATE)
+- Campo `tax` e ID da taxa de imposto (1 = IVA 23%), nao percentagem
+- Coluna BD e `reference_no`, nao `reference`
+- Script Python para extraccao de PDFs
+- 3 metodos de extraccao PDF documentados
+
+## v1.1.0 (2026-02-05)
+
+- Processamento de despesas a partir de tickets de contabilidade
+- Mapeamento automatico email domain -> categoria
+- Workflow completo com verificacao de anexos PDF
+
+## v1.0.0 (2026-02-05)
+
+- Versao inicial
+- Regra critica de verificacao de categorias
+- Criada apos limpeza de 9 categorias duplicadas
--- a/crm-ops/skills/expense/references/ticket-processing.md
+++ b/crm-ops/skills/expense/references/ticket-processing.md
@@ -0,0 +1,75 @@
+# /expense - Processamento de Despesas de Tickets
+
+## Regras
+
+1. Processar tickets UM A UM com confirmacao do utilizador (ou em lote se solicitado)
+2. Verificar SEMPRE se despesa ja foi lancada (prevenir duplicados)
+3. NAO adicionar respostas aos tickets - apenas criar despesa e anexos
+4. Manter valor original na moeda do documento (EUR=3, USD=2)
+5. Saltar tickets que sao apenas recibos de pagamento (nao sao facturas)
+
+---
+
+## Protocolo Ticket a Ticket
+
+```
+1. Obter ticket: get_ticket(ticket_id)
+2. Verificar anexos: SELECT * FROM tblticket_attachments WHERE ticketid = X
+3. SE nao tem PDFs: SALTAR ticket (apenas notificacao)
+4. VERIFICAR DUPLICADOS (OBRIGATORIO):
+   SELECT id, amount, date, note FROM tblexpenses
+   WHERE reference_no LIKE '%{receipt_number}%' OR note LIKE '%ticket #{ticket_id}%'
+   SE encontrar: PARAR e informar "Despesa ja existe: #ID"
+5. Extrair dados:
+   - Do HTML do ticket (valor, data, referencia)
+   - OU usar script Python: python3 /home/ealmeida/scripts/extract_invoice_data.py {pdf_path}
+6. APRESENTAR resumo ao utilizador e AGUARDAR confirmacao
+7. Apos confirmacao:
+   a. SQL: INSERT INTO tblexpenses (..., send_invoice_to_customer, ...) VALUES (..., 0, ...)
+      OU create_expense via MCP (se disponivel)
+   b. UPDATE tblexpenses SET expense_name = '{Fornecedor}' WHERE id = {id}
+   c. mcp__ssh-unified__ssh_execute: mkdir -p uploads/expenses/{expenseid}
+   d. mcp__ssh-unified__sftp_upload: PDF para uploads/expenses/{expenseid}/
+   e. mcp__ssh-unified__ssh_execute: chown -R ealmeida:ealmeida uploads/expenses/{expenseid}
+   f. SQL: INSERT INTO tblfiles (rel_id, rel_type, file_name, filetype,
+      visible_to_customer, staffid, contact_id, dateadded)
+      VALUES ({id}, 'expense', '{file}', 'application/pdf', 0, 1, 0, NOW())
+   g. Mover PDF para arquivo mensal: Contabilidade/YYYY/NN-NomeMes/
+8. Confirmar ao utilizador e passar ao proximo
+```
+
+---
+
+## Processamento em Lote
+
+Se utilizador pedir "criar todas" ou "processar em lote":
+1. Obter todos os tickets pendentes em paralelo
+2. Identificar duplicados e tickets a saltar
+3. Criar despesas em paralelo via `create_expense`
+4. Actualizar `expense_name` e `reference_no` em batch via SQL
+5. Copiar PDFs em batch
+6. Registar ficheiros em batch via SQL INSERT multiplo
+
+---
+
+## Tickets a Saltar
+
+| Tipo | Descricao | Accao |
+|------|-----------|-------|
+| Payment Receipt | Recibo de pagamento (nao e fatura) | SALTAR |
+| Duplicado | Mesmo numero fatura ja processado | SALTAR |
+| Sem anexo PDF | Apenas notificacao por email | SALTAR |
+
+Exemplos:
+- "Invoice Payment Confirmation" (e recibo, nao fatura)
+- Ticket com mesmo invoice_number de outro ja processado
+
+---
+
+## Credenciais Base de Dados
+
+Localizacao: `/home/ealmeida/desk.descomplicar.pt/application/config/app-config.php`
+
+```bash
+grep -E "APP_DB" /home/ealmeida/desk.descomplicar.pt/application/config/app-config.php
+```