feat(crm-ops): adiciona plugin crm-ops (agents, skills, knowledge e metadados do projeto)

This commit is contained in:
2026-10-28 16:08:32 +00:00
parent 83a69e681c
commit 81d1373977
61 changed files with 6037 additions and 0 deletions
+143
View File
@@ -0,0 +1,143 @@
---
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.
layer: wiki
---
# /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 qu
@@ -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)` |
@@ -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
@@ -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
```