# Feature Specification: Onboarding Abandonado → Lead CRM (012)

**Criado:** 2026-06-10  
**Solicitado por:** Roger  
**Status:** 📋 **Draft — decisões fechadas, pronta para plano**  
**Prioridade:** **P1**  
**Depende de:** Spec 001 (webhooks VM112), Spec 010 (ticket cedo + assist), Spec 007 (alertas — fase B)  
**API alvo:** `0.9.1-onboard-ticket` (VM122) + VM112 wizard + CRM TBD

---

## Resumo

Cada sessão de onboarding no wizard VM112 gera **um ticket no Desk** no momento em que o cliente preenche e-mail/senha e clica **«Criar conta agora»** (`onboarding.started` com `step: create_account`). Esse ticket acompanha **todas as etapas** do funil.

Se o cliente **abandonar** o processo ou ficar **parado muitas horas** sem concluir, o mesmo registro é **promovido a Lead** no CRM — base para outreach proativo via chat (canal a estudar: IP, tablet SEO, widget web, etc.).

**Princípio:** não duplicar ticket nem lead — **um registro, uma jornada**.

---

## Decisões confirmadas (Roger — 2026-06-10)

| # | Pergunta | Decisão |
|---|----------|---------|
| 1 | Quando criar ticket? | No clique **«Criar servidor/conta»** — webhook `onboarding.started` com `email` |
| 2 | Precisa pedir suporte? | **Não** — ticket sempre, independente de escalada |
| 3 | Etapas no ticket? | **Sim** — `funnel_notes` + backfill de `domain.validated` e `dns.applied` |
| 4 | Abandono | Ticket `open` + sessão stale → **Lead CRM** (Spec 012) |
| 5 | Outreach | Chat proativo com cliente — **dispositivo/canal TBD** |
| 6 | OTRS | Fora de escopo — Spec 011 futura |

---

## Fluxo VM112 → Desk (implementado 2026-06-10)

```mermaid
sequenceDiagram
    participant C as Cliente
    participant W as Wizard VM112
    participant D as Desk VM122

    C->>W: Valida domínio
    W->>D: domain.validated
    C->>W: Aplica DNS
    W->>D: dns.applied
    C->>W: E-mail + senha + Criar conta
    W->>D: onboarding.started (email, step=create_account)
    Note over D: Cria ticket + backfill etapas anteriores
    W->>W: zmprov create account
    W->>D: account.created
    W->>D: infra.synced / onboarding.completed
    Note over D: Notas no mesmo ticket
```

**Alteração VM112:** `onboarding.started` **removido** de `validate-domain`; **adicionado** em `POST /onboarding/account/create`.

---

## Estados `crm_track` (payload ticket)

| Valor | Significado | Gatilho |
|-------|-------------|---------|
| `onboarding` | Cliente comprometeu-se (criar conta) | `onboarding.started` |
| `onboarding_completed` | Funil concluído | `onboarding.completed` |
| `lead` | Abandonado / stale — candidato CRM | Job Spec 012 (futuro) |
| `lead_contacted` | Outreach iniciado | Chat Spec 012 |
| `lead_converted` | Voltou e concluiu ou fechou venda | Manual / webhook |
| `lead_lost` | Sem resposta após N tentativas | Manual / regra |

---

## Detecção de abandono

### Critérios (MVP)

| Critério | Valor default | Configurável |
|----------|---------------|--------------|
| Tempo sem evento | **24h** | `ONBOARD_STALE_HOURS` |
| Etapa máxima | < `completed` | — |
| Ticket status | `open` ou `escalated` (não `assisting`) | — |
| `crm_track` | `onboarding` (não já `lead`) | — |

### O que **não** é abandono

- Sessão `completed` ou `failed`
- Ticket em `assisting` (técnico activo)
- Ticket `closed` / `resolved` manualmente

### Job proposto (VM122 worker)

```
A cada 15 min:
  1. Listar sessões stale no funil (já calculado em _funnel_summary)
  2. Para cada sessão com ticket_id e crm_track=onboarding:
     - PATCH ticket payload: crm_track=lead, lead_detected_at=now
     - Opcional: push ops_lead (Spec 007)
     - Enfileirar outreach (Spec 012 Fase B)
```

---

## Outreach / Chat (Fase B — canal TBD)

Roger vai estudar ferramenta para identificar e contactar o visitante:

| Opção | Prós | Contras |
|-------|------|---------|
| Widget chat web (Crisp, Tawk, Chatwoot) | E-mail + sessão browser | Precisa embed no wizard |
| Tablet SEO / dispositivo loja | Presencial | Escopo físico |
| IP + WHOIS / enrichment | Automático | Baixa precisão, LGPD |
| E-mail do ticket | Já temos `account_email` | Só após «criar conta» |

**MVP Fase A:** ops contacta manualmente via e-mail/telefone do ticket.  
**MVP Fase B:** integrar canal escolhido + log em `lead_outreach_log`.

---

## Integração CRM

### Campos mínimos do Lead

| Campo | Origem |
|-------|--------|
| `session_id` | VM112 cookie |
| `domain` | Webhook |
| `email` | `onboarding.started` / `account.created` |
| `funnel_stage` | Última etapa conhecida |
| `last_event_at` | Funil Desk |
| `ticket_id` | Desk SQLite |
| `desk_ticket_url` | `https://desk.ligbox.com.br/#ticket/{id}` |

### Destino CRM (TBD)

- **Odoo CRM** (API key Roger já disponível no ambiente)
- Ou export CSV / webhook genérico

**Regra:** `ticket_id` é a chave de idempotência — não criar lead duplicado.

---

## API / Data model (VM122)

### Alterações em `tickets.payload`

```json
{
  "crm_track": "onboarding",
  "funnel_notes": [
    {"event": "domain.validated", "at": "...", "backfilled": true},
    {"event": "dns.applied", "at": "...", "backfilled": true},
    {"event": "account.created", "at": "...", "data": {"email": "..."}}
  ],
  "account_email": "admin@dominio.com",
  "onboarding_outcome": null,
  "lead_detected_at": null,
  "lead_outreach": []
}
```

### Endpoints novos (propostos)

| Método | Endpoint | Auth | Descrição |
|--------|----------|------|-----------|
| GET | `/api/v1/crm/leads` | JWT ops_lead+ | Lista tickets `crm_track=lead` |
| POST | `/api/v1/crm/leads/{ticket_id}/contact` | JWT | Regista tentativa outreach |
| POST | `/api/v1/crm/leads/{ticket_id}/promote` | JWT | Força lead manualmente |
| POST | `/api/v1/crm/leads/sync` | internal token | Job stale → lead |

---

## User stories

### US-1 — Ticket no compromisso

Como ops lead, quero um ticket quando o cliente clica «Criar conta», para ver a jornada mesmo sem pedido de suporte.

**Critério:** `onboarding.started` com `step=create_account` → `ticket_created=true`, assunto `[onboarding] domínio — email`.

### US-2 — Etapas completas no ticket

Como técnico, quero ver no ticket as etapas anteriores (domínio, DNS) e posteriores (conta, infra, concluído).

**Critério:** `funnel_notes` contém ≥3 eventos após funil completo; backfill marca `backfilled: true`.

### US-3 — Abandono vira Lead

Como ops lead, quero que sessões paradas 24h sem concluir apareçam como Leads para recuperação.

**Critério:** job marca `crm_track=lead`; lista `/api/v1/crm/leads` retorna o ticket.

### US-4 — Outreach rastreável

Como técnico, quero registar cada contacto ao lead (chat, e-mail, telefone) no ticket.

**Critério:** `POST .../contact` append em `lead_outreach[]`.

---

## RBAC

| Acção | super_admin | ops_lead | technician | noc |
|-------|-------------|----------|------------|-----|
| Ver leads | ✅ | ✅ | ✅ | ❌ |
| Contactar lead | ✅ | ✅ | ✅ | ❌ |
| Promover manual | ✅ | ✅ | ❌ | ❌ |
| Sync CRM externo | ✅ | ✅ | ❌ | ❌ |

---

## Fases de entrega

| Fase | Entrega | Estado |
|------|---------|--------|
| **A** | Ticket no `onboarding.started` (criar conta) + backfill + VM112 alinhado | ✅ 2026-06-10 |
| **B** | Job stale → `crm_track=lead` + UI lista Leads no Desk | ✅ 2026-06-10 |
| **C** | Outreach log + push ops_lead (007) | 📋 |
| **D** | Sync Odoo CRM / canal chat escolhido | 📋 |

---

## Fora de escopo

- Criar ticket só na validação de domínio (removido)
- Múltiplos tickets por sessão
- Chatbot com IA
- Spec 011 OTRS

---

## Referências

- `specs/010-desk-assist-takeover/spec.md` — assistência humana
- `specs/007-mobile-push-notifications/spec.md` — alerta funil travado
- VM112: `/opt/ibytera-mail-portal/backend/app/routers/onboarding.py`
- VM122: `api/app/main.py` — `TICKET_EVENTS_BY_SOURCE`, `_backfill_funnel_notes`