Atualizada documentação pós Refactor

Acess-Control.md

@@ -183,11 +183,19 @@ Base path:
 /admin/access
 ```
 
-### Listar opcoes de acesso
-
-```http
-GET /admin/access/options
-```
+### Listar opcoes de acesso
+
+```http
+GET /admin/access/options
+```
+
+Perfis autorizados:
+
+- `Admin`
+- `Supervisor`
+- `Agente`
+
+Essa rota tambem e usada por telas operacionais, como abertura de atendimento, para carregar areas ativas.
 
 Resposta:
 
@@ -230,12 +238,16 @@ Resposta:
 ]
 ```
 
-### Atualizar acesso de usuario
-
-```http
-PUT /admin/access/users/:id
-Content-Type: application/json
-```
+### Atualizar acesso de usuario
+
+```http
+PUT /admin/access/users/:id
+Content-Type: application/json
+```
+
+Perfil autorizado:
+
+- `Admin`
 
 Body:
 
@@ -246,13 +258,14 @@ Body:
 }
 ```
 
-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
+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
+- registra auditoria usando o usuario autenticado no JWT
 
 Para remover atribuicoes:
 

Admin.md

@@ -1,10 +1,12 @@
 # Modulo Admin
 
-Base tecnica:
-
-- Controller: `src/modules/admin/admin-access.controller.ts`
-- Service: `src/modules/admin/admin-access.service.ts`
-- Prefixo: `/admin/access`
+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
 
@@ -18,36 +20,51 @@ Sustenta o painel administrativo e parte do painel supervisor:
 - areas/especialidades;
 - conteudos da IA.
 
-## Endpoints principais
-
-| Metodo | Rota | Descricao |
-|---|---|---|
-| GET | `/admin/access/options` | Lista perfis e areas ativas |
-| GET | `/admin/access/overview` | Indicadores administrativos |
-| GET | `/admin/access/ranking?areaId=` | Ranking de atendentes |
-| GET | `/admin/access/audit?page=&limit=` | Eventos de auditoria |
-| GET | `/admin/access/users` | Lista usuarios com perfis/areas |
-| PUT | `/admin/access/users/:id` | Atualiza perfis e especialidades |
-| GET | `/admin/access/areas` | Lista areas |
-| POST | `/admin/access/areas` | Cria area |
-| PUT | `/admin/access/areas/:id` | Atualiza area |
-| DELETE | `/admin/access/areas/:id` | Desativa area |
-| GET | `/admin/access/ai-contents` | Lista documentos da IA |
-| GET | `/admin/access/ai-contents/:id/file` | Retorna arquivo base64 para download |
-| POST | `/admin/access/ai-contents` | Adiciona documento da IA |
-| DELETE | `/admin/access/ai-contents/:id` | Remove documento da IA |
+## 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.
-- `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 quando chamado pelos fluxos.
+- `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:
+
+```text
+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: deve exigir Admin.
-- Conteudo IA hoje armazena base64 em banco; avaliar storage externo se os arquivos crescerem.
-- Auditoria existe, mas nem toda acao sensivel ainda e auditada.
+- `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.