# Planteio API - Agentes

Este documento descreve como o modulo de agentes esta organizado, o que precisa rodar e como clonar um usuario padrao (com talhoes, safras e eventos).

Documento complementar de arquitetura conversacional:

- `README-agents.md`

## 1. Visao geral

O modulo de agentes fica em `src/agent` e funciona como um roteador conversacional:

- Recebe mensagem (Evolution webhook ou endpoint web).
- Monta/recupera contexto no Redis.
- `handleController` decide a rota.
- Executa o agente da rota (`profile`, `events`, `plot`, `safra`, `assistant`, etc).
- Envia resposta e salva contexto atualizado no Redis.

## 2. Endpoints principais

Controlador: `src/agent/agent.controller.ts`

- `POST /agent/evolution`
  - Entrada do WhatsApp (Evolution).
- `POST /agent/controller`
  - Entrada do web agent.

## 3. Roteamento do controller

Arquivo: `src/agent/agent.service.ts` (`handleController` + `executeRoute`)

Fluxo:

1. Hashtags com prioridade:
   - `#resumo-semanal` -> `resumosemanal`
   - `#relatorio` -> `relatorio`
   - `#agronews` -> `clima`
2. Interrupcao global por IA:
   - cancelamento de plano/assinatura -> `response` + `cancel_plan`
3. Se existe rota ativa/pending, mantem o fluxo (com regras de escape).
4. Menu principal (sem fluxo ativo):
   - `1` -> `events`
   - `2` -> `plot`
   - `3` -> `relatorio`
   - `4` -> `response` + `assistant_examples`
5. Classificacao por IA (`CONTROLLER_AGENT_PROMPT`) para fallback.

## 4. Agentes e responsabilidade

- `profile`: onboarding e dados de perfil.
- `events`: registro e edicao de eventos (custos, vendas, manejo, status, safra).
- `plot`: cadastro/edicao de talhao.
- `safra`: abertura/encerramento/listagem de safra.
- `assistant`: perguntas analiticas/operacionais sobre os dados.
- `relatorio`: gera link para painel.
- `resumosemanal`: resumo da semana.
- `clima` (agronews): mensagem diaria.
- `response`: mensagens de catalogo/menu.

## 5. Entradas suportadas (Evolution + Web)

### 5.1 Tipos suportados

No processamento de mensagem:

- `conversation`
- `extendedTextMessage`
- `audioMessage`
- `imageMessage`
- `documentMessage` (somente documentos textuais suportados)
- `locationMessage`

Para tipo nao suportado: resposta automatica `Arquivo nao comportado.`

### 5.2 Web Agent (`POST /agent/controller`)

DTO: `src/agent/shared/types/web-agent.dto.ts`

Campos principais:

- `message` (texto)
- ou `mediaBase64` + `mediaType`/`mediaMimeType`
- `mediaType`: `audio`, `image` ou outros (vira `documentMessage`)
- `caption` (opcional)
- `phone` ou `profileId`

Formatos de documento textual aceitos:

- `text/plain`
- `text/csv`, `application/csv`
- `application/json`, `text/json`
- `text/markdown`, `text/x-markdown`
- `application/xml`, `text/xml`

## 6. Regras de negocio importantes

### 6.1 Evento nao pode ter custo e faturamento juntos

- No agente de eventos: se vierem os dois, entra no fluxo de resolucao (`resolve_cost_or_profit`).
- Na API `PATCH /eventos/:id`: se atualizar `cost`, zera `profit`; se atualizar `profit`, zera `cost`.

Arquivo: `src/evento/eventos.service.ts`

### 6.2 Datas

- Para evento, considerar `date` como data principal.
- Em perguntas/consultas do assistant, prioridade para campo `date` dos eventos.

## 7. Assistant (logs e desambiguacao)

### 7.1 Logs adicionados

Arquivo: `src/agent/agent.service.ts`

- `[Assistant] PLANNER_REQUEST`
- `[Assistant] PLANNER_OUTPUT_RAW`
- `[Assistant] EXTRACTION`
- `[Assistant] PLAN`
- `[Assistant] QUERY_CONTEXT`
- `[Assistant] ANSWER_REQUEST`
- `[Assistant] ANSWER_OUTPUT_RAW`

### 7.2 Escolha por ID

Na desambiguacao do assistant (talhao/safra), a selecao e somente por ID.

## 8. Usuario padrao e clonagem de dados

Objetivo: clonar tudo de um `profile_id` origem para um novo profile.

Tabelas copiadas:

- `planteio_profiles`
- `planteio_plots`
- `planteio_safra`
- `planteio_evento`

Observacao de schema:

- `planteio_plots` usa `updated` (nao `modified`).

### 8.1 Colunas relevantes (schema Prisma)

- `planteio_profiles`: `id, name, phone, property_name, property_address, cidade, latitude, longitude, ...`
- `planteio_plots`: `id, profile_id, name, culture, area_ha, area_raw, created, updated, safra`
- `planteio_safra`: `id, profile_id, plot_id, date, culture, created, modified, end_date, status`
- `planteio_evento`: `id, profile_id, plot_id, safra_id, status_id, title, description, cost, profit, product, praga, dose, date, planted, harvested, created, modified, ...`

### 8.2 Script de clonagem (resumo)

Use o script SQL completo validado na conversa para:

1. Inserir novo `planteio_profiles`.
2. Copiar plots e mapear IDs antigos -> novos.
3. Copiar safras e mapear IDs antigos -> novos.
4. Copiar eventos usando os mapas.

Se for rodar varias vezes na mesma sessao SQL, sempre limpar temporarias antes:

```sql
DROP TEMPORARY TABLE IF EXISTS tmp_old_plots;
DROP TEMPORARY TABLE IF EXISTS tmp_new_plots;
DROP TEMPORARY TABLE IF EXISTS tmp_plot_map;
DROP TEMPORARY TABLE IF EXISTS tmp_old_safras;
DROP TEMPORARY TABLE IF EXISTS tmp_new_safras;
DROP TEMPORARY TABLE IF EXISTS tmp_safra_map;
```

Script manual pronto no projeto:

- `prisma/sql/planteio_clone_manual_template.sql`
- Parametros no topo:
  - `@old_profile_id`
  - `@new_phone`
  - `@new_name`
  - `@target_profile_id` (`NULL` auto increment ou ID fixo)

## 9. O que rodar localmente

Minimo:

1. API Nest (`npm run start:dev` ou comando do projeto)
2. Redis
3. MySQL
4. Variaveis:
   - `DATABASE_URL`
   - `REDIS_URL`/`REDIS_PORT`
   - `OPENAI_API_KEY`
   - `OPENAI_MODEL`
   - (Evolution) `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_API_INSTANCE`

## 10. Arquivos-chave

- `src/agent/agent.controller.ts`
- `src/agent/agent.service.ts`
- `src/agent/constants/prompts.ts`
- `src/agent/constants/catalog/main.catalog.ts`
- `src/agent/constants/catalog/events.catalog.ts`
- `src/evento/eventos.service.ts`
- `prisma/schema.prisma`