Modulo Admin

Base tecnica:

Controller: src/modules/admin/admin-access.controller.ts
Service: src/modules/admin/admin-access.service.ts
Repository: src/modules/admin/repositories/admin-access.repository.ts
DTOs: src/modules/admin/dto/admin-access.dto.ts
Prefixo: /admin/access

Responsabilidade

Sustenta o painel administrativo e parte do painel supervisor:

opcoes de perfis e areas;
overview mensal;
ranking de atendentes;
auditoria;
usuarios e acessos;
areas/especialidades;
conteudos da IA.

O fluxo do agente virtual e a configuracao de triagem ficam no modulo knowledge-base, mantendo o prefixo /admin/knowledge por compatibilidade.

A agenda de contatos fica no modulo contacts, mantendo o prefixo /contacts por compatibilidade.

Presenca e notas do atendente ficam no modulo agent, mantendo os prefixos /agent/presence e /agent/notes.

Endpoints principais

Metodo	Rota	Perfis	Descricao
GET	`/admin/access/options`	Admin, Supervisor, Agente	Lista perfis e areas ativas
GET	`/admin/access/overview`	Admin, Supervisor	Indicadores administrativos
GET	`/admin/access/ranking?areaId=`	Admin, Supervisor	Ranking de atendentes
GET	`/admin/access/audit?page=&limit=`	Admin, Supervisor	Eventos de auditoria
GET	`/admin/access/users`	Admin	Lista usuarios com perfis/areas
PUT	`/admin/access/users/:id`	Admin	Atualiza perfis e especialidades
GET	`/admin/access/areas`	Admin, Supervisor	Lista areas
POST	`/admin/access/areas`	Admin	Cria area
PUT	`/admin/access/areas/:id`	Admin	Atualiza area
DELETE	`/admin/access/areas/:id`	Admin	Desativa area
GET	`/admin/access/ai-contents`	Admin	Lista documentos da IA
GET	`/admin/access/ai-contents/:id/file`	Admin	Retorna arquivo base64 para download
POST	`/admin/access/ai-contents`	Admin	Adiciona documento da IA
DELETE	`/admin/access/ai-contents/:id`	Admin	Remove documento da IA

Funcoes importantes

getOptions(): carrega perfis e areas para selects do frontend. Agente tambem acessa esta rota para abrir atendimento.
listUsers(): monta usuario com perfis, areas, perfilPrincipal, areaPrincipal e accessStatus.
updateUserAccess(): apaga e recria vinculos de perfil/especialidade em transacao.
listAiContents(): lista metadados dos documentos da IA sem devolver o base64.
getAiContentFile(): devolve o conteudo base64 para download.
logAudit(): registra eventos administrativos com o usuario autenticado vindo do JWT.

Arquitetura interna

O modulo segue a separacao:

Controller -> Service -> Repository -> DatabaseService

Controller: HTTP, roles, params e DTOs.
Service: regra de negocio, normalizacao, transacao e auditoria.
Repository: SQL e persistencia.
DatabaseService: pool PostgreSQL e transacoes.

O modulo nao cria tabelas em runtime. Tabelas como admin_audit_logs e ai_knowledge_contents devem existir via migrations do repositorio de deploy.

Code review

updateUserAccess() e sensivel e exige Admin.
Conteudo IA hoje armazena base64 em banco; avaliar storage externo se os arquivos crescerem.
Auditoria usa o usuario autenticado como ator. Proximo passo natural e ampliar cobertura para outros modulos.