ligbox-ops-platform/specs/044-foss-desk-ticket-sync/spec.md

Spec 044 — Sincronização Tickets: Portal ↔ Desk ↔ FOSS

Criado: 2026-07-01
Solicitado por: Roger
Status: 📋 Especificado — implementação pendente
Prioridade: P1 (suporte unificado pós-activação)
Sistemas: VM112 Portal · VM122 Desk · VM123 FOSSBilling

---

Resumo

Hoje existem três filas de tickets isoladas:

Sistema	ID	Estado
Portal wizard (VM112)	OB-XXXXXXXX	✅ Activo — JSON local + portal cliente
Desk Ops (VM122)	#N / CH-*	✅ Activo — webhook VM112
FOSS Support (VM123)	foss_ticket_id	❌ Sem sync com portal/Desk

Esta spec define a ponte bidireccional Desk ↔ FOSS, preservando o portal wizard como canal de entrada do cliente e o Desk como fonte de verdade operacional.

Contratos:

• ticket-field-mapping.md — chaves de correlação
• ticket-sync-api.md — webhooks e endpoints API

---

Specs relacionadas

Spec	Relação
001	Webhooks VM112 → Desk (base)
010	Escalada, ASM, onboarding.escalated
012	Ticket único por jornada onboarding
024	FOSS VM123, módulo Support
027	support FOSS, roles comercial
039	vm123_foss.support.ticket
041	Central Operacional — canal Tickets
043	external_customer_id FOSS pós-activação

---

Arquitectura alvo

┌─────────────────────────────────────────────────────────────────────────┐
│ VM112 — Portal (onboard.ligbox.com.br)                                   │
│  OB-* tickets · POST /api/onboarding/support/ticket                      │
│  Cliente acompanha: GET .../support/ticket/{OB-}/public                  │
└───────────────────────────────┬─────────────────────────────────────────┘
                                │ webhook onboarding.escalated (+ started)
                                ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ VM122 — Desk (fonte de verdade ops)                                      │
│  tickets.payload: wizard_ticket_id, foss_ticket_id, external_customer_id│
│  Staff: Chamados · Serviços · Central Operacional (041)                  │
└───────────────┬───────────────────────────────┬─────────────────────────┘
                │ POST espelho (M2M)             │ webhook FOSS → Desk
                ▼                                ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ VM123 — FOSSBilling Support                                              │
│  Cliente: financeiro.ligbox.com.br/support                               │
│  Staff: /admin/support · API /api/admin/support/*                        │
└─────────────────────────────────────────────────────────────────────────┘

---

Regras de negócio

1. Um incidente = um ticket Desk — nunca duplicar #N para a mesma session_id ou foss_ticket_id.
2. Portal OB- continua a existir para onboarding; Desk grava wizard_ticket_id no payload (já parcialmente implementado na UI).
3. FOSS espelho só após external_customer_id conhecido (Spec 043) — tickets de onboarding pré-FOSS ficam só Desk + OB-.
4. Sync bidireccional de estado: open ↔ in_progress ↔ resolved ↔ closed (mapa em contrato).
5. Cliente pós-activação pode abrir ticket no FOSS client area ou no portal/console Ligbox; ambos convergem no Desk.

---

Fases de implementação

Fase	Entrega	VM
A	Documentação + contratos (esta spec)	CT130
B	foss_client.create_support_ticket() + espelho Desk→FOSS	VM122
C	Webhook FOSS → Desk (POST /api/v1/webhooks/foss/support)	VM122 + VM123
D	UI Desk: link FOSS ticket + badge sync	VM122
E	Portal pós-activação: criar via Desk API (propaga FOSS)	VM112 / Console

Ver tasks.md.

---

Fora de escopo (v1)

• OTRS (→ Spec 011)
• Sync automático e-mail inbound (→ Spec 041 fase B)
• Tickets Odoo Helpdesk

---

Validação Roger

# 1) Cliente abre OB- no wizard → Desk #N com wizard_ticket_id
# 2) Activar conta (Spec 043) → external_customer_id preenchido
# 3) Staff responde no Desk → foss_ticket_id criado no FOSS
# 4) Cliente responde no FOSS → webhook actualiza nota no Desk #N