# Spec 035-UX — Ligbox Console — Shell unificada

**Criado:** 2026-06-21  
**Solicitado por:** Roger  
**Status:** ✅ Decisões UX fixadas — implementação Fase A (gerente) primeiro  
**URL canónica:** `https://console.ligbox.com.br`  
**Relacionado:** [domain-manager-console-ui.md](./domain-manager-console-ui.md) · [ligbox-system-admin-ui.md](./ligbox-system-admin-ui.md) · Spec **019** (Ops) · Spec **030** (Agentic Ops UI — Mission Board)

---

## 1. Decisões Roger (2026-06-21) — FIXADAS

| # | Decisão | Valor |
|---|---------|-------|
| 1 | Shell visual partilhada | ✅ **Sim** — um design system React para gerente + Admin Ligbox + Ops |
| 2 | URL única de marca | ✅ **`console.ligbox.com.br`** — login detecta role |
| 3 | Ops / chamados Wazuh | ✅ **Dentro do mesmo shell** — secção Operações (Spec 019 integrada) |
| 4 | Tom visual | ✅ **Caloroso BR** — tokens Desk (`styles.css`) + layout Spec **030** |
| 5 | Prioridade Fase A | ✅ **Gerente de domínio (cliente)** primeiro — Admin Ligbox staff depois |
| 6 | Padrões UX | ✅ **Spec 030 Mission Board** — status bar, 3 colunas, cards, contexto |

**Princípio:** FOSS, OpenPanel, Carbonio, Nextcloud **nunca** aparecem como nomes na UI. Só **Ligbox Console** com vocabulário: Email, Files, Plano, Pagamento, Certificação, Operações.

---

## 2. URL única + routing por role

```
https://console.ligbox.com.br
        │
        ├── /login              → detecção role pós-autenticação
        │
        ├── /admin              → Gerente de domínio (Fase A — PRIORIDADE)
        ├── /admin/contas
        ├── /admin/files
        ├── /admin/plano
        └── …
        │
        ├── /ops                → Staff Ligbox — chamados CH-*, Wazuh (Spec 019)
        ├── /ops/ch/:id
        └── …
        │
        ├── /comercial          → Staff Ligbox — preços, catálogo, clientes (Fase C)
        ├── /comercial/precos
        └── …
        │
        └── /me                   → Utilizador email (Fase B — futuro)
```

### Login único — detecção de role

| Credencial | Role detectada | Redirect |
|------------|----------------|----------|
| `admin@{dominio}` + senha | `domain_manager` | `/admin` (contexto domínio) |
| `{user}@{dominio}` + senha | `domain_user` | `/me` ou webmail (Fase B) |
| `@ligbox.com.br` staff + RBAC | `ligbox_staff` | `/ops` ou `/comercial` conforme permissões |
| SSO FOSS pós-compra | `domain_manager` | `/admin?sso=TOKEN` |

**API:** `POST /api/console/login` → JWT com claims `{ role, domain?, permissions[] }`.

### Redirects legacy (Traefik CT114)

| URL antiga | Redirect |
|------------|----------|
| `onboard.ligbox.com.br/admin` | 301 → `console.ligbox.com.br/admin` |
| `onboard.ligbox.com.br/admin/*` | 301 → `console.ligbox.com.br/admin/*` |
| `desk.ligbox.com.br` | 301 → `console.ligbox.com.br/ops` (staff) |
| `desk.ligbox.com.br/admin` | 301 → `console.ligbox.com.br/comercial` |

Manter redirects **mín. 12 meses** — bookmarks e emails antigos.

---

## 3. Shell partilhada — componentes React

**Monorepo proposto:** `ligbox-console-ui/` (VM123 Docker, Spec 019 host)

```
ligbox-console-ui/
├── packages/
│   ├── design-system/     # tokens, Button, Card, Table, Modal, Toast
│   ├── shell/             # AppLayout, Sidebar, Header, CommandPalette
│   ├── domain-admin/      # rotas /admin/*  ← FASE A
│   ├── ligbox-admin/      # rotas /comercial/*
│   ├── ops/               # rotas /ops/*     ← Spec 019
│   └── user-self/         # rotas /me/*      ← Fase B
└── apps/
    └── console/           # Vite + React Router — entry console.ligbox.com.br
```

**Um `AppLayout`** — sidebar e header adaptam-se ao role:

| Elemento | Gerente | Staff Ligbox |
|----------|---------|--------------|
| Logo Ligbox | ✅ | ✅ |
| Selector domínio | ✅ (1 domínio) | ✅ (todos + impersonate) |
| Sidebar items | 6–7 (§4) | 8–10 (§4) |
| Pesquisa global ⌘K | domínio próprio | clientes, domínios, CH-* |
| Avatar / sair | ✅ | ✅ |

---

## 4. Navegação por role (mesma shell, menus diferentes)

### 4.1 Gerente de domínio — `/admin` (Fase A)

| Item sidebar | Rota | Pergunta que responde |
|--------------|------|------------------------|
| 📊 Início | `/admin` | Está tudo bem? |
| 📧 Contas | `/admin/contas` | Quem tem email? |
| 📁 Files | `/admin/files` | Armazenamento e Mail NC |
| 🔐 Certificação | `/admin/certificacao` | Email chega bem? |
| 🌐 Domínio | `/admin/dominio` | DNS correcto? |
| 💳 Plano | `/admin/plano` | Quanto pago? Boleto/PIX |

**Footer atalhos:** Webmail · Files · Suporte

### 4.2 Staff Ligbox — `/comercial` + `/ops`

**Comercial** (`/comercial`):

| Item | Rota |
|------|------|
| 📊 Início | KPIs, fila preços |
| 💰 Planos & preços | catálogo + aprovação Roger |
| 👥 Clientes | pesquisa, estado |
| 🌐 Domínios | todos, health, impersonate → `/admin` |
| 💳 Pagamentos | gateway boleto/PIX |
| ⚙️ Provisionamento | jobs (sem nome OpenPanel) |

**Operações** (`/ops`) — Spec 019 no mesmo shell:

| Item | Rota |
|------|------|
| 📊 Overview | alertas activos |
| 🔍 Discover | eventos correlacionados |
| 🎫 Chamados | `CH-*` hub |
| 🛡️ Segurança | Wazuh deep-link |

Staff com role `ops` vê `/ops`; `commercial` vê `/comercial`; Roger vê **ambos** no mesmo sidebar (secções agrupadas).

---

## 5. Design system — Spec 030 (Mission Board) + tom caloroso BR

Roger (2026-06-21): UX de referência = **Spec 030 Agentic Ops UI** (Mission Board) — **não** Spec 029-tickets-workspace.

### Mapa das specs (para não confundir)

| Spec | Nome | O que é |
|------|------|---------|
| **029-agentic-ops-runbooks** | Backend agentes | API, agentes A0–A7, LLM Ollama, cenários, runbooks |
| **030-agentic-ops-ui** | **Mission Board UI** ✅ | Painel comando: status bar, kanban, cards, context panel |
| 029-tickets-workspace | Motor tickets Desk | KPIs tickets, filas — **spec separada**, não é a referência UX Console |

**Código referência Spec 030 (VM122 / repo):**

```
projects/ops-desk/frontend/assets/
  styles.css           # tokens globais Desk (creme + bordô)
  agentic-ops.js       # Mission Board, Fleet rail, Context panel
  agentic-ops.css      # grid ao-* · componentes ao-incident-card
```

Ver: [specs/030-agentic-ops-ui/spec.md](../../030-agentic-ops-ui/spec.md) · [wireframes.md](../../030-agentic-ops-ui/design/wireframes.md)

### 5.1 Padrões Spec 030 → reutilizar no Console React

| Padrão Spec 030 | O que faz | Aplicar em `/admin` gerente | Aplicar em `/ops` |
|-----------------|-----------|----------------------------|-------------------|
| **Status bar fixa** | Tier, último tick, contagens | Plano · contas · pagamento · certificação | **Reutilizar** overview agentes + tickets |
| **Layout 3 colunas** | Frota \| Board \| Contexto | Nav \| Conteúdo \| Painel detalhe | Mission Board + tickets Spec 019 |
| **Cards por severidade** | Kanban Crítico → OK | Cards contas por estado (activa/suspensa/quota) | Incident cards **já prontos** |
| **1 problema = 1 card** | Deduplicação cenário | 1 conta = 1 card (não duplicar linhas) | Manter dedup `agent_incidents` |
| **Context panel** | Thread + chat ao seleccionar | Quotas, reset senha, atalhos webmail/Files | Thread CH-* + Copiloto A6 |
| **Fleet rail** | Agentes A0–A7 compactos | Sidebar secções (Início, Contas, Files…) | Frota agentes + filtro |
| **Próxima acção no card** | Ack / Abrir / Atribuir | «Criar conta» · «Pagar boleto» | CTAs operador |
| **Poll 30s** | Refresh sem flash | Actualizar quotas / pagamento | Manter |
| **Mobile tabs** | Board \| Frota \| Contexto | Contas \| Plano \| Detalhe | Responsivo |

**Referências UX Spec 030:** Mission Control · Agent Track Dashboard — mission board, inbox, timeline.

### 5.2 Tokens — herdar Desk (`styles.css`) + componentes `ao-*`

Tom **caloroso BR** vem do Desk global; layout **3 colunas** vem da Spec 030:

| Token Desk | Valor | Uso Console |
|------------|-------|-------------|
| `--bg` | `#f5f0e8` | fundo `/admin` gerente |
| `--card` | `#fffdf9` | cards |
| `--accent` | `#5c2e2e` | CTAs (bordô Ligbox) |
| `--sidebar-bg` | `#2e1218` | rail esquerda |
| `--sidebar-active-bar` | `#ff5c8a` | item activo |
| Font | **DM Sans** | global |

**Zona `/ops` agentic:** `agentic-ops.css` (superfície escura scoped) — OK para missões SIEM; gerente `/admin` usa tokens creme.

### 5.3 Padrões UX «banco digital BR» (complemento)

| Padrão | Aplicação Ligbox |
|--------|------------------|
| Cards com ícone + número grande | «12/25 contas», «R$ 549/mês» |
| Linguagem directa PT-BR | «Seu plano» não «Subscription tier» |
| CTAs contrastantes | «Criar conta», «Pagar agora», «Aprovar preço» |
| Feedback imediato | toast verde «Conta criada»; skeleton loading |
| Empty states amigáveis | «Você ainda não tem contas — vamos criar a primeira?» |
| Status chips coloridos | Em dia · Aguardando · Vencido |
| Ilustrações leves (opcional Fase 2) | empty states, onboarding |

### 5.4 `/admin` gerente — wireframe alinhado Spec 030 (3 colunas)

```
┌──────────────────────────────────────────────────────────────────────────┐
│ STATUS BAR · Business · 12/25 contas · Certif. ✅ · Pagamento em dia      │
├──────────┬───────────────────────────────────────────┬───────────────────┤
│ NAV      │  CONTAS (cards)                           │ CONTEXTO          │
│ Início   │  ┌─────────────────┐ ┌─────────────────┐│ vendas@           │
│ Contas   │  │ vendas@  activa   │ │ suporte@ activa ││ Quota mail 30GB   │
│ Files    │  │ 30GB · Files ✅   │ │ 20GB · Files ✅ ││ [Reset senha]     │
│ Plano    │  └─────────────────┘ └─────────────────┘│ [Abrir webmail]   │
│ …        │  [+ Nova conta]                          │                   │
└──────────┴───────────────────────────────────────────┴───────────────────┘
```

Mesma lógica Spec 030: **seleccionar card → painel contexto à direita**.

### 5.5 O que evitar

- Jargon técnico (FOSS, OpenPanel, webhook, VM)
- Cinza corporativo frio estilo enterprise US
- Sidebars com 15+ itens
- Modais em cascata
- Tabelas sem acção inline

---

## 6. Orquestração invisível — padrão UI

Toda acção multi-backend mostra **um fluxo Ligbox**:

```
[ Criar conta ]  →  barra progresso «Criando sua conta…»
                 →  ✅ «Pronto! vendas@empresa.com.br»
                 →  atalhos: Abrir webmail · Abrir Files
```

Erro: mensagem humana + botão «Tentar novamente» ou «Falar com suporte». Log técnico só em `/ops` (staff).

---

## 7. Fases de implementação UI

| Fase | Entrega | Prioridade |
|------|---------|------------|
| **UX-0** | Design tokens + `AppLayout` + login role routing | P0 |
| **UX-A0** | Portar layout Spec 030 (status bar + 3 colunas + cards) | P0 |
| **UX-A** | **`/admin` gerente completo** (Roger: primeiro) | **P0** |
| UX-A1 | Início — status bar + nav rail (Spec 030) | P0 |
| UX-A2 | CRUD contas + quotas | P0 |
| UX-A3 | Files + toggle Mail NC | P1 |
| UX-A4 | Certificação + Plano/boleto PIX | P1 |
| **UX-B** | `/comercial` Admin Ligbox (preços, clientes) | P1 |
| **UX-C** | `/ops` — migrar **Spec 030 Mission Board** + tickets/chamados Spec 019 | P1 |
| **UX-D** | `/me` utilizador (Fase B) | P2 |

**Deploy:** VM123 Docker (`ligbox-console` container), Traefik `console.ligbox.com.br` → VM123.

**Motor API:** VM122 Desk + VM112 Wizard (inalterado — só UI unifica).

---

## 8. Impersonate (staff → gerente)

Staff clica «Entrar como gerente» num domínio:

```
/comercial/dominios/empresa.com.br  →  [ Entrar como gerente ]
  → JWT impersonate (audit Spec 027)
  → /admin?impersonate=1&domain=empresa.com.br
  → mesma UI gerente + banner amarelo «Modo suporte Ligbox»
```

Gerente **nunca** vê este modo — só staff.

---

## 9. Relacionados

| Doc | Conteúdo |
|-----|----------|
| [domain-manager-console-ui.md](./domain-manager-console-ui.md) | Detalhe secções `/admin` |
| [034-console-process-ui.md](../034-nextcloud-carbonio-vm112-integration/034-console-process-ui.md) | Processos Carbonio + Files no Console |
| [ligbox-system-admin-ui.md](./ligbox-system-admin-ui.md) | Detalhe `/comercial` |
| Spec **019** | Motor `/ops` — UI migra para shell partilhada |
| [user-self-service-ui.md](./user-self-service-ui.md) | Futuro `/me` |

---

## 10. Critérios de aceite shell

- [ ] Um login em `console.ligbox.com.br` — roles distintos, mesma marca
- [ ] Gerente não vê menus staff; staff vê `/admin` via impersonate
- [ ] Zero ocorrência «FOSS» ou «OpenPanel» na UI gerente
- [ ] `onboard.ligbox.com.br/admin` redirect 301 funcional
- [ ] Ops `/ops` no mesmo header/logo que `/admin`
- [ ] Lighthouse acessibilidade ≥ 90 na rota `/admin`