Initial commit

Schema/etapas/06-api-rest-backend.md

@@ -0,0 +1,41 @@
+# Etapa 06 — API REST do backend
+
+## Objetivo
+Expor os endpoints REST que o frontend vai consumir: autenticação, disparo de buscas, consulta/listagem de leads, exportação e curadoria de ramos.
+
+## Contexto
+Esta etapa também implementa a persistência com deduplicação (que ainda não existia nas etapas anteriores) e o worker que processa buscas pendentes de forma assíncrona.
+
+## Tarefas
+
+1. Criar `security/` com autenticação JWT:
+   - `POST /auth/login` — recebe email/senha, retorna token JWT
+   - Proteger todos os demais endpoints exigindo o token
+2. Criar `worker/BuscaWorker`:
+   - Processo assíncrono (`@Scheduled` com polling, ou `@Async`) que busca registros `buscas` com status `pendente`, executa o `BuscaOrchestrator` (etapas 03+05) e, ao final, aplica o `LeadNormalizerService` (etapa 04) em cada lead extraído
+   - Antes de persistir, checar duplicidade por `hash_dedup` e `place_id`; se já existir, atualizar o vínculo com a nova busca em vez de duplicar
+   - Atualizar `busca.status`, `busca.total_encontrados`, `busca.finalizado_em` ao concluir (ou `erro` + `detalhe_erro` em caso de falha)
+3. Criar `controller/BuscaController`:
+   - `POST /buscas` — cria uma nova busca (termo, localização, ramo opcional) com status `pendente`
+   - `GET /buscas` — lista buscas (paginado, filtrável por status)
+   - `GET /buscas/{id}` — detalhe de uma busca específica, incluindo status e total de leads encontrados
+4. Criar `controller/LeadController`:
+   - `GET /leads` — lista leads paginada, com filtros por ramo, cidade/UF, status, busca de origem
+   - `GET /leads/{id}` — detalhe de um lead
+   - `PATCH /leads/{id}/status` — atualizar status do lead (novo, contatado, qualificado, convertido, descartado)
+   - `GET /leads/export` — exportação em CSV dos leads filtrados
+5. Criar `controller/RamoController`:
+   - `GET /ramos` — lista ramos cadastrados
+   - `POST /ramos` — cria novo ramo (curadoria manual)
+   - `PATCH /ramos/{id}/aliases` — adiciona um alias a um ramo existente (para a fila de curadoria de categorias sem mapeamento)
+   - `GET /leads/sem-ramo` — lista leads com `ramo_id = null` pendentes de curadoria
+6. Documentar a API (Swagger/OpenAPI via springdoc) para facilitar a integração do frontend
+
+## Critérios de aceite
+
+- [ ] Login retorna JWT válido e endpoints protegidos rejeitam requisição sem token
+- [ ] Criar uma busca via API resulta, em segundos/minutos, em leads persistidos sem duplicação
+- [ ] Listagem de leads suporta paginação e os filtros definidos
+- [ ] Exportação CSV funciona com os filtros aplicados
+- [ ] Fila de curadoria de ramos (`/leads/sem-ramo`) reflete corretamente os leads sem mapeamento
+- [ ] Documentação Swagger acessível e atualizada