Rider Issue Reports

A rider taps "Report an Issue" in the mobile app, snaps a photo of a wobbly handlebar, and submits. Thirty seconds later, the right tech's phone buzzes with a repair task pinned to that exact vehicle. That's the rider issue flow.

Where it lives in the rider app

The screen is ReportIssueScreen.tsx in the mobile-app/src/screens/main/ folder. Riders reach it from:

• The post-ride confirmation screen ("How was your ride? Report an issue")
• The active-ride safety menu
• The vehicle detail screen before they unlock

The screen has four inputs:

1. Category picker — mechanical, electrical, cosmetic, safety, lost_and_found, cleanliness
2. Severity — minor, moderate, severe (rider's self-assessment)
3. Description — a free-text field
4. Photos — up to 4 attachments from camera or library

Submitting POSTs to /api/rider-issues with the rider's auth token and the active or just-ended ride context.

What happens server-side

The /api/rider-issues route does three things in order:

1. Writes a rider_issues row with the category, severity, description, photos, and ride context
2. Calls the rule engine's onRiderIssueSubmitted handler
3. The handler looks up any active rule with trigger_type = 'rider_issue' and creates a task

The rule that handles rider issues looks like:

{
  "trigger_type": "rider_issue",
  "trigger_config": { "category": "mechanical" },
  "task_type": "repair",
  "default_priority": "high",
  "action_config": {
    "assign_by_proximity": true,
    "change_vehicle_status": "maintenance"
  }
}

You can write one rule per category (mechanical, electrical, etc.) or one catch-all rule. The dedup logic prevents duplicate open tasks against the same vehicle.

AI severity escalation

If the rider attaches a photo, the rule engine runs the photo through an AI severity classifier. The classifier rates the damage on a 1-5 scale, and:

• Severity 4 or higher bumps task priority to critical regardless of the rule's default
• Severity 5 also triggers the auto-flip to maintenance immediately

The AI rating is stored in task_photos.ai_severity and shown on the dashboard task detail page so the ops manager can sanity-check it. False positives are rare but not zero — the model has been tuned conservatively (more "this is fine" than "this is broken") to avoid alarm fatigue.

What the rider sees after submitting

The rider sees a confirmation screen with:

• "Thanks — we got it"
• A truncated task ID for reference
• An estimated time-to-resolution based on the SLA config

If the rider has email notifications enabled, they also get an email when the task moves to verified so they know the vehicle is back in service.

Triage queue (Phase 5 roadmap)

Right now every rider issue creates a task immediately. The Phase 5 roadmap adds a triage queue that holds rider issues for 60 seconds before creating the task, so ops can intercept obvious junk (duplicates, vandalism reports with no photo, accidental submissions). Until then, expect a handful of "lol my friend did it" submissions per week — bulk close them from the Kanban.

Riders cannot game it

A few hardening rules:

• A rider can submit at most 3 issue reports per ride
• A rider who has submitted 10 issues in 7 days without any reaching verified gets rate-limited
• Issues against a vehicle the rider has not rented are rejected at the API layer

These limits live in /api/rider-issues and have not been a friction point for legitimate users in pilot fleets.

Integration with refunds

Sometimes a rider reports an issue AND deserves a refund (they paid for a moped that turned out to be broken). The rider issue flow does NOT automatically refund — refunds always go through POST /api/rides/[id]/adjust-fare or POST /api/rides/[id]/refunds. The ops manager makes the refund decision after looking at the issue and the ride.