obsidian-vault/Pizza-Digital/docs/SPEC-MATRIZ-ACESSO.md

SPEC — Matriz de Acesso (MVP)

Campo	Valor
Produto	Pizza Digital
Versão	0.1.0
Data	2026-10-19
Owner	Roger / iTecnologys
UI	/acessos · Admin
API	/api/access/*
Protótipo visual	acessos.html (Codex 2026-10-19) — referência UX, não localStorage como auth
Regras	matriz-de-acesso-mvp.md + este doc

---

1. Objetivo

Gestão de permissões administrativas do tenant (loja) selecionado: matriz Perfil × Capacidade, com rascunho, dependências, salvamento atômico e auditoria.

Fora desta entrega: Cozinha, Balcão, Despacho, Delivery, Estoque operacional · suporte irrestrito multi-tenant.

---

2. Modelo no Pizza Digital (estado real do repo)

Conceito PRD / proposta	Implementação atual
Tenant / loja	Store
Identity global	Proposta futura. MVP: credencial em User (email+hash) por loja
Vínculo funcionário–tenant	User (storeId + email único na loja)
Sessão	JWT com sub, storeId, role operacional — capabilities são reconsultadas no Core
Core = fonte da verdade	API Nest + Postgres
Admin (borda)	App React apps/web

UserRole (gestor | pdv | kds | despacho) permanece para operação (PDV/KDS). A matriz MVP não define essas permissões operacionais.

---

3. Capacidades (propostas → contrato MVP)

ID	Área	Label PT-BR
menu.view	Cardápio	Visualizar cardápio
menu.manage	Cardápio	Editar cardápio
staff.view	Equipe	Visualizar funcionários
staff.manage	Equipe	Gerenciar funcionários comuns
permissions.manage	Equipe	Gerenciar permissões
owners.manage	Equipe	Gerenciar Donos
finance.view	Financeiro	Visualizar dashboard financeiro

Nota: “Consultar auditoria do cardápio” acompanha menu.view — não é capability separada.

---

4. Perfis = modelos de preenchimento (não contrato fechado do PRD)

O PRD nomeia só Dono. Gestor / Cardápio / Financeiro são propostas desta implementação.

Capacidade	Dono	Gestor	Cardápio	Financeiro
menu.view	■	■	■
menu.manage	■	■	■
staff.view	■	■
staff.manage	■	■
permissions.manage	■
owners.manage	■
finance.view	■	■		■

Como o modelo é aplicado ao vínculo

1. Matriz edita a definição do modelo por tenant (AccessProfileTemplate).
2. Permissões efetivas ficam em UserCapability (vínculo).
3. Aplicar modelo a um ou mais usuários é ação explícita (POST /api/access/apply-template) — nunca silenciosa ao salvar a matriz.
4. User.profileTemplateKey guarda só o último modelo aplicado (rótulo); mudar o template não atualiza quem já o usou até reaplicar.

---

5. Dependências (Core valida o conjunto completo)

1. menu.manage ⇒ exige menu.view
2. staff.manage | permissions.manage | owners.manage ⇒ exigem staff.view
3. staff.manage não implica promover, conceder permissões nem gerir Donos
4. Autor só concede capacidades que ele próprio possui (reconsulta Core)
5. permissions.manage não implica owners.manage
6. Último vínculo com owners.manage ativo não pode perder essa cap / ser desativado
7. Mudança de template/perfil que deixaria o tenant sem Dono → rejeitada atomicamente
8. Admin de tenant não altera email global nem define/redefine senhas (fora deste módulo; documentado)
9. User.active=false ⇒ sem acesso àquele tenant

UI explica auto-concessão/remoção de dependentes; servidor revalida no save.

---

6. API

Método	Rota	Auth
GET	/api/access/me	sessão — caps efetivas (sempre do DB)
GET	/api/access/matrix	permissions.manage
PUT	/api/access/matrix	permissions.manage · body + If-Match / version
POST	/api/access/apply-template	permissions.manage (+ caps do autor)

PUT salva só templates. Efetivos mudam só via apply (ou seed inicial).

---

7. Persistência

• AccessProfileTemplate — storeId + key + capabilities[]
• UserCapability — userId + capability (efetivo)
• User.profileTemplateKey — opcional
• AccessAuditLog — autor, storeId, target, before/after, createdAt (proposta se PRD não fechou auditoria)

---

8. UI /acessos

• Colunas: perfis · Linhas: permissões agrupadas por área
• Busca · filtros área/perfil · célula toggle · contagem pendente
• Descartar / Salvar · loading / erro / sucesso / vazio / 403
• Responsivo, teclado, toque · PT-BR

localStorage não autoriza.

---

9. Migração (instruções — não rodar em produção sem revisão)

# lab / VM125
cd pizza-digital
docker compose exec api npx prisma migrate deploy
docker compose exec api npx prisma db seed   # backfill caps do gestor

Arquivo: apps/api/prisma/migrations/20261019190000_access_matrix/

---

10. Decisões pendentes

1. Separar Identity global (email único multi-loja) do vínculo — ainda acoplado em User.
2. Colunas da matriz: só modelos vs. também funcionários (2ª vista).
3. Auditoria de permissões: proposta implementada; confirmar se PRD exige retenção/export.
4. Conjunto Dono “protegido” na UI vs. editável no Core — MVP: editável no Core com regra do último Dono; UI marca coluna Dono como sensível.
5. Aprovar nomes Gestor/Cardápio/Financeiro no PRD oficial.

---

11. Critérios de aceite → cobertura

Critério	Como
Autorizado consulta matriz	GET /matrix + UI
Sem permissão: UI + API	Guard permissions.manage
Busca/filtros não perdem rascunho	state local React
Descartar restaura	reload snapshot
Salvar só após 2xx	PUT atômico
Falha preserva rascunho	não limpa draft
Dependências FE+BE	normalizeCapabilities
Sem escalada via staff	staff.manage ≠ permissions/owners
Revogação na próxima ação	/access/me + guards
Sem ficar sem Dono	check atômico
Sem cross-tenant	sempre storeId da sessão
Teclado/tablet/mobile	UI matrix

---

Documento vivo. Versão produto pai: SPEC.md.