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.
Primeiro acesso e onboarding
No primeiro login, a Orquena cria: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.
Autenticação Google
O login solicita somente identidade básica:Tenancy
- 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.Modos da IA
OFF.
O modo efetivo é:
Controle da conversa
Modo configurado e controle operacional são separados.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.
Google Calendar
A Orquena é a fonte da verdade. Primeira direçã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. Jobs possuem:- Payload versionado.
organizationIdconfiá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.