# PRD — Matriz de Acesso (MVP)

| Campo | Valor |
|-------|--------|
| **Produto** | Pizza Digital |
| **Versão app auditada** | v0.5.0 |
| **Ambiente** | https://pizza.itecnologys.com · VM125 · loja `pizza-digital-piloto` |
| **Spec de origem** | `docs/SPEC-MATRIZ-ACESSO.md` |
| **Módulo** | Capabilities admin por tenant |
| **Rotas UI** | `/admin/acessos` |
| **APIs** | `/api/access/*` |
| **Data** | 2026-11-09 |
| **Estilo** | PRD operacional detalhado (visão de desenvolvedor) |
| **Audiência** | Dev / QA / Product |

> Como ler: cada seção descreve o **processo real** (o que o sistema faz hoje),
> com passos de usuário, chamadas de API, regras de negócio e estados.
> Status: ✅ construído · ⚠️ parcial · ⏳ especificado / não entregue · 🐛 gap observado.


## 1. Ideia central (dev)

Roles operacionais (`gestor|pdv|kds|despacho`) ≠ capabilities admin.
Capabilities vivem em `UserCapability` e são **revalidadas no Core** a cada ação sensível.

### Caps
`menu.view/manage` · `staff.view/manage` · `permissions.manage` · `owners.manage` · `finance.view`

## 2. Processo — ver minhas permissões
1. Login JWT (`sub`, `storeId`, `role`)
2. `GET /api/access/me` → capabilities efetivas
3. Front esconde/mostra Admin conforme caps

## 3. Processo — editar matriz
1. Usuário com `permissions.manage`
2. `GET /api/access/matrix` carrega templates Perfil×Cap
3. Edita rascunho na UI `/admin/acessos`
4. `PUT /api/access/matrix` salva definição do template (atômico)
5. **Não** propaga sozinho aos users

## 4. Processo — aplicar template a usuários
1. Seleciona staff `GET /api/access/staff`
2. `POST /api/access/apply-template` { userIds, templateKey }
3. Reescreve `UserCapability`
4. Auditoria `AccessAuditLog` (quando habilitada)

## 5. Dependências Core
- `menu.manage` ⇒ `menu.view`
- `staff.manage` ⇒ `staff.view`
- Normalização em `capabilities.ts`

## 6. Aceite
- ✅ API matrix/me/staff/apply
- ✅ UI AccessMatrixPage
- ⚠️ Auditoria completa em todos writes


## 7. Camada de serviço (AccessService)

| Método | Fluxo |
|--------|-------|
| `ensureTemplates` | Garante templates default da loja |
| `getEffectiveCapabilities` | Resolve caps (+ fallback gestor) |
| `assertCapability` | Throws ForbiddenException |
| `getMatrix` / `saveMatrix` | CRUD definição |
| `applyTemplate` | Propaga para users |
| `listStaffForApply` | Alvos |
| `assertTenantKeepsOwner` | Não deixa loja sem owner |
| `setUserCapabilities` | Write direto |