# Documentation Standards — OmniMeta

Padrão inspirado no OmniPlus Next (`docs/standards/DOCUMENTATION_STANDARDS.md`), adaptado ao gateway OmniMeta.

## Princípios

- Documentar o **porquê**, não só o como
- Objetivo, estruturado e acionável
- Português no texto; termos técnicos e identificadores em inglês
- Sem emojis
- Links internos **relativos**
- Evidência: citar arquivo/caminho quando afirmar comportamento atual
- Divergência doc × código: **implementação prevalece**; reportar a diferença

## Estrutura de pasta

```
docs/
├── INDEX.md
├── adr/
├── architecture/
├── modules/
└── standards/
```

Um índice único (`INDEX.md`). Evitar READMEs extras por pasta, salvo lista útil de módulos.

## Skeleton de módulo

1. Metadados (status, ADR, go-live)
2. Escopo (incluído / excluído)
3. Objetivo
4. Estado atual (evidência no código) — se aplicável
5. Arquitetura / fluxos (mermaid quando ajudar)
6. Contratos (collections, API, webhooks)
7. Limites e dependências
8. Critérios de aceite
9. Referências / histórico

## Skeleton de ADR

Status, data, contexto, decisão, consequências, alternativas, referências.

## Quando atualizar

- Toda feature que altere contrato público (API, webhook, collection)
- Toda decisão arquitetural relevante → novo ADR ou update
- Após implementação: marcar status do módulo e apontar arquivos reais criados

## Boa prática obrigatória: orquestrador multi-parceiro

Toda feature nova vinculada a uma `WhatsappAccount` (CRUD de recurso, envio, etc.) precisa nascer com a separação orquestrador (`Core\OmniMeta\UseCase\{Feature}\*`) × implementação por parceiro (`Core\UseCase\{Feature}\*` para Meta, `Core\Gupshup\UseCase\*`, etc.) — mesmo que só um parceiro tenha suporte no dia 1. Ver [ARCHITECTURE.md — Padrão orquestrador multi-parceiro](../architecture/ARCHITECTURE.md#padrão-orquestrador-multi-parceiro-coreomnimetausecase). Nunca travar a rota inteira num único parceiro (ex.: 422 hard-coded em middleware) — quem decide "esse parceiro não suporta ainda" é o orquestrador, com uma exceção de domínio clara.