# ABC da Construção W3 Sul — Backend (Laravel 11 + FilamentPHP)

Backend + CMS da Fase 2. API REST consumida pelo Next.js (frontend em `../frontend`) e painel Filament para o cliente ABC editar todo o conteúdo do site.

## Stack

- **Laravel 11** (PHP 8.3+) — API REST
- **FilamentPHP v3** — CMS administrativo em `/admin`
- **Laravel Sanctum** — autenticação do painel
- **MySQL 8** — banco principal com FULLTEXT em produtos e posts
- **Redis** — cache das rotas públicas, sessões e filas
- **Spatie** — medialibrary, permission, activitylog, sluggable, query-builder
- **Sentry** — observabilidade em produção (opcional)

## Setup local

```bash
# 1. Dependências PHP
composer install

# 2. Ambiente
cp .env.example .env
php artisan key:generate

# 3. Banco de dados (MySQL 8 rodando)
mysql -u root -p -e "CREATE DATABASE abc_construcao CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p -e "CREATE USER 'abc_user'@'localhost' IDENTIFIED BY 'senha_local'; GRANT ALL ON abc_construcao.* TO 'abc_user'@'localhost';"

# Ajuste DB_PASSWORD no .env

# 4. Migrations + seed
php artisan migrate --seed

# 5. Storage
php artisan storage:link

# 6. Filament — criar usuário inicial caso o seeder não tenha rodado
php artisan make:filament-user

# 7. Servidor local
php artisan serve                    # http://localhost:8000
# Painel: http://localhost:8000/admin
# API:    http://localhost:8000/api/v1/*
```

## Credenciais padrão (dev)

Após o seed:
- **E-mail:** `atendimento@hoogli.marketing`
- **Senha:** `abc-change-me-2026` (troque imediatamente em produção)

## O que o CMS permite editar

| Seção | Recurso Filament |
|-------|------------------|
| Textos, banners e blocos de cada página | **Páginas** + **Blocos da Página** |
| Produtos (nome, preço, SKU, fotos, ficha técnica) | **Produtos** |
| Categorias e departamentos | **Categorias**, **Departamentos** |
| Marcas parceiras (logos na home) | **Marcas** |
| Hero carrossel da home | **Banners** |
| Depoimentos de clientes | **Depoimentos** |
| Linha do tempo da página Sobre | **Linha do Tempo** |
| Perguntas frequentes | **FAQ** |
| Posts do blog | **Blog** |
| Leads capturados (formulários) | **Leads** |
| Logo, cores, telefones, e-mail, endereço, redes | **Configurações do Site** |
| Meta tags (SEO) de cada página fixa | **SEO por Página** |

Todo conteúdo hoje hardcoded no preview HTML aprovado deve ser migrado para o CMS via seed inicial. Nada de texto ou imagem deve ficar cravado no frontend Next.

## API pública (v1)

Todas GET cacheadas no Redis (5-30 min conforme a rota).

```
GET  /api/v1/settings                              # configurações públicas agrupadas
GET  /api/v1/departments                           # lista
GET  /api/v1/departments/{slug}                    # detalhe com categorias
GET  /api/v1/products?department=&brand=&q=        # lista com filtros e paginação
GET  /api/v1/products/featured                     # vitrine da home
GET  /api/v1/products/{slug}                       # detalhe
GET  /api/v1/brands                                # marcas ativas
GET  /api/v1/banners?position=hero|mid|department  # carrosséis
GET  /api/v1/pages/{slug}                          # página com blocos
GET  /api/v1/posts?category=                       # blog
GET  /api/v1/posts/{slug}                          # post
GET  /api/v1/testimonials?featured=1               # depoimentos
GET  /api/v1/faqs?category=                        # FAQ
POST /api/v1/leads                                 # submete lead (retorna whatsapp_url)
GET  /api/v1/health                                # status
```

### POST /api/v1/leads — payload esperado

```json
{
  "name": "Igor Lima",
  "email": "igor@exemplo.com",
  "phone": "(61) 9 9999-9999",
  "type": "contact",
  "source": "home | produto | contato",
  "product_sku": "POR-BROADWAY-LIME-9090",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "porcelanato-brasilia",
  "consent_lgpd": true,
  "hp_field": ""
}
```

Resposta:
```json
{
  "ok": true,
  "lead_id": 42,
  "whatsapp_url": "https://wa.me/556186257584?text=..."
}
```

O frontend deve **redirecionar o usuário para `whatsapp_url` em nova aba** assim que receber a resposta. Nunca mostrar tela de sucesso (regra fixa do cliente).

## Ambiente mobile-first

O backend não cuida do layout — mas expõe todas as URLs de imagem em duas variantes quando aplicável (`image_path` + `mobile_image_path` nos banners, por exemplo), e os endpoints são leves o suficiente para não bloquear LCP no mobile. Cache de 5+ minutos por rota ajuda a manter TTFB baixo mesmo em conexões ruins.

## Estrutura de arquivos relevantes

```
app/
├── Filament/Resources/         # 14 Resources do CMS
│   ├── ProductResource.php
│   ├── PageResource.php        (+ BlocksRelationManager)
│   ├── LeadResource.php
│   └── ...
├── Http/Controllers/Api/       # 9 controllers públicos
├── Http/Requests/
│   └── StoreLeadRequest.php
├── Http/Resources/             # JSON Resources (Product, Page, etc.)
├── Models/                     # 14 Eloquent models
└── Notifications/
    └── NewLeadReceived.php

database/
├── migrations/                 # 21 migrations
└── seeders/                    # 13 seeders (DatabaseSeeder orquestra)

routes/
└── api.php                     # rotas v1 organizadas por middleware
```

## Comandos úteis

```bash
php artisan migrate:fresh --seed         # reseta tudo (DEV apenas)
php artisan cache:clear                  # limpa cache Redis
php artisan queue:work                   # processa filas (notificações de lead)
php artisan horizon                      # dashboard de filas (prod)
./vendor/bin/pint                        # formata código
./vendor/bin/phpstan analyse             # static analysis
```

## Próximas fases

- **Fase 3:** Frontend Next.js mobile-first consumindo esta API
- **Fase 4:** Integrações (GA4, Meta Pixel, cookie banner, schema.org)
- **Fase 5:** QA, SEO técnico, acessibilidade, Lighthouse
- **Fase 6:** Deploy (Vercel + Laravel Forge) + treinamento do cliente
