# Spec 034-UI — Visão processo Console (Carbonio + Nextcloud)

**Criado:** 2026-06-21  
**Solicitado por:** Roger  
**Status:** 📋 Draft — design aprovado conceptualmente  
**URL:** `https://console.ligbox.com.br` (shell Spec [035-UX](../035-ligbox-mail-bundles-foss-openpanel/ligbox-console-shell.md))  
**Referência layout:** Spec **030** (Mission Board) · Spec **035** (bundles, toggle Mail NC)

---

## 1. Objectivo

Documentar **como a visão de processo** da Spec 034 (mail hot + Files warm + provision NC-1→NC-5) aparece no **Ligbox Console** — sem expor Carbonio, Nextcloud ou OCS ao utilizador.

**Princípio Roger:** mesma shell Spec 030 (status bar · 3 colunas · cards · contexto), **componentes novos** para quotas duplas e pipeline de provisionamento.

---

## 2. Avaliação Spec 030 como referência

| Área | Nota | Decisão |
|------|------|---------|
| Shell 3 colunas + status bar | 8/10 | ✅ Herdar directo |
| Staff ops / health / falhas NC | 8/10 | ✅ Mission Board para incidentes |
| Gerente: lista contas | 6/10 | ⚠️ Adaptar cards |
| Pipeline NC-1→NC-5 | 4/10 | ➕ Componente **`ProvisionPipeline`** novo |
| Quotas mail + Files | 5/10 | ➕ Componente **`QuotaDualBar`** novo |
| Forms CRUD (criar conta) | 4/10 | ➕ Modal / context panel com forms |

**Conclusão:** Spec 030 = **chassis**; Spec 034-UI = **indicadores e fluxos** do motor híbrido.

---

## 3. Vocabulário UI (nunca mostrar motores)

| Backend | UI Ligbox Console |
|---------|-------------------|
| Carbonio VM112 | **Email** · quota **caixa** |
| Nextcloud VM116 Files | **Files** · quota **armazenamento** |
| OCS Provisioning API | *(invisível)* — «A criar Files…» |
| NC-1…NC-5 | **`ProvisionPipeline`** — passos humanos |
| Hot / Warm tier | **`StorageTierBadge`** — «Caixa» / «Files» |
| `nextcloud_mail_enabled` | Toggle **«Mail no Nextcloud»** |
| VM116 health | **«Armazenamento»** ● online / offline |

---

## 4. Processos Spec 034 → ecrãs Console

### 4.1 Mapa processo → rota

| Processo Spec 034 | Role | Rota Console | Componente principal |
|-------------------|------|--------------|----------------------|
| Onboarding conta (Carbonio + NC) | Gerente | `/admin/contas` | `ProvisionPipeline` + modal criar |
| Quotas duplas por conta | Gerente | `/admin/contas` | `QuotaDualBar` no card + context |
| Toggle Mail Nextcloud domínio | Gerente | `/admin/files` | `DomainFilesToggle` |
| Ver uso domínio mail + Files | Gerente | `/admin` Início | Status bar + cards resumo |
| Health VM116 + VM112 | Staff | `/ops` ou `/comercial/dominios` | `StackHealthTile` |
| Falha provision OCS | Staff | `/ops` Mission Board | `IncidentCard` (Spec 030) |
| Provision manual ops | Staff | `/ops` context | Form + `ProvisionPipeline` |
| Purge domínio (017+034) | Staff | `/ops` runbook | Fora UI 034 — link runbook |
| Offload anexo grande | Utilizador | webmail Carbonio | Banner «Guarde em Files» — **não** Console |

### 4.2 Pipeline NC-1 → NC-5 (componente novo)

Backend Spec 034 §Integração VM112:

```
NC-1  Criar user Nextcloud (OCS)
NC-2  Quota Files conforme plano
NC-3  Mail app pré-config (se toggle ON)
NC-4  Registar estado domínio
NC-5  Webhook Desk provisioned
```

**UI `ProvisionPipeline`** — barra horizontal de passos:

```
┌─────────────────────────────────────────────────────────────────┐
│  Criando vendas@empresa.com.br                                  │
│                                                                 │
│  ● Email ─── ● Files ─── ○ Mail NC ─── ○ Finalizar             │
│    OK           OK         (skip)        …                      │
└─────────────────────────────────────────────────────────────────┘
```

| Estado | Visual | Mensagem PT-BR |
|--------|--------|----------------|
| `pending` | ○ cinza | «Aguardando…» |
| `running` | ◐ animado | «A criar Files…» |
| `ok` | ● verde | «Pronto» |
| `skipped` | ○ tracejado | «Não activo» (NC-3 OFF) |
| `error` | ● vermelho | «Não foi possível — tentar novamente» |

**Regra:** utilizador vê **uma** barra — nunca «OCS API» ou «NC-3».

### 4.3 Quotas duplas (componente novo)

**`QuotaDualBar`** — duas barras empilhadas por conta:

```
Email (caixa)     ████████░░  24 / 30 GB
Files             ███░░░░░░░  60 / 200 GB
```

| Prop | Fonte API |
|------|-----------|
| Mail usado/máx | Wizard `/api/domain-admin/accounts` |
| Files usado/máx | Desk `/api/v1/nextcloud/domains/{domain}/users` |

**`StorageTierBadge`** no card:

| Badge | Significado |
|-------|-------------|
| `Caixa` | Quota Carbonio (hot) |
| `Files` | Quota Nextcloud (warm) |
| `Arquivo` | Fase 3 S3 — futuro |

---

## 5. Wireframes — Gerente (`/admin`)

Shell Spec 030 adaptada · tokens Desk creme ([035-UX §5](../035-ligbox-mail-bundles-foss-openpanel/ligbox-console-shell.md)).

### 5.1 Início — `/admin`

```
┌──────────────────────────────────────────────────────────────────────────┐
│ STATUS BAR · Business · 12/25 contas · Certif. ✅ · Pagamento em dia        │
│ Armazenamento Files ● online · 2.1 TB usados no domínio                    │
├──────────┬───────────────────────────────────────────┬───────────────────┤
│ NAV      │  RESUMO                                   │ CONTEXTO          │
│ Início ● │  ┌─────────────┐ ┌─────────────┐          │ Próxima acção:    │
│ Contas   │  │ Email       │ │ Files       │          │ «13 vagas —       │
│ Files    │  │ 360 GB usado│ │ 2.1 TB usado│          │  criar conta»     │
│ Plano    │  │ 12 contas   │ │ 12 contas   │          │ [+ Nova conta]    │
│ …        │  └─────────────┘ └─────────────┘          │                   │
└──────────┴───────────────────────────────────────────┴───────────────────┘
```

### 5.2 Contas — `/admin/contas`

```
┌──────────────────────────────────────────────────────────────────────────┐
│ STATUS BAR · 12/25 contas · Plano Business                                 │
├──────────┬───────────────────────────────────────────┬───────────────────┤
│ NAV      │  CONTAS (cards — Spec 030 board)          │ CONTEXTO          │
│ Contas ● │  ┌─────────────────────────────────────┐  │ vendas@           │
│          │  │ vendas@empresa.com.br    [Caixa][Files]│  │ QuotaDualBar    │
│          │  │ ● activa · Email 24/30GB · Files 60/200│  │ [Editar quotas] │
│          │  └─────────────────────────────────────┘  │ [Reset senha]     │
│          │  [+ Nova conta] → modal + ProvisionPipeline│ [Abrir webmail]   │
│          │                                           │ [Abrir Files]     │
└──────────┴───────────────────────────────────────────┴───────────────────┘
```

**Modal criar conta:**

```
Email:    [ vendas        ] @empresa.com.br
Nome:     [ Vendas        ]
Quota email:  [ 30 GB ▼ ]
Quota Files: [ 200 GB ▼ ]
☑ Criar armazenamento Files
( Mail no Nextcloud: controlado em Files — toggle domínio )

[ Cancelar ]  [ Criar ]

→ ProvisionPipeline inline até concluir
```

### 5.3 Files — `/admin/files`

```
┌──────────────────────────────────────────────────────────────────────────┐
│ DomainFilesToggle                                                        │
│ ☐ Activar Mail no Nextcloud (email dentro do Files)                      │
│   Webmail mail.{dom} continua sempre disponível                          │
├──────────┬───────────────────────────────────────────┬───────────────────┤
│ NAV      │  Lista contas (quota Files — espelho)     │ CONTEXTO          │
│ Files ●  │  vendas@ · 60/200 GB · Files ✅          │ editar quota Files│
└──────────┴───────────────────────────────────────────┴───────────────────┘
```

Ver Spec 035 §2.2.1 — default toggle **OFF**.

---

## 6. Wireframes — Staff (`/ops`)

Mission Board Spec 030 · zona escura `agentic-ops.css` para incidentes; tiles health podem usar creme.

### 6.1 Stack health — domínio ou global

**`StackHealthTile`** (novo — tile ou status bar):

```
┌─────────────────────────────────────┐
│ Stack domínio empresa.com.br        │
│ Email (VM112)     ● OK              │
│ Files (VM116)     ● OK              │
│ Último provision  há 2 min          │
└─────────────────────────────────────┘
```

API: Desk `GET /api/v1/nextcloud/health` + wizard domain status.

### 6.2 Incidentes provision (Mission Board)

Cards Spec 030 quando NC falha:

```
┌─────────────────────────────────────┐
│ [ALTO] Files não criado             │
│ empresa.com.br · vendas@            │
│ Detectado há 6 min · 2 tentativas   │
├─────────────────────────────────────┤
│ Acção: Repetir criação Files        │
├─────────────────────────────────────┤
│ [Abrir domínio]  [Retry]  [Ack]     │
└─────────────────────────────────────┘
```

Context panel: `ProvisionPipeline` com passo em erro + log sanitizado (staff only).

---

## 7. Componentes React (packages Console)

| Componente | Spec origem | Fase |
|------------|-------------|------|
| `AppLayout` | 030 / 035-UX | UI-0 |
| `StatusBar` | 030 | UI-0 |
| `ContextPanel` | 030 | UI-0 |
| `IncidentCard` | 030 | `/ops` |
| **`ProvisionPipeline`** | **034** | UI-034-A |
| **`QuotaDualBar`** | **034** | UI-034-A |
| **`StorageTierBadge`** | **034** | UI-034-A |
| **`DomainFilesToggle`** | **034 / 035** | UI-034-B |
| **`StackHealthTile`** | **034 / 033** | UI-034-B |
| **`AccountCard`** | 030 card + 034 badges | UI-034-A |

**Monorepo:** `ligbox-console-ui/packages/domain-admin/` — rotas `/admin/*`.

---

## 8. APIs consumidas (034 → UI)

| UI | Endpoint | Spec |
|----|----------|------|
| QuotaDualBar (mail) | Wizard `GET/PUT /api/domain-admin/accounts` | 010 |
| QuotaDualBar (Files) | Desk `GET .../nextcloud/domains/{d}/users` | [contract](./contracts/nextcloud-provisioning-api.md) |
| ProvisionPipeline | Wizard `POST accounts` + webhook progress | 034 §NC |
| DomainFilesToggle | Wizard `PATCH .../nextcloud-mail` | 035 §2.2.1 |
| StackHealthTile | Desk `/api/v1/nextcloud/health` | 034 |
| Incident retry | Desk `POST .../nextcloud/domains/{d}/users` | 034 |

**Eventos websocket/poll (fase 2):** `onboarding.nextcloud.provisioned` → actualiza pipeline sem reload.

---

## 9. Fases de entrega UI-034

| Fase | Entrega | Depende infra |
|------|---------|---------------|
| **UI-034-A** | `QuotaDualBar` + `AccountCard` + modal criar + `ProvisionPipeline` mock | Wizard API (parcial OK) |
| **UI-034-B** | `DomainFilesToggle` + secção `/admin/files` | VM116 + OCS |
| **UI-034-C** | `StackHealthTile` staff + incident cards retry | Desk nextcloud routes |
| **UI-034-D** | Poll pipeline live + empty/error states | Webhooks NC-5 |

**Ordem Roger:** UI-034-A integrada na **UX-A** gerente ([035 tasks](../035-ligbox-mail-bundles-foss-openpanel/tasks.md)) — pode mockar Files até VM116.

---

## 10. Critérios de aceite UI

- [ ] Gerente vê quota **Email** e **Files** na mesma conta — zero menção «Nextcloud»
- [ ] Criar conta mostra `ProvisionPipeline` com passos NC humanizados
- [ ] Toggle Mail NC domínio default OFF — Spec 035
- [ ] Falha OCS → mensagem PT-BR + retry — staff vê card Mission Board
- [ ] Layout 3 colunas Spec 030 em `/admin/contas` e `/admin/files`
- [ ] Mobile: tabs Contas | Files | Detalhe (Spec 030 mobile pattern)
- [ ] Zero regressão login `admin@{dom}` → `/admin`

---

## 11. Fora de scope (034-UI)

- UI offload anexo no webmail Carbonio (banner link Files — fase separada)
- Purge UI (Spec 017 runbook)
- OIDC senha única (034 fase 2 auth)
- React rewrite completo Desk tickets (opcional futuro)

---

## 12. Documentos relacionados

| Doc | Conteúdo |
|-----|----------|
| [spec.md](./spec.md) | Arquitectura 034 |
| [035-UX shell](../035-ligbox-mail-bundles-foss-openpanel/ligbox-console-shell.md) | Console unificado |
| [035 domain-manager-ui](../035-ligbox-mail-bundles-foss-openpanel/domain-manager-console-ui.md) | Secções `/admin` |
| [030-agentic-ops-ui](../030-agentic-ops-ui/spec.md) | Mission Board referência |
| [nextcloud-provisioning-api.md](./contracts/nextcloud-provisioning-api.md) | Contrato API |