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
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)

---

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

---

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:

# 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

Desk (staff directo):

GET /api/v1/dns/viewer/{domain}
Authorization: Bearer <staff JWT>
Query: ?email_service=true&include_public=true

Console gerente (proxy Desk — implementado V3):

GET /api/v1/domain-console/dns/viewer/{domain}
Authorization: Bearer <domain-admin JWT>
Query: ?email_service=true&include_public=true

Frontend Console (AdminDominio.jsx) chama o proxy acima via API Desk (console.ligbox.com.br → VM122).
Implementação: domain_console_routes.py — filtra links CF Ligbox para gerente.

Agrega CF / OpenPanel / público conforme dns_mode. Ver 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