From 29bdb39506a8f8b3b894e89744d6d72563cacc13 Mon Sep 17 00:00:00 2001 From: weeihan Date: Wed, 14 Oct 2026 11:02:12 +0800 Subject: [PATCH] docs: spec for zone picker, CAPA completion proof, test-data cleanup Co-Authored-By: Claude Sonnet 5.5 --- ...26-10-14-zone-capa-proof-cleanup-design.md | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-14-zone-capa-proof-cleanup-design.md diff --git a/docs/superpowers/specs/2026-10-14-zone-capa-proof-cleanup-design.md b/docs/superpowers/specs/2026-10-14-zone-capa-proof-cleanup-design.md new file mode 100644 index 0000000..a08d96e --- /dev/null +++ b/docs/superpowers/specs/2026-10-14-zone-capa-proof-cleanup-design.md @@ -0,0 +1,73 @@ +# 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=` 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) +```sql +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.