openspec: laravel-admin change — Filament admin (users/tags/products/orders/dashboard) on shared Postgres

openspec/changes/laravel-admin/design.md

@@ -0,0 +1,41 @@
+## Context
+
+Phase 1–3 built the GOAT frontend + shared Postgres (users, tags, scans, products, orders on `.13:5434`). Phase 4 adds the Laravel admin: a management UI for users, tags (with the product/order linkage built in Phase 2.5), products/orders, and a dashboard. It reuses the same DB — no sync layer.
+
+## Goals / Non-Goals
+
+**Goals:**
+- A working Laravel + Filament admin on .27 via Docker (no PHP installed natively).
+- Reads/writes the shared Postgres on `.13:5434` (single source of truth).
+- Admin login gated by `users.is_admin`; full CRUD for users/tags/products/orders; dashboard stats.
+
+**Non-Goals:**
+- Billing/payments (Phase 5).
+- Photo uploads in admin (frontend has it; admin can reuse photo_url display).
+- Public-facing Laravel pages (this is admin-only for now).
+- Laravel owning migrations yet — `db/schema.sql` stays canonical; Eloquent reads the existing tables.
+
+## Decisions
+
+1. **Docker dev on .27** — `admin/docker-compose.yml` with `php:8.3-fpm` + a composer bootstrap; `php artisan serve --host=0.0.0.0 --port=3030`. No PHP/Composer installed natively (keeps .27 clean). Docker volume mounts `admin/` so edits are live.
+2. **Filament v3** for the admin panel (CRUD resources: User, Tag, Product, Order + dashboard stats). Rationale: the 2014 system needed forms-heavy admin; Filament is the Laravel-idiomatic generator and the best skills-update vehicle for Laravel conventions.
+3. **Shared DB via Eloquent** — models map to the existing tables (users, tags, scans, products, orders). No migrations in Phase 4; `db/schema.sql` remains the source of truth (Laravel takes over migrations at deploy, generating from it). `users.is_admin` added via the existing idempotent ALTER in schema.sql.
+4. **Auth** — Laravel's session auth + a middleware/policy: `Filament::auth()->user()->is_admin` gate. Seed one admin user (env-configured email, password from env).
+5. **Connection** — `admin/.env` `DB_CONNECTION=pgsql`, `DB_HOST=192.168.20.13`, `DB_PORT=5434`, `DB_DATABASE=wherewoof`, `DB_USERNAME=wherewoof`, password via env (gitignored `.env`).
+
+## Risks / Trade-offs
+
+- [Docker image pulls + composer install are slow first-time] → one-time cost; cached after.
+- [Laravel writing to a schema it doesn't own] → read-only via Eloquent where possible; writes (tag product/order assignment, order status) are simple column updates already exercised by the GOAT app; migrations reconciled at deploy.
+- [Shared users table across both apps] → `is_admin` flag only; no schema conflict.
+- [NixOS Docker networking to .13] → plain TCP to 192.168.20.13:5434, already proven by the Go app.
+
+## Migration Plan
+
+1. `make db-up` (adds `users.is_admin`).
+2. `admin/docker-compose.yml` up → composer create-project laravel/laravel admin → filament install → models/resources.
+3. Seed admin user; verify login + CRUD against the shared DB.
+
+## Open Questions
+
+- Whether the admin gets public-facing pages later (likely not — the GOAT frontend serves the public).