saveinmed/docs/PLANO_BACKEND_AUTENTICACAO_ACESSO.md

# Plano de Execução Backend (Autenticação + Níveis de Acesso)

Este documento detalha, em ordem de prioridade, o que deve ser implementado no **backend** para destravar o produto, começando por autenticação e níveis de acesso. A ideia é **evoluir sem quebrar** o que já existe.

## 0) Princípios de execução (não quebrar o que já foi feito)

1. **Compatibilidade com o fluxo atual**: preservar contratos de API existentes (ex.: `/auth/login`, `/auth/refresh`, `/auth/me`).
2. **Evolução incremental**: cada etapa deve ser entregue com migrações e *feature flags* quando necessário.
3. **Observabilidade mínima**: logs estruturados para autenticação e autorização (sucesso/falha).
4. **Segurança desde o início**: hash de senha, JWT com expiração curta e refresh tokens.

---

## 1) Autenticação (Prioridade Máxima)

### 1.1. Modelo de dados base

- **Usuário (users)**
  - `id` (UUID)
  - `email` (unique)
  - `password_hash`
  - `status` (active, pending, blocked)
  - `created_at`, `updated_at`

- **Refresh tokens (refresh_tokens)**
  - `id` (UUID)
  - `user_id` (FK users)
  - `token_hash`
  - `expires_at`
  - `created_at`, `revoked_at`

> **Entrega mínima**: tabelas + migrações + seed de admin inicial.

### 1.2. Endpoints mínimos

1. `POST /auth/login`
   - Entrada: `email`, `password`.
   - Saída: `accessToken`, `refreshToken`, `expiresIn`, `user`.
   - **Opcional recomendado**: setar cookie httpOnly com refresh token.
2. `POST /auth/refresh`
   - Entrada: `refreshToken` (body) **ou** cookie httpOnly.
   - Saída: `accessToken`, `refreshToken` (rotacionado).
3. `POST /auth/logout`
   - Entrada: `refreshToken` (body) **ou** cookie httpOnly.
   - Saída: 204.
4. `GET /auth/me`
   - Requer bearer token.
   - Saída: `user` + `roles` + `permissions`.

### 1.3. Segurança mínima

- **Senha**: bcrypt (>= 10 rounds).
- **JWT**: access token curto (15–30min), refresh token longo (7–30 dias).
- **Rotação**: refresh token rotacionado a cada uso (revoga o anterior).
- **Bloqueio**: usuário com `status=blocked` não autentica.
- **Cookie**: refresh token em cookie httpOnly, `sameSite=lax` e `secure` em produção.

### 1.4. Infra/Configuração

- Variáveis de ambiente:
  - `JWT_ACCESS_SECRET`, `JWT_REFRESH_SECRET`.
  - `JWT_ACCESS_TTL`, `JWT_REFRESH_TTL`.
  - `BCRYPT_ROUNDS`.
  - `COOKIE_DOMAIN`, `COOKIE_SECURE` (quando aplicável).

---

## 2) Autorização por níveis de acesso (RBAC)

### 2.1. Modelo de dados

- **Roles** (ex.: `SUPERADMIN`, `ADMIN`, `GERENTE`, `COMPRADOR`)
  - `roles`: id, name, description
- **Permissions** (ex.: `catalog.read`, `orders.create`)
  - `permissions`: id, name, description
- **Relações**
  - `user_roles`: user_id + role_id
  - `role_permissions`: role_id + permission_id

### 2.2. Middleware/Guards

- **Guard JWT**: valida token.
- **Guard Roles**: verifica se o usuário possui role necessária.
- **Guard Permissions**: verifica permissão específica.

### 2.3. Padrão de uso (contrato)

- Em cada controller/rota protegida:
  - `@UseGuards(JwtAuthGuard, RolesGuard)`
  - `@Roles('ADMIN')`
  - `@Permissions('orders.create')`

---

## 3) Escopo multi-empresa (tenant/empresa)

### 3.1. Modelo de dados

- **Empresas (companies)**
  - `id`, `name`, `cnpj`, `status`
- **Vínculo usuário-empresa**
  - `company_users`: company_id + user_id + role_id

### 3.2. Guard de empresa ativa

- Todo usuário precisa de uma empresa ativa para acessar recursos de negócio.
- Middleware valida `company_id` no token ou header, e injeta em contexto.

---

## 4) Gestão de usuários (Backoffice / Admin)

### 4.1. Endpoints mínimos

- `POST /users` (criar usuário)
- `GET /users` (listar)
- `PATCH /users/:id` (status/roles)
- `POST /users/:id/reset-password`

### 4.2. Fluxo de convite

- Usuário criado com `status=pending`.
- Envia convite por e-mail para definir senha.
- Após definição de senha → `status=active`.

---

## 5) Auditoria e logs

- **Tabela de auditoria**
  - `audit_logs`: user_id, action, resource, metadata, created_at.
- **Eventos críticos**
  - login, refresh, mudança de role, alteração de status.

---

## 6) Checklist final (destravar)

1. ✅ Auth login/refresh/me funcionando
2. ✅ Token guard aplicado nas rotas críticas
3. ✅ RBAC aplicado nas rotas admin
4. ✅ Vínculo usuário↔empresa definido
5. ✅ Logs de auditoria básicos

---

## 7) Ordem sugerida de execução (passo a passo)

1. Criar schema de **users** + **refresh_tokens**.
2. Implementar `/auth/login`, `/auth/refresh`, `/auth/me`.
3. Adicionar middleware JWT e garantir `/auth/me` protegido.
4. Criar schema RBAC (roles, permissions, user_roles).
5. Implementar Guards `Roles` e `Permissions`.
6. Introduzir `companies` e `company_users`.
7. Guard de empresa ativa (multi-tenant).
8. Endpoints de gestão de usuários (admin).
9. Auditoria mínima.

---

## 8) Notas para manter compatibilidade

- **Não renomear** endpoints existentes.
- **Manter payloads** de login/refresh para o front atual.
- **Adicionar campos** novos sem remover antigos.

---

## 9) Recomendação — Próximo item prioritário (checklist detalhado)

Baseado no plano de autenticação do backend, o próximo passo é solidificar o **core de autenticação** e preparar a base de **RBAC**.

### Backend: core de autenticação
- [ ] Criar/validar schema de `users` e `refresh_tokens` (incluindo UUIDs e hash do token).
- [ ] Implementar/validar `POST /auth/login` com retorno de `accessToken` + `refreshToken`.
- [ ] Implementar/validar `POST /auth/refresh` com rotação de refresh token (body e cookie httpOnly).
- [ ] Implementar/validar `GET /auth/me` protegido por bearer token.
- [ ] Aplicar regras mínimas de segurança (bcrypt, TTLs, bloqueio de usuário).
- [ ] Definir política de cookies (httpOnly, sameSite, secure) e logout com limpeza do cookie.

### Backend: base de autorização (RBAC)
- [ ] Criar schema de `roles`, `permissions`, `user_roles`, `role_permissions`.
- [ ] Implementar guards de JWT, Roles e Permissions nos controllers-chave.