176 lines
7.0 KiB
Markdown
176 lines
7.0 KiB
Markdown
# Phase 3 — AI Features & Dashboard Upgrade
|
||
**Date:** 2026-07-11
|
||
**Status:** Approved
|
||
|
||
---
|
||
|
||
## Scope
|
||
|
||
Phase 3 adds AI-assisted capabilities via the Claude API and upgrades all role dashboards from placeholders to functional views. Similar-incident retrieval (pgvector) is deferred to Phase 4.
|
||
|
||
**Deliverables:**
|
||
1. Upgraded dashboards for all 5 roles
|
||
2. Report quality check (AI)
|
||
3. Severity/category suggestion at triage (AI)
|
||
4. RCA/CAPA drafting assistant (AI)
|
||
|
||
---
|
||
|
||
## 1. Dashboard Upgrades
|
||
|
||
### Approach
|
||
Replace placeholder home pages for each role with data-driven dashboards scoped to what that role needs to act on. All dashboards are server-rendered (Next.js App Router, `force-dynamic`). Site/zone heatmap is a plain HTML table with Tailwind bg-opacity intensity — no canvas library.
|
||
|
||
### Role Dashboards
|
||
|
||
**HSE Officer** — `/hse/dashboard` (upgrade existing)
|
||
- Leading vs lagging split: near_miss + hazard = leading indicators; injury + lti = lagging
|
||
- Site/zone heatmap: incident count per site × zone, color-coded by intensity
|
||
- CAPA on-time completion rate: `(verified CAPAs where completed_at <= due_date) / total verified * 100`
|
||
- Top 3 incident categories by count (current month)
|
||
- Top 3 root causes from `investigations.root_cause_summary` (simple text frequency, no NLP)
|
||
- DOSH-reportable filing status: counts of `dosh_reports` rows by status (not_required / pending / submitted)
|
||
- CSV export endpoint: `GET /api/dashboard/export?role=hse` — all incidents with key fields
|
||
|
||
**Management** — `/management` (upgrade placeholder)
|
||
- This month vs last month incident count (delta + arrow)
|
||
- LTI count (incidents where `medical_status = 'lti'`)
|
||
- Severity distribution bar (count per severity 1-5)
|
||
- Leading/lagging split (same calc as HSE)
|
||
- CAPA overdue count (status = 'overdue')
|
||
- Site comparison table: incident count per site, sorted descending
|
||
- CSV export: `GET /api/dashboard/export?role=management`
|
||
|
||
**Supervisor** — `/supervisor` (upgrade placeholder)
|
||
- Scoped to `user.site_id` — only their site's data
|
||
- Open incidents count + list (status != closed), linked to incident detail
|
||
- CAPA status summary for their site: open / in_progress / overdue counts
|
||
- Overdue CAPAs: list with owner name + due date
|
||
|
||
**CAPA Owner** — `/capa-owner` (upgrade placeholder)
|
||
- Scoped to `capa_actions.owner_user_id = current_user`
|
||
- My open CAPAs: list with incident ref, description, due date, status
|
||
- Overdue count highlighted in red
|
||
- No export needed
|
||
|
||
**Reporter** — `/reporter` (upgrade placeholder)
|
||
- Scoped to `incidents.reported_by = current_user`
|
||
- My submissions: list with reference_no, date, type, current status
|
||
- Status shown as colored badge (reported / triaged / investigating / capa_pending / verification / closed)
|
||
- No export needed
|
||
|
||
---
|
||
|
||
## 2. AI Features
|
||
|
||
### Architecture
|
||
- All Claude API calls: server-side only, `/app/api/...` routes
|
||
- Model: `claude-sonnet-4-6`
|
||
- API key: `ANTHROPIC_API_KEY` env var (never client-side)
|
||
- Every AI suggestion logged to `audit_log` with: table=`ai_suggestion`, action=`suggested`, old_value=null, new_value=JSON of suggestion, changed_by=current user
|
||
|
||
### 2a. Report Quality Check
|
||
|
||
**Trigger:** Incident report form submit — before DB write, client POSTs to quality-check route first.
|
||
|
||
**API route:** `POST /api/incidents/quality-check`
|
||
|
||
**Request payload:**
|
||
```json
|
||
{
|
||
"description": "string",
|
||
"incident_type": "injury | near_miss | ...",
|
||
"injury_involved": true,
|
||
"evidence_count": 0
|
||
}
|
||
```
|
||
|
||
**Claude prompt strategy:** Send incident fields; ask Claude to return a JSON array of short warning strings covering: vague description (< 20 words), injury with no photo, no location detail, missing witness info for serious incidents.
|
||
|
||
**Response:**
|
||
```json
|
||
{ "warnings": ["Description too vague — add what happened and where", "Injury reported but no photo attached"] }
|
||
```
|
||
|
||
**UI:** If warnings exist, show yellow warning panel above the submit button listing each warning. "Submit anyway" button still present — user is never blocked, only informed.
|
||
|
||
**Audit log:** Not logged (no human decision to record — warnings are informational only).
|
||
|
||
### 2b. Severity/Category Suggestion (Triage)
|
||
|
||
**Trigger:** "Get AI suggestion" button in existing triage panel at `/hse/incidents/[id]/triage`.
|
||
|
||
**API route:** `POST /api/incidents/[id]/ai-triage`
|
||
|
||
**Claude prompt strategy:** Send description, incident_type, injury_involved, lost_days. Ask Claude to return suggested severity 1-5 with confidence (high/medium/low) and one-sentence reasoning. Return as JSON.
|
||
|
||
**Response:**
|
||
```json
|
||
{
|
||
"suggested_severity": 3,
|
||
"confidence": "medium",
|
||
"reasoning": "Injury involved with medical treatment but no LTI reported — consistent with severity 3."
|
||
}
|
||
```
|
||
|
||
**UI:** Suggestion card appears below the severity input in the triage form. "Accept" pre-fills the severity field. HSE can ignore and type their own value. Card shows confidence label and reasoning text.
|
||
|
||
**Audit log:** On triage form save, log: suggested_severity, confidence, human's final severity value. `record_id` = incident id.
|
||
|
||
### 2c. RCA/CAPA Drafting Assistant
|
||
|
||
**Trigger:** "Generate suggestions" button in investigation workspace at `/hse/incidents/[id]/investigation`.
|
||
|
||
**API route:** `POST /api/incidents/[id]/ai-rca`
|
||
|
||
**Claude prompt strategy:** Send incident description, investigation findings_text, root_cause_summary. Ask Claude to return: 2-3 root cause categories (from standard EHS taxonomy: Human Factors, Equipment Failure, Procedure, Environment, Management System) + 2-3 draft CAPA action descriptions as JSON array.
|
||
|
||
**Response:**
|
||
```json
|
||
{
|
||
"root_causes": [
|
||
{ "category": "Procedure", "explanation": "No documented SOP for forklift loading at Dock A" }
|
||
],
|
||
"capa_drafts": [
|
||
"Develop and implement SOP for forklift loading operations at all dock areas within 14 days",
|
||
"Conduct refresher training for all forklift operators on LOTO procedure by end of month"
|
||
]
|
||
}
|
||
```
|
||
|
||
**UI:** Collapsible "AI Suggestions" panel below the RCA form fields. Each root cause has a "Use this" button that appends text to `root_cause_summary`. Each CAPA draft has a "Create CAPA" button that opens the CAPA creation form pre-filled with that description.
|
||
|
||
**Audit log:** Log on button click: which suggestion index was used, full suggestions array as old_value context. `record_id` = incident id.
|
||
|
||
---
|
||
|
||
## 3. Data & Schema
|
||
|
||
No new DB tables required. Existing `audit_log` table handles AI suggestion logging via `action = 'ai_suggested'`.
|
||
|
||
CSV export routes query existing tables — no new schema.
|
||
|
||
---
|
||
|
||
## 4. Implementation Order
|
||
|
||
1. Dashboard — HSE (upgrade existing, most complex)
|
||
2. Dashboard — Management
|
||
3. Dashboard — Supervisor
|
||
4. Dashboard — CAPA Owner
|
||
5. Dashboard — Reporter
|
||
6. CSV export endpoint (shared, covers HSE + management)
|
||
7. Report quality check (AI)
|
||
8. Severity suggestion at triage (AI)
|
||
9. RCA/CAPA drafting assistant (AI)
|
||
|
||
---
|
||
|
||
## 5. Out of Scope (Phase 3)
|
||
|
||
- Similar-incident retrieval via pgvector — Phase 4
|
||
- WhatsApp notifications — Phase 4
|
||
- Multi-language UI — Phase 4
|
||
- CAPA effectiveness re-check automation — Phase 4
|
||
- Risk heatmap / predictive analytics — Phase 4
|