96 lines
8.8 KiB
Markdown
Executable File
96 lines
8.8 KiB
Markdown
Executable File
# 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.
|