# Documentation Standards (Baseado em Comportamento Observado no Código)

Este documento define um padrão mínimo de documentação para novas mudanças. Ele é baseado no que foi observado no repositório (incluindo as docs criadas a partir da auditoria).

## 1) Como a documentação atual se comporta

### 1.1 Existe documentação?
- Existe `README.md`, que descreve instalação/configuração da VM e dependências.
- Não foi identificado no código (durante a auditoria) um conjunto prévio e formal de “standards” de arquitetura/por camada.
- Durante esta análise foram gerados documentos estruturados em:
  - `docs/architecture/*`
  - `docs/architecture/violations.md`
  - `docs/decisions/*` (o ADR será criado separadamente)

### 1.2 Está atualizada?
- `README.md` está presente no repositório, mas é focado em instalação/configuração; não serve como standard arquitetural.
- Os docs `docs/architecture/*` foram criados com base no que foi encontrado no código.

### 1.3 Está confiável?
- A confiabilidade depende da evidência: os docs de arquitetura foram baseados no que foi encontrado no código e em trechos/arquivos específicos.

## 2) Problemas encontrados

1. Não existe um “contrato” formal único de documentação arquitetural prévio (no sentido de estar evidente no repositório antes da auditoria).
2. Há evidências de padrões e anti-padrões (controllers com lógica e SQL inline, services acoplados a request/handlers), mas não havia um guia escrito para evolução segura.

## 3) Regras obrigatórias para documentação futura

### 3.1 Regra de evidência

Toda regra/descrição que for afirmativa deve ter uma evidência no código (arquivo/ponto).

Quando não houver evidência:
- marcar explicitamente como **“Não identificado no código”**.

### 3.2 Regras para multi-tenancy

Documentar sempre:
- qual middleware ou modelo é responsável pelo isolamento do tenant;
- qual mecanismo de conexão é acionado (ex.: `connect()` / `DB::purge('tenant')` / `DB::reconnect('tenant')`).

Evidências usadas:
- `app/Http/Middleware/Tenant.php`
- `app/Models/Cliente/Cliente.php::connect()`
- `app/Models/TenantModel.php`

## 4) Padrão de escrita para IA

1. Antes de afirmar, verificar o código (quando a evidência já existe, citar a fonte).
2. Nunca “inventar” contratos não presentes no código.
3. Se for sobre integração front/back (ex.: DataTables), manter o contrato observado no JS.
4. Se houver dependência de rotas/middleware, listar quais rotas/arquivos conectam isso.

## 5) Como lidar com incerteza

Quando algo não estiver claro no código:
- escrever **“Não identificado no código”**.

Não usar conhecimento externo para preencher lacunas.