Adicionado doc pós refatoração

Admin.md

@@ -23,6 +23,8 @@ Sustenta o painel administrativo e parte do painel supervisor:
 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
 

Agent.md

@@ -1,57 +1,82 @@
-# Modulo Agente
+# Modulo Agente
-
+
-O backend do agente esta dentro de `src/modules/admin`, dividido em presenca e notas.
+Modulo responsavel por presenca operacional do agente e notas pessoais do atendente.
-
+
-## Presenca do agente
+## Base tecnica
-
+
-Arquivos:
+- Module: `src/modules/agent/agent.module.ts`
-
+- Presence Controller: `src/modules/agent/agent-presence.controller.ts`
-- `agent-presence.controller.ts`
+- Presence Service: `src/modules/agent/agent-presence.service.ts`
-- `agent-presence.service.ts`
+- Presence Repository: `src/modules/agent/repositories/agent-presence.repository.ts`
-
+- Notes Controller: `src/modules/agent/agent-notes.controller.ts`
-Prefixo:
+- Notes Service: `src/modules/agent/agent-notes.service.ts`
-
+- Notes Repository: `src/modules/agent/repositories/agent-notes.repository.ts`
-```txt
+- DTOs: `src/modules/agent/dto/agent.dto.ts`
-/agent/presence
+
-```
+## Responsabilidades
-
+
-### Endpoints
+- Controlar status do agente: `available`, `paused`, `offline`.
-
+- Liberar atendimentos do agente quando ele pausa.
-| Metodo | Rota | Descricao |
+- Restaurar atendimentos reservados quando ele retoma.
-|---|---|---|
+- Marcar agente offline e devolver atendimentos para fila.
-| GET | `/agent/presence` | Lista presenca dos agentes |
+- Gerenciar notas pessoais do agente.
-| GET | `/agent/presence/me?userId=` | Retorna presenca de um agente |
+
-| POST | `/agent/presence/pause` | Marca agente como pausado |
+## Presenca do agente
-| POST | `/agent/presence/resume` | Retoma agente |
+
-| POST | `/agent/presence/offline` | Marca agente como offline |
+Prefixo:
-
+
-### Regras
+```text
-
+/agent/presence
-- Pausar move atendimentos do agente para fila e cria reserva temporaria.
+```
-- Retomar tenta recuperar atendimentos reservados ainda livres.
+
-- Offline remove reserva e evita atribuicao direta.
+| Metodo | Rota | Perfis | Descricao |
-
+|---|---|---|---|
-## Notas do agente
+| GET | `/agent/presence` | Admin, Supervisor | Lista presenca dos agentes |
-
+| GET | `/agent/presence/me` | Admin, Supervisor, Agente | Retorna presenca do usuario autenticado |
-Arquivos:
+| POST | `/agent/presence/pause` | Admin, Supervisor, Agente | Pausa o usuario autenticado |
-
+| POST | `/agent/presence/resume` | Admin, Supervisor, Agente | Retoma o usuario autenticado |
-- `agent-notes.controller.ts`
+| POST | `/agent/presence/offline` | Admin, Supervisor, Agente | Marca o usuario autenticado como offline |
-- `agent-notes.service.ts`
+
-
+O parametro/body `userId` pode continuar vindo do frontend por compatibilidade, mas o backend usa o usuario autenticado no JWT.
-Prefixo:
+
-
+## Notas do agente
-```txt
+
-/agent/notes
+Prefixo:
-```
+
-
+```text
-### Endpoints
+/agent/notes
-
+```
-| Metodo | Rota | Descricao |
+
-|---|---|---|
+| Metodo | Rota | Perfis | Descricao |
-| GET | `/agent/notes?userId=` | Lista notas do agente |
+|---|---|---|---|
-| POST | `/agent/notes` | Cria nota |
+| GET | `/agent/notes` | Admin, Supervisor, Agente | Lista notas do usuario autenticado |
-| DELETE | `/agent/notes/:id?userId=` | Remove nota |
+| POST | `/agent/notes` | Admin, Supervisor, Agente | Cria nota para o usuario autenticado |
-
+| DELETE | `/agent/notes/:id` | Admin, Supervisor, Agente | Remove nota do usuario autenticado |
-## Code review
+
-
+O parametro/body `userId` pode continuar vindo do frontend por compatibilidade, mas o backend usa o usuario autenticado no JWT.
-Hoje `userId` vem por query/body. Em producao, deve sair do JWT validado no backend.
+
+## Arquitetura interna
+
+```text
+Controller -> Service -> Repository -> DatabaseService
+```
+
+- Controller: rotas, roles, Swagger, DTOs e usuario autenticado.
+- Service: regra de negocio e validacao de usuario.
+- Repository: SQL de `agent_presence`, `agent_notes` e reserva/liberacao de atendimentos.
+- DatabaseService: pool PostgreSQL e transacoes.
+
+## Banco
+
+O modulo nao cria schema em runtime.
+
+As tabelas/colunas devem existir via migrations:
+
+- `008_agent_notes.sql`
+- `015_agent_presence_pause.sql`
+
+## Code review
+
+- Presenca e notas sairam de `admin` porque sao dominio operacional do agente.
+- Acoes pessoais usam `@CurrentUser()` e JWT, nao `userId` vindo do cliente.
+- `AgentPresenceService` e usado pelo `AttendanceAssignmentService` para impedir atribuicao a usuario indisponivel.

Whatsapp.md

@@ -9,6 +9,7 @@ Base tecnica:
 - Contacts Service: `src/modules/contacts/contacts.service.ts`
 - Attendance Assignment: `src/modules/attendance/attendance-assignment.service.ts`
 - Attendance Repository: `src/modules/attendance/repositories/attendance-assignment.repository.ts`
+- Agent Presence: `src/modules/agent/agent-presence.service.ts`
 - Gateway: `src/modules/whatsapp/whatsapp.gateway.ts`
 - Prefixo: `/whatsapp`
 
@@ -70,6 +71,7 @@ Fila, atribuicao, transferencia, fechamento e triagem do atendimento ficam no mo
 - Impede envio quando atendimento ativo aguarda resposta do cliente.
 - Roteia conversas por area, fluxo configurado ou arvore do bot.
 - Monta observacao de transferencia do Agente Virtual.
+- Consulta `AgentPresenceService` antes de atribuir atendimento a um usuario.
 - Nao cria/altera schema em runtime; `whatsapp_chat_atribuicoes` deve ser mantida pelas migrations.
 
 ### `attendance-assignment.repository.ts`