omnichannel-backend/docs/access-control.md

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

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

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:

{
  "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.

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:

/admin/access

Listar opcoes de acesso

GET /admin/access/options

Resposta:

{
  "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

GET /admin/access/users

Resposta:

[
  {
    "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

PUT /admin/access/users/:id
Content-Type: application/json

Body:

{
  "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:

{
  "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

cd backend
npm run dev

Endpoints de validacao:

http://localhost:3001/admin/access/options
http://localhost:3001/admin/access/users

Frontend sem depender de AD

No console do navegador:

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:

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.