b03bb2c37c
Commita governance, user-wizard, operational-feed e catálogo RBAC; adiciona deploy-desk-full.sh, smoke-desk.sh e regra anti-deploy parcial; documenta credencial VM112 @betinplace. Co-authored-by: Cursor <cursoragent@cursor.com>
217 lines
8.6 KiB
Markdown
217 lines
8.6 KiB
Markdown
# Spec 040 — Desk Design System v0.13 (UI Operacional)
|
||
|
||
**Criado:** 2026-06-29
|
||
**Solicitado por:** Roger
|
||
**Status:** ✅ UI Access Control Hub **aprovado Roger** 2026-06-25 · `0.13.1-ac-hub-ui-aprovado-roger`
|
||
**Prioridade:** P0
|
||
**Versão Desk:** `0.13.1-ac-hub-ui-aprovado-roger`
|
||
**Rollback DS v0.13:** `projects/ops-desk/frontend/staging-snapshot/v0.12.2-pre-ds-20260625/`
|
||
**Rollback UI aprovado:** `projects/ops-desk/frontend/staging-snapshot/v0.13.1-ac-hub-ui-aprovado-20260625/`
|
||
**Aprovação Obsidian:** [[APROVADO-UI-ROGER-20260625]]
|
||
**Estende:** Spec **027** (Matriz RBAC), **039** (catálogo autorização), **015** (módulos Desk)
|
||
**Não inclui:** Central Operacional / Operational Feed — ver **[Spec 041](../041-desk-operational-feed/spec.md)**
|
||
|
||
---
|
||
|
||
## 1. Problema
|
||
|
||
O Desk v0.12.2 tinha:
|
||
|
||
- Modal simples para criar utilizador (1 ecrã)
|
||
- Controle de acesso em split compacto (tabela inline)
|
||
- Aba «Mensagens» = apenas pedidos de cadastro
|
||
|
||
Roger definiu **Design System enterprise** (UI principles, visual language, navigation, action patterns, user wizard) e mockups para:
|
||
|
||
1. **UserWizard** — criar utilizador (5 passos, fullscreen)
|
||
2. **Access Control Hub** — gestão completa na aba Controle de acesso (Matriz)
|
||
3. Vocabulário: *Operational feed*, *Access capabilities*, *Desactivar conta*
|
||
|
||
A Spec **041** cobre isoladamente a aba Central Operacional (ex-Mensagens).
|
||
|
||
---
|
||
|
||
## 2. Escopo desta spec (040)
|
||
|
||
| Incluído | Excluído (→ 041) |
|
||
|----------|------------------|
|
||
| UserWizard fullscreen | Feed omnicanal |
|
||
| Access Control Hub | `/api/v1/ops-inbox/*` |
|
||
| Governance API | Canais WhatsApp, email inbound |
|
||
| Audit log utilizadores | KPIs inbox |
|
||
| Design tokens CSS (`ligbox-ds.css`) | |
|
||
|
||
---
|
||
|
||
## 3. Arquitetura UI
|
||
|
||
```text
|
||
Matriz de Acesso (#view-access-matrix)
|
||
└── Aba «Controle de acesso» (tab access-control)
|
||
└── DeskAccessControlHub (DS-FE-004)
|
||
├── Sub-aba «Gestão de utilizadores»
|
||
│ ├── StatsCard row (KPIs)
|
||
│ ├── Entity cards (lista utilizadores — NÃO tabela primária)
|
||
│ ├── Right detail panel (Detalhes | Access capabilities | Actividades)
|
||
│ └── + Criar utilizador → DeskUserWizard (DS-FE-003)
|
||
└── Sub-aba «Capacidades da função»
|
||
└── DeskAccessControlPanel.paintCapabilitiesOnly (Spec 027/039)
|
||
|
||
DeskUserWizard (DS-FE-003) — fullscreen modal
|
||
├── Step 1 Basic data
|
||
├── Step 2 Profile and group
|
||
├── Step 3 Access capabilities (module matrix)
|
||
├── Step 4 Review
|
||
└── Step 5 Success (+ audit + invite link)
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Registo de ficheiros (referência futura)
|
||
|
||
Código interno: **`DS-{tipo}-{nnn}`** — usar em commits, PRs e tickets.
|
||
|
||
### 4.1 Frontend — Design System
|
||
|
||
| Código | Ficheiro | Global JS | Função |
|
||
|--------|----------|-----------|--------|
|
||
| **DS-FE-001** | `frontend/assets/ligbox-ds.css` | — | Tokens CSS (`--lb-*`), cards, wizard, modals, layout ops |
|
||
| **DS-FE-002** | `frontend/assets/ligbox-ds.css` | — | Cache bust: `?v=20260629v013` |
|
||
|
||
### 4.2 Frontend — Módulos
|
||
|
||
| Código | Ficheiro | Global JS | Função |
|
||
|--------|----------|-----------|--------|
|
||
| **DS-FE-003** | `frontend/assets/user-wizard.js` | `window.DeskUserWizard` | Wizard fullscreen criar utilizador (≥3 passos) |
|
||
| **DS-FE-004** | `frontend/assets/access-control-hub.js` | `window.DeskAccessControlHub` | Hub img 4 — cards, KPIs, painel direito |
|
||
| **DS-FE-005** | `frontend/assets/access-control-panel.js` | `window.DeskAccessControlPanel` | Delega hub; sub-aba capacidades (Spec 039) |
|
||
| **DS-FE-006** | `frontend/assets/user-management-panel.js` | `window.DeskUserManagement` | Edit modal, clone; `openEdit()` para hub |
|
||
|
||
### 4.3 Frontend — Integração
|
||
|
||
| Código | Ficheiro | Alteração |
|
||
|--------|----------|-----------|
|
||
| **DS-FE-010** | `frontend/index.html` | Scripts DS-FE-003/004/005/006, `ligbox-ds.css`, nav «Central Operacional», footer v0.13.0 |
|
||
| **DS-FE-011** | `frontend/assets/app.staging.js` | Títulos Spec 040/041; `renderMessages()` delega Spec 041 |
|
||
| **DS-FE-012** | `frontend/assets/access-matrix.js` | Host `#am-access-control-host` → `DeskAccessControlPanel.paint` |
|
||
|
||
### 4.4 API — Backend
|
||
|
||
| Código | Ficheiro | Router prefix | Função |
|
||
|--------|----------|---------------|--------|
|
||
| **DS-API-001** | `api/app/desk_governance_store.py` | — | Schema SQLite: audit, user_meta, module permissions |
|
||
| **DS-API-002** | `api/app/governance_routes.py` | `/api/v1/governance` | Wizard, freeze, reset password, audit, stats |
|
||
| **DS-API-003** | `api/app/main.py` | — | Registo routers; init schema; version `0.13.0-design-system` |
|
||
|
||
### 4.5 Versionamento e rollback
|
||
|
||
| Código | Ficheiro | Função |
|
||
|--------|----------|--------|
|
||
| **DS-META-001** | `projects/ops-desk/VERSION` | `0.13.0-design-system` |
|
||
| **DS-META-002** | `frontend/staging-snapshot/v0.12.2-pre-ds-20260625/` | Snapshot pré-build + `ROLLBACK.md` |
|
||
|
||
### 4.6 Skills (Cursor — design system)
|
||
|
||
| Código | Ficheiro | Função |
|
||
|--------|----------|--------|
|
||
| **DS-SK-001** | `~/.cursor/skills/ligbox/product.skill.md` | Identidade produto |
|
||
| **DS-SK-002** | `~/.cursor/skills/ligbox/ux.skill.md` | UX + visual + navigation |
|
||
| **DS-SK-003** | `~/.cursor/skills/ligbox/permissions.skill.md` | Hierarquia RBAC UI |
|
||
| **DS-SK-004** | `~/.cursor/skills/ligbox/onboarding.skill.md` | User creation flow |
|
||
| **DS-SK-005** | `~/.cursor/skills/ligbox/messaging.skill.md` | → aponta Spec 041 |
|
||
| **DS-SK-006** | `~/.cursor/skills/ligbox/audit.skill.md` | Audit log pattern |
|
||
|
||
---
|
||
|
||
## 5. API Governance (resumo)
|
||
|
||
Contrato completo: [contracts/governance-api.md](contracts/governance-api.md)
|
||
|
||
| Método | Endpoint | Código acção | Descrição |
|
||
|--------|----------|--------------|-----------|
|
||
| GET | `/api/v1/governance/modules` | `desk.governance.modules.list` | Módulos + níveis + grupos |
|
||
| GET | `/api/v1/governance/users/stats` | `desk.governance.users.stats` | KPIs gestão utilizadores |
|
||
| GET | `/api/v1/governance/users/{username}/meta` | `desk.governance.user.meta` | Meta + internal_id + permissions |
|
||
| POST | `/api/v1/governance/users/wizard` | `desk.auth.user.create` | Criar via wizard (audit + invite) |
|
||
| POST | `/api/v1/governance/users/{username}/freeze` | `desk.auth.user.freeze` | Congelar/activar + audit |
|
||
| POST | `/api/v1/governance/users/{username}/reset-password` | `desk.auth.user.password.reset` | Reset admin + audit |
|
||
| GET | `/api/v1/governance/audit` | `desk.governance.audit.list` | Audit por target |
|
||
|
||
**Auth:** Bearer JWT · `can_manage_users` (super_admin).
|
||
|
||
---
|
||
|
||
## 6. Modelo de dados (SQLite)
|
||
|
||
### `desk_governance_audit`
|
||
|
||
| Coluna | Tipo | Notas |
|
||
|--------|------|-------|
|
||
| actor_username | TEXT | Quem executou |
|
||
| action | TEXT | ex. `user.created`, `user.frozen` |
|
||
| target_type | TEXT | ex. `user` |
|
||
| target_id | TEXT | username |
|
||
| summary | TEXT | «Created by Super Admin» |
|
||
|
||
### `desk_user_meta`
|
||
|
||
| Coluna | Tipo | Notas |
|
||
|--------|------|-------|
|
||
| internal_id | TEXT | `LB-XXXXXXXX` |
|
||
| main_group | TEXT | Ops, Comercial, … |
|
||
| secondary_groups_json | TEXT | JSON array |
|
||
| module_permissions_json | TEXT | Desk/OpenPanel/… × none/read/partial/full |
|
||
| invite_token | TEXT | Link convite |
|
||
|
||
---
|
||
|
||
## 7. User Wizard — fluxo
|
||
|
||
Ver skill **DS-SK-004** e mockups Roger (imgs 1–2).
|
||
|
||
Passos UI: Basic data → Profile/group → Access capabilities → Review → Success.
|
||
|
||
Submit `POST /api/v1/governance/users/wizard` executa:
|
||
|
||
1. INSERT `desk_users`
|
||
2. INSERT `desk_user_meta`
|
||
3. INSERT `desk_governance_audit` (`user.created`)
|
||
4. E-mail convite (opcional)
|
||
5. Resposta: `user`, `meta`, `internal_id`, `invite_link`
|
||
|
||
---
|
||
|
||
## 8. Regras UX (obrigatórias)
|
||
|
||
- **Create:** sempre wizard, mínimo 3 passos, fullscreen
|
||
- **Edit:** side panel / modal médio (`DeskUserManagement.openEdit`)
|
||
- **Desactivar conta:** small modal + audit (nunca «Delete» na UI)
|
||
- **Cards > tables** para lista primária de utilizadores
|
||
- Paleta: `#F6F3EE` / `#5B1632` / cards `#FFFFFF`
|
||
|
||
---
|
||
|
||
## 9. Relação com outras specs
|
||
|
||
| Spec | Relação |
|
||
|------|---------|
|
||
| 027 | Matriz RBAC; aba Controle de acesso dentro da Matriz |
|
||
| 039 | Catálogo acções; toggles capacidades da função |
|
||
| 041 | Central Operacional (aba ex-Mensagens) — **spec separada** |
|
||
| 004 | Pedidos cadastro — `renderRegistrationRequestsLegacy()` preservado |
|
||
|
||
---
|
||
|
||
## 10. Deploy
|
||
|
||
```bash
|
||
# VM122 produção
|
||
docker cp → ligbox-ops-platform_frontend_1:/usr/share/nginx/html/
|
||
docker cp → ligbox-ops-platform_api_1:/app/app/
|
||
docker restart ligbox-ops-platform_api_1
|
||
```
|
||
|
||
Validação:
|
||
|
||
- `GET https://desk.ligbox.com.br/api/health` → `"version":"0.13.0-design-system"`
|
||
- Matriz → Controle de acesso → + Criar utilizador (wizard)
|