# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. --- ## Stack obrigatória > Esta stack é fixa para todos os projetos de site institucional. Não trocar sem decisão de equipe. | Tecnologia | Função | Versão | |---|---|---| | Laravel | Framework PHP full-stack | ^11.x | | Inertia.js | Bridge Laravel ↔ React (sem API REST) | ^2.x | | React | Front-end (renderizado via Inertia) | ^19.x | | TypeScript | Tipagem no front-end | ^5.x | | Tailwind CSS | Estilização | ^4.x | | shadcn/ui | Componentes UI base | latest | | Vite | Build do front-end | ^6.x | | Filament | Painel admin / CMS | ^3.x | | MySQL | Banco de dados | 8.x | | Pest | Testes PHP | ^3.x | | Vitest | Testes front-end | ^2.x | | Laravel Sail | Ambiente local (Docker) | latest | --- ## Pré-requisitos | Ferramenta | Versão mínima | |---|---| | PHP | 8.2+ | | Composer | 2.x | | Node.js | 20+ | | npm | 10+ | | Git | 2+ | | Laravel CLI | latest | Verificar instalação: ```bash php --version # deve mostrar 8.2+ composer --version node --version # deve mostrar v20+ git --version ``` --- ## Comandos comuns ```bash # Ambiente local (Docker via Sail) ./vendor/bin/sail up ./vendor/bin/sail down # Front-end npm run dev # dev server (Vite) npm run build # build de produção # Laravel php artisan migrate php artisan db:seed php artisan storage:link php artisan queue:work php artisan schedule:run # Cache (produção) php artisan config:cache && php artisan route:cache && php artisan view:cache # Testes ./vendor/bin/pest # todos os testes PHP ./vendor/bin/pest --filter NomeDoTeste # teste específico npx vitest # testes front-end npx vitest run # testes front-end (sem watch) ``` --- ## Estrutura de pastas ``` meu-projeto/ ├── app/ │ ├── Http/Controllers/ # Controllers por feature │ ├── Http/Middleware/ │ ├── Models/ # Eloquent models │ ├── Services/ # Regras de negócio │ └── Filament/ # Resources do painel admin ├── resources/ │ ├── js/ # Front-end React + Inertia │ │ ├── Components/ # Componentes reutilizáveis │ │ ├── Layouts/ # Layouts da aplicação │ │ ├── Pages/ # Páginas Inertia (= rotas) │ │ │ ├── Home.tsx │ │ │ ├── About.tsx │ │ │ ├── Contact.tsx │ │ │ └── Blog/ # Variável — se tiver blog │ │ └── types/ # Types TypeScript │ └── views/ # Apenas app.blade.php (root do Inertia) ├── database/ │ ├── migrations/ │ └── seeders/ ├── routes/ │ ├── web.php # Rotas públicas │ └── admin.php # Rotas do painel admin ├── storage/app/public/ # Uploads (symlink para public/) ├── tests/ ├── .env.example └── docker-compose.yml # Laravel Sail ``` --- ## Arquitetura - **Sem API REST**: o Inertia.js faz a bridge entre Laravel e React. Não criar endpoints JSON separados — usar `Inertia::render()` nos controllers. - **Roteamento**: definido em `routes/web.php`, cada rota aponta para um controller que retorna `Inertia::render('NomeDaPagina', $props)`. A página correspondente fica em `resources/js/Pages/NomeDaPagina.tsx`. - **Painel admin**: gerenciado pelo Filament em rota separada (`routes/admin.php`). Não reimplementar autenticação, paginação, busca ou upload — o Filament já provê. - **Formulário de contato**: rate limiting (máx 3 envios/IP/hora) + honeypot + salvar em `contact_messages` + enviar email via Laravel Mail (Mailable). Template em `resources/views/emails/`. - **SEO**: usar `spatie/laravel-sitemap` para sitemap automático gerado via job agendado. Meta tags Open Graph e Twitter Card em todas as páginas via SEO component React. - **Slugs**: usar `spatie/laravel-sluggable`. - **Queue**: driver `database`. Workers gerenciados pelo Supervisor no servidor. --- ## Banco de dados ### Migrations fixas (sempre presentes) - `users` — autenticação do painel admin (Filament) - `pages` — páginas gerenciadas pelo CMS (`slug`, `title`, `content`, `meta`) - `settings` — configurações globais (nome da empresa, telefone, email, redes sociais) - `contact_messages` — mensagens do formulário de contato ### Migrations deste projeto (OmniCo) - `press_clippings` — campos: `id`, `title`, `vehicle_name`, `url`, `published_at`, `created_at` - `testimonials` — campos: a definir > Nunca criar tabelas não listadas acima sem justificativa de negócio. --- ## Filament CMS — Resources ### Fixos (sempre criar) - `PageResource` — gerenciar páginas do site - `SettingResource` — configurações globais da empresa - `ContactMessageResource` — visualizar mensagens do formulário - `UserResource` — gerenciar usuários do painel ### Deste projeto (OmniCo) - `PressClippingResource` — cadastrar notícias externas (título, veículo, URL) - `TestimonialResource` — a definir --- ## Páginas do site (OmniCo) | Página | Arquivo | Observação | |---|---|---| | Home | `Home.tsx` | Exibe as 3 notícias mais recentes de Imprensa | | Quem Somos | `About.tsx` | | | Governança | `Governance.tsx` | | | Relações com Investidores | `Investors.tsx` | | | Sustentabilidade | `Sustainability.tsx` | | | Carreiras | `Careers.tsx` | | | Imprensa | `Press/Index.tsx` | Clipping: lista de notícias externas clicáveis | | Contato | `Contact.tsx` | | | 404 | `NotFound.tsx` | | **Comportamento da página Imprensa:** lista de notícias cadastradas no CMS; ao clicar, redireciona para a URL externa da matéria. **Destaque na Home:** as 3 notícias mais recentes de `press_clippings` aparecem automaticamente, com link externo. --- ## Identidade visual - **Cores e tipografia**: extrair do Figma via MCP antes de iniciar o front-end. Configurar no Tailwind CSS como tokens. - **Referência visual**: usar o design da Home como referência para implementar as demais páginas a partir dos wireframes de baixa fidelidade. --- ## CI/CD e branches - **Branch `homolog`** → deploy automático via GitHub Actions + FTP para o ambiente de homologação. - **Branch `master`** → produção. **Push direto bloqueado** — aceita apenas Pull Requests revisados. - **Fluxo**: commitar em `homolog` → validar → abrir PR para `master` → deploy em produção. - Sempre fazer `git pull` da `master` antes de iniciar qualquer alteração. - **Pipeline**: lint → testes → build assets → deploy via FTP. - **Secrets no GitHub**: `FTP_HOST`, `FTP_USER`, `FTP_PASSWORD`, `FTP_PORT` (produção e homologação). - O `.env` de produção **nunca vai para o repositório** — gerenciar diretamente no servidor. --- ## Variáveis de ambiente relevantes | Variável | Descrição | |---|---| | `APP_NAME` | Nome do projeto | | `APP_URL` | URL pública do site (a definir após setup do servidor de homologação) | | `APP_KEY` | Gerada via `php artisan key:generate` | | `DB_HOST` / `DB_DATABASE` / `DB_USERNAME` / `DB_PASSWORD` | Credenciais MySQL | | `MAIL_MAILER` | `smtp` (fixo) | | `MAIL_FROM_ADDRESS` | Email remetente | | `FILAMENT_PATH` | Caminho do painel admin | | `QUEUE_CONNECTION` | `database` (fixo) | > Todas as configurações de ambiente serão fornecidas manualmente via `.env` — não assumir valores de produção. --- ## Checklist de go-live - [ ] SSL ativo com renovação automática - [ ] Redirect HTTP → HTTPS configurado - [ ] `APP_ENV=production` e `APP_DEBUG=false` - [ ] `php artisan config:cache && route:cache && view:cache` rodados - [ ] Queue workers rodando via Supervisor - [ ] Cron do Laravel Scheduler configurado - [ ] Sitemap gerado e acessível em `/sitemap.xml` - [ ] `robots.txt` correto (não bloqueando indexação) - [ ] Google Search Console verificado - [ ] Meta tags revisadas em todas as páginas - [ ] Score PageSpeed Insights > 85 em mobile --- ## Repositório - **GitHub**: `https://github.com/neotix/OmniCo-Site.git` - **Ambiente atual**: homologação (sem domínio de produção definido ainda)