> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquena.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding e ativação

> Primeiro acesso, progresso do setup, conexão inicial do WhatsApp e critérios para ativar uma organização.

# Onboarding e ativação

O primeiro acesso da Orquena transforma uma conta recém-criada em uma organização pronta para atender clientes.

O setup é guiado, possui progresso visual e pode ser retomado depois. A pessoa começa conectando o WhatsApp e continua cadastrando o negócio enquanto contatos e conversas recentes são sincronizados em segundo plano.

## Primeiro acesso

A autenticação oferece:

* Continuar com Google.
* Email e senha.

O mesmo botão do Google serve para cadastro e login.

No primeiro acesso, a Orquena cria:

```text theme={null}
User
CustomerAccount
Organization
Memberships de proprietário
OnboardingProgress
```

A organização inicia como:

```text theme={null}
SETUP_REQUIRED
```

Depois do primeiro passo concluído, passa para `SETUP_IN_PROGRESS`. Quando todos os requisitos mínimos são atendidos, passa para `READY`.

## Boas-vindas

A experiência utiliza o nome recebido no login:

```text theme={null}
Olá, José 👋
Vamos preparar a Orquena para o seu negócio.
```

O usuário pode sair e retomar exatamente de onde parou.

## Progresso visual

A porcentagem é calculada pelo backend a partir de resultados concluídos ou decisões explícitas.

| Etapa                            | Peso |
| -------------------------------- | ---: |
| Dados do negócio                 |  15% |
| WhatsApp conectado               |  20% |
| Serviços                         |  15% |
| Profissionais                    |  15% |
| Horários e regras de agendamento |  15% |
| Decisão sobre Google Calendar    |  10% |
| Decisão e simulação da IA        |  10% |

Exemplo:

```text theme={null}
Configuração da Barbearia do José

████████████░░░░░░░░ 60%

✅ Dados do negócio
✅ WhatsApp conectado
✅ Serviços
⬜ Profissionais
⬜ Horários
⬜ Google Calendar
⬜ Inteligência artificial
```

Não existe porcentagem enviada livremente pelo navegador. A API calcula o progresso usando os registros reais da organização.

## Ordem do setup

```text theme={null}
Login
  ↓
Boas-vindas e criação da organização
  ↓
Conectar WhatsApp por QR Code
  ↓ sincronização em segundo plano
Dados do negócio
  ↓
Serviços
  ↓
Profissionais
  ↓
Horários, intervalos e regras simples
  ↓
Google Calendar
  ↓
Simulador e escolha do modo da IA
  ↓
Validação final
  ↓
Dashboard
```

A ordem pode permitir retorno a etapas anteriores, mas os critérios finais são validados no servidor.

## Conectar o WhatsApp primeiro

A conexão começa cedo para que a sincronização aconteça enquanto o proprietário configura o negócio.

```text theme={null}
[ QR CODE ]

Abra o WhatsApp no celular
→ Aparelhos conectados
→ Conectar aparelho
→ Escaneie este código
```

Estados mostrados ao usuário:

```text theme={null}
Preparando
Aguardando QR Code
Conectando
Conectado
Sincronizando
Reconectando
Desconectado
Ação necessária
Erro
```

Depois de conectado:

```text theme={null}
WhatsApp conectado ✅
Importando contatos: 347 encontrados
Sincronizando conversas recentes…

Você pode continuar configurando seu negócio.
```

A conexão deve persistir até que o usuário desconecte, remova o dispositivo no próprio WhatsApp ou a sessão seja invalidada.

## Escopo da sincronização inicial

A Orquena não promete importar todo o histórico antigo.

O MVP busca:

* Contatos disponibilizados pelo provider.
* Chats existentes e metadados básicos.
* Um número limitado de mensagens recentes por conversa.
* Todas as novas mensagens depois da conexão.

Uma falha parcial na importação não impede o recebimento de novas mensagens quando o canal já está conectado.

## Dados do negócio

Informações mínimas:

* Nome do negócio.
* Segmento.
* Telefone.
* Endereço ou indicação de atendimento móvel.
* Fuso horário.
* Idioma e região.
* Moeda.

## Serviços

Para completar a etapa, deve existir pelo menos um serviço ativo com:

* Nome.
* Duração.
* Preço atual.
* Moeda.

A IA nunca inventa serviços ou preços que não estejam cadastrados.

## Profissionais

Para completar a etapa, deve existir pelo menos um profissional ativo e associado a um serviço.

O profissional não precisa ter acesso ao dashboard.

## Horários e regras simples

A etapa reúne:

* Horário de funcionamento.
* Dias de atendimento.
* Jornada dos profissionais.
* Intervalos.
* Bloqueios e folgas quando necessários.
* Antecedência mínima para agendamento.
* Limite futuro de agendamento.
* Regra de cancelamento.
* Confirmação antes de criar o compromisso.

Não existe uma etapa pesada chamada “Políticas” no MVP. As regras necessárias ficam junto da configuração da agenda.

## Google Calendar

Entrar com Google e conectar o Calendar são autorizações separadas.

O proprietário escolhe:

```text theme={null}
[ Conectar Google Calendar ]
[ Pular por enquanto ]
```

Pular é uma decisão válida e conclui a etapa. A agenda nativa da Orquena continua funcionando.

Quando conectado, a primeira direção é:

```text theme={null}
Appointment da Orquena
    ↓
Evento do Google Calendar
```

A Orquena permanece a fonte oficial do agendamento.

## Escolha da IA

O padrão é sempre:

```text theme={null}
IA desligada
```

O proprietário compara os três comportamentos em um simulador antes de escolher:

* Desligada.
* Assistente.
* Automática.

Escolher “Desligada” conclui a etapa. A pessoa não é obrigada a ativar automação para finalizar o setup.

## Simulador

O simulador utiliza serviços, profissionais e horários já cadastrados.

Mensagem de exemplo:

```text theme={null}
Olá! Meu nome é José.
Gostaria de agendar um corte na Barbearia do José amanhã.
```

A tela apresenta três experiências:

### Desligada

Somente a mensagem recebida e o campo para resposta humana.

### Assistente

Sugestões aparecem acima do campo. Clicar em uma sugestão apenas preenche o texto; nada é enviado automaticamente.

### Automática

A IA consulta os dados cadastrados e demonstra como responderia e ofereceria horários.

O simulador nunca envia uma mensagem real para o WhatsApp.

## Critérios para ativação

A organização fica `READY` quando:

* Dados do negócio estão completos.
* WhatsApp está conectado.
* Existe pelo menos um serviço ativo.
* Existe pelo menos um profissional ativo ligado a um serviço.
* Horários são válidos.
* Google Calendar foi conectado ou explicitamente ignorado.
* Um modo de IA foi escolhido.
* A simulação foi concluída.

A sincronização histórica pode continuar depois da ativação, desde que o caminho de mensagens novas esteja funcionando.

## Depois da ativação

Se o WhatsApp desconectar mais tarde:

```text theme={null}
Organization.status = READY
ProviderConnection.status = DISCONNECTED
```

O setup não é reiniciado. O dashboard mostra a ação necessária para reconectar.

## Fonte canônica

Os detalhes de entidades, estados, segurança e critérios de aceitação estão no PRD:

```text theme={null}
docs/prds/onboarding-inbox-ai-v1.md
```