# Coding Standards (Baseado em Código Existente)

Este documento formaliza **o mínimo necessário** para evoluir o sistema com segurança, baseado somente em padrões observados no repositório. Não impõe arquitetura ideal e não exige refatoração do legado.

## 1) Padrões atuais identificados

### 1.1 Controllers são o principal local de orquestração e lógica

Evidências:
- `app/Http/Controllers/Resposta/RespostaController.php` inicia transação e coordena regra + efeito.
- `app/Http/Controllers/Webhook/WebhookController.php` persiste dados e também executa chamada externa (cURL) dentro do controller (`testeWebhook`).
- `app/Http/Controllers/Relatorio/ReportsHelper.php` monta query e formata estrutura de resposta (DataTables).

### 1.2 Queries são feitas dentro de Controllers/Helpers, com uso de `DB::raw` em SQL inline

Evidências:
- `app/Http/Controllers/Relatorio/ReportsHelper.php` usa `DB::raw(...)` extensivamente em selects e joins.

### 1.3 Models existem como Eloquent, com estratégia explícita de conexão

Evidências:
- `app/Models/TenantModel.php` fixa `protected $connection = 'tenant'`.
- `app/Models/MainModel.php` fixa `protected $connection = 'mysql'`.

### 1.4 Multi-tenancy é resolvida por middleware e troca de conexão dinâmica

Evidências:
- `app/Http/Middleware/Tenant.php` identifica o tenant e chama `$user->connect()`.
- `app/Models/Cliente/Cliente.php` `connect()` faz `DB::purge('tenant')`, ajusta `Config::set('database.connections.tenant.*')` e faz `DB::reconnect('tenant')`.

### 1.5 Serviços existem, mas nem sempre estão isolados de contexto HTTP

Evidências:
- `app/Services/Bot/CheckFlowService.php` usa `request()->route('token_whatsapp')` em um service (dependência implícita do contexto HTTP).
- Em `app/Services/Bot/CheckFlowService.php` há acoplamento entre service e controllers via `app($controller)` e dispatch de métodos.
- Em `app/Services/Bot/FileUploadService.php` e `app/Services/Atendimento/FilasServices.php` existe instância de `FuncoesController` dentro de service.

### 1.6 Existe documentação de arquitetura criada na auditoria

Evidência:
- `docs/architecture/*` e `docs/architecture/violations.md` foram gerados com base no código mapeado.

## 2) Inconsistências encontradas

### 2.1 Existência de Services vs. lógica forte nos Controllers

Observação:
- A pasta `app/Services` existe e há classes/handlers por domínio.
- Ao mesmo tempo, controllers incluem regra de negócio, consultas complexas e até integrações externas.

Evidência:
- `WebhooksController` faz persistência + cURL (controller).
- `ReportsHelper` faz SQL inline + formatação (controller/ helper no namespace `Http\Controllers`).

### 2.2 Serviços dependem de contexto HTTP

Observação:
- Em alguns services, o código acessa `request()` global (ou depende de rota) para tomar decisões.

Evidência:
- `app/Services/Bot/CheckFlowService.php` usa `request()->route('token_whatsapp')`.

### 2.3 Mistura de responsabilidades em classes “não-HTTP”

Observação:
- `CheckFlowService` decide controlador/método e chama controllers, o que aproxima camadas.

Evidência:
- `app/Services/Bot/CheckFlowService.php` instancia controller e chama `$controller->$method(...)`.

## 3) Regras obrigatórias (baseadas no que já funciona)

Estas regras não propõem “o padrão ideal”; elas definem o mínimo para evitar regressões.

### 3.1 Regras obrigatórias de multi-tenancy (críticas)

1. Para dados de tenant, usar o que o sistema já usa:
   - modelos que herdam de `app/Models/TenantModel.php` (conexão `tenant` fixa), e/ou
   - rotas que passam pelo middleware `app/Http/Middleware/Tenant.php`.

2. A IA deve respeitar o mecanismo de conexão dinâmica do sistema:
   - se a feature precisa trocar o banco do tenant, seguir o padrão `Cliente::connect()` (purge/reconnect da conexão `tenant`).

3. Não assumir que `client_id`/`tenant_id` existe em toda tabela do schema de tenant:
   - algumas migrations do tenant schema mostram tabelas sem `tenant_id`/`client_id` (ex.: `atendimento`),
   - enquanto outras tabelas incluem `client_id`/`tenant_id` (ex.: `configuracao_email`).

### 3.2 Regras obrigatórias sobre contratos com o front

1. Se a feature for consumida por DataTables serverSide/exports:
   - manter o formato de resposta esperado pelo JS existente (ex.: chaves como `draw`, `recordsTotal`, `data`).

Evidência:
- `public/pages/scripts/relatorioatendimento/initrelatorio.js` consome `responseJSON.data` e `responseJSON.recordsTotal` e usa `draw`.

### 3.3 Regras obrigatórias sobre webhooks e CSRF

1. Não remover/alterar o `VerifyCsrfToken::$except` sem evidência clara.

Evidência:
- `app/Http/Middleware/VerifyCsrfToken.php` lista exceções para rotas de webhook e outras.

## 4) Regras para NOVAS features (incrementais e compatíveis)

### 4.1 Abordagem recomendada (sem invalidar legado)

1. Novas features devem seguir o mesmo “contrato de tenant” já utilizado:
   - usar Tenant middleware quando a rota for do tipo que precisa de isolamento de tenant,
   - usar `TenantModel` para dados do tenant.

2. Ao criar novas rotas que integram com o front:
   - manter o formato JSON esperado pelas partes existentes (ex.: DataTables).

### 4.2 Quando usar Services

1. Services podem ser usados quando já existe padrão na pasta `app/Services` para aquela responsabilidade.
2. Se o Service depender de contexto HTTP (request/rota), declarar explicitamente essa dependência no design (sem “magic”).

Observação:
- O repositório já tem exemplos de service com dependência de request (`CheckFlowService`), então “não é proibido”.

### 4.3 Queries e relatórios

1. Para features que exigem relatórios/queries complexas:
   - seguir o estilo existente (pelo menos até onde for compatível): montagem de SQL com `DB::raw` e retornos no formato esperado.
2. Não migrar tudo para um estilo novo ao mesmo tempo.

## 5) Regras CRÍTICAS de multi-tenancy

Resumo em “check rápido”:

1. Rota do tenant?
   - Passar por `app/Http/Middleware/Tenant.php` (onde aplicável).
2. Dados do tenant?
   - Usar models que fixam conexão `tenant` (`TenantModel`).
3. Conexão tenant dinâmica?
   - Se necessário, usar `Cliente::connect()` (purge/reconnect).
4. `tenant_id` existe em toda tabela?
   - Não assumir; seguir schema real das migrations.

## 6) Anti-patterns encontrados no código (com exemplos reais)

### 6.1 Controllers misturando persistência + integrações externas

Exemplo:
- `app/Http/Controllers/Webhook/WebhookController.php`:
  - `store()` faz persistência de configuração e itera `request->campos`;
  - `testeWebhook()` faz integração externa com `curl_init`, `curl_setopt_array` e execução.

### 6.2 SQL inline/`DB::raw` extenso em controllers/helpers

Exemplo:
- `app/Http/Controllers/Relatorio/ReportsHelper.php` monta selects e joins com `DB::raw(...)`.

### 6.3 Services dependentes de request/rota e acoplamento a controllers

Exemplos:
- `app/Services/Bot/CheckFlowService.php`:
  - usa `request()->route('token_whatsapp')`;
  - instancia controllers e chama métodos dinamicamente.
- `app/Services/Bot/FileUploadService.php` e `app/Services/Atendimento/FilasServices.php`:
  - instanciam `FuncoesController`.