# perk/ai-onboarding

## Hero

### De dias de setup manual pra minutos — com IA de produção.

Lançar um programa de fidelidade levava dias de configuração. Construímos um sistema de IA que gera um programa completo a partir da URL do site da marca, com chamadas LLM retentáveis, validação e audit trail.

## Contexto

Cada vez que a Perk onboardava um novo cliente, alguém tinha que configurar o programa manualmente: subir assets da marca, escolher cores, criar desafios, configurar produtos, montar tiers. Levava dias por cliente e exigia envolvimento de desenvolvedor na maioria dos passos.

O objetivo não era adicionar um chatbot. Era construir infraestrutura de IA que pudesse analisar de forma confiável a presença online de uma marca e gerar uma configuração production-ready de programa de fidelidade — automaticamente.

- Setup de programa levava dias de configuração manual por cliente
- Exigia envolvimento de desenvolvedor na maioria dos passos
- Assets da marca, cores, desafios, produtos, tiers — tudo manual
- Output da IA precisava ser production-ready, não sugestões
- Precisava funcionar de forma confiável em sites de marcas diversas

## Nosso papel

Projetamos e construímos o 'Assist' — um módulo de IA que pega a URL de um site e gera um programa de fidelidade totalmente configurado. Não é protótipo. É um sistema de produção com chamadas retentáveis, validação, audit logging e rollout com feature flags.

### Quote

> "Tem um nível de profissionalismo e consistência nesse output ser de alta qualidade e confiável. Em vez de só dizer sim e fazer a coisa, vocês garantem que tá alinhado com o propósito."

## O que mudou

Setup de programa caiu de dias pra minutos. O pipeline de IA cuida de análise de marca, extração de cores, geração de desafios, identificação de produtos e sugestão de recompensas — tudo automaticamente.

- Setup de programa reduzido de dias pra minutos
- Wizard de onboarding de 9 passos com save/resume
- Análise automática de marca a partir de qualquer URL
- Configurações de desafios, recompensas e tiers geradas automaticamente
- Rollout com feature flags pra adoção controlada

## Áreas que assumimos

#### Pipeline de Análise de Website

Browser headless captura e analisa sites de marcas automaticamente.

- **Captura com Browser Headless**: Ferrum (Chromium headless) tira screenshots e captura conteúdo do site de forma assíncrona. O sistema navega pelo site da marca, identificando páginas, produtos, artigos e contas de redes sociais.
- **Extração de Marca**: LLM analisa os dados capturados pra extrair cores da marca com checagem de contraste, detectar tom da marca em posts de redes sociais, identificar produtos da loja, e puxar conteúdo pra desafios.

#### Infraestrutura de LLM

Pipeline de IA production-grade — não um wrapper em cima de uma chamada de API.

- **Chamadas LLM Retentáveis**: Funções de validação customizadas verificam cada output do LLM. Chamadas que falham são retentadas com feedback do erro da tentativa anterior injetado no prompt de retry, melhorando taxas de sucesso sem intervenção manual.
- **Audit Trail**: Cada chamada LLM é logada com resposta raw, resultado de validação, detalhes de erro e histórico de retentativas. Rastreabilidade completa do input ao output.
- **Processamento em Background**: Todos os pipelines de extração rodam como jobs em background via Solid Queue. A UI mostra progresso em tempo real enquanto o processamento pesado acontece de forma assíncrona.

#### Geração de Programa

Output da IA vira um programa real e configurável — não só sugestões.

- **Wizard de Onboarding**: Wizard de 9 passos com save/resume via onboarding drafts. Cada passo pode ser executado independentemente ou como parte do fluxo. Admins revisam e ajustam sugestões da IA antes de finalizar.
- **Output de Configuração**: Gera paleta de cores, configurações de desafios (visita a artigos, quizzes de produto, social feeds), produtos elegíveis pra escaneamento de recibos, sugestões de recompensas e estrutura de tiers.

## Por que isso importa

Essa é a diferença entre 'integramos uma API de LLM' e 'construímos infraestrutura de IA que opera de forma confiável em condições reais.'

Chamadas retentáveis com validação customizada. Feedback de erro injetado nos prompts de retry. Audit trail completo. Rollout com feature flags. Processamento em background. IA de produção significa que o sistema funciona quando ninguém tá olhando, não só durante demos.

## Resultado

Setup de programa saiu de processo manual de vários dias pra minutos de geração automatizada mais revisão humana. A infraestrutura de IA que construímos — chamadas retentáveis, validação, audit logging — é reutilizável em qualquer feature futura de IA que a Perk adicionar à plataforma.