admin d7ba6a5265 fix(docs): document evidence file upload issue and VPS setup
Files not displaying after upload due to missing EVIDENCE_DIR and
EVIDENCE_URL_SECRET environment variables. Uploads fail silently when
env vars unset, files never inserted into database.

Add bug fix documentation with root cause analysis and VPS deployment
instructions. Update .env.local.example to emphasize these vars are
required for file uploads to work.

See docs/BUG_FIX_evidence_display.md for details.
2026-08-15 11:01:49 +08:00

IMS — HSE Incident Management System

AI-powered HSE incident management for Setia Corporation's 3PL warehouse operations. Replaces WhatsApp/Excel safety reporting with a structured report → triage → investigation → CAPA → verification → closure workflow, compliant with Malaysian DOSH law (OSHA 1994, NADOPOD 2004).

Features

  • QR-based incident capture — zone-specific QR codes, mobile-first form, works offline (PWA + IndexedDB sync), EN / Bahasa Malaysia / 中文
  • Type-specific intake — injury, near miss, hazard, asset/MHE, environmental, security, fire
  • Triage & DOSH check — severity 1–5, automatic NADOPOD 2004 obligation detection (immediate notify / JKKP 6 / JKKP 7 / JKKP 8)
  • Investigation — 5-Why and fishbone RCA, witness statements, alcohol/urine test log
  • CAPA module — kanban board, owner assignment, evidence-gated completion, auto-escalation ladder, 30/60/90-day effectiveness rechecks
  • Closure lock — closed incidents are immutable at the DB level; addenda only
  • Compliance exports — JKKP 6/7 PDF auto-fill, JKKP 8 annual register CSV, January deadline reminder
  • Notifications — email (Resend), WhatsApp (Meta Cloud API), in-app bell
  • AI (Claude, server-side only) — report quality check, severity suggestion, similar-incident retrieval (pgvector), RCA drafting, rising-risk zone flags
  • Dashboards — leading vs lagging indicators, 12-month trend, zone heatmap, top root causes, CAPA on-time rate, DOSH filing status

Stack

Next.js 15 (App Router, basePath /ims) · Supabase (Postgres + RLS + pgvector) · Claude API · Voyage AI embeddings · Resend · Meta WhatsApp Cloud API · pdf-lib · Vitest

Development

npm install
npm run dev        # http://localhost:3000/ims
npm test           # vitest
npm run build      # production build (standalone output)
npm run generate-qr  # zone QR PNGs into public/qr

Environment: copy .env.local.example (Supabase URL/keys, SUPABASE_SERVICE_ROLE_KEY for admin invites, RESEND_API_KEY, Meta WhatsApp creds, CRON_SECRET). Claude/Voyage keys live in the app_settings table (admin UI at /hse/settings) with env fallback.

Migrations: supabase/migrations/ — apply with supabase db push.

Cron (VPS): daily CAPA escalation + effectiveness recheck — see docs/vps-cron.md.

Docs

  • docs/01_PRD_HSE_Incident_Management_System.md — product requirements
  • docs/02_Technical_Specification_for_Claude_Code.md — technical spec
  • docs/03_Development_Roadmap_and_Claude_Code_Brief.md — phase roadmap
  • docs/superpowers/plans/ — per-phase implementation plans
  • .superpowers/sdd/progress.md — build ledger

Compliance notes

  • Evidence files retained ≥5 years, never hard-deleted (JKKP 8 register requirement)
  • Every mutation audit-logged (audit_log table); AI suggestions logged with human decision
  • RLS enforced at the database level for every table
S
Description
No description provided
Readme
2.2 MiB
Languages
TypeScript 57.9%
HTML 30.5%
JavaScript 6.9%
PLpgSQL 2.6%
CSS 1.4%
Other 0.7%