From 312f330bdf769c2b155b0c8b307da14f37a2c73a Mon Sep 17 00:00:00 2001 From: Rafael Lopes Date: Thu, 14 May 2026 17:45:00 -0300 Subject: [PATCH] =?UTF-8?q?DOCS:=20Adicionado=20documenta=C3=A7=C3=A3o=20s?= =?UTF-8?q?obre=20controle=20de=20acesso?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/access-control.md | 351 +++++++++++++++++++++++++++++++++++++++++ docs/auth.md | 10 +- 2 files changed, 360 insertions(+), 1 deletion(-) create mode 100644 docs/access-control.md diff --git a/docs/access-control.md b/docs/access-control.md new file mode 100644 index 0000000..231b922 --- /dev/null +++ b/docs/access-control.md @@ -0,0 +1,351 @@ +# Controle de Acesso, Areas e Usuarios + +## Visao geral + +O backend agora usa o banco PostgreSQL para manter o usuario interno da aplicacao e suas atribuicoes operacionais. + +A autenticacao continua sendo feita por provedores externos: + +- LDAP / Active Directory +- Microsoft OAuth + +Depois que o provedor confirma a identidade, o backend sincroniza esse usuario no banco e consulta: + +- perfis de acesso +- areas vinculadas +- area principal +- status de acesso + +Esse status determina qual experiencia o frontend deve renderizar em `/home`. + +--- + +## Fluxo de login com banco + +```text +Frontend + -> POST /auth/login ou OAuth Microsoft + -> Backend autentica no provedor externo + -> Backend cria/atualiza usuarios + -> Backend cria/atualiza usuarios_provedores + -> Backend consulta usuarios_perfis e usuarios_areas + -> Backend emite JWT com perfis/areas + -> Frontend salva authToken/authUser + -> Frontend navega para /home +``` + +O provedor externo valida identidade. O banco define acesso dentro do Omnichannel. + +--- + +## Tabelas usadas + +### `usuarios` + +Representa uma pessoa autenticada no produto. + +Campos principais: + +- `id` +- `nome` +- `email` +- `ativo` +- `created_at` +- `updated_at` + +### `usuarios_provedores` + +Relaciona o usuario interno com o provedor externo usado no login. + +Exemplos: + +- `ldap` + username do AD +- `microsoft` + userPrincipalName/email + +### `perfis_acesso` + +Define os niveis de acesso. + +Perfis iniciais: + +- `Agente` +- `Supervisor` +- `Admin` + +### `usuarios_perfis` + +Relaciona usuarios e perfis. + +Hoje o frontend usa o perfil principal para decidir a experiencia em `/home`. + +### `areas` + +Representa as areas operacionais. + +Areas iniciais: + +- `Suporte` +- `Financeiro` +- `Comercial` + +### `usuarios_areas` + +Relaciona usuarios e areas. + +Um usuario pode ter mais de uma area, mas a regra atual permite no maximo uma area principal por usuario. + +--- + +## Status de acesso + +O backend devolve `accessStatus` no usuario autenticado. + +Valores: + +- `assigned`: usuario tem pelo menos um perfil e uma area +- `unassigned`: usuario existe/autenticou, mas ainda nao tem perfil ou area + +### Comportamento no frontend + +```text +assigned + Admin -> /home renderiza painel Admin +assigned + Supervisor -> /home renderiza painel Supervisor +assigned + Agente -> /home renderiza tela do Atendente +unassigned -> /home renderiza tela de acesso aguardando configuracao +``` + +Esse comportamento permite que um usuario novo entre via AD/OAuth, seja criado no banco e fique bloqueado ate um Admin atribuir perfil e area. + +--- + +## Payload do usuario autenticado + +Exemplo de resposta do login: + +```json +{ + "token": "jwt", + "user": { + "id": "1", + "databaseId": 1, + "name": "Atendente Demo", + "email": "atendente@sothis.com.br", + "username": "atendente", + "provider": "ldap", + "perfis": ["Agente"], + "profiles": ["Agente"], + "areas": ["Suporte"], + "areaPrincipal": "Suporte", + "accessStatus": "assigned" + } +} +``` + +No JWT tambem entram: + +- `name` +- `email` +- `provider` +- `username` +- `perfis` +- `profiles` +- `areas` +- `areaPrincipal` +- `accessStatus` + +--- + +## Variaveis de ambiente + +O backend le as variaveis de banco pelo `.env.development` em desenvolvimento. + +```env +DB_HOST=10.0.120.75 +DB_PORT=5432 +DB_USER=desenvolvimento +DB_PASSWORD=******** +DB_NAME=omnichannel-dev +``` + +Observacao: + +- `npm run dev` usa `NODE_ENV=development` e carrega `.env.development`. +- `npm run start` usa `NODE_ENV=production`; nesse caso, configure `.env.production` ou variaveis do ambiente. + +--- + +## Endpoints administrativos + +Base path: + +```text +/admin/access +``` + +### Listar opcoes de acesso + +```http +GET /admin/access/options +``` + +Resposta: + +```json +{ + "profiles": [ + { "id": 3, "nome": "Admin" }, + { "id": 1, "nome": "Agente" }, + { "id": 2, "nome": "Supervisor" } + ], + "areas": [ + { "id": 3, "nome": "Comercial" }, + { "id": 2, "nome": "Financeiro" }, + { "id": 1, "nome": "Suporte" } + ] +} +``` + +### Listar usuarios + +```http +GET /admin/access/users +``` + +Resposta: + +```json +[ + { + "id": 1, + "nome": "Admin Demo", + "email": "admin@sothis.com.br", + "ativo": true, + "perfis": [{ "id": 3, "nome": "Admin" }], + "areas": [{ "id": 1, "nome": "Suporte", "principal": true }], + "perfilPrincipal": { "id": 3, "nome": "Admin" }, + "areaPrincipal": { "id": 1, "nome": "Suporte", "principal": true }, + "accessStatus": "assigned" + } +] +``` + +### Atualizar acesso de usuario + +```http +PUT /admin/access/users/:id +Content-Type: application/json +``` + +Body: + +```json +{ + "perfilId": 2, + "areaId": 1 +} +``` + +Comportamento atual: + +- remove perfis anteriores do usuario +- remove areas anteriores do usuario +- cria o novo perfil informado +- cria a nova area como principal +- retorna o usuario atualizado + +Para remover atribuicoes: + +```json +{ + "perfilId": null, + "areaId": null +} +``` + +--- + +## Usuarios de demonstracao + +A migration `003_demo_access.sql` cria usuarios iniciais para demonstracao: + +| Usuario | Email | Perfil | Area | +|---|---|---|---| +| Admin Demo | `admin@sothis.com.br` | Admin | Suporte | +| Supervisor Demo | `supervisor@sothis.com.br` | Supervisor | Suporte | +| Atendente Demo | `atendente@sothis.com.br` | Agente | Suporte | + +Esses usuarios existem no banco, mas nao substituem a autenticacao real. + +Para logar pela tela de login, o usuario precisa existir no AD ou no provedor Microsoft configurado. + +--- + +## Como testar + +### Backend + +```bash +cd backend +npm run dev +``` + +Endpoints de validacao: + +```text +http://localhost:3001/admin/access/options +http://localhost:3001/admin/access/users +``` + +### Frontend sem depender de AD + +No console do navegador: + +```js +localStorage.setItem('authUser', JSON.stringify({ + username: 'admin@sothis.com.br', + name: 'Admin Demo', + email: 'admin@sothis.com.br', + perfis: ['Admin'], + profiles: ['Admin'], + areas: ['Suporte'], + accessStatus: 'assigned' +})); +localStorage.setItem('authToken', 'dev-token'); +location.href = '/home'; +``` + +Para usuario sem atribuicao: + +```js +localStorage.setItem('authUser', JSON.stringify({ + username: 'novo.usuario', + name: 'Novo Usuario', + email: 'novo.usuario@sothis.com.br', + perfis: [], + profiles: [], + areas: [], + accessStatus: 'unassigned' +})); +localStorage.setItem('authToken', 'dev-token'); +location.href = '/home'; +``` + +--- + +## Limitacoes atuais + +- Os endpoints `/admin/access/*` ainda nao possuem guard JWT nem checagem de perfil Admin. +- A alteracao de acesso substitui perfil/area atuais por um unico perfil e uma unica area principal. +- Ainda nao ha auditoria das alteracoes de acesso. +- O painel Admin consome os endpoints reais, mas ainda possui fallback visual mockado se o backend estiver indisponivel. +- A senha do banco nao deve ser commitada; arquivos `.env.*` seguem ignorados pelo Git. + +--- + +## Proximos passos sugeridos + +- Adicionar `AuthGuard` JWT. +- Proteger `/admin/access/*` para `Admin`. +- Registrar auditoria em `logs_auditoria`. +- Criar endpoints CRUD completos para `areas`. +- Permitir multiplas areas por usuario na UI, mantendo uma area principal. diff --git a/docs/auth.md b/docs/auth.md index e421eb9..386eb56 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -257,4 +257,12 @@ loginComNovoProvedor(dados: any) { - [ ] Guard NestJS para proteger rotas privadas (`@UseGuards(AuthGuard)`) - [ ] Roles e permissões - [ ] Auditoria de login -- [ ] Trocar token na query string por cookie HTTP-only (reduz exposição no browser) \ No newline at end of file +- [ ] Trocar token na query string por cookie HTTP-only (reduz exposição no browser) + +--- + +## Documentacao complementar + +A sincronizacao de usuarios autenticados com o banco, os perfis de acesso, as areas operacionais e os endpoints administrativos estao documentados em: + +- [`access-control.md`](./access-control.md)