ligbox-ops-platform/specs/040-desk-design-system-v013/spec.md

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

---

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

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

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

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