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

2026-07-09 21:33:59 +08:00
commit f83686fcca
29 changed files with 11655 additions and 0 deletions
@@ -0,0 +1,99 @@
+# Development Roadmap & Claude Code Brief
+## How to actually build this, phase by phase
+
+You're a coding beginner, so the goal here is: don't try to build everything at once. Build a small working version, get your HSE team using it, then add the smarter features. Each phase below is something you can hand to Claude Code as a separate session, with a ready-to-use starting prompt.
+
+---
+
+## Before you start
+
+1. Create free accounts: Supabase, Vercel, Anthropic (Claude API), Resend (or SendGrid).
+2. Create a project folder and put all three documents (`01_PRD...`, `02_Technical_Specification...`, this file) inside a `/docs` folder in that project. Claude Code will read them for context.
+3. Open Claude Code in that folder and paste the starting prompt for Phase 0 below.
+
+---
+
+## Phase 0 — Foundation (Week 1–2)
+
+**Goal:** Empty but working skeleton — login, roles, database, one site set up.
+
+**Deliverables:**
+- Next.js project connected to Supabase
+- Database schema from `02_Technical_Specification...md` §3 created as migrations
+- Login + role-based routing (reporter/supervisor/HSE/CAPA owner/management/admin)
+- One test site + zone + QR code generated
+
+**Starting prompt for Claude Code:**
+> "Read the files in /docs. Set up a Next.js + Supabase project implementing the database schema in section 3 of the technical spec. Add Supabase Auth with the roles listed in the PRD section 2. Build a simple login page and a role-based redirect (each role lands on a different placeholder home page for now). Don't build the incident form yet — just the foundation."
+
+---
+
+## Phase 1 — MVP: core reporting (Week 3–6)
+
+**Goal:** A real, usable incident reporting tool — this alone already replaces WhatsApp/Excel reporting.
+
+**Deliverables:**
+- QR-triggered incident report form (mobile-first), photo/video upload
+- Auto reference number generation
+- Email notification to supervisor + HSE on new report
+- Incident inbox (list + filter) for supervisor/HSE
+- Incident detail page showing evidence + basic status
+- Basic dashboard: total incidents, open vs closed, by site
+
+**Starting prompt for Claude Code:**
+> "Read /docs. Build the incident report form and incident inbox described in PRD sections 3-4 and technical spec section 4, items 1-5. Use Supabase Storage for photo/video uploads. Send an email via Resend to the site's supervisor and HSE officer when a new incident is submitted. Keep the AI features out of scope for this phase — pure data capture and notification only."
+
+**Milestone check:** Get 2-3 real HSE staff to use this for two weeks before moving on. Real feedback here is worth more than building further blind.
+
+---
+
+## Phase 2 — Investigation, CAPA & compliance (Week 7–10)
+
+**Goal:** Close the loop — this is what makes it a *management* system, not just a form.
+
+**Deliverables:**
+- Triage panel with severity (1-5) and the DOSH regulatory checklist (PRD §9)
+- Investigation workspace with RCA templates (5-Why, fishbone)
+- CAPA board (Kanban + table), owner assignment, due dates, overdue escalation
+- Verification step with completion evidence + reopen-if-ineffective logic
+- JKKP 6/7 draft PDF generation
+
+**Starting prompt for Claude Code:**
+> "Read /docs. Build the triage, investigation, and CAPA modules described in PRD sections 4 and 6, and technical spec section 4, items 6-9. Implement the DOSH notification logic from PRD section 9 as a checklist shown during triage. Add the CAPA overdue escalation rules from PRD section 6. Don't build AI drafting yet — HSE and CAPA owners fill everything manually for now."
+
+---
+
+## Phase 3 — AI features (Week 11–14)
+
+**Goal:** This is the part that makes it better than most commercial EHS tools your competitors would pay for.
+
+**Deliverables:**
+- Report quality check (flags incomplete submissions before they're sent)
+- AI severity/category suggestion at triage
+- Similar-incident retrieval
+- RCA/CAPA drafting assistant
+- Full dashboard with leading/lagging split and site/zone heatmap
+
+**Starting prompt for Claude Code:**
+> "Read /docs. Add the AI-assisted features from PRD section 8 and technical spec section 5, using the Claude API. Start with the report quality check and severity suggestion, since those are the simplest. Log every AI suggestion and the human's final decision to the audit_log table, as described in technical spec section 5."
+
+---
+
+## Phase 4 — Scale & polish (ongoing, Week 15+)
+
+- Roll out to additional warehouse sites
+- WhatsApp Business API notifications (in addition to email)
+- Multi-language UI (Bahasa Malaysia / Mandarin, per PRD §11)
+- Offline capture for low-signal warehouse zones
+- CAPA effectiveness re-check automation (30/60/90-day follow-up)
+- Optional: link incidents to your WMS zone/shift data, so you can cross-reference whether incidents cluster around specific shifts, pick zones, or peak-season periods — something a generic commercial EHS platform cannot do out of the box because it doesn't know your WMS.
+
+---
+
+## Working with Claude Code as a beginner — a few tips
+
+- **One phase per session.** Don't paste all four phases into one giant request — Claude Code works best with a clear, scoped task, and you'll understand what's happening if you review it in chunks.
+- **Ask it to explain, not just build.** Add "explain what you're doing in simple terms as you go" to your prompts if you want the learning benefit, not just the output.
+- **Review before merging.** Ask Claude Code to summarize each change before you accept it — especially anything touching the database schema or user roles/permissions.
+- **Keep the docs updated.** If you change a requirement mid-build (e.g., decide to add a new incident type), update the PRD first, then tell Claude Code to re-read it — keeping the docs as the source of truth avoids drift between what's documented and what's built.
+- **Test with real HSE staff early**, especially after Phase 1. A reporting tool that's technically correct but that warehouse floor staff find annoying to use will fail the same way WhatsApp-only reporting has gaps today — usability is a compliance issue here, not just a nice-to-have.