ligbox-ops-platform/specs/035-ligbox-mail-bundles-foss-openpanel/domain-manager-console-ui.md

# Spec 035-UI — Área Gerente de Domínio (Console único)

**Criado:** 2026-06-21  
**Solicitado por:** Roger  
**Status:** ✅ Decisões UX fixadas — ver [ligbox-console-shell.md](./ligbox-console-shell.md)  
**URL canónica:** `https://console.ligbox.com.br/admin` (alias 301: `onboard.ligbox.com.br/admin`)  
**Relacionado:** Spec **035** · **035-UX shell** · **010** · **034** · **024** · **037** ([dns-viewer.md](../037-dns-multi-cloudflare-orchestration/dns-viewer.md))

---

## 1. Decisão Roger (2026-06-21)

| Agora (Fase A) | Depois (Fase B — estudo separado) |
|----------------|-----------------------------------|
| **Área Gerente de Domínio** — uma página/app única | **Área por utilizador de email** — cada caixa gere as suas próprias coisas |
| Gerente configura bundle, contas, quotas, Nextcloud, DMARC | Redirects, out-of-office, férias, assinaturas, calendário pessoal |
| Login: `admin@{dominio}` ou SSO FOSS | Login: `{user}@{dominio}` — self-service limitado |

**Princípio:** o gerente **nunca** salta para FOSS, OpenPanel ou Nextcloud em modo «setup». Tudo converge num **cockpit Ligbox**.

---

## 2. Três portais Ligbox — mesmo princípio de agregação

Roger (2026-06-21): **três UIs** na **mesma shell** `console.ligbox.com.br` — design system React partilhado, tom caloroso BR (banco digital).

```
┌─────────────────────────────────────────────────────────────────┐
│  LIGBOX CONSOLE — console.ligbox.com.br                         │
│  Login único · role detecta menu                                │
├─────────────────────────────────────────────────────────────────┤
│  /comercial + /ops     Staff Ligbox (Fase C — depois gerente)   │
│  /admin                Gerente domínio ← FASE A PRIORIDADE      │
│  /me                   Utilizador email (Fase B)                │
└─────────────────────────────────────────────────────────────────┘
```

Ver shell completa: [ligbox-console-shell.md](./ligbox-console-shell.md)

---

## 3. Onde vive a Área Gerente

| Opção | Decisão |
|-------|---------|
| FOSS área cliente | ❌ Só billing embebido via API — não UI principal |
| OpenPanel user panel | ❌ Backend hub — não face visível |
| **Wizard SPA `/admin`** | ✅ **Escolhido** — evolui para `console.ligbox.com.br/admin` |
| Portal Ligbox novo | ❌ Evitar duplicar — **shell unificada** Spec 035-UX |

**URL canónica:** `https://console.ligbox.com.br/admin`  
**Redirect:** `https://onboard.ligbox.com.br/admin` → 301 console (legacy)

### Mockup sandbox (seguro — zero produção)

Ficheiro estático interactivo — **não liga a APIs**, estado só em memória do browser:

```
specs/035-ligbox-mail-bundles-foss-openpanel/mockups/domain-manager-sandbox.html
```

Abrir localmente:

```bash
# no CT130 ou laptop
xdg-open /opt/ligbox-spec-hub/repos/ligbox-ops-platform/specs/035-ligbox-mail-bundles-foss-openpanel/mockups/domain-manager-sandbox.html
# ou servir estático (opcional):
python3 -m http.server 8765 --directory specs/035-ligbox-mail-bundles-foss-openpanel/mockups
# → http://localhost:8765/domain-manager-sandbox.html
```

Barra vermelha **SANDBOX** sempre visível. Acções (criar conta, remover, upgrade) mostram toast «simulado» — Carbonio, FOSS, OpenPanel e Nextcloud **não são tocados**.

### Modo Live create-only (produção segura)

O mesmo ficheiro HTML inclui botão **Live create-only**:

| Modo | Comportamento |
|------|---------------|
| **Mock** | Zero API — UI only |
| **Live** | Desk API → VM112 cria domínio/contas **reais** |

**Regras de segurança (API Desk):**

- ✅ Criar cenário = domínio novo `cenario-*`.ops.ligbox.com.br` + `admin@`
- ✅ Adicionar contas **só** dentro do cenário criado
- ❌ **Delete/purge bloqueado** (HTTP 403) — nada existente apagado
- ❌ Domínios protegidos (`ligbox.com.br`, etc.) bloqueados
- ❌ Domínio que **já tem contas** não pode ser usado como cenário novo

**API:** `POST /api/v1/domain-console/sandbox/scenarios`  
**Auth:** JWT Desk (`ops_lead`, `super_admin`, `technician` com `manage_vm112_domains`)  
**Deploy:** código em `projects/ops-desk/api/app/domain_console_sandbox*.py` — activar no VM122

**Login único:** sessão wizard (`/api/domain-admin/auth`) + opcional SSO desde FOSS (`sso_token`).

---

## 4. Wireframe — página única (desktop)

```
╔══════════════════════════════════════════════════════════════════╗
║  LIGBOX · Gerente de Domínio          empresa.com.br    [Sair]  ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                  ║
║  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ║
║  │ Plano       │ │ Contas      │ │ DMARC       │ │ Faturação   │ ║
║  │ Business    │ │ 12 / 25     │ │ ✅ Certificado│ │ Boleto/PIX  │ ║
║  │ R$ 549/mês  │ │             │ │ SPF DKIM OK │ │ [Pagar]     │ ║
║  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ ║
║                                                                  ║
║  ┌─ Navegação lateral ─┐  ┌─ Conteúdo principal ──────────────┐ ║
║  │ 📊 Visão geral       │  │                                    │ ║
║  │ 📧 Contas de email   │  │  (secção activa — ver §5)          │ ║
║  │ 📁 Nextcloud / Files │  │                                    │ ║
║  │ 🔐 Certificação mail │  │                                    │ ║
║  │ 🌐 Domínio & DNS     │  │                                    │ ║
║  │ 💳 Plano & pagamento │  │                                    │ ║
║  │ 🔗 Atalhos rápidos   │  │                                    │ ║
║  └──────────────────────┘  └────────────────────────────────────┘ ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝
```

### Mobile
- Cards resumo empilhados
- Menu lateral → drawer hamburger
- Tabelas contas → cards por utilizador

---

## 5. Secções da Área Gerente (Fase A)

### 5.1 Visão geral

| Widget | Fonte API | Acção |
|--------|-----------|-------|
| Plano activo + uso | Desk `bundle_entitlements` | — |
| Barra contas (12/25) | Wizard domain-admin | Link → Contas |
| DMARC score | EasyDMARC API | Link → Certificação |
| Disco mail domínio | Carbonio zmprov | — |
| Disco Files domínio | Nextcloud OCS | — |
| Últimas contas criadas | Wizard audit log | — |

### 5.2 Contas de email

**Tabela principal — tudo na mesma página, sem ir ao Carbonio Admin Console.**

| Coluna | Editable |
|--------|----------|
| Email | criar nova |
| Nome | ✅ |
| Quota mail (GB) | ✅ (≤ bundle) |
| Quota Files (GB) | ✅ (≤ bundle) |
| Nextcloud activo | toggle |
| Estado | activo / suspenso |
| Acções | reset senha · editar · remover |

**Botão «+ Nova conta»** → modal inline (não redirect):

```
Email:     [ vendas        ] @empresa.com.br
Nome:      [ Vendas        ]
Quota mail:[ 30 GB ▼       ]
Quota NC:  [ 200 GB ▼      ]
☑ Criar Nextcloud Files
[ Cancelar ]  [ Criar conta ]
```

**Backend:** Wizard `POST /api/domain-admin/accounts` → Carbonio + Nextcloud OCS (Spec 034).

**Limite:** se `seats_used >= max_seats` → modal «Upgrade plano» (embed FOSS ou deep-link).

### 5.3 Nextcloud / Files

| Elemento | Comportamento |
|----------|---------------|
| **Toggle «Mail no Nextcloud»** | **ON/OFF por domínio** — default OFF (Roger 2026-06-21) |
| Resumo quota total domínio | soma quotas contas |
| Lista contas com quota Files | read-only espelho §5.2 |
| Coluna «Mail NC» | ✅ / — conforme toggle domínio + conta |
| Botão «Abrir Files do domínio» | nova tab `files.{dominio}` (SSO token NC) |
| Botão «Abrir webmail» | nova tab `mail.{dominio}` (sempre disponível) |
| Política default novas contas | dropdown 100–500 GB |

**UI toggle (domínio):**

```
Nextcloud / Files
─────────────────────────────────────────
☐ Activar Mail no Nextcloud (email dentro do Files)
  Lê email via Carbonio — webmail mail.{dom} continua disponível

  Quando activo: novas contas recebem Mail app pré-configurado.
  Quando inactivo: só Files — utilizadores usam mail.{dom} ou Outlook.
```

**Backend:** `PATCH /api/domain-admin/domains/{dom}/nextcloud-mail` → wizard → OCS + entitlements.

**Nota:** gestão quota **na mesma app** — não enviar gerente ao painel admin Nextcloud.

### 5.4 Certificação mail (EasyDMARC)

| Item | UI |
|------|-----|
| SPF | ✅ / ⚠️ + texto simples |
| DKIM | ✅ / ⚠️ |
| DMARC | policy + score |
| Histórico 30 dias | gráfico simples |
| «O que significa?» | tooltip layman |

**Sem** link para easydmarc.com — dados via API Ligbox (Desk proxy).

### 5.5 Domínio & DNS (DNS Viewer — Spec 037-DNS-VIEWER)

Secção **read-only** — gerente **vê** apontamentos; **não edita** na Console. Edição via link externo (Cloudflare cliente, OpenPanel, registrador).

**Regra wizard (037):**

| Escolha onboarding | O que esta secção mostra |
|--------------------|--------------------------|
| **Trazer DNS para Ligbox** | Apontamentos **que a Ligbox aplicou / vai aplicar** (MX, SPF, DKIM, DMARC, A mail) + NS Cloudflare |
| **DNS externo / BYO / registrador** | O que está **publicamente resolvido agora** + instruções se faltar algo |

#### Layout `/admin/dominio` ou tab «Domínio & DNS»

```
┌─ DNS — empresa.com.br ─────────────────────────────────────────┐
│ [Cloudflare Ligbox]  14 registos · 6 para e-mail               │
│ NS actuais: ada.ns.cloudflare.com …  ✅ delegação Ligbox       │
├────────────────────────────────────────────────────────────────┤
│ Função │ Nome           │ Tipo │ Conteúdo          │ Estado    │
│ MX     │ empresa.com.br │ MX   │ mail.empresa…     │ ✅ OK     │
│ SPF    │ empresa.com.br │ TXT  │ v=spf1 include…   │ ✅ OK     │
│ DKIM   │ …._domainkey   │ TXT  │ v=DKIM1…          │ ⚠ pendente│
├────────────────────────────────────────────────────────────────┤
│ Verificação pública: MX ✅ · SPF ✅ · DKIM ⚠ · DMARC ✅         │
├────────────────────────────────────────────────────────────────┤
│ Subdomínio incluído: intranet.empresa.com.br → CNAME …        │
│ [Ver instruções DNS]  [Contactar suporte]  [Actualizar]        │
└────────────────────────────────────────────────────────────────┘
```

#### API

```http
GET /api/v1/dns/viewer/{domain}
Authorization: Bearer <domain-admin JWT>
```

Proxy Desk → agrega CF / OpenPanel / público conforme `dns_mode`. Ver [dns-viewer.md](../037-dns-multi-cloudflare-orchestration/dns-viewer.md).

#### Elementos UI

| Item | Comportamento |
|------|---------------|
| Badge origem | `DNS Ligbox` · `Cloudflare sua conta` · `OpenPanel BIND` · `Registrador externo` |
| Tabela registos | Todas as linhas relevantes (mail + subdomínio bundle) |
| NS | Actuais (público) vs Ligbox CF (se aplicável) |
| Checks mail | MX/SPF/DKIM/DMARC — reutilizar Spec 009 / `public_checks` |
| Subdomínio incluído | Linha CNAME/A do bundle §2.4 — read-only ou link suporte |
| «Ver instruções DNS» | Modal com `dns/instructions` (modo externo) |
| «Editar DNS» | **Só se BYO/OpenPanel gerido pelo cliente** — nova tab |
| Modo Ligbox gerida | Sem link CF interna — «Alterações via suporte Ligbox» |

#### Modo externo (exemplo copy)

> O seu domínio usa DNS **fora da Ligbox**. Abaixo está o que os servidores públicos respondem **agora**. Para activar email, configure os valores em «Instruções DNS» no seu registrador.

#### Modo Ligbox (exemplo copy)

> A Ligbox gere o DNS deste domínio na Cloudflare. Apontamentos abaixo estão **activos** (ou **serão aplicados** após apontar os nameservers).

#### Staff impersonate

Staff Ligbox (Spec 027) em impersonate vê links adicionais «Editar na Cloudflare (staff)» — ocultos para gerente normal.

**Critérios aceite (A4):**

1. Gerente vê tabela completa mail sem abrir Cloudflare.
2. Domínio externo mostra estado público — **não** lista preview Ligbox.
3. Domínio Ligbox pré-NS mostra NS + registos planeados.
4. Zero botões «Apagar» / «Guardar registo» nesta secção.

### 5.6 Plano, pagamento & upgrade

| Elemento | Comportamento |
|----------|---------------|
| Plano actual | nome + preço + renovação |
| **Status pagamento** | Em dia · Aguardando · Vencido |
| **Boleto bancário** | botão «Gerar / Ver boleto» → PDF ou linha digitável (gateway via FOSS) |
| **PIX QR Code** | QR inline + copia-e-cola (gateway via FOSS) |
| Uso vs limites | barras visuais |
| «Upgrade plano» | iframe FOSS checkout **ou** API FOSS embed |
| Faturas recentes | lista 3 últimas via FOSS API |
| «Ver faturação completa» | abre FOSS cliente **nova tab** (única excepção externa) |

**Regra Roger:** boleto + PIX **visíveis no `/admin`** — gerente não precisa caçar fatura noutro portal para pagar.

**Backend:** Gateway (ASAAS/Iugu) → webhook FOSS → Desk → activa entitlements quando pago.

### 5.7 Atalhos rápidos (sidebar footer)

| Atalho | Destino |
|--------|---------|
| Webmail gerente | `mail.{dom}` nova tab |
| Files gerente | `files.{dom}` SSO |
| Suporte Ligbox | Desk ticket (email gerente) |

---

## 6. Integrações invisíveis (backend)

O gerente vê **uma app**. Por baixo:

```
Domain Manager SPA (console.ligbox.com.br/admin)
        │
        ├── Wizard API /api/domain-admin/*     → Carbonio CRUD
        ├── Desk API /api/v1/domain-console/*  → entitlements, DMARC, FOSS proxy
        ├── Nextcloud OCS (via wizard proxy)   → quotas Files, activar/desactivar
        ├── FOSS API (via Desk proxy)          → faturação, plano, upgrade
        └── Gateway pagamento (via FOSS)         → boleto + PIX QR
```

**OpenPanel:** zero UI exposta ao gerente — só provision backend (Spec 035 §4.1).

---

## 7. Autenticação

### 7.1 Login directo

```
POST /api/domain-admin/login
{ "email": "admin@empresa.com.br", "password": "..." }
→ JWT session (domínio no claim)
```

### 7.2 SSO desde FOSS (pós-compra)

```
FOSS cliente → «Abrir Console Gerente»
→ Desk POST /api/v1/domain-console/sso-token
→ redirect onboard.ligbox.com.br/admin?sso=TOKEN
→ wizard valida → sessão
```

### 7.3 Quem pode entrar

| Email | Acesso Área Gerente |
|-------|---------------------|
| `admin@{dom}` | ✅ sempre |
| `administrator@{dom}` | ✅ se flag Carbonio |
| Outros `@dom` | ❌ → Fase B (self-service user) |
| Staff Ligbox Desk | ✅ impersonate auditado (Spec 027) |

---

## 8. Fase B — Área Utilizador Email (placeholder)

**Status:** 📋 A estudar — **não implementar na Fase A**

Cada `{user}@{dominio}` terá portal **separado** e **limitado**:

| Funcionalidade | Carbonio nativo | UI Ligbox proposta |
|----------------|-----------------|-------------------|
| Redirects / encaminhamento | sieve / prefs | Secção «O meu email» |
| Out of office / férias | vacation | Form datas + mensagem |
| Assinatura | prefs | Editor HTML simples |
| Calendário | CalDAV | Link ou embed leve |
| Alterar senha | ✅ | Form |
| Quota pessoal | read-only | Barra uso |
| Criar contas domínio | ❌ | Só gerente |

**URL proposta Fase B:** `https://mail.{dominio}/settings` ou `onboard.ligbox.com.br/me`

**Decisão pendente Roger:** webmail Carbonio prefs nativas vs SPA Ligbox custom.

Documento futuro: `user-self-service-ui.md` (Spec 036 ou § Fase B desta spec).

---

## 9. Fases de entrega UI

| Fase | Entregável | Prioridade |
|------|------------|------------|
| **A1** | Shell SPA + login + cards resumo | P0 |
| **A2** | CRUD contas + quotas inline | P0 |
| **A3** | Nextcloud quota + toggle Mail opcional + atalho Files SSO | P1 |
| **A4** | EasyDMARC card + **DNS Viewer** (`/admin/dominio`) | P1 |
| **A5** | FOSS plano/faturação embed | P2 |
| **B*** | Self-service utilizador email | P2 futuro |

---

## 10. Critérios de aceite (Fase A)

1. Gerente entra **só** em `onboard.ligbox.com.br/admin` — gere contas **sem** abrir Carbonio Admin Console.
2. Criar conta `vendas@` + quota NC → funcional em **um modal**, ≤3 cliques.
3. Resumo plano + 12/25 contas visível no dashboard.
4. DMARC status legível (não técnico).
5. Utilizador `vendas@` **não** acede `/admin` — redirect para webmail ou 403.
6. Mobile: criar conta e ver resumo utilizável.

---

## 11. Referências

| Doc | Path |
|-----|------|
| Bundles comercial | `spec.md` |
| Domain Admin actual | Spec 010 · VM112 `DomainAdmin.jsx` |
| Nextcloud OCS | `../034-.../contracts/nextcloud-provisioning-api.md` |
| RBAC gerente | Spec 027 § client_domain_admin (a formalizar) |
| **DNS Viewer (read-only)** | [037 dns-viewer.md](../037-dns-multi-cloudflare-orchestration/dns-viewer.md) |