3cb51e7ba7
Documenta liberação formal webmail (company_gate), decisões UX Painel Admin, links Spec 044 tickets FOSS↔Desk, VM112 e chat bruto da sessão Roger. Co-authored-by: Cursor <cursoragent@cursor.com>
111 lines
5.8 KiB
Markdown
111 lines
5.8 KiB
Markdown
# 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](./contracts/ticket-field-mapping.md) — chaves de correlação
|
|
- [ticket-sync-api.md](./contracts/ticket-sync-api.md) — webhooks e endpoints API
|
|
|
|
**Chat bruto:** [CHAT_BRUTO_WEBMAIL_GATE_TICKETS_SPEC043_044_20260701.txt](../../chat-bruto/CHAT_BRUTO_WEBMAIL_GATE_TICKETS_SPEC043_044_20260701.txt)
|
|
|
|
---
|
|
|
|
## Specs relacionadas
|
|
|
|
| Spec | Relação |
|
|
|------|---------|
|
|
| [001](../001-webhook-vm112-integration/spec.md) | Webhooks VM112 → Desk (base) |
|
|
| [010](../010-desk-assist-takeover/spec.md) | Escalada, ASM, `onboarding.escalated` |
|
|
| [012](../012-abandoned-onboarding-lead/spec.md) | Ticket único por jornada onboarding |
|
|
| [024](../024-openpanel-fossbilling/spec.md) | FOSS VM123, módulo Support |
|
|
| [027](../027-desk-rbac-function-matrix/contracts/vm123-product-roles.md) | `support` FOSS, roles comercial |
|
|
| [039](../039-ligbox-ops-authorization-catalog/spec.md) | `vm123_foss.support.ticket` |
|
|
| [041](../041-desk-operational-feed/spec.md) | Central Operacional — canal Tickets |
|
|
| [043](../043-desk-client-activation-sync/spec.md) | `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](./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
|
|
|
|
```bash
|
|
# 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
|
|
```
|