feat(crm-ops): adiciona plugin crm-ops (agents, skills, knowledge e metadados do projeto)
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user