Files
ims/docs/superpowers/specs/2026-10-14-zone-capa-proof-cleanup-design.md
T

5.0 KiB

Zone picker, CAPA completion proof, test-data cleanup

Date: 2026-10-14. Status: draft for review.

Three independent changes from the 2026-10-13 field feedback. Each can ship on its own.

1. Zone picker on /report

Problem

/report without ?zone=<qr_token> shows "No zone detected — zone will not be recorded", but POST /api/incidents requires zone_token and returns 404 "Zone not found" without it. A user who opens Report from the Incidents page cannot submit.

Design

  • app/report/page.tsx also loads active sites with their active zones (asAdmin, same pattern as trucks) and passes sites: { id, name, zones: { id, name, qr_code_token }[] }[] and defaultSiteId (users.site_id of the session user) to ReportForm.
  • With a valid QR token: unchanged ("Site — Zone" header, token sent as today).
  • Without a token (or an unknown token): the "No zone detected" banner is removed. ReportForm shows two required selects, Site (default defaultSiteId) then Zone (filtered to the site). The chosen zone's qr_code_token is sent as zone_token.
  • Submit button stays disabled until a zone is resolved (token or selection).
  • No API or schema change; the server still validates the token and the active flags.
  • New labels (Site, Zone, "Select zone…") added to the existing i18n message files.
  • Offline queue: the queued payload already carries zone_token, so it keeps working.

Out of scope

Making zone optional; a "General" zone per site.

2. CAPA completion proof

Problem

CapaOwnerActions sends PATCH /api/capa/[id] {status:'pending_verification'} directly. The PIC can submit with no evidence and no notes.

Design

  • "Submit for Verification" opens a form: completion note (required) and 1 to 5 photos (required, JPG/PNG/HEIC, same size limit as incident evidence). The submit button is disabled until both are present.
  • New POST /api/capa/[id]/submit (multipart):
    • Allowed: CAPA owner, or hse/admin. Status must be in_progress; otherwise 409.
    • Validates note non-empty and 1 to 5 image files; otherwise 422.
    • In one withUser transaction: store files via lib/storage/evidence.ts, insert evidence_files rows (stage = 'capa', capa_id set, hash recorded), set owner_notes, completed_at, status = 'pending_verification', and write audit_log (include file ids and the note).
    • Existing in-app notification to HSE on submission is kept.
  • PATCH /api/capa/[id] rejects status: 'pending_verification' with 403 for everyone (the new endpoint is the only path). Owner in_progress transition is unchanged.
  • CAPA detail page: "Completion report" section shows the note and a photo gallery (signed /api/evidence/... URLs) so HSE sees proof when verifying or reopening.
  • Evidence rows are never hard-deleted (5-year retention).

Schema change (manual, needs owner go-ahead)

ALTER TABLE evidence_files ADD COLUMN capa_id uuid REFERENCES capa_actions(id);
CREATE INDEX evidence_files_capa_id_idx ON evidence_files(capa_id);

The evidence_stage enum already has capa; no enum change. Update db/schema.sql, lib/db/schema.ts, and check the evidence_* RLS policies in db/rls.sql cover CAPA owners (insert) and hse/admin (read); add a read policy for the CAPA owner if missing.

Out of scope

Photos on "Mark In Progress"; HSE-side evidence upload; video.

3. Test-data cleanup (ops, one-off)

Scope

Delete all incidents and every user with role != 'admin' from the production DB.

Design

  • Script db/ops/cleanup-test-data.sql plus a short runbook in docs/.
  • Steps:
    1. pg_dump of ims and a tar of /var/lib/ims-evidence on the server, kept outside the deploy folders.
    2. Dry run: print row counts per table (incidents, children, users to delete, admins kept). Show the list of admins kept.
    3. Wait for explicit user confirmation of those counts.
    4. Run in one transaction, FK order: notifications (notifications_log, in-app), capa_actions, investigations, dosh_reports, addenda, evidence_files, audit_log rows for incidents, incidents, then users where role != 'admin'. Anything else referencing those users (audit_log changed_by, etc.) is nulled or removed per the real FK list found in the dry run.
    5. Verify counts and that admin login works.
  • Evidence files on disk are left in place (retention rule); orphaned files can be reviewed separately.
  • Nothing runs against production without step 3 confirmation. Run after the schema change in section 2, or independently.

Testing

  • Zone picker: component test for site-to-zone filtering and submit gating; manual check with and without ?zone=.
  • CAPA submit: API tests for 401/403/409/422, success path writes files, audit row and status; PATCH bypass returns 403.
  • Cleanup: dry-run counts match expectations on a restored dump before running on production.
  • npm run check:design must print design gates: clean for UI changes.

Deploy

Follow CLAUDE.md deploy steps (build locally, upload standalone build only, check BUILD_ID, restart, verify). Schema SQL applied by hand beforehand with the owner's go-ahead.