# Spec 027-UI — Matriz de Acessos (Página Desk)

**Criado:** 2026-06-20  
**Solicitado por:** Roger  
**Status:** 🔄 Preview (read-only, feature flag)  
**Sistema:** Desk VM122 · view `access-matrix`  
**Relacionado:** Spec **027** (matriz) · Spec **004** (cadastro) · `platform_role_catalog.py`

---

## Objetivo

Página visual **estilo Odoo Groups + Permission Matrix** para consultar a matriz de funções Ligbox (VM112 / VM122 / VM123 / externas / agentes), **sem alterar** produção até Roger aprovar as telas.

---

## Princípios de entrega

| Regra | Implementação |
|-------|---------------|
| Zero impacto produção | `ACCESS_MATRIX_UI=0` (default) — menu oculto |
| Preview staging | `ACCESS_MATRIX_UI=1` no compose staging (`:8192`) |
| Só leitura v1 | Sem PATCH de roles/módulos na matriz |
| Fonte de verdade | `platform_role_catalog.py` + tabelas Spec 027 §3 |
| Quem vê | `super_admin` apenas (preview) |
| Não substituir | Página **Equipe Ligbox** (`admin-users`) mantida |

---

## Feature flag

```bash
# .env / docker-compose staging
ACCESS_MATRIX_UI=1   # staging preview
ACCESS_MATRIX_UI=0   # produção (default)
```

API:

```http
GET /api/v1/config/features
→ { "access_matrix_ui": true, "preview_mode": true }

GET /api/v1/rbac/matrix
→ catálogo completo (roles, módulos Desk, bindings, agentes, legenda)
```

---

## Referências UI (modelos a seguir)

### GitHub — RBAC admin / permission matrix

| Repo | O que reutilizar | URL |
|------|------------------|-----|
| **rbac-admin-platform** | Dashboard admin, tabela role×ação, audit, dark mode | https://github.com/bankotij/rbac-admin-platform |
| **RBAC-UI** (jagadish-pattanaik) | `PermissionMatrix.js`, sidebar roles, grouping | https://github.com/jagadish-pattanaik/RBAC-UI |
| **rbac-ui** (balamuruganpm) | User/role tables, collapsible sidebar | https://github.com/balamuruganpm/rbac-ui |

### shadcn/ui blocks (padrão visual da grelha)

| Block | O que reutilizar | URL |
|-------|------------------|-----|
| **Tables Permission Matrix** | Linhas agrupadas por módulo, colunas = roles, badges de nível | https://www.shadcn.io/blocks/tables-permission-matrix |
| **Dashboard Permission Matrix** | Grelha recurso×role, cores none/read/write/admin | https://www.shadcn.io/blocks/dashboard-permission-matrix |

### Odoo (modelo conceptual — não fork)

| Conceito Odoo | Equivalente Ligbox |
|---------------|-------------------|
| `res.users` + `groups_id` | `desk_users.role` + provisionamento VM123 |
| `res.groups` | `PLATFORM_ROLE_CATALOG[*].bindings` |
| `ir.model.access` | `permissions.py` + route guards |
| `ir.rule` (record rules) | mascaramento NOC, ticket assignee |
| Settings → Users → Groups UI | Página Matriz de Acessos |

Docs: https://www.odoo.com/documentation/16.0/developer/reference/backend/security.html

### Desk Ligbox (consistência visual)

- Paleta existente: `styles.css` (`--accent`, `--ok`, `--warn`, `--sidebar-bg`)
- Padrão módulo isolado: `agentic-ops.js` + CSS scoped (`#access-matrix-content`)
- Tabs admin: Equipe Ligbox | Matriz (quando flag ON)

---

## Wireframe (Preview v1)

```
┌─ PREVIEW — read-only · Spec 027 ─────────────────────────────────────┐
│ [ Equipe Ligbox ] [ Matriz de Acessos ● ]                            │
├──────────────┬───────────────────────────────────────────────────────┤
│ Funções      │ [ VM122 Desk ] [ VM112 ] [ VM123 ] [ Externas ] [A0-A7]│
│ ─────────    │                                                       │
│ ▶ Ops        │  Grelha módulo × função (✅ 🔒 ❌ ⚙️ 🔗)              │
│   super_admin│  ou painel bindings por serviço (Odoo groups)         │
│   ops_lead   │                                                       │
│ ▶ Comercial  │  Ao seleccionar função → detalhe bindings:            │
│   sales_admin│    vm123_odoo: sales_team.group_sale_manager          │
│   …          │    vm123_foss: ligbox-sales-admin                      │
└──────────────┴───────────────────────────────────────────────────────┘
```

---

## Fases

### Fase UI-A — Preview (esta entrega) ✅

- [x] Spec UI (este documento)
- [x] `GET /api/v1/rbac/matrix` read-only
- [x] `GET /api/v1/config/features`
- [x] `access-matrix.js` + CSS scoped
- [x] Flag staging ON, produção OFF
- [x] Tab **Software em escopo** (VM112 / VM123 / consolas externas — Spec 027 §2, §4, §5)
- [x] Cartão por função (resumo SW ≠ none)
- [ ] Roger aprova layout

### Fase UI-A2 — Melhorias sugeridas (backlog)

| Melhoria | Descrição | Prioridade |
|----------|-----------|------------|
| **Visão unificada** | Uma grelha Desk + SW (coluna «camada»: Desk / VM112 / VM123 / Externa) | Alta |
| **Deep-links activos** | Clicar 🔗 abre URL do serviço (Traefik, OpenPanel, etc.) se binding existir | Alta |
| **Diff vs. realidade** | Comparar matriz Spec 027 com `desk_users.role` + último login por SW | Média |
| **Export CSV/PDF** | Matriz completa para auditoria / onboarding | Média |
| **Filtro por produto** | Chips FOSSBilling, Odoo, OpenPanel, Carbonio… | Baixa |
| **Contas sistema** | Linha 🤖 `api_service` / agentes com credenciais mascaradas | Baixa |
| **Histórico** | Quem alterou role e quando (audit log Spec 004) | Futuro |

### Fase UI-B — Pós-aprovação

- Tab integrada em Administradores (sem flag)
- Export CSV/PDF da matriz
- Link «Ver matriz» no drawer Equipe

### Fase UI-C — Edição Agentics ✅ (staging)

- [x] Tabela SQLite `agent_role_bindings` + `agent_governance_caps`
- [x] `PATCH /api/v1/rbac/agent-bindings` (UI / focus / approve)
- [x] `PATCH /api/v1/rbac/agent-governance` (caps globais)
- [x] `GET /api/v1/rbac/agent-bindings/audit`
- [x] Enforcement API Agentics (`can_use_agentics_ui`, `can_chat_agent`, `can_trigger_runs`)
- [x] Toggles UI / OP / AP na matriz (flag `ACCESS_MATRIX_EDIT=1`)
- [x] Bindings A7→agentic_operator **locked** (Spec FR-027-007)
- [ ] Roger valida em staging → activar produção

---

## Critérios de aceite (Preview)

- [ ] Produção (`8091`): menu Matriz **invisível** com flag default
- [ ] Staging (`8192`): Roger vê Matriz como `super_admin`
- [ ] Página é 100% read-only (sem POST/PATCH)
- [ ] Dados batem com Spec 027 §3–6 e `platform_role_catalog.py`
- [ ] Equipe Ligbox / Mensagens / cadastro **inalterados**

---

*Roger — revisar em http://10.10.10.122:8192 após deploy staging.*