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

2.6 KiB

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)

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.