chore: scaffold Next.js 15 + Supabase clients + vitest

docs/01_PRD_HSE_Incident_Management_System.md

@@ -0,0 +1,182 @@
+# Product Requirements Document (PRD)
+## Centralized AI-Powered HSE Incident Management & Reporting System
+
+**Prepared for:** Setia Corporation — 3PL Warehouse Operations
+**Based on:** Draft Proposal (Nurul Ain Athirah, June 2026) + Incident Reporting Flowchart, reviewed and extended
+**Purpose:** This document defines *what* the system must do. Hand it to Claude Code together with `02_Technical_Specification_for_Claude_Code.md` and `03_Development_Roadmap_and_Claude_Code_Brief.md` to build it.
+
+---
+
+## 1. Objectives
+
+Replace the current WhatsApp / Excel / paper-based HSE reporting process with a single digital system that:
+
+1. Captures every incident, near miss, hazard, and asset event in one database — with photo, video, and document evidence attached at every stage, not just at first report.
+2. Runs a structured, auditable workflow from report → response → investigation → CAPA → verification → closure.
+3. Tracks CAPA (Corrective and Preventive Actions) to completion with owner, due date, evidence, and automatic overdue escalation.
+4. Gives management a live dashboard instead of a monthly manual compilation.
+5. Keeps Setia Corporation compliant with Malaysian DOSH reporting law (NADOPOD 2004) without manual form-filling.
+6. Uses AI (Claude) to reduce the admin burden on HSE staff — drafting summaries, suggesting root causes and CAPA, flagging incomplete reports, and detecting risk patterns across sites.
+
+---
+
+## 2. Users & Roles
+
+| Role | Who | Access | Key responsibility |
+|---|---|---|---|
+| Reporter | Any employee, supervisor, witness, security guard | Submit reports via QR/app; view status of own reports only | Report incidents/hazards immediately |
+| Operation Supervisor | Warehouse/shift supervisor | Full access to incidents in their site/zone | Secure area, first response, initial classification |
+| HSE Officer | Safety Assistant / HSE team | Full access across all sites | Investigation, RCA, CAPA assignment, verification, closure, DOSH filing |
+| CAPA Owner | Department head (Ops, Maintenance, HR, etc.) | Access to CAPA items assigned to their department only | Complete corrective actions, upload proof |
+| Management / Admin | Ms. Agnes, Mr. Terence, Mr. Yap, Mr. Jensen, etc. | Read-only dashboard across all sites; admin can manage users/config | Review trends, approve budget for corrective actions, audit readiness |
+| System Admin | IT/appointed super-user | Full config access | User management, site/zone setup, form configuration |
+
+Every action in the system must be attributable to a logged-in user — no anonymous edits (see §9 Compliance).
+
+---
+
+## 3. Incident Types Covered
+
+The current flowchart only branches on **Injury** and **MHE (asset)**. The system must cover all of the following, each with its own lightweight intake form:
+
+- Injury / medical treatment case (LTI and non-LTI)
+- Near miss (no injury/damage, but could have) — **kept fast and low-friction on purpose**, since near-miss volume is the single best leading indicator of future serious incidents
+- Unsafe condition / hazard observation (proactive, not tied to an event)
+- Property / asset / MHE damage (forklift, racking, dock equipment)
+- Environmental incident (spill, leak, chemical release, waste)
+- Security incident (theft, unauthorized access, if relevant to your sites)
+- Fire / emergency incident
+
+---
+
+## 4. Incident Lifecycle & Workflow Rules
+
+This corrects and extends the two flowcharts supplied. The visual summary was shown earlier in this conversation; the rules below are the ones that must be encoded in the system's logic.
+
+### Phase 1 — Report
+- Reporter scans a site/zone-specific QR code (or opens the app), selects incident type, fills a short form, and attaches at least one photo (video/documents optional at this stage).
+- System auto-generates a unique incident reference number (format: `SITE-YYYYMM-####`) and timestamps the report.
+- System auto-detects the reporting site/zone from the QR code (no manual typing → fewer errors).
+- Automatic notification fires immediately to the relevant Supervisor and HSE Officer (see §7).
+
+### Phase 2 — Triage & Initial Response
+- Supervisor/HSE confirms or reclassifies incident type and assigns a **severity level (1–5)**, which the current flowchart does not have — this is what drives SLA timers in step below. AI can suggest a severity level from the description (see §8), but a human always confirms it.
+- Workflow branches based on type:
+  - **Injury involved →** medical treatment or first aid → medical status (LTI / non-LTI).
+  - **Asset/MHE involved →** emergency shutdown & LOTO if needed → operator-error check → minor/major classification → HR/discipline path if applicable.
+  - **Environmental →** containment steps, spill-kit deployment logged, environmental authority check.
+  - **Near miss / hazard observation →** skip straight to root-cause + CAPA, no medical/asset branch needed.
+- **Regulatory check (new, mandatory):** at this point the system checks the severity/injury data against the DOSH NADOPOD 2004 rules (see §9) and tells the HSE Officer exactly which obligation applies — immediate notification, JKKP 6/7 within 7 days, or record-only in JKKP 8. This removes reliance on the HSE officer remembering the rule.
+
+### Phase 3 — Investigation & CAPA
+- HSE conducts investigation: witness statements, alcohol/urine test (if applicable), evidence collection, structured root cause analysis (5-Why and/or fishbone — selectable template, not free text only).
+- Every CAPA item created must have: description, responsible department/owner, due date, priority, and linkage to the root cause it addresses.
+- System auto-escalates (notifies owner, then owner's manager, then HSE) if a CAPA passes its due date without a status update.
+
+### Phase 4 — Verification & Closure
+- CAPA owner uploads **completion evidence** (photo/document proof the fix is in place) before marking a CAPA "done."
+- HSE verifies effectiveness. If not effective, the CAPA **reopens** rather than the incident being closed with an open gap — this loop is missing from both flowcharts provided and is added here deliberately.
+- Once all CAPAs are verified, HSE closes the incident; record locks (no further edits, only addenda) and flows into the dashboard and the JKKP 8 annual register automatically.
+
+---
+
+## 5. Evidence Management (Photos, Videos, Documents)
+
+This must be a first-class feature across the entire lifecycle, not just at initial report:
+
+| Stage | Evidence expected |
+|---|---|
+| Report | Scene photo/video, hazard photo |
+| Response | LOTO tag photo, first-aid record, medical referral letter |
+| Investigation | Witness statement scans, CCTV export, equipment inspection report, alcohol/urine test result |
+| CAPA | **Before/after photos**, purchase receipts, training attendance sheets, updated SOP document |
+| Verification | Final confirmation photo/video that the corrective action is in place and working |
+
+Requirements:
+- Accept JPG/PNG/HEIC, MP4/MOV, PDF/DOCX/XLSX. Max file size per upload configurable (recommend 200MB for video, compress on upload).
+- Every file stores: uploader, timestamp, incident ID, stage, and an immutable file hash (for audit integrity — important if DOSH ever questions a record).
+- Files retained **minimum 5 years** to match DOSH JKKP 8 register retention law — do not auto-delete.
+- Thumbnail/preview generation so HSE doesn't have to download every file to review it.
+
+---
+
+## 6. CAPA Monitoring (dedicated module)
+
+Because this was explicitly requested as a standout feature:
+
+- Central CAPA register, filterable by site, department, status (open/in progress/overdue/verified/closed), and due date.
+- Kanban-style board view (To Do / In Progress / Verification / Closed) in addition to table view — much faster for a department head to scan than a spreadsheet.
+- Auto-escalation ladder: 3 days before due → reminder; on due date → notify owner; 3 days overdue → notify owner's manager; 7 days overdue → notify HSE + flagged red on dashboard.
+- CAPA effectiveness re-check scheduled automatically (e.g., 30/60/90 days after closure) to confirm the fix actually held — this is beyond what the current proposal covers and beyond most SME-level systems, but is standard in mature EHS practice.
+
+---
+
+## 7. Notifications
+
+- **Email** for formal records (investigation assignment, CAPA assignment, closure).
+- **WhatsApp Business API** for time-critical alerts (new serious incident, CAPA overdue) — recommended in addition to email because your teams already operate on WhatsApp; email-only notification (as in the original proposal) will likely be checked less often by warehouse floor staff.
+- In-app notification badge for all users.
+
+---
+
+## 8. AI-Assisted Capabilities (this is what makes it an "AI" system, not just a digital form)
+
+| Capability | What it does | Business value |
+|---|---|---|
+| Report quality check | Flags incomplete reports (e.g., injury reported but no photo, or description too vague) before submission | Fixes the "delayed/incomplete information" problem named in the original proposal |
+| Auto severity/category suggestion | Suggests severity level and incident category from the free-text description | Speeds up triage, reduces inconsistent classification between HSE staff |
+| Similar-incident retrieval | Surfaces past incidents with similar description/location/equipment | Reveals recurring hazards fast — supports the "limited safety trend visibility" gap named in the proposal |
+| Root cause & CAPA drafting assistant | Suggests likely root causes and draft corrective actions based on the investigation notes, for HSE to accept/edit | Cuts investigation write-up time, improves CAPA quality consistency |
+| Auto-fill regulatory forms | Generates JKKP 6/7 draft PDFs and the JKKP 8 annual register from stored data | Removes the single biggest admin burden named in the proposal |
+| Risk heatmap / prediction | Combines near-miss + incident + audit data by site/zone/shift to flag rising-risk areas before a serious incident occurs | Matches what leading commercial EHS platforms (VelocityEHS, Intelex) market as "predictive safety" in 2026 — but tuned to your own warehouses instead of generic industry data |
+
+All AI outputs are **suggestions the human reviews and approves** — never auto-submitted to DOSH or auto-closed without a human sign-off. This matters both legally and for HSE staff trust in the tool.
+
+---
+
+## 9. Compliance Requirements — Malaysia Specific (correction to the source flowchart)
+
+The uploaded flowchart labels the legal threshold box "OSHA Regulations." **For Malaysia this should be the Occupational Safety and Health Act 1994 (amended 2022) and its subsidiary regulation, NADOPOD 2004** (Notification of Accident, Dangerous Occurrence, Occupational Poisoning and Occupational Disease Regulations), enforced by DOSH/JKKP. The system's compliance logic should follow the actual rule, which is more specific than the flowchart's single ">4 days" box:
+
+| Situation | Obligation |
+|---|---|
+| Fatality, or serious bodily injury as defined in NADOPOD's First Schedule (e.g., fracture, amputation, loss of sight) | Notify nearest DOSH office **immediately** by fastest means, then submit **JKKP 6** within 7 days |
+| Dangerous occurrence (Second Schedule — e.g., boiler explosion, structural collapse), regardless of injury | Notify DOSH **immediately**, then **JKKP 6** within 7 days |
+| Other injury causing incapacity for **more than 4 consecutive days** | Submit **JKKP 6** within 7 days (immediate call not legally required, but recommended for serious cases) |
+| Occupational poisoning/disease (Third Schedule) | **JKKP 7** within 7 days |
+| Any of the above | Also logged in the **JKKP 8** annual register, kept on-site 5 years, submitted to DOSH before 31 January each year |
+
+Build the severity/injury intake fields so the system can determine which box applies automatically, and generate a checklist/reminder for the HSE Officer rather than relying on memory.
+
+---
+
+## 10. Dashboard & Analytics Requirements
+
+- Total incidents, near misses, severity rate, open vs. closed — as in the original proposal — **plus**:
+- Leading vs. lagging indicator split (near-miss/hazard reports = leading; injury/LTI = lagging) — this is the single biggest gap vs. commercial platforms and the cheapest to add.
+- Site/zone/shift heatmap — critical for a multi-warehouse 3PL operation to compare performance and spot which dock, zone, or shift is generating the most risk.
+- CAPA on-time completion rate (%).
+- Top incident category and top root cause, trended over time.
+- DOSH-reportable incident count and filing status (filed / pending / overdue) — audit-readiness at a glance.
+- Exportable to PDF/Excel for board reporting.
+
+---
+
+## 11. Non-Functional Requirements
+
+- **Mobile-first**, works on low-end Android phones common on warehouse floors; must work with poor/no signal (offline capture, syncs when back online).
+- **Multi-language** UI: Bahasa Malaysia, English, Mandarin at minimum (Tamil if your workforce needs it) — the original proposal's Google Form is English-only, which will suppress reporting from non-English-fluent floor staff.
+- **Multi-site** from day one — site and zone are first-class fields on every record, not an afterthought.
+- **Role-based access control** enforced at the data level, not just hidden UI elements.
+- **Full audit trail**: every create/edit/status-change/file-upload logged with user + timestamp, immutable.
+- **Data retention**: minimum 5 years per DOSH requirement; evidence files never hard-deleted.
+
+---
+
+## 12. Success Metrics for the Project
+
+- 100% of incidents captured digitally within 30 days of launch (zero WhatsApp-only reports).
+- CAPA on-time closure rate above 85% within 3 months.
+- Time from incident report to HSE Officer notification under 2 minutes (vs. current dependency on someone forwarding a WhatsApp message).
+- Monthly HSE report preparation time reduced from days to minutes (auto-generated from dashboard).
+- Zero missed DOSH statutory reporting deadlines.