ligbox-ops-platform/specs/041-desk-operational-feed/spec.md

Spec 041 — Central Operacional (Operational Feed)

Criado: 2026-06-29
Solicitado por: Roger
Status: Implementado v0.13.0 — fase mock/simulação
Prioridade: P1 (integrações reais = fases futuras)
Versão Desk: 0.13.0-design-system
Substitui: Aba Desk Mensagens (data-view="messages")
UI label: Central Operacional (vocabulário: Operational feed — nunca «Mensagens»)
Spec UI geral: Spec 040 (tokens, principles)
Host: VM122 · desk.ligbox.com.br

---

1. Problema

A aba «Mensagens» mostrava apenas pedidos de cadastro (/api/v1/auth/registration-requests).

Roger definiu Central Operacional (mockup img 3): inbox unificada omnicanal com canais, KPIs, feed de eventos, painel conversa, SLA.

Decisão: construir UI completa + banco simulação até webhooks/APIs reais (WhatsApp, email inbound, telefonia, etc.).

Pedidos de cadastro: preservados em renderRegistrationRequestsLegacy() — reintegrar via link no Controle de acesso (Spec 040).

---

2. Escopo

Fase	Estado
Fase A (actual)	Mock SQLite + seed 6 eventos + API REST
Fase B	Webhook email inbound → ops_inbox_events
Fase C	WhatsApp Business API, Telegram, SMS
Fase D	Integração tickets Desk + agentes A0–A7

---

3. Arquitetura — Aba Desk

Nav: «Central Operacional» (#nav-messages, data-view=messages)
View: #view-messages
Host: #messages-content
Module: messages (Spec 015 modules registry)

app.staging.js
└── renderMessages()
    └── DeskOperationalFeed.paint(#messages-content)   [OF-FE-001]

DeskOperationalFeed
├── Sidebar canais (stats.channels)
├── KPI row (stats)
├── Feed entity cards (GET /events)
└── Right panel
    ├── Tabs: Conversa | Detalhes | Histórico
    ├── Chat (GET event.messages + POST messages)
    └── SLA bar + acções (PATCH event)

View ID legacy: messages — mantido por compatibilidade módulos/URL; label UI = Central Operacional.

---

4. Registo de ficheiros (referência futura)

Código interno: OF-{tipo}-{nnn}

4.1 Frontend

Código	Ficheiro	Global JS	Função
OF-FE-001	frontend/assets/operational-feed.js	window.DeskOperationalFeed	UI Central Operacional (layout 3 colunas)
OF-FE-002	frontend/assets/ligbox-ds.css	—	Partilhado Spec 040 — classes .lb-ops-*
OF-FE-010	frontend/index.html	—	Script operational-feed.js?v=20260629v013
OF-FE-011	frontend/assets/app.staging.js	renderMessages()	Delegação para DeskOperationalFeed.paint
OF-FE-012	frontend/assets/app.staging.js	titles.messages	«Central Operacional»
OF-FE-013	frontend/assets/app.staging.js	subtitles.messages	«Spec 041 · Operational feed…»

4.2 API — Backend

Código	Ficheiro	Router	Função
OF-API-001	api/app/ops_inbox_store.py	—	Schema + seed + queries SQLite
OF-API-002	api/app/ops_inbox_routes.py	/api/v1/ops-inbox	REST endpoints
OF-API-003	api/app/main.py	—	include_router(ops_inbox_router) + init_inbox_schema

4.3 Contratos

Código	Ficheiro	Função
OF-CTR-001	specs/041-desk-operational-feed/contracts/ops-inbox-api.md	Contrato endpoints
OF-CTR-002	contracts/stack-services.yaml	Serviço vm122-ops-inbox-api

---

5. Endpoints — arquitectura

Contrato detalhado: contracts/ops-inbox-api.md

Código	Método	Path	Descrição
OF-EP-001	GET	/api/v1/ops-inbox/stats	KPIs + contadores por canal
OF-EP-002	GET	/api/v1/ops-inbox/events	Lista eventos (filtros)
OF-EP-003	GET	/api/v1/ops-inbox/events/{id}	Detalhe + mensagens
OF-EP-004	POST	/api/v1/ops-inbox/events/{id}/messages	Resposta / nota interna
OF-EP-005	PATCH	/api/v1/ops-inbox/events/{id}	status, assignee, priority

Auth: Bearer JWT · can_manage_users (fase mock — alinhar RBAC dedicado em fase B).

---

6. Modelo de dados (SQLite — fase mock)

ops_inbox_events

Coluna	Tipo	Descrição
id	TEXT PK	ex. evt-wa-001
channel	TEXT	whatsapp, email, tickets, …
event_type	TEXT	message, ticket, alert, missed_call
priority	TEXT	normal, high, critical
title, preview	TEXT	Card feed
tags_json	TEXT	JSON array
assignee	TEXT	nullable
status	TEXT	open, pending, resolved
contact_*	TEXT	empresa, CNPJ, client_id
sla_minutes, sla_remaining_sec	INT	Barra SLA UI
created_at, updated_at	TEXT	ISO8601

ops_inbox_messages

Coluna	Tipo	Descrição
event_id	TEXT FK
author_type	TEXT	user, agent, operator, internal, system
author_label	TEXT
body	TEXT

Seed: 6 eventos em init_inbox_schema() quando tabela vazia.

---

7. Canais (sidebar)

ID	Label UI
all	Todos os canais
email	Email
whatsapp	WhatsApp API
voice	Telefonia / Voz
sms	SMS
telegram	Telegram
tickets	Tickets
agents	Agentes IA
internal	Solicitações internas
clients	Clientes
alerts	Alertas sistema

---

8. Integrações futuras (stubs)

Canal	Endpoint futuro	Notas
Email	POST /api/v1/ops-inbox/webhooks/email	Inbound parse → event
WhatsApp	POST /api/v1/ops-inbox/webhooks/whatsapp	Meta Cloud API
Tickets	Link desk_tickets	Sync bidireccional — Spec 044
Agentes	agents/routes.py threads	Unificar inbox agentes
Cadastro	registration-requests	Link desde Spec 040 hub

---

9. KPIs (header)

KPI	Fonte
Eventos hoje	COUNT events
Pendentes	status open/pending
Críticos	priority=critical
Aguardando você	assignee NOT NULL + open
SLA médio	Mock 96% (fase A) — calcular fase B

---

10. Validação

curl -s -H "Authorization: Bearer $TOKEN" \
  https://desk.ligbox.com.br/api/v1/ops-inbox/stats

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://desk.ligbox.com.br/api/v1/ops-inbox/events?channel=whatsapp"

UI: Menu Central Operacional → feed com 6 cards seed → painel conversa.

---

11. Deploy

Mesmo procedimento Spec 040 — ficheiros OF-API-001/002 + OF-FE-001.

Health API: "version": "0.13.0-design-system"