amare/README.md

# Amare Site

Aplicação Laravel 13 para assessoria de eventos (Fase 0 — Fundação).

## Requisitos

- PHP 8.4 com extensões `pdo_pgsql`, `intl`, `mbstring`, `zip`, `sodium` (canônico do `Dockerfile` e do CI; `composer.json` aceita `^8.3`)
- Composer 2.x
- Node.js 22+ e npm
- Docker e Docker Compose

## Setup local

1. Copie o ambiente:

```bash
cp .env.example .env
php artisan key:generate
```

2. Suba o PostgreSQL (requer o `.env` do passo 1 — o serviço `app` referencia esse arquivo via `env_file`, e o Compose valida todo o `docker-compose.yml` mesmo ao subir só o `postgres`):

```bash
docker compose up -d postgres
```

3. Instale dependências e rode migrations:

```bash
composer install
npm install
php artisan migrate
```

4. (Opcional) Seed de desenvolvimento:

```bash
php artisan db:seed
```

5. Servidor de desenvolvimento:

```bash
php artisan serve
npm run dev
```

Painel interno: `/admin`

Healthcheck: `GET /up`

## Paridade local com produção (FrankenPHP via Docker Compose)

Além do fluxo host-side acima, `docker-compose.yml` tem um serviço `app` que builda a mesma imagem FrankenPHP usada em staging/produção (`Dockerfile`), útil para testar o comportamento real do container antes do deploy:

```bash
docker compose up -d        # sobe postgres + app
php artisan migrate         # rode migrations (o entrypoint do container não migra sozinho)
curl localhost:8000/up
```

O serviço `app` depende de `postgres` estar saudável (`depends_on: condition: service_healthy`) e sobrescreve `DB_HOST`/`DB_PORT` do `.env` para apontar para o serviço `postgres` pelo nome (o padrão `127.0.0.1` do `.env` só funciona para processos rodando no host). Não há job de CI dedicado a este smoke — o job `container` do CI já builda e healthcheca a mesma imagem.

## Variáveis principais

| Variável | Valor local |
|---|---|
| `APP_LOCALE` | `pt_BR` |
| `APP_TIMEZONE` | `America/Sao_Paulo` |
| `DB_CONNECTION` | `pgsql` |
| `SESSION_DRIVER` | `database` |
| `CACHE_STORE` | `database` |
| `QUEUE_CONNECTION` | `database` |

## Comandos de qualidade

```bash
composer quality      # Pint + PHPStan + audit (composer + npm) + testes
composer test:unit    # Unit + Architecture
composer test:feature # Feature + Livewire + Filament
composer test:browser # E2E browser
composer test         # Todos os testes
```

## Banco de testes (PostgreSQL)

Feature tests usam PostgreSQL conforme `phpunit.xml` (`DB_DATABASE=amare_test`).

Crie o banco de teste uma vez (com PostgreSQL local via Docker Compose):

```bash
docker exec amare-postgres psql -U amare -d amare -c "CREATE DATABASE amare_test;"
```

## Armazenamento de mídia

Uploads de conteúdo usam o disco `public` em desenvolvimento. Crie o symlink antes de servir arquivos localmente:

```bash
php artisan storage:link
```

Em produção, configure `FILESYSTEM_DISK=r2` (Cloudflare R2). O disco legado `s3` continua suportado se necessário.

## Provedores de produção

Produção usa **Resend** (e-mail transacional) e **Cloudflare R2** (mídia pública via domínio customizado). Local e CI permanecem com defaults seguros (`MAIL_MAILER=log`/`array`, disco `public`).

### Checklist de variáveis (produção)

| Variável | Valor |
|---|---|
| `MAIL_MAILER` | `resend` |
| `RESEND_API_KEY` | API key Resend |
| `MAIL_FROM_ADDRESS` / `MAIL_FROM_NAME` | Remetente verificado no Resend |
| `FILESYSTEM_DISK` | `r2` |
| `R2_ACCESS_KEY_ID` | Access key do token R2 |
| `R2_SECRET_ACCESS_KEY` | Secret do token R2 |
| `R2_BUCKET` | Nome do bucket |
| `R2_ENDPOINT` | `https://<account_id>.r2.cloudflarestorage.com` |
| `R2_URL` | Domínio customizado público (ex.: `https://media.example.com`) |

Infra manual (fora do app): criar bucket R2, token API, mapear domínio customizado ao bucket, criar API key Resend e verificar domínio de envio.

## Credenciais de desenvolvimento

Após `php artisan db:seed`:

| Papel | E-mail | Senha |
|---|---|---|
| Admin | `admin@amare.local` | `password` |

**Somente para ambiente local.** Nunca usar em produção.

## Documentação normativa

- [SPEC.md](SPEC.md) — especificação do produto
- [docs/adr/](docs/adr/) — ADRs aceitas
- [docs/conventions/php-strict-types.md](docs/conventions/php-strict-types.md) — convenção de strict types
- [docs/operations/atualizacao-de-conteudo.md](docs/operations/atualizacao-de-conteudo.md) — runbook de atualização de conteúdo do site pelo painel admin
- [docs/deployment/dokploy.md](docs/deployment/dokploy.md) — deploy staging/produção no Dokploy + GHCR

## Deploy (Dokploy)

Staging publica automaticamente após CI verde em `main` (imagem GHCR por SHA + alias `:staging`). Produção promove a **mesma digest** com workflow manual `Promote production` (sem rebuild).

Ver runbook completo: [docs/deployment/dokploy.md](docs/deployment/dokploy.md).