# RULES — Projeto Laravel + MySQL ## Contexto do projeto Este projeto utiliza: - Backend: Laravel - Banco de dados: MySQL - Frontend: React + Inertia - Objetivo: manter código limpo, previsível, seguro, performático e fácil de evoluir O agente deve sempre seguir estas regras ao gerar código, migrations, models, queries, services e qualquer lógica que envolva banco de dados. --- ## 1. Princípios gerais 1. Sempre priorizar: - clareza - consistência - segurança - performance - manutenibilidade 2. Nunca gerar soluções “rápidas” que prejudiquem a arquitetura do projeto. 3. Toda alteração de estrutura de banco deve ser feita via migration. - Nunca sugerir alteração manual diretamente no banco como solução final. - Comandos SQL diretos só podem ser usados para diagnóstico ou scripts controlados. 4. Toda regra de negócio importante deve ficar no backend. - O banco deve refletir integridade dos dados. - O frontend não deve ser a única camada de validação. --- ## 2. Convenções de banco de dados 1. Usar MySQL como banco principal. 2. Charset padrão: - `utf8mb4` 3. Collation padrão: - preferir `utf8mb4_unicode_ci` - se o projeto estiver padronizado em MySQL 8, pode usar `utf8mb4_0900_ai_ci` 4. Tabelas devem usar: - nomes em `snake_case` - plural - exemplo: `users`, `customer_orders`, `invoice_items` 5. Colunas devem usar: - `snake_case` - nomes claros e sem abreviações desnecessárias 6. Chaves primárias: - usar `id` como chave primária padrão - preferir `bigint unsigned` / `bigIncrements` 7. Chaves estrangeiras: - nome no formato `{entidade_singular}_id` - exemplos: - `user_id` - `company_id` - `order_id` 8. Campos booleanos devem começar com: - `is_` - `has_` - exemplos: - `is_active` - `is_default` - `has_children` 9. Campos de data devem ser explícitos: - `created_at` - `updated_at` - `deleted_at` - `approved_at` - `expires_at` 10. Campos monetários: - nunca usar `float` ou `double` - sempre usar `decimal(10,2)` ou superior conforme a necessidade 11. Campos percentuais: - usar `decimal`, nunca `float` 12. Campos de texto: - `string` para textos curtos - `text` para conteúdos médios/longos - evitar `longText` sem necessidade 13. Campos JSON: - usar apenas quando os dados forem realmente semiestruturados - nunca usar JSON para substituir relações que deveriam ser normalizadas --- ## 3. Migrations 1. Toda nova tabela deve conter, salvo exceções justificadas: - `id` - `created_at` - `updated_at` 2. Usar `softDeletes()` apenas quando fizer sentido de negócio. - Não ativar soft delete por padrão sem necessidade real. 3. Toda foreign key deve ser declarada explicitamente. 4. Toda foreign key relevante deve ter índice. 5. Toda coluna usada com frequência em filtros, joins, ordenações ou busca deve ser indexada. 6. Antes de criar uma migration, o agente deve pensar: - essa coluna realmente precisa existir? - esse dado pertence a esta tabela? - isso deveria ser uma relação? - esse campo precisa de índice? - o delete deve ser `cascade`, `restrict` ou `set null`? 7. Nunca usar `cascadeOnDelete()` sem avaliar impacto. - O padrão deve ser conservador. - Se houver risco de apagar dados importantes, preferir `restrictOnDelete()` ou `nullOnDelete()`. 8. Se a tabela representar domínio central do sistema, evitar exclusão física automática. --- ## 4. Modelagem de dados 1. Priorizar modelagem relacional correta. 2. Evitar duplicação desnecessária de dados. 3. Normalizar até um nível saudável. - Não hiper-normalizar sem ganho real. - Não desnormalizar sem justificativa de performance ou negócio. 4. Quando houver listas dinâmicas de opções, preferir tabelas auxiliares em vez de `enum`. 5. Só usar `enum` quando os valores forem extremamente estáveis e controlados. 6. Sempre considerar integridade referencial. 7. Nunca criar relações implícitas sem foreign key quando houver controle do schema. 8. Se houver multi-tenant, toda tabela dependente deve refletir claramente o vínculo do tenant: - `company_id` - `tenant_id` - `organization_id` conforme o padrão do projeto --- ## 5. Regras para queries 1. Nunca usar `SELECT *` em código de produção. - Selecionar apenas as colunas necessárias. 2. Sempre evitar N+1 queries. - Em Eloquent, usar `with()` quando necessário. - Não carregar relações em loop sem necessidade. 3. Queries devem ser legíveis e previsíveis. 4. Sempre preferir: - Eloquent para regras de domínio simples - Query Builder para consultas intermediárias - SQL bruto apenas quando realmente necessário 5. Toda query de listagem deve considerar: - paginação - filtros - ordenação controlada - índices compatíveis 6. Nunca montar SQL concatenando input do usuário. - Sempre usar binding, Query Builder ou Eloquent. 7. Em consultas pesadas: - reduzir colunas retornadas - revisar joins - revisar índices - evitar subqueries desnecessárias - evitar consultas dentro de loops 8. Ao gerar queries, o agente deve pensar em: - volume de dados - custo do join - uso de índice - possibilidade de paginação - impacto em produção --- ## 6. Índices 1. Criar índices para: - foreign keys - colunas de filtro frequente - colunas de ordenação frequente - colunas usadas em busca exata - colunas usadas em chaves únicas 2. Não criar índices excessivos sem critério. - Índices também custam escrita e manutenção. 3. Índices compostos devem seguir a ordem de uso mais comum na query. 4. Para tabelas grandes, o agente deve considerar: - índices compostos - cardinalidade - frequência de leitura vs escrita 5. Sempre que criar: - `unique` - `foreign key` - coluna de busca frequente o agente deve avaliar se precisa de índice explícito ou se já foi coberto. --- ## 7. Integridade e consistência 1. Toda operação crítica com múltiplos writes deve usar transaction. - Exemplo: - criar pedido + itens - registrar pagamento + atualizar status - criar usuário + perfil + permissões 2. Nunca deixar o banco em estado parcial se a operação for atômica. 3. O agente deve usar: - `DB::transaction()` para operações multi-etapas 4. Validações devem existir em dois níveis quando aplicável: - validação da aplicação - restrições do banco 5. Sempre usar: - `unique` - `nullable` - `default` - foreign key de forma coerente com a regra de negócio --- ## 8. Datas, horários e fuso 1. Armazenar datas em UTC sempre que possível. 2. Converter para timezone do usuário apenas na camada de aplicação/apresentação. 3. Não misturar lógica de timezone diretamente no banco sem necessidade forte. 4. Campos de auditoria temporal devem ser explícitos: - `processed_at` - `sent_at` - `paid_at` - `canceled_at` --- ## 9. Exclusão de dados 1. O agente nunca deve apagar dados críticos sem considerar auditoria e rastreabilidade. 2. Para entidades de negócio relevantes, avaliar: - soft delete - status de inativação - arquivamento lógico 3. Hard delete só deve ser sugerido quando: - for dado temporário - for tabela técnica - não houver impacto histórico ou legal --- ## 10. Segurança 1. Nunca confiar em input do usuário. 2. Nunca gerar queries vulneráveis a SQL Injection. 3. Nunca expor dados sensíveis desnecessariamente. 4. Nunca retornar colunas confidenciais em listagens ou APIs. - exemplos: - senha - tokens - segredos - documentos sensíveis - dados financeiros sem necessidade 5. O agente deve respeitar LGPD e minimização de dados quando aplicável. --- ## 11. Laravel + Eloquent 1. Models devem representar o domínio com clareza. 2. Definir corretamente: - `$fillable` ou `$guarded` - casts - relationships - scopes quando fizer sentido 3. Evitar colocar regra de negócio complexa diretamente em controllers. - Preferir: - services - actions - domain classes - jobs - policies conforme a arquitetura do projeto 4. O agente deve preferir: - `FormRequest` para validação - `Policies` para autorização - `Resources` quando houver retorno estruturado - `Scopes` para filtros recorrentes 5. Não usar model “gorda” com lógica excessiva e desorganizada. --- ## 12. Performance 1. O agente deve sempre considerar performance antes de propor: - loops com queries internas - joins desnecessários - eager loading exagerado - consultas sem índice - ordenações pesadas - filtros com `%texto%` em tabelas grandes sem estratégia 2. Para grandes volumes, considerar: - paginação - chunking - cursor - jobs assíncronos - cache - materialização controlada 3. Não otimizar prematuramente, mas também não ignorar escalabilidade óbvia. --- ## 13. Seeders e dados iniciais 1. Dados essenciais do sistema devem ser inseridos via seeder. 2. Seeders devem ser idempotentes quando possível. 3. Nunca depender de inserção manual em produção para regras básicas do sistema. 4. Listas controladas e estáveis devem ser semeadas: - perfis - permissões - status base - categorias fixas - configurações iniciais --- ## 14. Logs e auditoria 1. Operações sensíveis devem poder ser rastreadas. 2. O agente deve considerar auditoria para: - alteração de status - exclusões - aprovações - pagamentos - permissões - dados críticos 3. Sempre que necessário, registrar: - quem fez - quando fez - o que mudou --- ## 15. Padrão de resposta do agente ao criar banco ou query Sempre que o agente propuser: - nova tabela - alteração de schema - índice - relacionamento - query relevante ele deve explicar objetivamente: 1. objetivo da alteração 2. impacto no banco 3. por que o tipo de dado foi escolhido 4. por que o índice foi criado ou não 5. riscos ou pontos de atenção --- ## 16. O que o agente deve evitar O agente nunca deve: - usar `float` para dinheiro - usar JSON no lugar de relacionamento relacional sem justificativa - usar `SELECT *` - criar queries vulneráveis - ignorar índices em tabelas grandes - usar cascade delete automaticamente - criar migration sem pensar em rollback - duplicar dados sem motivo - colocar regra de negócio crítica apenas no frontend - sugerir alteração manual no banco como padrão de trabalho - criar nomes confusos de tabelas e colunas - gerar código sem considerar integridade referencial --- ## 17. Checklist obrigatório antes de entregar qualquer solução com MySQL Antes de responder, o agente deve validar: - a modelagem está coerente? - os nomes estão padronizados? - os tipos de dados estão corretos? - campos monetários usam decimal? - datas estão corretas? - há foreign keys adequadas? - os índices necessários foram considerados? - a query evita N+1? - há risco de SQL Injection? - precisa de transaction? - precisa de soft delete? - precisa de unique? - precisa de auditoria? - a solução escala razoavelmente? --- ## 18. Regra de prioridade Quando houver conflito entre velocidade e qualidade: 1. priorizar integridade dos dados 2. priorizar segurança 3. priorizar clareza 4. priorizar performance 5. só então priorizar rapidez de implementação --- ## 19. Saída esperada do agente Ao gerar código relacionado ao banco, o agente deve preferir entregar: - migration completa - model ajustado - relacionamentos necessários - validações principais - índices importantes - explicação curta e objetiva da decisão técnica Não entregar apenas trechos soltos se for possível entregar a estrutura completa de forma consistente. ################### # RULES — Frontend, Layout e CSS ## Stack oficial de interface Este projeto utiliza: - React - Inertia.js - Tailwind CSS - shadcn/ui O agente deve seguir estas regras ao gerar páginas, layouts, componentes, formulários e estilos. --- ## 1. Princípios de UI 1. Toda interface deve priorizar: - clareza - consistência - responsividade - acessibilidade - legibilidade - reutilização 2. O agente não deve criar interfaces visualmente poluídas. 3. O agente deve preferir layouts limpos, modernos e escaláveis. 4. O design deve parecer produto real, não protótipo improvisado. --- ## 2. Regra principal de CSS 1. O projeto deve usar **Tailwind CSS como padrão principal de estilização**. 2. O agente deve evitar CSS solto e desorganizado. 3. O agente deve evitar criar arquivos CSS personalizados sem necessidade real. 4. O agente deve preferir: - classes utilitárias do Tailwind - composição de componentes - variantes reutilizáveis 5. Só criar CSS customizado quando: - Tailwind não resolver bem - houver animação muito específica - houver integração com biblioteca externa - houver necessidade real de sobrescrita global 6. Evitar `style={{ ... }}` inline, exceto em casos realmente dinâmicos. --- ## 3. Biblioteca de componentes 1. O agente deve priorizar **shadcn/ui** para componentes base. 2. Não reinventar componentes já existentes no shadcn/ui sem motivo. 3. Sempre que possível, reutilizar: - Button - Input - Select - Dialog - Sheet - Card - Table - Tabs - DropdownMenu - Badge - Alert - Form - Tooltip - Skeleton 4. O agente deve customizar componentes via Tailwind, mantendo consistência visual. 5. Não misturar múltiplas bibliotecas de UI sem necessidade clara. --- ## 4. Organização visual e layout 1. Toda página deve ter hierarquia visual clara: - título - subtítulo ou contexto - ações principais - conteúdo principal - ações secundárias 2. O agente deve estruturar páginas com: - `container` - `max-width` - espaçamento consistente - grid ou flex coerente 3. Sempre pensar no layout em blocos: - header da página - toolbar/filtros - conteúdo - sidebar, quando necessário - footer, se aplicável 4. Evitar interfaces com elementos “soltos” sem alinhamento. 5. Evitar excesso de cards dentro de cards sem necessidade. 6. Evitar grids quebrados ou desalinhados. --- ## 5. Espaçamento e rhythm 1. O agente deve manter escala consistente de espaçamento. 2. Preferir spacing do Tailwind em múltiplos coerentes: - `p-4`, `p-6`, `p-8` - `gap-4`, `gap-6`, `gap-8` - `space-y-4`, `space-y-6` 3. Evitar misturar muitos espaçamentos aleatórios na mesma tela. 4. Toda seção deve respirar visualmente. 5. O agente deve evitar elementos colados nas bordas da tela. --- ## 6. Responsividade 1. Toda interface deve ser responsiva por padrão. 2. O agente deve pensar em: - mobile primeiro - tablet - desktop 3. Ao criar grids, considerar breakpoints do Tailwind: - `grid-cols-1` - `md:grid-cols-2` - `lg:grid-cols-3` - conforme o contexto 4. O agente não deve assumir desktop como único cenário. 5. Tabelas muito largas devem prever: - scroll horizontal - simplificação no mobile - versões condensadas quando necessário 6. Barras laterais e menus devem se adaptar bem em telas menores. --- ## 7. Tipografia 1. A tipografia deve ser simples, clara e consistente. 2. O agente deve construir hierarquia usando: - tamanho - peso - cor - espaçamento 3. Preferir padrões como: - título principal: `text-2xl` a `text-4xl` - subtítulos: `text-lg` a `text-xl` - corpo: `text-sm` ou `text-base` - textos auxiliares: `text-muted-foreground` 4. Evitar muitos tamanhos diferentes na mesma tela. 5. Evitar textos com contraste ruim. 6. Evitar blocos muito densos sem respiro. --- ## 8. Cores e tema 1. O agente deve seguir o tema visual do projeto. 2. Não usar cores aleatórias por componente. 3. O agente deve preferir tokens semânticos: - `background` - `foreground` - `primary` - `secondary` - `muted` - `accent` - `destructive` - `border` - `input` - `ring` 4. Sempre usar a paleta definida no projeto. 5. Cores devem comunicar função, não decoração exagerada. 6. Verde, vermelho, amarelo e azul devem ser usados com significado consistente. --- ## 9. Componentização 1. O agente deve quebrar a interface em componentes reutilizáveis. 2. Não criar páginas gigantes com muito JSX embutido. 3. Extrair componentes quando houver: - repetição - complexidade - bloco visual independente - comportamento reutilizável 4. Componentes devem ter responsabilidade clara. 5. Evitar componente “faz tudo”. 6. Evitar duplicação de markup. --- ## 10. Layout padrão de páginas 1. Toda página Inertia deve preferir uma estrutura consistente. 2. O agente deve usar layouts compartilhados quando apropriado: - layout autenticado - layout público - layout admin - layout de dashboard 3. O agente deve manter consistência entre páginas: - espaçamento - cabeçalhos - breadcrumb - ações - largura máxima - comportamento de formulário 4. Evitar cada página parecer de um sistema diferente. --- ## 11. Formulários 1. Todo formulário deve ser claro e fácil de usar. 2. O agente deve priorizar: - labels visíveis - mensagens de erro claras - feedback de loading - estados disabled quando necessário - validação visual consistente 3. Campos devem ter: - label - placeholder apenas como apoio - mensagem de erro - ajuda contextual quando necessário 4. Não usar placeholder como substituto de label. 5. Botões de ação devem ser claros: - salvar - cancelar - excluir - continuar 6. A ação principal deve ter destaque visual. 7. Em formulários longos, dividir em seções. --- ## 12. Tabelas e listagens 1. Tabelas devem priorizar leitura e ação. 2. O agente deve sempre pensar em: - cabeçalho claro - alinhamento correto - ações por linha - paginação - filtros - estados vazios 3. Dados numéricos devem ter alinhamento coerente. 4. Datas, status e valores devem ter formatação visual consistente. 5. Em tabelas densas, usar: - badges - truncamento controlado - tooltips - colunas realmente necessárias 6. Evitar tabelas com informação excessiva sem hierarquia. --- ## 13. Estados da interface 1. Toda tela deve prever estados de: - carregamento - vazio - erro - sucesso - sem permissão, se aplicável 2. O agente deve usar: - `Skeleton` para loading elegante - mensagens vazias úteis - alertas claros para erro - feedback visual em ações assíncronas 3. Nunca deixar a tela “sem resposta” ao usuário. --- ## 14. Acessibilidade 1. Toda interface deve buscar acessibilidade mínima real. 2. O agente deve: - usar elementos semânticos - garantir foco visível - usar labels corretos - respeitar contraste - usar `aria-*` quando necessário - permitir navegação por teclado 3. Botões e links devem ser distinguíveis. 4. Ícones sozinhos devem ter `aria-label` quando necessário. 5. Não depender apenas de cor para comunicar estado. --- ## 15. Ícones 1. O agente deve usar uma biblioteca consistente, preferencialmente `lucide-react`. 2. Ícones devem apoiar a interface, não competir com ela. 3. Evitar excesso de ícones. 4. Ícones devem ter tamanho e alinhamento consistentes. --- ## 16. Animações e transições 1. O agente deve usar animações com moderação. 2. Transições devem melhorar percepção, não distrair. 3. Preferir: - hover sutil - fade curto - transições suaves - feedback visual de clique e loading 4. Evitar animações exageradas em sistemas administrativos. --- ## 17. Classes utilitárias 1. O agente deve manter classes Tailwind organizadas e legíveis. 2. O agente deve evitar blocos enormes e caóticos de classes sem estrutura. 3. Quando houver repetição de variantes, extrair para: - componente reutilizável - helper - variant pattern 4. Quando fizer sentido, usar `cn()` para composição de classes. 5. Para variantes de componentes, preferir padrão consistente de variantes. --- ## 18. Padrões visuais que o agente deve seguir 1. Bordas suaves 2. Sombras leves 3. Espaçamento generoso 4. Tipografia limpa 5. Contraste equilibrado 6. Destaque claro para ações principais 7. Cards com conteúdo bem organizado 8. Interface com aparência profissional --- ## 19. O que o agente deve evitar no frontend O agente nunca deve: - misturar Tailwind com muito CSS aleatório - usar inline style sem necessidade - criar layout quebrado no mobile - usar cores incoerentes - criar páginas visualmente poluídas - duplicar componentes existentes - deixar formulários sem feedback de erro - deixar loading sem estado visual - usar tipografia inconsistente - criar JSX gigante e desorganizado - usar componentes sem acessibilidade mínima - montar interface sem hierarquia visual --- ## 20. Regra de decisão para UI Quando houver dúvida entre: - algo mais rápido - algo mais consistente o agente deve priorizar: 1. consistência visual 2. experiência do usuário 3. reutilização 4. acessibilidade 5. velocidade de implementação --- ## 21. Saída esperada do agente para frontend Ao gerar telas ou componentes, o agente deve preferir entregar: - componente React completo - estrutura limpa - Tailwind organizado - uso de shadcn/ui quando aplicável - responsividade básica já pronta - estados principais previstos - explicação curta da decisão visual Não entregar apenas markup solto quando for possível entregar o componente completo.