# Padrões de Código e Diretrizes

## Nomenclatura (PSR-1/PSR-12)
- **Classes**: PascalCase (`UserController`)
- **Métodos**: camelCase (`getUserById`)
- **Variáveis**: camelCase (`userData`)
- **Constantes**: UPPER_SNAKE_CASE (`MAX_ATTEMPTS`)
- **Tabelas DB**: snake_case, com prefixo do nome da tabela nos campos (ex: tabela `bus` -> campos `bus_id`, `bus_name`).

## Uso de Instruções Deprecated (Obsoletas)
1. **Proibição**: É estritamente PROIBIDO o uso de funções, métodos ou bibliotecas marcadas como *deprecated* nas versões atuais do PHP (8.1+) ou de dependências do sistema.
2. **Atualização Pró-ativa**: Ao encontrar avisos de obsolescência (ex: `curl_close()` em PHP 8.0+ para objetos `CurlHandle`), a IA deve substituir a instrução pela alternativa recomendada imediatamente.
3. **Compatibilidade**: Sempre garanta que a substituição mantenha a funcionalidade e a segurança, tratando retornos de tipos conforme as novas especificações da linguagem (ex: *type casting* em retornos ambíguos).

## Compatibilidade Cross-Platform
1. **Agnosticismo de S.O.**: O código DEVE rodar em Windows e Linux sem modificações.
2. **Caminhos de Arquivo**: Use sempre a constante `DIRECTORY_SEPARATOR` ou a barra normal `/` (que o PHP entende em ambos os sistemas). Nunca use `\` hardcoded.
3. **Comandos de Sistema**: Evite `exec()`, `system()`, `passthru()` com comandos específicos de shell (ex: `rm`, `ls`, `grep`). Use funções nativas do PHP (`unlink`, `scandir`, etc.).
4. **Symlinks**: Não dependa de symlinks. O sistema utiliza rotas de aplicação para servir arquivos.

## Banco de Dados e Multiempresa
1. **Prefixo de Campos**: OBRIGATÓRIO. Todo campo deve ter o prefixo da tabela.
   - Ex: Tabela `users` -> `users_id`, `users_name`, `users_email`.
2. **Isolamento Multiempresa e Multiusuário**:
   - O SysCMS é um sistema multi-empresas e multi-usuários.
   - Todo registro deve obrigatoriamente ser vinculado aos seus proprietários via campos de controle:
     - `idbus`: Identificador da empresa/business (ex: `subjects_idbus`, `notes_idbus`).
     - `iduser`: Identificador do usuário proprietário (ex: `subjects_iduser`, `notes_iduser`).
   - **Os dados das empresas (companies) não se misturam de forma alguma.**
   - **Todas** as consultas devem filtrar pela empresa (`idbus`) e, quando aplicável, pelo usuário (`iduser`) logado.
   - **Regra de Acesso Global**: Quando `***_idbus` e `***_iduser` (onde `***` é o prefixo da tabela) em alguma tabela do banco de dados forem `0` e `0`, **OU quando estas colunas NÃO existirem na tabela**, significa que este registro é global e está disponível para qualquer módulo, qualquer empresa (company) e qualquer usuário. Esta regra deve ser respeitada em todos os módulos.
3. **Novos Módulos**: A criação de novos módulos deve SEMPRE seguir este critério de isolamento.
4. **Não usar SQL puro**: Use o Eloquent/Query Builder, exceto em casos de performance extrema devidamente documentados.
4. **Imutabilidade de Tabelas Existentes (Novos Módulos)**: Ao criar um novo módulo, a IA é estritamente PROIBIDA de alterar a ESTRUTURA (DDL) de tabelas que já existem no sistema (ex: adicionar colunas em users). O novo módulo deve ser autossuficiente. A inserção, atualização ou remoção de REGISTROS (DML) em tabelas existentes (ex: inserir na tabela modules ou permissions) é PERMITIDA e esperada.
5. **Módulo de Listas Globais (Exceção ao Isolamento)**:
   - O módulo `lists` é uma exceção à regra de isolamento `idbus`/`iduser`.
   - Ele fornece dados globais (Países, Estados, Cidades e Atividades) que são compartilhados por todos os inquilinos (tenants).
   - **Tabelas do Módulo Lists**: `lists_countries`, `lists_states`, `lists_cities`, `lists_activities`.
   - Estas tabelas NÃO possuem campos `idbus` ou `iduser` e são acessíveis globalmente.
   - **Uso Obrigatório**: Novos módulos que necessitem de dados de localização ou ramos de atividade DEVEM utilizar as tabelas globais do módulo `lists` via seus respectivos Modelos (`Modules\Lists\Models`), evitando a criação de tabelas duplicadas ou isoladas para estes fins.
   - **Proibição Alpine.js**: É estritamente PROIBIDO o uso de Alpine.js nos selects que interagem com o módulo `globallists` (ex: select de Estado que carrega select de Cidade). Nestes casos, deve-se utilizar JavaScript puro (Vanilla JS) para realizar as chamadas de API e manipulação do DOM. Isso evita conflitos de reatividade e garante performance.
   - **Manipulação de JSON (API)**: Ao retornar dados destas listas via API, é MANDATÓRIO o uso de `json_encode($data, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR)`. O flag `JSON_UNESCAPED_UNICODE` é essencial para que caracteres acentuados (ex: "São Paulo") sejam legíveis e processados corretamente pelo JavaScript no frontend.
   - **Estrutura de Retorno**: Utilize `->values()->all()` após um `map()` em coleções do Eloquent para garantir que o JSON resultante seja um array indexado (ex: `[...]`) e não um objeto associativo (ex: `{"0": ..., "1": ...}`).
   - **Multi-idioma**: Campos de nome nestas tabelas (ex: `countries_name`, `activities_name`) são do tipo `JSON` e suportam 5 idiomas padrão (`pt_BR`, `en_US`, `es_ES`, `de_DE`, `fr_FR`). O acesso deve ser feito via o accessor `getNameAttribute()` ou propriedade `name` no Eloquent, que gerencia a tradução automática baseada no locale atual.

## Padronização de Componentes ERP
1. **Unidade de Medida (UOM)**:
   - É **OBRIGATÓRIO** o uso de um campo `select` para a "Unidade de Medida" em todos os formulários do ERP (Produtos, Matérias-Primas, Pedidos, etc.).
   - O uso de campo de texto livre (`input type="text"`) para este fim é **PROIBIDO**.
   - **Opções Padrão**: UN, KG, G, MG, L, ML, M, CM, MM, M2, M3, PC, CX, PAC, RO, FR.
   - O valor padrão inicial deve ser sempre `UN` (Unidade).

## Frontend e JavaScript
1. **Preferência por Vanilla JS**: A IA coder deve dar preferência absoluta ao uso de **JavaScript puro (Vanilla JS)** em vez de Alpine.js para todas as interações no frontend. 
2. **Restrição ao Alpine.js**: O uso de Alpine.js deve ser limitado apenas a componentes que exijam alta reatividade ou gerenciamento de estado complexo onde o Vanilla JS resultaria em código excessivamente verboso ou difícil de manter.
3. **Módulo de Listas Globais**: É **expressamente proibido** o uso de Alpine.js em seletores que interagem com o módulo `globallists` (ex: País/Estado/Cidade). Nestes casos, o uso de Vanilla JS é mandatório para garantir performance e evitar conflitos.
4. **DataTables.js**:
   - Use sempre a **Versão COMPLETA** (baseada em jQuery) integrada ao sistema.
   - O uso de `simple-datatables` é **PROIBIDO**.
   - A inicialização deve ser feita no `{% block scripts %}` do template Twig.
   - Configure sempre a tradução (`language`) utilizando a URL do CDN oficial ou arquivo local, priorizando o idioma do sistema.
   - Garanta a responsividade habilitando a opção `responsive: true`.

## Segurança
1. **Validação**: Obrigatória em todos os inputs.
2. **CSRF**: Obrigatório em formulários `POST`.
3. **Captcha**: Obrigatório em formulários públicos.
4. **Permissões**: Verificar permissões antes de qualquer ação (`can()`, middlewares).

## Uploads e Arquivos
1. **Localização Física**: Sempre em `storage/uploads/{modulo}/`.
2. **Proibição**: É terminantemente PROIBIDO gravar arquivos diretamente em `public/`.
3. **Acesso Web**: Use sempre o helper `url()` com o caminho completo (ex: `url('storage/uploads/modulo/arquivo.jpg')`).
61→4. **Processamento**: Imagens devem ser processadas pelo Intervention Image (formatar e comprimir conforme `.env`).
62→5. **Permissões**: Não criar pastas fora de `storage`.

## Logs
- Todos os logs devem ser gravados em `/logs`.
- Usar Monolog para estruturar logs.

## Editor de Texto Rico (Quill)
Usar Quill apenas para:
- Conteúdo extenso (artigos, posts).
- Necessidade de formatação (HTML).
- **Não usar** para campos simples (títulos, nomes).
- Container deve ter ID `#quill-editor` ou classe `.quill-editor`.

## Comentários e Documentação Técnica
1. **Formato**: OBRIGATÓRIO o uso de PHPDoc (`/** ... */`) para classes, métodos, propriedades e cabeçalhos de arquivo.
2. **Idioma**: OBRIGATÓRIO escrever todos os comentários técnicos em **Inglês**.
   - Exceção: Strings literais exibidas ao usuário final (mensagens de erro, labels, etc.) devem permanecer no idioma original (Português/Multi-idioma).
3. **Escopo**:
   - Cabeçalhos de arquivo devem conter informações de copyright e licença em inglês.
   - Métodos devem descrever parâmetros (`@param`), retornos (`@return`) e exceções (`@throws`).
4. **Lógica**: A tradução de comentários NÃO deve alterar nomes de variáveis, funções ou lógica do sistema.