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

name, description, layer

name	description	layer
billing-check	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.	wiki

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)

-- 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

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

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

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

---

CÁLCULO DE SALDO

O dashboard calcula automaticamente:

// 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

## 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 ↔