Specification Pack v1
A primeira implementação será guiada por contratos explícitos, não por decisões improvisadas durante a geração de código.
Produto inicial
O primeiro produto completo atende empresas baseadas em agendamento e combina:
- Login com Google ou email.
- Onboarding guiado e retomável.
- Uma organização tenant para cada loja.
- Conexão antecipada do WhatsApp.
- Orquena Inbox.
- Serviços, profissionais, horários e appointments.
- Google Calendar opcional.
- IA desligada, assistente ou automática.
- Handoff humano na mesma conversa.
- Dashboard composto pelas capacidades ativas.
O cliente externo nunca precisa de conta no painel: ele utiliza o próprio WhatsApp para falar com o número comercial da organização.
Clínicas podem reutilizar o motor de agenda no futuro, mas prontuários, convênios e dados médicos ficam fora da primeira versão.
Primeiro acesso e onboarding
No primeiro login, a Orquena cria:
A organização começa em SETUP_REQUIRED.
O progresso é calculado no backend a partir de resultados concluídos:
- Dados do negócio.
- WhatsApp conectado.
- Serviços.
- Profissionais.
- Horários e regras simples.
- Decisão sobre Google Calendar.
- Escolha e simulação da IA.
O WhatsApp é conectado cedo. A importação limitada de contatos e conversas recentes continua em segundo plano enquanto a pessoa configura o negócio.
Escolher IA desligada e pular o Google Calendar são decisões explícitas válidas.
Autenticação Google
O login solicita somente identidade básica:
Google Calendar exige uma autorização separada e contextual.
Entrar com Google nunca concede automaticamente acesso a Calendar, Gmail, Drive ou Contacts.
Tenancy
Cada organização é:
- Tenant.
- Fronteira de segurança.
- Unidade futura de cobrança.
- Proprietária de contatos, WhatsApp, catálogo, agenda, agentes e plugins.
OrganizationGroup serve apenas para navegação e relatórios explicitamente autorizados.
Orquena Inbox
A Inbox é a fonte oficial de conversas e mensagens normalizadas.
O MVP importa contatos, chats e um histórico recente limitado. Depois da conexão, todas as novas mensagens são persistidas antes de IA ou automação.
A tela permite atendimento humano mesmo sem IA e continua acessível quando o provider está desconectado.
Modos da IA
Toda nova Inbox começa em OFF.
O modo efetivo é:
Mudanças de default não apagam overrides silenciosamente.
Controle da conversa
Modo configurado e controle operacional são separados.
Um chat configurado como AUTOPILOT pode permanecer em HUMAN_ACTIVE, impedindo respostas automáticas até retorno explícito ou por inatividade segura.
O handoff:
- Continua na mesma conversa.
- Gera resumo.
- Cria notificação.
- Pode enviar uma mensagem de espera apenas uma vez.
- Permite takeover e retorno.
Agendamento
A disponibilidade é calculada pela interseção de:
- Horário de funcionamento da organização.
- Horário de trabalho do profissional.
- Intervalos, folgas, bloqueios e exceções.
- Serviço habilitado para o profissional.
- Duração e buffers.
- Agendamentos e holds existentes.
- Recursos obrigatórios.
- Lead time, horizonte e timezone.
A IA não interpreta escalas livremente. Ela chama uma tool de disponibilidade e recebe slots válidos.
Google Calendar
A Orquena é a fonte da verdade.
Primeira direção:
Create, update e cancel usam mapping e idempotência. Falha do Google não desfaz um appointment confirmado.
Sincronização bidirecional fica fora da primeira versão.
Preços
Serviços possuem versões de preço com vigência.
- Novas consultas usam o preço vigente.
- Mudanças futuras podem ser agendadas.
- Agendamentos confirmados preservam o preço aceito.
- Alterar preço emite evento, mas não dispara mensagens automaticamente.
- Campanhas em massa via WAHA ficam desabilitadas no beta.
Plugins
Plugins oficiais são pacotes revisados do monorepo e descobertos por catálogo estático gerado no build.
A primeira versão não instala pacotes npm arbitrários em produção. Integrações externas executam em serviços ou containers isolados.
Cada plugin declara:
- ID e versão.
- Compatibilidade.
- Capabilities e dependências.
- Permissões.
- Configuração.
- Rotas e contribuições de interface.
- Eventos e jobs.
- Ferramentas para agentes.
- Health check e classificação dos dados.
Eventos e jobs
PostgreSQL é a fonte da verdade e utiliza transactional outbox para publicar eventos.
BullMQ sobre Valkey é o primeiro transporte de jobs, sempre atrás dos contratos da plataforma.
O worker não possui um tenant global ativo. Cada job abre um contexto isolado para sua organização, valida os registros e destrói o contexto ao terminar.
- Payload versionado.
organizationId confiável.- Idempotency key.
- Timeout.
- Retry classificado.
- Backoff.
- Dead-letter durável.
- Controle de concorrência.
- Retenção.
Modelo de dados
O modelo cobre identidade, conta comercial, tenancy, onboarding, contatos, catálogo, profissionais, agenda, Inbox, preferências de IA, controle de conversa, handoff, integrações de calendário, notificações e operação da plataforma.
Dados específicos de novos verticais entram em plugins próprios.
Segurança
Controles críticos incluem:
- Membership e permissões por organização.
- Row-Level Security quando aplicável.
- Testes entre organizações irmãs.
- Webhooks autenticados e deduplicados.
- Resolução do tenant pelo mapeamento interno da conexão.
- Credenciais e refresh tokens criptografados.
- Agentes sem acesso direto ao banco.
- Tools com menor privilégio.
- Proteção contra prompt injection.
- Revalidação do controle da conversa antes de resposta automática.
- Constraints transacionais para evitar conflito de agenda.
- Rate limits, budgets e kill switch por organização.
Desempenho
Metas são separadas por tipo de carga.
Dez mil conexões realtime, dez mil sessões de WhatsApp e dez mil execuções de IA são problemas diferentes e nunca serão tratados como a mesma promessa.
A primeira etapa terá metas mensuráveis de API, disponibilidade, webhook, filas, sincronização e concorrência, validadas por testes antes da comercialização.
Documentos canônicos