Ligbox Spec Hub ef126d1e52 Spec 044: sync tickets Portal OB- ↔ Desk ↔ FOSS Support

Documenta arquitectura, mapeamento de IDs e contratos API para ponte
bidireccional entre portal wizard, Desk ops e FOSSBilling Support.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-01 17:40:05 +00:00

3.2 KiB

Raw Blame History

Contrato — Mapeamento IDs: Portal ↔ Desk ↔ FOSS

Spec: 044
Versão: 1.0 · 2026-07-01 · Roger
Status: Fonte única para correlação de tickets

1. Identificadores

Campo	Formato	Sistema dono	Persistência Desk
`wizard_ticket_id`	`OB-[A-F0-9]{8}`	VM112 portal	`tickets.payload.wizard_ticket_id`
`desk_ticket_id`	inteiro `#N`	VM122 Desk	`tickets.id`
`foss_ticket_id`	inteiro FOSS	VM123 FOSS	`tickets.payload.foss_ticket_id`
`external_customer_id`	inteiro FOSS client	VM123 FOSS	`billing_accounts.external_customer_id`
`session_id`	UUID wizard	VM112	`tickets.session_id`
`domain`	FQDN	—	`tickets.payload.domain`

2. Chaves de idempotência

Operação	Chave única	Comportamento se duplicado
Portal → Desk	`event + session_id + domain`	Actualizar ticket existente (Spec 001 FR-012)
Desk → FOSS espelho	`desk_ticket_id`	Retornar `foss_ticket_id` existente
FOSS → Desk webhook	`foss_ticket_id + event_type`	Append nota, não criar ticket novo
Cliente FOSS novo	`foss_ticket_id`	Lookup Desk; criar só se ausente

3. Mapa de estados

Desk `status`	Portal OB- `status`	FOSS Support
`open`	`open`	`open`
`escalated`	`in_review`	`open`
`assisting`	`in_progress`	`on hold`
`resolved`	`resolved`	`closed` (resolvido)
`closed`	`closed`	`closed`

Regra: Desk é master para ops; FOSS é master para visibilidade cliente billing.

4. Payload Desk (`tickets.payload` — extensão Spec 044)

{
  "event": "onboarding.escalated",
  "domain": "empresa.com.br",
  "session_id": "331b4022-70a5-4a9d-ba3e-08aaa06cb4f4",
  "data": {
    "wizard_ticket_id": "OB-D424843A",
    "client_note": "DNS não propaga",
    "reason": "client_support_request"
  },
  "foss_sync": {
    "foss_ticket_id": 42,
    "external_customer_id": 17,
    "synced_at": "2026-07-01T18:00:00Z",
    "last_foss_event": "ticket.reply",
    "foss_url": "https://financeiro.ligbox.com.br/admin/support/ticket/42"
  }
}

5. Pré-requisitos para espelho FOSS

Condição	Obrigatório
`billing_accounts.external_customer_id`	Sim (Spec 043)
Ticket Desk com `domain`	Sim
Role staff a criar espelho	`sales_admin`, `sales_support`, `technician`, `ops_lead`
Onboarding puro (sem FOSS client)	Espelho adiado até Activar conta

6. URLs deep-link

Destino	URL
Desk ticket	`https://desk.ligbox.com.br/#ticket/{desk_ticket_id}`
Portal OB- tracking	`https://onboard.ligbox.com.br/onboard?session={session_id}&ticket={wizard_ticket_id}`
FOSS admin ticket	`https://financeiro.ligbox.com.br/admin/support/ticket/{foss_ticket_id}`
FOSS client ticket	`https://financeiro.ligbox.com.br/support/ticket/{foss_ticket_id}`

Histórico

Versão	Data	Autor	Notas
1.0	2026-07-01	Roger / Cursor	Documento inicial Spec 044

3.2 KiB Raw Blame History