← story.propek
STORY 8.2
API: Deals & Pipeline
Epic: CRM Propek v2
PENDING
Implementar os endpoints da API para gestao de deals (CRUD completo) e visualizacao do pipeline v2 (Kanban por stage), adicionando 7 novos endpoints ao backend Express do bot na Hostinger.
ACCEPTANCE CRITERIA (0/12)
AC1: `GET /api/crm/deals` — retorna lista paginada de deals com filtros (pipeline_type, stage, assigned_to, status), JOIN com customers para exibir customer_name/business_name/phone_number, campo `days_in_stage` calculado via deal_stage_log, campo `next_follow_up` via LATERAL JOIN em follow_ups_crm
AC2: `POST /api/crm/deals` — cria deal, valida customer_id existe, valida current_stage valido para o pipeline_type, INSERT em deals + INSERT inicial em deal_stage_log, se B2B lead_qualificado: cria follow_up_crm tipo 'lead_contact' com due_at NOW()+2h e atribui assigned_to via round-robin
AC3: `PATCH /api/crm/deals/:id` — atualiza campos opcionais (assigned_to, estimated_value, actual_value, metadata, close_reason), se close_reason fornecido seta closed_at=NOW()
AC4: `PATCH /api/crm/deals/:id/stage` — move deal para novo stage, valida que stage e diferente do atual, valida stage e valido para o pipeline_type, regra: stage 'confirmado' requer estimated_value > 0 (422 se nao), INSERT em deal_stage_log, side effects: se to_stage='entregue' cria follow_up 'nps' +48h, se to_stage='pos_venda' cria follow_ups Ezra (d3, d7, d14), se to_stage='won'|'lost' seta closed_at
AC5: `GET /api/crm/deals/:id` — retorna deal completo com stage_history (todos os registros deal_stage_log ordenados por changed_at ASC), follow_ups vinculados, dados basicos do customer
AC6: `GET /api/crm/pipeline/v2` — retorna pipeline agrupado por stage para Kanban, requer query param `pipeline_type` ('b2b'|'b2c'), cada stage inclui deals_count, total_value (SUM estimated_value), sla_days, e array de deals com sla_status calculado (green/yellow/red baseado em days_in_stage vs sla_days)
AC7: `GET /api/crm/pipeline/summary` — retorna contadores resumidos agrupados por pipeline_type e stage, inclui overdue_count (deals que passaram do SLA), totals.open_deals, totals.total_value, totals.overdue_deals; aceita query params pipeline_type e assigned_to
AC8: Todos os endpoints retornam erro 404 adequado quando deal nao existe (GET/PATCH :id)
AC9: Todos os endpoints validam o header `X-CRM-Token` via middleware existente `crmAuthMiddleware`
AC10: Novos routers registrados no `index.ts`: `deals.ts` em `/deals`, `pipeline-v2.ts` em `/pipeline` (montando /v2 e /summary sob /pipeline)
AC11: SLAs por stage configurados corretamente no pipeline-v2.ts: B2B: lead_qualificado(1d), diagnostico(3d), proposta(5d), confirmado(1d), enviado(3d), entregue(1d), pos_venda(14d); B2C: pedido(1d), enviado(3d), entregue(1d), nps(2d), recompra(90d)
AC12: Round-robin em `POST /api/crm/deals` atribui ao atendente com menor numero de deals abertos (COUNT deals WHERE assigned_to = agent AND closed_at IS NULL)