diff --git a/docs/superpowers/specs/2026-10-15-truck-site-link-design.md b/docs/superpowers/specs/2026-10-15-truck-site-link-design.md new file mode 100644 index 0000000..c403f7a --- /dev/null +++ b/docs/superpowers/specs/2026-10-15-truck-site-link-design.md @@ -0,0 +1,43 @@ +# Link trucks to a site + +Date: 2026-10-15. Status: draft for review. + +## Problem +Trucks are a flat list. The Report an Incident form shows every active truck regardless of site. Admin cannot say which site a truck belongs to. + +## Decisions +- A truck links to **one** site (optional). +- The report form **filters** the Truck dropdown by the selected site. +- A truck with no site (all existing trucks) shows for **every** site until an admin assigns one. + +## 1. Schema (manual, needs owner go-ahead) +```sql +ALTER TABLE trucks ADD COLUMN IF NOT EXISTS site_id UUID REFERENCES sites(id); +CREATE INDEX IF NOT EXISTS trucks_site_id_idx ON trucks(site_id); +``` +- Add `db/ops/2026-10-15-trucks-site-id.sql` (wrapped in BEGIN/COMMIT), update `db/schema.sql` and `lib/db/schema.ts` (`siteId: uuid('site_id').references(() => sites.id)`). +- No RLS change: `trucks_read` (all) and `trucks_admin_all` already cover the column. + +## 2. Admin, Trucks tab +- `app/(protected)/admin/page.tsx` selects `trucks.siteId`; `TruckManager` receives `site_id` per truck and the list of active sites. +- Add form: optional Site select. Each row shows the site name, or "Unassigned". Edit modal: Site select with a "No site" option. +- `POST /api/admin/trucks` and `PATCH /api/admin/trucks` accept `site_id` (uuid or null). Non-null must reference an existing active site, otherwise 422. Audit log entry stays in the same transaction and records old and new `site_id`. + +## 3. Report form +- `app/report/page.tsx` passes `site_id` with each truck. +- New pure helper `trucksForSite(trucks, siteId)` in `lib/report/trucks.ts`: returns trucks where `site_id` is null or equals `siteId`; with no `siteId`, returns all. +- The site comes from the QR zone when present, otherwise from the Site select. When the site changes and the selected truck no longer fits, the selection clears. +- `?truck_id=` still pre-selects the truck. If no zone is given, the truck's `site_id` (when set) becomes the default site. +- `POST /api/incidents` is unchanged and does not reject a truck/site mismatch (UI filter only). + +## Testing +- `trucksForSite` unit tests (null site, matching, other site, no site selected). +- API tests for `site_id` on create and edit: invalid site 422, valid site saved with audit row, null clears. +- Component test: truck dropdown filters on site change and clears an invalid selection. +- `npm run check:design` must print `design gates: clean`. + +## Out of scope +Several sites per truck, bulk assignment, filtering the Incidents list by truck site. + +## Deploy +Apply the SQL by hand first (additive, nullable, safe for the old build), then deploy per CLAUDE.md.