# AI_GUIDELINES.md (Guia de Uso Seguro de IA)

Este documento define regras para uso de IA ao evoluir o repositório. Ele é baseado **exclusivamente** no que foi identificado em código e na documentação já gerada em `docs/architecture/*`.

Quando algo não estiver explícito no repositório, está marcado como **Não identificado no código**.

## Regras explícitas existentes

### Multi-tenancy / Tenant

- Tenant é resolvido no middleware `app/Http/Middleware/Tenant.php`, que identifica o tenant e chama `connect()`:
  - Identificação por `request->token_whatsapp` quando presente.
  - Caso contrário, usa `Auth()->user()->cliente_id`.
  - Em seguida, chama `$user->connect()`.

Evidência:
- `app/Http/Middleware/Tenant.php`
- `app/Models/Cliente/Cliente.php` (método `connect()` ajusta dinamicamente a connection `tenant`)
- `app/Models/TenantModel.php` (define `protected $connection = 'tenant'`)

### Conexão de Models

- Model base tenant: `app/Models/TenantModel.php` fixa a connection `tenant`.
- Model base central: `app/Models/MainModel.php` fixa `protected $connection = 'mysql'`.

### Auth/MFA e fluxo de request

- `app/Http/Middleware/VerifiedMFA.php` delega para métodos do `LoginController` com base em flags no request (`verify`, `sendcode`, `sendRedefine`) e também controla emissão do QR quando `Auth::user()->secret_fa` e `fa_status == 1` e `key_used` está vazio.

### CSRF

- `app/Http/Middleware/VerifyCsrfToken.php` define `except` para rotas específicas, incluindo:
  - `email/webhook/*`, `whatsapp/webhook/*`, `instagram/webhook/*`, `webchat/*`
  - `ambiente`, `envia/link/email`, `redefinir/senha`, `sincronizar-cache`

### Formato esperado de respostas usadas pelo front (exemplo)

- O front de relatório usa DataTables serverSide e faz `POST` para `/atendimento/query`.
- O JS espera `responseJSON.data`, `responseJSON.recordsTotal` e usa `draw`.

Evidência:
- `public/pages/scripts/relatorioatendimento/initrelatorio.js` (requisição e tratamento do JSON)
- rota em `routes/web.php` para `Atendimento\AtendimentoController@relatorio`

## Regras obrigatórias

### Multi-tenancy obrigatória

1. Para qualquer feature que leia/escreva dados do “tenant”, a IA deve:
   - assegurar que a rota/controller esteja sob `app/Http/Middleware/Tenant.php` (quando aplicável), e/ou
   - usar modelos que herdam de `app/Models/TenantModel.php`.

2. Se a feature exigir conexão com o “banco do tenant” via `Cliente::connect()`, a IA deve respeitar o mecanismo existente:
   - chamar via middleware `Tenant` (preferencialmente) ou
   - seguir o mesmo padrão de `connect()` visto em `app/Models/Cliente/Cliente.php`.

### Evolução segura (compatibilidade com o que o código já espera)

1. Se a feature afetar rotas usadas por DataTables, a IA deve manter o contrato do JSON que o front consome:
   - `data`, `recordsTotal` e `draw` (e demais chaves usadas pelo JS).

2. Se a feature afetar rotas de webhook (WhatsApp/Instagram/Email/Webchat), a IA deve respeitar o comportamento de CSRF existente:
   - não remover/alterar sem evidência e ajuste do `VerifyCsrfToken::$except` para as rotas necessárias.

## Regras críticas de multi-tenancy

1. Não introduzir queries em connection central (`mysql`) para dados que devem ser do tenant, a menos que exista evidência no código de que aquele dado é realmente do banco central.
   - Evidência de separação: `TenantModel` fixa connection `tenant` e `MainModel` fixa `mysql`.

2. Não assumir que `client_id`/`tenant_id` existe em todas as tabelas do tenant schema.
   - Evidência: migrations do diretório `database/migrations/tenant` mostram tabelas sem `tenant_id/client_id` (ex.: `atendimento`, `fila_canal`), e ao mesmo tempo existem tabelas com `client_id/tenant_id` (ex.: `configuracao_email`).

3. Para features de integração que recebem `client_id`/token pela URL/request, a IA deve manter o caminho de identificação do tenant:
   - `Tenant` usa `token_whatsapp` -> `cliente_id` -> `connect()`.
   - Para e-mail/credenciais OAuth, aparecem `tenant_id`, `client_id`, `client_secret` na lógica de controllers específicos (ex.: `ApiEmailController`, `Integracao/EmailController`).

## Regras obrigatórias para evolução segura

1. Não inventar novos contratos entre camadas: quando um contrato existir, ele deve estar evidente (ex.: formatos de JSON consumidos por JS; middleware em rotas; conexão fixada por Model).
2. Não alterar a estratégia de multi-tenancy sem evidência de suporte no código (ex.: sem alterar `Tenant.php`, sem mudar `TenantModel`/`MainModel`).
3. Quando a feature envolver relatórios/SQL:
   - manter o formato do resultado esperado (ex.: campos do select usados pelo front/export).

**Não identificado no código**: uso obrigatório de testes, padrão de mocks, pipeline CI/CD e critérios de “Definition of Done”.

## Regras para uso seguro da IA

1. Não incluir dados sensíveis (tokens, secrets, credenciais) em docs, patches ou mensagens.
2. Ao propor trechos de código, a IA deve:
   - reutilizar padrões já presentes (ex.: chaves esperadas pelo front, uso de `TenantModel` quando o dado é do tenant),
   - e citar evidências existentes quando possível.
3. Ao identificar violação arquitetural ou risco:
   - referenciar explicitamente o arquivo/trecho do código onde foi observado.
4. Não “inventar” comportamentos ausentes:
   - se algo não existir (ex.: Global Scope de tenant), marcar como **Não identificado no código**.

## Checklist para novas features

1. A feature é “tenant” (dados isolados por cliente)?
   - Se sim: garantir `Tenant` middleware e/ou `TenantModel`.
2. A feature é “web” ou “api”?
   - Se web: respeitar CSRF e MFA quando aplicável.
   - Se api: respeitar padrões de middleware existentes em `routes/api.php`.
3. A feature troca dados com front (HTML/JS)?
   - Garantir contrato do JSON esperado (quando houver DataTables/exports).
4. A feature usa SQL/relatórios?
   - Verificar se campos/joins/DB::raw já seguem o padrão usado no controller/return atual.
5. A feature envolve integrações externas (cURL/RabbitMQ/Providers)?
   - Manter logs/strings e contratos já usados (quando existirem), sem suposições.

## Proibições

1. Proibido adicionar acesso a dados de tenant sem que esteja claro no código como a connection `tenant` é estabelecida (via `Tenant` middleware e/ou `TenantModel`).
2. Proibido remover/ignorar o contrato do front quando a rota é consumida por DataTables/JS.
3. Proibido introduzir dependência implícita de `request()` dentro de serviços sem evidência de que isso já é aceito no repositório.

**Não identificado no código**: políticas explícitas de “sempre” usar DI (injection) vs `new`/`app()`.

## Violações encontradas (referência)

Baseadas em `docs/architecture/violations.md`:

1. Controllers com lógica de negócio + persistência/transação + efeitos/integracão externas (ex.: `RespostaController`, `WebhookController`).
2. Queries complexas e `DB::raw`/SQL inline no controller/helper de relatório (ex.: `ReportsHelper`, `RelatorioWhatsController`).
3. Services acoplados ao contexto HTTP:
   - `CheckFlowService` usa `request()->route('token_whatsapp')`.
4. Alto acoplamento entre Services e Controllers:
   - `CheckFlowService` instanciando/selecionando controllers e chamando métodos.
   - Services instanciando `FuncoesController` diretamente.

## Riscos arquiteturais (derivados do que foi encontrado)

1. Risco de multi-tenancy incorreto:
   - caso uma rota não use `Tenant` middleware ou uma query use model/connection incorreta.
2. Risco de manutenção em relatórios:
   - por uso extensivo de SQL inline/`DB::raw` em helpers/controllers.
3. Risco de acoplamento e regressão:
   - por services chamando controllers e dependendo de contexto HTTP (`request()`).
4. Risco de compatibilidade com front:
   - caso o contrato JSON de relatórios/exports seja alterado.

## Padrões existentes (observados)

1. Multi-tenancy:
   - `Tenant` middleware + `Cliente::connect()` + `TenantModel` com `protected $connection = 'tenant'`.
2. Controle de permissões/queues:
   - `app/Traits/OmniRolesPermissions.php` define `getAllowedQueues()` usado em relatórios.
3. Relatórios via DataTables serverSide:
   - front `initrelatorio.js` consome `responseJSON.data` e `recordsTotal`.
4. Whitelist CSRF:
   - `VerifyCsrfToken::$except` para rotas de webhook e algumas rotas públicas internas.
5. RabbitMQ particionado por cliente:
   - `app/Repositories/RabbitMQ/MessageRepository.php` usa `cliente_id` para postfix de exchange/routing_key/queue.