> ## 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.

# Produto

> Visão simples do primeiro produto da Orquena, das jornadas e das regras que orientam a implementação.

# Produto

A Orquena transforma o WhatsApp de uma empresa de serviços em uma central operacional com Inbox, agenda e inteligência artificial controlada.

<Info>
  Esta página é uma porta de entrada. Os requisitos detalhados e critérios de aceitação continuam nos PRDs versionados e não são substituídos por este resumo.
</Info>

## Primeiro produto

O MVP atende negócios que trabalham com horário marcado, como barbearias, salões, estúdios de unhas, estética e outros prestadores de serviços.

```text theme={null}
Login com Google ou email
        ↓
Onboarding guiado e retomável
        ↓
WhatsApp conectado por QR Code
        ↓ sincronização recente em segundo plano
Serviços, profissionais e horários
        ↓
Google Calendar opcional
        ↓
Escolha e teste do modo da IA
        ↓
Dashboard, Inbox e Agenda
```

O cliente externo não cria conta na Orquena. Ele continua usando o próprio WhatsApp para falar com o número comercial da organização.

## Estrutura comercial e tenant

* `CustomerAccount` representa a relação comercial, assinatura e entitlements.
* `Organization` representa uma loja operada separadamente, seu tenant e sua fronteira de dados.
* `OrganizationGroup` é apenas um agrupamento de navegação e relatórios autorizados.
* Uma loja não herda contatos, mensagens, agenda ou credenciais de outra loja.
* Um `Professional` pode existir sem login no dashboard.
* Um `Contact` é local à organização, mesmo quando o telefone também existe em outro tenant.

## Onboarding

No primeiro acesso, o sistema cria a identidade do usuário, a conta comercial, a primeira organização e as memberships de proprietário.

A organização começa em `SETUP_REQUIRED` e avança conforme resultados reais são concluídos:

* Dados do negócio.
* WhatsApp conectado.
* Pelo menos um serviço.
* Pelo menos um profissional.
* Horários e regras mínimas de agendamento.
* Decisão explícita sobre Google Calendar.
* Escolha do modo da IA.
* Simulação concluída.

O progresso é calculado no backend. O frontend apenas apresenta o resultado e orienta o próximo passo.

A conexão do WhatsApp acontece cedo. Enquanto contatos e conversas recentes são sincronizados, o proprietário continua cadastrando o negócio.

## Orquena Inbox

A Orquena Inbox é a superfície canônica de atendimento.

Ela oferece:

* Lista de conversas.
* Mensagens persistidas e paginadas.
* Campo para resposta humana.
* Contagem de não lidas.
* Atribuição e estados da conversa.
* Notas internas e tags.
* Status da conexão do canal.
* Controle de IA e atendimento humano.
* Realtime como atualização de experiência, nunca como fonte da verdade.

WAHA envia e recebe mensagens, mas não decide identidade do contato, estado da conversa, autorização ou comportamento da IA.

## Modos da IA

Toda Inbox nova começa com IA desligada.

| Modo        | Comportamento                                    |
| ----------- | ------------------------------------------------ |
| `OFF`       | Atendimento totalmente humano                    |
| `COPILOT`   | A IA sugere; o clique apenas preenche o composer |
| `AUTOPILOT` | A IA responde e usa ferramentas controladas      |

Uma Inbox possui um modo padrão e uma conversa pode ter override próprio.

```typescript theme={null}
effectiveAiMode = conversation.aiModeOverride ?? inbox.defaultAiMode
```

Alterar o padrão da Inbox não pode apagar silenciosamente overrides existentes. Mudanças em massa exigem preview, seleção explícita e auditoria.

## Controle operacional e handoff

O modo configurado não é o mesmo que o estado operacional da conversa.

```text theme={null}
AI_ACTIVE
HUMAN_REQUIRED
HUMAN_ACTIVE
PAUSED
```

Quando a IA não consegue continuar com segurança, ela:

1. interrompe respostas automáticas;
2. cria um pedido de handoff;
3. gera um resumo curto do ocorrido;
4. notifica a equipe;
5. mantém o atendimento na mesma conversa;
6. pode enviar uma única mensagem de espera aprovada.

A primeira resposta humana muda a conversa para `HUMAN_ACTIVE`. A devolução para a IA é explícita ou segue uma política segura e auditada.

## Agendamento

A disponibilidade é calculada pelo domínio, não pelo modelo de linguagem.

Um slot considera:

* Funcionamento da organização.
* Escala e intervalos do profissional.
* Serviço permitido para o profissional.
* Duração e buffers.
* Folgas, bloqueios e exceções.
* Agendamentos e holds.
* Recursos necessários.
* Antecedência, horizonte e timezone.

A IA usa ferramentas tipadas para consultar disponibilidade, criar hold, confirmar, reagendar ou cancelar. Ela não inventa preço, profissional, horário, desconto ou política.

## Google

Google Login e Google Calendar são consentimentos separados.

```text theme={null}
Google Login
└── identidade básica

Google Calendar
└── integração opcional da organização
```

Na primeira versão, a Orquena publica appointments confirmados no calendário escolhido. A Orquena continua sendo a fonte da verdade, e falhas do Google não desfazem agendamentos já confirmados.

## Dashboard

O dashboard é composto pelas capacidades habilitadas. Exemplos:

* Agendamentos de hoje.
* Próximo atendimento.
* Conversas não lidas.
* Handoffs aguardando humano.
* WhatsApp conectado ou degradado.
* Sincronizações de calendário pendentes.
* Sugestões aceitas no modo assistente.
* Atendimentos e appointments realizados pela IA.

## Escopo que fica para depois

* Gmail como caixa de envio do cliente.
* Sincronização bidirecional completa com calendários externos.
* Campanhas em massa pelo WAHA.
* CRM completo antes da operação principal.
* Múltiplos canais oficiais no primeiro piloto.
* Personalização profunda de tom, personalidade ou voz.
* Marketplace público de plugins.

## Especificações detalhadas

<CardGroup cols={2}>
  <Card title="Onboarding, Inbox e IA" icon="clipboard-check" href="/product/onboarding">
    Primeiro acesso, progresso, WhatsApp, simulador e ativação.
  </Card>

  <Card title="Orquena Inbox" icon="messages-square" href="/product/inbox">
    Conversas, mensagens, canal e atendimento humano.
  </Card>

  <Card title="Modos da IA" icon="bot" href="/product/ai-modes">
    OFF, COPILOT, AUTOPILOT, overrides e handoff.
  </Card>

  <Card title="Agendamento" icon="calendar-days" href="/integrations/scheduling">
    Regras determinísticas, holds e appointments.
  </Card>
</CardGroup>

Os contratos canônicos completos estão em:

* `docs/prds/appointments-vertical-v1.md`
* `docs/prds/onboarding-inbox-ai-v1.md`
* `docs/architecture/conversation-ai-control-v1.md`