diff --git a/docs/PLANO_BACKEND_AUTENTICACAO_ACESSO.md b/docs/PLANO_BACKEND_AUTENTICACAO_ACESSO.md new file mode 100644 index 0000000..0c97538 --- /dev/null +++ b/docs/PLANO_BACKEND_AUTENTICACAO_ACESSO.md @@ -0,0 +1,163 @@ +# 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`. +2. `POST /auth/refresh` + - Entrada: `refreshToken`. + - Saída: `accessToken`, `refreshToken` (rotacionado). +3. `POST /auth/logout` + - Entrada: `refreshToken`. + - 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. + +### 1.4. Infra/Configuração + +- Variáveis de ambiente: + - `JWT_ACCESS_SECRET`, `JWT_REFRESH_SECRET`. + - `JWT_ACCESS_TTL`, `JWT_REFRESH_TTL`. + - `BCRYPT_ROUNDS`. + +--- + +## 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. +