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

# Specification Pack v1

> Decisões de produto, plugins, eventos, jobs, dados, segurança e desempenho que precedem o primeiro código.

# 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

O primeiro vertical atende empresas baseadas em agendamento.

Inclui:

* `CustomerAccount` para assinatura e gestão comercial.
* Uma `Organization` tenant para cada loja operada separadamente.
* Agrupamento opcional de organizações sem compartilhamento automático de dados.
* Membros e permissões independentes por tenant.
* Serviços, preços versionados e profissionais.
* Horários de funcionamento, escalas, intervalos e agendamentos.
* Contatos, tags e inbox isolados por organização.
* Secretária de IA usando tools controladas.
* WAHA como primeiro provider de testes e pilotos.
* Notificações transacionais.

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.

## Tenancy

```text theme={null}
CustomerAccount
└── OrganizationGroup?
    ├── Organization: Loja Centro
    ├── Organization: Loja Shopping
    └── Organization: Loja Zona Sul
```

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.

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

## 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.
* Um plugin futuro de campanhas poderá criar um rascunho sujeito a consentimento e aprovação.
* 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.

<Warning>
  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.
</Warning>

Jobs possuem:

* 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, contatos, catálogo, versões de preço, profissionais, disponibilidade, agenda, inbox, IA, notificações, campanhas futuras, CRM opcional 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 criptografadas.
* Agentes sem acesso direto ao banco.
* Tools com menor privilégio.
* Proteção contra prompt injection.
* Constraints transacionais para evitar conflito de agenda.
* Rate limits e budgets 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 e concorrência, validadas por testes de carga antes da comercialização.