Files
ims/docs/superpowers/specs/2026-10-14-zone-capa-proof-cleanup-design.md
2026-10-14 11:14:57 +08:00

73 lines
4.9 KiB
Markdown

# 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).
- `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 IF NOT EXISTS capa_id UUID REFERENCES capa_actions(id) ON DELETE RESTRICT;
CREATE INDEX IF NOT EXISTS 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`, no RLS change: the PIC is the uploader and already reads own rows.
### 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.