claude-plugins/crm-ops/skills/billing-check/SKILL.md

---
name: billing-check
description: Verificação de facturação e validação de facturas. Sincroniza facturas Moloni com horas Desk CRM para projectos 360, compara horas facturadas vs entregues e calcula saldos.
---

# Billing Check - Desk vs Moloni (v2.0)

Sincroniza facturas Moloni com horas Desk CRM para projectos 360.

---

## EXECUÇÃO AUTOMÁTICA

| Dia do Mês | Acção |
|------------|-------|
| **5, 15, 25** | Sincronizar facturas Moloni → tabela `billing_360_invoices` |

> O dashboard plan-eal.descomplicar.pt mostra dados em tempo real da BD.

---

## BASE DE DADOS

### Tabelas (ealmeida_desk24)

```sql
-- Clientes 360
billing_360_clients (
  id, client_name, desk_client_id, desk_project_id,
  moloni_customer_id, monthly_hours, active
)

-- Facturas sincronizadas
billing_360_invoices (
  id, client_id, moloni_invoice_id, invoice_number,
  invoice_date, hours_invoiced, amount, synced_at
)

-- Log de sincronizações
billing_360_sync (
  id, sync_date, invoices_processed, status, notes
)
```

### Clientes Activos

| Cliente | desk_project_id | moloni_customer_id | Horas/Mês |
|---------|-----------------|-------------------|-----------|
| SolarFV | 67 | 96914420 | 10h |
| Carstuff | 77 | 128784439 | 30h |

---

## PROTOCOLO DE EXECUÇÃO

### 1. Obter Data Actual

```
mcp__mcp-time__current_time (timezone: Europe/Lisbon)
```

### 2. Verificar Clientes 360 Activos

```sql
SELECT * FROM billing_360_clients WHERE active = 1
```

### 3. Para Cada Cliente: Obter Facturas Moloni

```
Sequência MCP Moloni:
1. moloni_documents_invoices_getall
   - company_id: 69473
   - customer_id: [moloni_customer_id]
   - year: [ano_corrente]

2. Para cada factura, extrair horas com regex:
   /Avença\s+(\d+)\s+horas.*360/i
```

### 4. Inserir Novas Facturas

```sql
INSERT INTO billing_360_invoices
  (client_id, moloni_invoice_id, invoice_number, invoice_date, hours_invoiced, amount)
VALUES (?, ?, ?, ?, ?, ?)
ON DUPLICATE KEY UPDATE synced_at = NOW()
```

### 5. Registar Sincronização

```sql
INSERT INTO billing_360_sync (sync_date, invoices_added, status, details)
VALUES (NOW(), ?, 'success', ?)
```

---

## CÁLCULO DE SALDO

O dashboard calcula automaticamente:

```php
// Horas entregues (timesheets Desk)
SELECT SUM(
  CASE
    WHEN LENGTH(start_time) < 15 THEN (end_time - start_time) / 3600  -- Unix timestamp
    ELSE TIMESTAMPDIFF(SECOND, start_time, end_time) / 3600          -- Datetime
  END
) FROM tbltaskstimers tt
INNER JOIN tbltasks t ON tt.task_id = t.id
WHERE t.rel_id = [desk_project_id] AND t.rel_type = 'project'

// Horas facturadas (Moloni)
SELECT SUM(hours_invoiced) FROM billing_360_invoices WHERE client_id = ?

// Saldo
Saldo = Horas_Facturadas - Horas_Entregues
```

### Interpretação

| Saldo | Status | Significado |
|-------|--------|-------------|
| > +5h | 🟢 credit | Temos crédito (cliente não usou) |
| -5h a +5h | 🟡 ok | Equilibrado |
| < -5h | 🔴 debt | Devemos horas (trabalhámos mais) |

---

## MCPs NECESSÁRIOS

### Carregar Tools

```
ToolSearch: "+moloni invoices"
ToolSearch: "+desk timesheets"
```

### Moloni

| Tool | Uso |
|------|-----|
| `moloni_company_company_getall` | Company ID (69473) |
| `moloni_documents_invoices_getall` | Listar facturas |
| `moloni_documents_invoices_getone` | Detalhe factura |

### Desk CRM

| Tool | Uso |
|------|-----|
| `get_timesheets` | Horas por projecto |
| `timesheet_summary` | Resumo período |

---

## EXEMPLO DE USO

```
/billing-check                    # Sincronizar todos
/billing-check --client SolarFV   # Apenas SolarFV
/billing-check --report           # Relatório sem sync
```

### Output Esperado

```markdown
## Billing Check - 2026-02-02

### Sincronização Moloni → BD

| Cliente | Facturas Novas | Total Sync |
|---------|---------------|------------|
| SolarFV | 1 | 3 |
| Carstuff | 0 | 2 |

### Saldos Actuais

| Cliente | Facturado | Entregue | Saldo | Status |
|---------|-----------|----------|-------|--------|
| SolarFV | 30h | 28.5h | +1.5h | 🟡 OK |
| Carstuff | 60h | 72.3h | -12.3h | 🔴 DEBT |

### Alertas
⚠️ **Carstuff**: 12.3h extra por facturar (~501€)
```

---

## VALORES DE REFERÊNCIA (2026)

| Cliente | Avença | Valor/Hora | Valor Mensal |
|---------|--------|------------|--------------|
| SolarFV | 10h/mês | 45.90€ | 459€ + IVA |
| Carstuff | 30h/mês | 40.80€ | 1224€ + IVA |

---

## TROUBLESHOOTING

### Factura sem padrão "Avença X horas"
- Verificar descrição manual
- Pode ser factura de extras (não contar como avença)

### Cliente novo
1. Adicionar à tabela `billing_360_clients`
2. Obter `moloni_customer_id` via pesquisa
3. Definir `monthly_hours` do contrato

### Timestamps mistos no Desk
- O query do dashboard já trata Unix e datetime
- Conversão automática

---

## CHANGELOG

### v2.0.0 (2026-02-02)
- Integração com tabelas BD (billing_360_*)
- Sincronização automática dias 5, 15, 25
- Dashboard dinâmico em plan-eal.descomplicar.pt
- Tratamento de timestamps híbridos

### v1.0.0 (2026-01-27)
- Versão inicial
- Documentação de mapeamento Desk ↔ Moloni

---

**Dashboard:** https://plan-eal.descomplicar.pt
**Versão**: 2.0.0 | **Autor**: Descomplicar®

---


## Quando NÃO Usar

- Para tarefas fora do domínio de especialização desta skill
- Quando outra skill mais específica está disponível
- Para operações que requerem aprovação manual obrigatória
- Quando os requisitos não estão claramente definidos


## Protocolo de Execução

1. **Análise Inicial**
   - Verificar requisitos e contexto
   - Identificar ferramentas necessárias

2. **Preparação**
   - Validar acesso a recursos
   - Preparar ambiente de trabalho

3. **Execução**
   - Executar operações de forma incremental
   - Validar cada passo antes de prosseguir

4. **Validação**
   - Verificar resultados obtidos
   - Confirmar sucesso da operação

5. **Conclusão**
   - Documentar alterações realizadas
   - Reportar status final e próximos passos


## Exemplos de Uso

### Exemplo 1: Caso Básico
```
User: [requisição simples relacionada com billing-check]
Skill: [execução directa com validação]
Output: [resultado conciso e accionável]
```

### Exemplo 2: Caso Complexo
```
User: [requisição multi-passo ou complexa]
Skill:
  1. Análise dos requisitos
  2. Planeamento da abordagem
  3. Execução faseada
  4. Validação contínua
Output: [resultado detalhado com próximos passos]
```

### Exemplo 3: Caso com Dependências
```
User: [requisição que depende de outros sistemas]
Skill:
  1. Verificar dependências disponíveis
  2. Coordenar com skills/MCPs necessários
  3. Executar workflow integrado
Output: [resultado completo com referências]
```