analysis/04-functional-spec/ratings-and-reviews-module.md
Ratings & Reviews
Ratings & Reviews Module – Functional Specification
1. Purpose
This module manages all customer feedback submitted after completing a trip.
It covers:
- General trip rating (overall)
- Detailed sub-ratings: Program overall, Hotel, Bus, Driver, Rest Stops
- Optional written comments
- Rating eligibility rules
- How ratings propagate into provider dashboards and trip details
- Integration with Trip Details UI (B2C) and Management Panels
4. Rating Entity Fields
| Field | Type | Notes |
|---|---|---|
| id | PK | — |
| user_id | FK (end user) | — |
| trip_id | FK | — |
| booking_id | FK | — |
| overall_rating | Integer (1–5) | mandatory |
| program_rating | Integer (1–5) | optional |
| hotel_rating | Integer (1–5) | optional |
| bus_rating | Integer (1–5) | optional |
| driver_rating | Integer (1–5) | optional |
| rest_stops_rating | Integer (1–5) | optional |
| comments | Text | optional |
| submitted_at | timestamp | — |
| created_at | timestamp | — |
| updated_at | timestamp | — |
5. Rating Components
Program Overall
program_rating → Trip itinerary quality
Hotel
hotel_rating → Hotel entity
Bus
bus_rating → Bus entity
Driver
driver_rating → driver fields in Bus
Rest Stops
rest_stops_rating → RestStop entities
6. Business Rules
BR-1. Eligibility
A user may submit a rating ONLY if:
- User has a completed booking (booking_status = Completed)
- Trip end_date < now()
- Rating not previously submitted for the same booking
BR-2. Mandatory General Rating
From UI: The first step (How was your trip?) has no skip button, therefore overall_rating is required.
BR-3. Detailed Ratings Are Optional
UI shows 'Skip' button and 'Submit Rating' button. Thus all sub-ratings and comments are optional.
BR-4. Ratings Affect Multiple Modules
- Trip average rating (trip.avg_rating)
- Provider rating (rolling weighted average)
- Hotel rating (optional calculated field)
- Bus/Driver/RestStop quality metrics
BR-5. Ratings Are Immutable
Once submitted: Cannot be edited, Cannot be deleted by the user. Admin can delete for moderation if needed.
BR-6. Text Comments Are Optional
UI uses: 'Enter any notes' — No minimum length required.
7. Actions & Behaviors
A-1. Trigger Rating Prompt
Triggered after trip end_date passes or when user opens app after completed trip. Displayed once per booking.
A-2. Submit Overall Rating
User selects 1–5 stars and taps 'Submit Rating'. System validates eligibility, booking ownership, and completeness.
A-3. Submit Detailed Ratings
User selects values or taps skip. Then displays: 'Your rating has been submitted successfully'
A-4. Aggregation
After submitting: Update trip.avg_rating, provider.overall_rating, and optionally hotel/bus/reststop averages.
8. Validation Rules
| Field | Validation |
|---|---|
| overall_rating | required, integer 1–5 |
| detailed ratings | optional, integer 1–5 |
| comments | optional |
| booking_id | must belong to user |
| trip must be completed | end_date < now |
| no duplicate | unique(user_id, booking_id) |
9. Error Cases
| Case | Behavior |
|---|---|
| User tries rating an upcoming trip | Show: Cannot rate trip before completion |
| User already rated | Hide rating prompt |
| Missing required rating | Highlight stars |
| Backend unavailable | Local retry on next app launch |
| Trip without hotel/bus | Store null values |
11. Cross-Module Relations
| Module | Interaction |
|---|---|
| Trips | receives updated average rating |
| Bookings | ensures booking is completed before rating is allowed |
| Hotels/Buses/RestStops | receive sub-ratings for quality metrics |
| Provider Portal | displays aggregated ratings per trip/provider/resource |
| Financial Reports | no direct financial impact |
| Notifications | 'Thanks for rating' or rating-request messages |