4e65555abb
Sync completo da spec 044, contratos, registry e sidebar no vault VM130. Co-authored-by: Cursor <cursoragent@cursor.com>
97 lines
3.2 KiB
Markdown
97 lines
3.2 KiB
Markdown
# Contrato — Mapeamento IDs: Portal ↔ Desk ↔ FOSS
|
|
|
|
**Spec:** [044](../spec.md)
|
|
**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)
|
|
|
|
```json
|
|
{
|
|
"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 |
|