Files
ims/docs/superpowers/specs/2026-10-15-truck-site-link-design.md
2026-10-15 11:17:15 +08:00

44 lines
2.6 KiB
Markdown

# 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.