analysis/04-functional-spec/rest-stops-module.md
Rest Stops List
Rest Stops Module – Functional Specification
1. Purpose
The Rest Stops Module manages all rest stops (استراحات الطريق) used in trip itineraries, specifically during road transportation. Rest stops serve as structured points along the trip route where travelers can rest, refuel, eat, or access essential services.
This module covers:
- Adding rest stops
- Managing facilities and location
- Contact information
- Activation/deactivation
- Selecting rest stops during trip creation
- Displaying rest stops in B2C Trip Details
4. Rest Stop Entity Fields
| Field | Type | Notes |
|---|---|---|
| id | PK | — |
| provider_id | FK | — |
| name | String | Rest stop name |
| city | String | City |
| address | Text | Detailed address |
| phone | String | Mobile number |
| String | Email address | |
| manager_name | String | Manager name |
| is_active | Boolean | Active / Inactive |
| facilities | JSON / Array | Services list |
| working_hours | String | Working hours (e.g., 24 hours) |
| notes | Text | Additional notes |
| created_at | timestamp | — |
| updated_at | timestamp | — |
5. Available Facilities
In API/DB → stored as facilities[].
6. Statuses
| UI Label | Enum | Meaning |
|---|---|---|
| Active | ACTIVE | Rest stop available for trip assignment |
| Inactive | INACTIVE | Hidden from trip creation and B2C |
7. Business Rules
BR-1. Only active rest stops appear in Trip Creation
Providers selecting rest stops for outbound and return stops will only see is_active = true.
BR-2. Rest stop must include contact information
Based on UI fields: Mobile number, Email, Manager name
BR-3. Facilities must be represented via boolean flags
Because the UI uses checkboxes.
BR-4. Rest stop must have a valid city and address
Needed for proper listing and for B2C Trip Details.
BR-5. Deleting rest stop is restricted
Cannot delete if used in an active or upcoming trip, or has dependencies in trip itineraries. Soft delete recommended.
BR-6. Working hours must match predefined patterns
UI uses a dropdown; values are limited (e.g., 24 hours).
8. Actions & Behaviors
A-1. Add New Rest Stop
Modal sections:
- Rest stop information
- Contact information
- Available facilities
- Additional information
- Status
A-2. Edit Rest Stop
Provider can modify all fields except provider_id. Changing status immediately impacts availability during trip creation.
A-3. Delete Rest Stop
Modal: 'Delete Rest Stop!' — Confirmation required.
A-4. Select Rest Stop
Modal inside Trip Creation. Displayed as cards with Name, Location, Facilities, Add button. Provider selects for outbound and return stops.
9. Validation Rules
VR-1. Required fields
Rest stop name, City, Address, Mobile number, Manager name, Status
VR-2. Email & phone must be valid formats
Phone must follow Saudi mobile pattern. Email must match standard email verification.
VR-3. At least one facility recommended (not required)
UI allows 0, but UX best practice is to have at least 1.
VR-4. Notes optional
The 'Additional notes' field is optional and unstructured text.
10. Error Cases
| Case | Message |
|---|---|
| Missing required field | Please complete all required fields |
| Invalid email | Invalid email address |
| Invalid phone | Invalid phone number |
| Deletion blocked | Cannot delete this rest stop as it is linked to active trips |
| Duplicate name (per provider) | Rest stop name is already in use |
12. Cross-Module Relations
- Trip Module → uses Rest Stops for outbound and return journeys
- Rating Module → users rate 'Rest Stops' separately post-trip
- Buses/Hotels Modules → no direct relationship
- Financial Module → no financial impact
- Provider Module → rest stop belongs to provider