Adicionado doc pós refatoração

Admin.md

@@ -24,6 +24,8 @@ O fluxo do agente virtual e a configuracao de triagem ficam no modulo `knowledge
 
 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 |

Agent.md

@@ -1,57 +1,82 @@
 # 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.
+
+## Base tecnica
+
+- Module: `src/modules/agent/agent.module.ts`
+- Presence Controller: `src/modules/agent/agent-presence.controller.ts`
+- Presence Service: `src/modules/agent/agent-presence.service.ts`
+- Presence Repository: `src/modules/agent/repositories/agent-presence.repository.ts`
+- Notes Controller: `src/modules/agent/agent-notes.controller.ts`
+- Notes Service: `src/modules/agent/agent-notes.service.ts`
+- Notes Repository: `src/modules/agent/repositories/agent-notes.repository.ts`
+- DTOs: `src/modules/agent/dto/agent.dto.ts`
+
+## Responsabilidades
+
+- Controlar status do agente: `available`, `paused`, `offline`.
+- Liberar atendimentos do agente quando ele pausa.
+- Restaurar atendimentos reservados quando ele retoma.
+- Marcar agente offline e devolver atendimentos para fila.
+- Gerenciar notas pessoais do agente.
 
 ## Presenca do agente
 
-Arquivos:
-
-- `agent-presence.controller.ts`
-- `agent-presence.service.ts`
-
 Prefixo:
 
-```txt
+```text
 /agent/presence
 ```
 
-### Endpoints
+| Metodo | Rota | Perfis | Descricao |
+|---|---|---|---|
+| GET | `/agent/presence` | Admin, Supervisor | Lista presenca dos agentes |
+| GET | `/agent/presence/me` | Admin, Supervisor, Agente | Retorna presenca do usuario autenticado |
+| POST | `/agent/presence/pause` | Admin, Supervisor, Agente | Pausa o usuario autenticado |
+| POST | `/agent/presence/resume` | Admin, Supervisor, Agente | Retoma o usuario autenticado |
+| POST | `/agent/presence/offline` | Admin, Supervisor, Agente | Marca o usuario autenticado como offline |
 
-| Metodo | Rota | Descricao |
+O parametro/body `userId` pode continuar vindo do frontend por compatibilidade, mas o backend usa o usuario autenticado no JWT.
-|---|---|---|
-| GET | `/agent/presence` | Lista presenca dos agentes |
-| GET | `/agent/presence/me?userId=` | Retorna presenca de um agente |
-| POST | `/agent/presence/pause` | Marca agente como pausado |
-| POST | `/agent/presence/resume` | Retoma agente |
-| POST | `/agent/presence/offline` | Marca agente como offline |
-
-### Regras
-
-- 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.
 
 ## Notas do agente
 
-Arquivos:
-
-- `agent-notes.controller.ts`
-- `agent-notes.service.ts`
-
 Prefixo:
 
-```txt
+```text
 /agent/notes
 ```
 
-### Endpoints
+| Metodo | Rota | Perfis | Descricao |
+|---|---|---|---|
+| GET | `/agent/notes` | Admin, Supervisor, Agente | Lista notas do usuario autenticado |
+| POST | `/agent/notes` | Admin, Supervisor, Agente | Cria nota para o usuario autenticado |
+| DELETE | `/agent/notes/:id` | Admin, Supervisor, Agente | Remove nota do usuario autenticado |
 
-| Metodo | Rota | Descricao |
+O parametro/body `userId` pode continuar vindo do frontend por compatibilidade, mas o backend usa o usuario autenticado no JWT.
-|---|---|---|
+
-| GET | `/agent/notes?userId=` | Lista notas do agente |
+## Arquitetura interna
-| POST | `/agent/notes` | Cria nota |
+
-| DELETE | `/agent/notes/:id?userId=` | Remove nota |
+```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
 
-Hoje `userId` vem por query/body. Em producao, deve sair do JWT validado no backend.
+- 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`