# SPEC — Usuários, senha e sessão

| Campo | Valor |
|-------|--------|
| **Produto** | Pizza Digital |
| **Capítulo** | Equipe / Auth |
| **Versão** | 0.1.0 |
| **Data** | 2026-10-20 |
| **Owner** | Roger / iTecnologys |
| **UI** | `/admin/equipe` · `/forgot-password` · `/reset-password` |
| **API** | `/api/users` · `/api/auth/*` |
| **Irmã** | [`SPEC-MATRIZ-ACESSO.md`](SPEC-MATRIZ-ACESSO.md) |

---

## 1. Objetivo

Cadastrar quem opera a loja (PDV, KDS, despacho, gestor), com senha forte, bloqueio por tentativa, recuperação e vínculo à matriz de acesso.

---

## 2. Modelo

```text
User
  email, name, role (gestor|pdv|kds|despacho)
  jobTitle, areas[], phone, active
  passwordHash, mustChangePassword, passwordChangedAt
  failedLoginAttempts, lockedUntil, lastLoginAt
  profileTemplateKey   ← rótulo do último modelo aplicado

AuthToken     password_reset | invite | email_verify
PushDevice    token web/app
NotifyLog     email | push (auditoria de envio)
UserCapability  fonte da verdade no vínculo (SPEC matriz)
```

---

## 3. Requisitos

| ID | Requisito | Status |
|----|-----------|--------|
| RF-USR-01 | CRUD equipe (`staff.view` / `staff.manage`) | **feito** |
| RF-USR-02 | Cargo (`jobTitle`) + áreas (`pdv`, `kds`, `despacho`, `admin`, …) | **feito** |
| RF-USR-03 | Política de senha: ≥8, maiúscula, minúscula, dígito; sem o local-part do e-mail | **feito** |
| RF-USR-04 | Lockout: 5 falhas → 15 min (`lockedUntil`) | **feito** |
| RF-USR-05 | Recuperação por e-mail (link 60 min) + stub push | **feito** (SMTP produção opcional) |
| RF-USR-06 | Convite / `mustChangePassword` no primeiro acesso | **feito** |
| RF-USR-07 | Aplicar template da matriz no cadastro | **feito** |
| RF-USR-08 | Gestor extra exige `owners.manage` | **feito** |
| RF-USR-09 | Desbloquear conta (`unlock`) | **feito** |
| RF-USR-10 | SMTP/push reais em produção | **stub** |

---

## 4. Política de senha (congelada)

```text
minLength 8 · max 128
1 maiúscula · 1 minúscula · 1 dígito
não contém o e-mail
maxFailedAttempts 5 · lockMinutes 15
resetTokenTtlMinutes 60
```

Código: `apps/api/src/auth/password-policy.ts`.

---

## 5. Fluxos

1. Gestor cria usuário em `/admin/equipe` → hash bcrypt → opcional convite.
2. Login `/api/auth/login` incrementa falhas; 5× bloqueia 15 min.
3. Esqueci senha → `AuthToken.password_reset` → e-mail com link (resposta genérica, não vaza existência).
4. Reset consome token, valida política, limpa lockout.

---

## 6. Fora desta SPEC

- SSO / SAML
- 2FA TOTP (fase futura)
- Multi-loja no mesmo login

---

*Satélite. Produto pai: SPEC.md v0.3.5.*