manoel freitas
58ad990488
Promote five capability specs from the completed setup-foundation change into openspec/specs and move the change to archive. Co-authored-by: Cursor <cursoragent@cursor.com>
125 lines
6.4 KiB
Markdown
125 lines
6.4 KiB
Markdown
## Context
|
||
|
||
Repositório greenfield: contém [SPEC.md](../../../SPEC.md) (especificação normativa aprovada), scaffold OpenSpec e um commit inicial. Não existe aplicação Laravel, banco, CI ou contêiner.
|
||
|
||
Versões-alvo confirmadas no Packagist (jul/2026): Laravel 13.23, Filament 5.7, Livewire 4.3, Pest 4.7, Larastan 3.10, Pint 1.29. Ambiente local: PHP 8.5.8, Composer 2.9.5, Node 22, Docker 29 + Compose v5.3.
|
||
|
||
ADRs ADR-001..ADR-010 do SPEC §21 são aceitas e serão registradas em `docs/adr/` sem reabertura de decisões.
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
|
||
- Entregar esqueleto Laravel funcional com Filament autenticado, Livewire/Tailwind configurados e Postgres local.
|
||
- Estabelecer gates de qualidade (Pint, Larastan, Pest, arch tests) e scripts Composer padronizados.
|
||
- Produzir imagem Docker FrankenPHP reproduzível com healthcheck e processos web/queue/scheduler.
|
||
- CI verde nos 5 jobs bloqueantes antes de avançar para Fase 1.
|
||
- Design tokens mínimos e layout público placeholder para validar pipeline visual futuro.
|
||
|
||
**Non-Goals:**
|
||
|
||
- Implementar requisitos funcionais das Fases 1–5 (site, CRM, eventos, financeiro, documentos).
|
||
- Deploy em staging ou produção (adiado).
|
||
- FrankenPHP worker mode, Redis, S3 em produção, integração de e-mail transacional.
|
||
- Qualquer item listado em SPEC §4.2 "Fora do MVP".
|
||
|
||
## Decisions
|
||
|
||
### 1. Bootstrap via `composer create-project` em diretório temporário
|
||
|
||
**Decisão:** Instalar Laravel 13 com `composer create-project laravel/laravel` em diretório temporário e mover arquivos para a raiz, preservando `SPEC.md`, `openspec/` e `.codex/`.
|
||
|
||
**Alternativas:** Instalar na raiz (conflita com arquivos existentes); copiar skeleton manualmente (mais erro-prone).
|
||
|
||
**Rationale:** Padrão Laravel garante estrutura correta; evita sobrescrever artefatos de spec.
|
||
|
||
### 2. PostgreSQL 17 via Docker Compose local
|
||
|
||
**Decisão:** Serviço `postgres:17` no Compose com volume nomeado, healthcheck e credenciais em `.env.example`.
|
||
|
||
**Alternativas:** SQLite local (proibido pelo SPEC §14.2 para integração); Postgres instalado no host (sem `psql` no ambiente).
|
||
|
||
**Rationale:** Alinha dev local com CI; evita diferenças SQLite/Postgres.
|
||
|
||
### 3. Sessão, cache e fila em `database`
|
||
|
||
**Decisão:** `SESSION_DRIVER=database`, `CACHE_STORE=database`, `QUEUE_CONNECTION=database`.
|
||
|
||
**Alternativas:** Redis (fora do MVP, ADR-008); file/cookie session (menos alinhado com deploy containerizado).
|
||
|
||
**Rationale:** ADR-008; sem dependência extra; migrations padrão Laravel cobrem tabelas.
|
||
|
||
### 4. Papéis via enum `UserRole` na coluna `users.role`
|
||
|
||
**Decisão:** Enum PHP `UserRole: admin|assistant` + coluna `is_active` boolean. Filament `canAccessPanel()` nega inativos.
|
||
|
||
**Alternativas:** Spatie Permission (proibido pelo SPEC §3.4); flags booleanas separadas.
|
||
|
||
**Rationale:** YAGNI; atende ADM-01 e §12.2 sem complexidade.
|
||
|
||
### 5. Design tokens como CSS custom properties + Tailwind theme extension
|
||
|
||
**Decisão:** Arquivo `resources/css/tokens.css` com custom properties; `tailwind.config.js` referencia tokens via `theme.extend`.
|
||
|
||
**Alternativas:** SCSS variables espalhadas; JSON tokens com build step extra.
|
||
|
||
**Rationale:** Centraliza SPEC §6.3; Tailwind consome nativamente; sem dependência extra.
|
||
|
||
### 6. Isolamento visual: layout público separado do painel Filament
|
||
|
||
**Decisão:** Layout Blade público em `resources/views/layouts/public.blade.php` com tokens próprios; Filament usa tema padrão do painel.
|
||
|
||
**Alternativas:** Tema Filament customizado para site (mistura concerns); component library compartilhada prematura.
|
||
|
||
**Rationale:** Mitiga conflito Tailwind 4 / Filament 5 / tema público premium.
|
||
|
||
### 7. FrankenPHP regular mode, multi-stage Dockerfile
|
||
|
||
**Decisão:** Dockerfile com stages `composer`, `frontend`, `runtime` (FrankenPHP). PHP fixado conforme suporte Laravel 13 no momento da instalação (8.4 ou 8.5). `config:cache` apenas no entrypoint/deploy, nunca em stage sem env final.
|
||
|
||
**Alternativas:** Nginx + PHP-FPM (SPEC exige FrankenPHP); worker mode (ADR-006 proíbe no MVP).
|
||
|
||
**Rationale:** ADR-006; imagem única para web/queue/scheduler (§15.2).
|
||
|
||
### 8. CI em GitHub Actions com PostgreSQL service container
|
||
|
||
**Decisão:** Workflow `.github/workflows/ci.yml` com jobs `static`, `unit`, `feature`, `browser`, `container`. Feature tests usam Postgres service; browser job builda imagem e roda Pest Browser com locale `pt-BR`, TZ `America/Fortaleza`, animações desabilitadas.
|
||
|
||
**Alternativas:** GitLab CI; CircleCI (remote já é GitHub).
|
||
|
||
**Rationale:** Remote `manoel-freitas/amore-site`; SPEC §14.1.
|
||
|
||
### 9. Estrutura de diretórios modular preparada, não populada
|
||
|
||
**Decisão:** Criar apenas diretórios quando primeiro arquivo for adicionado (SPEC §9.4). Na Fase 0, garantir `tests/Architecture/` e namespace base; não criar `app/Application/`, `app/Domain/` vazios.
|
||
|
||
**Rationale:** YAGNI; arch tests validam boundary quando Domain existir na Fase 2+.
|
||
|
||
## Risks / Trade-offs
|
||
|
||
| Risco | Mitigação |
|
||
|---|---|
|
||
| Conflito Tailwind 4 + Filament 5 + tema público | Layouts separados; Vite entries distintos se necessário |
|
||
| Snapshots visuais instáveis no CI | Imagem Linux fixa, fontes instaladas, relógio congelado, seed determinístico (preparação na Fase 1) |
|
||
| `config:cache` congela env incorreto | Cache apenas no entrypoint com env final do deploy |
|
||
| PHP 8.5 muito novo para alguma extensão | Fixar versão PHP no Dockerfile conforme matriz Laravel 13; testar build no job `container` |
|
||
| Filament panel + Livewire 4 coexistência | Seguir docs oficiais de instalação Filament 5; testes feature de login |
|
||
|
||
## Migration Plan
|
||
|
||
1. Bootstrap Laravel em diretório temp → mover para raiz.
|
||
2. Configurar `.env` / `.env.example` com Postgres e locale.
|
||
3. Instalar Filament, Pest, Larastan, Pint; configurar scripts Composer.
|
||
4. Adicionar Compose, Dockerfile, CI workflow.
|
||
5. Seed admin local; documentar credenciais apenas para dev.
|
||
6. Validar `composer quality` e jobs CI no PR.
|
||
|
||
**Rollback:** Reverter commit da Fase 0; repo volta ao estado spec-only.
|
||
|
||
## Open Questions
|
||
|
||
- **Staging target:** VPS próprio, Fly.io, Render ou Railway — decisão adiada; change futura para deploy.
|
||
- **Registry de imagem:** GitHub Container Registry vs Docker Hub — definir na change de deploy.
|
||
- **Provedor S3-compatible:** necessário na Fase 1+ para mídia pública; local usa `storage/app/public` ou MinIO opcional no Compose.
|
||
- **Provedor de e-mail:** necessário na Fase 2 (notificação de leads); Fase 0 usa `log` driver ou Mailpit no Compose opcional.
|