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

# Operações

> Segurança, qualidade, documentação, ambientes, observabilidade e regras de contribuição da Orquena.

# Operações

Operar a Orquena significa manter isolamento entre tenants, proteger credenciais e dados pessoais, preservar rastreabilidade e impedir que automações ou providers externos contornem regras do produto.

<Info>
  Esta página reúne a visão operacional. Threat models, políticas, runbooks e contratos específicos permanecem separados e versionados.
</Info>

## Requisitos desde o primeiro código

* Tenant isolation na aplicação e no banco.
* Least privilege para usuários, serviços, agentes e plugins.
* Credenciais criptografadas e preparadas para rotação.
* Webhooks autenticados, deduplicados e observáveis.
* Sessões seguras e revogáveis.
* Auditoria de ações privilegiadas e automáticas.
* Redação de dados sensíveis em logs e traces.
* Dependency, secret e container scanning.
* Backups com testes reais de restauração.
* Idempotência para side effects.
* Kill switches para respostas automáticas e providers.
* Aprovação humana para ações de maior impacto.

## Fronteiras de confiança

Os principais limites são:

1. Navegador para edge/API.
2. Provider de mensagens para webhook público.
3. Aplicações para PostgreSQL, Valkey e object storage.
4. AI Runtime para APIs internas autenticadas.
5. Plataforma para providers externos.
6. Suporte da plataforma para dados de uma organização.
7. Plugins externos para contracts restritos.

Cruzar uma fronteira exige autenticação ou origem confiável, validação de schema, autorização atual, tenant resolvido por estado interno, correlation e audit quando aplicável.

## Privacidade

* Contacts, mensagens e appointments são dados da organização.
* Acesso de suporte é temporário, justificado e auditado.
* Conversas não entram em logs completos por conveniência.
* Export, retenção e exclusão são tenant-aware.
* Media utiliza URLs assinadas e curtas.
* Memória e retrieval da IA seguem a mesma política de retenção dos dados de origem.
* Provider ou modelo recebe apenas o mínimo necessário para executar a tarefa.

## Observabilidade

OpenTelemetry é o contrato de telemetria.

A stack inicial planejada inclui:

* Grafana Alloy para coleta.
* Prometheus para métricas.
* Loki para logs.
* Tempo para traces.
* Grafana para visualização e alertas.

Sinais importantes:

* Latência e erros da API.
* Webhooks recebidos, rejeitados e duplicados.
* Jobs, retries e dead letters.
* Estado das sessões WAHA.
* Falhas e atraso de sincronização do Calendar.
* Execuções de IA, tool failures, custo e handoff.
* Cross-tenant authorization denials.
* Backlog de mensagens e notificações.

Logs e traces carregam correlation IDs, mas não credenciais, tokens, conteúdo completo de conversa ou dados pessoais desnecessários.

## Ambientes

```text theme={null}
local
 test
preview
staging
production
```

Regras:

* Configuração é tipada e validada no startup.
* Falta de variável obrigatória causa fail fast.
* `.env.example` contém somente nomes e exemplos seguros.
* Credenciais de produção não são reutilizadas em desenvolvimento.
* Preview não acessa dados reais de clientes.
* Migrações e rollback são exercitados antes de produção.

## Implantação inicial

A primeira topologia será Docker Compose em VPS, com processos e stores separados em containers.

Antes do piloto, precisam existir:

* Health checks.
* Persistent volumes revisados.
* Backup e restore testados.
* TLS e headers de segurança.
* Firewall e acesso administrativo restrito.
* Métricas, logs e alertas básicos.
* Procedimentos de atualização e rollback.
* Plano para reconectar sessões WAHA.

Escala horizontal ou Kubernetes só entram quando métricas e operação justificarem.

## Qualidade

Checks esperados no bootstrap:

```text theme={null}
install
format
lint
typecheck
unit tests
integration tests
build
architecture boundaries
documentation validation
security scan
```

Mudanças de domínio exigem testes para:

* Tenant isolation.
* Permission enforcement.
* Idempotência.
* Concorrência.
* Retry e recovery.
* Timezone e DST quando aplicável.
* Provider outage.
* Auditoria.

## Modelo documental híbrido

A documentação possui quatro camadas:

1. **Orientação:** seis páginas simples do Mintlify.
2. **Especificação:** PRDs, contratos de arquitetura, threat models e ADRs.
3. **Componentes:** READMEs próximos de apps, packages, plugins, providers e infra.
4. **Pesquisa:** avaliações, referências e candidatos ainda não aceitos.

Páginas de orientação facilitam descoberta, mas não substituem contratos específicos.

Um documento detalhado só pode ser removido quando houver:

* Destino canônico explícito.
* Mapeamento de seções preservadas.
* Redirect quando houver rota pública.
* Revisão das referências e links.
* Confirmação de que histórico e governança não foram enfraquecidos.

Consulte `docs/documentation-governance.md` para precedência e manutenção.

## Fluxo de contribuição

1. Referenciar uma tarefa, requisito, RFC ou incidente.
2. Ler as páginas de orientação.
3. Ler os documentos específicos da área.
4. Identificar impactos de tenancy, segurança, events, migration, privacy e operação.
5. Trabalhar em branch dedicada.
6. Atualizar especificações e testes junto com o comportamento.
7. Executar os checks relevantes.
8. Explicar riscos, rollback e trabalho restante no PR.

## Resposta a vulnerabilidades

Até existir um canal privado formal, vulnerabilidades não devem ser publicadas com detalhes exploráveis em issues ou PRs. O proprietário do repositório deve ser contatado de forma privada, sem incluir credenciais ou dados de cliente.

## Documentos detalhados

* `SECURITY.md`
* `CONTRIBUTING.md`
* `docs/security/threat-model-v1.md`
* `docs/product/non-functional-requirements.md`
* `docs/legal/open-source-policy.md`
* `docs/architecture/events-and-jobs-v1.md`
* `infra/`
* `docs/operations/`
* `docs/runbooks/`