analysis/04-functional-spec/hotels-module.md
Hotels List
Hotels Module – Functional Specification
1. Purpose
The Hotels Module manages all hotel records used within trips. A Hotel is a core accommodation resource that appears in Trip Details (B2C Mobile/Web) and is created/managed by Providers via the Provider Portal.
This module covers:
- Adding and maintaining hotel data
- Defining hotel rating (5, 6, 7 stars as seen in UI)
- Managing hotel facilities
- Location and contact information
- Uploading hotel images
- Controlling hotel activation status (Active / Inactive)
- Integrating hotels in trip creation, itineraries, and B2C display
2. Involved Entities
| Entity | Description |
|---|---|
| Hotel | Accommodation resource offered by the provider. |
| Provider | Company that manages hotels. |
| Trip | Trips reference one hotel (in the trip's accommodation section). |
Note: There is no separate "Hotel Manager" entity; manager/owner information is stored inside the hotel record.
4. Hotel Entity Fields
| Field | Type | Notes |
|---|---|---|
| id | PK | — |
| provider_id | FK | — |
| name | String | Hotel Name |
| city | String | City / Region |
| phone | String | Mobile Number |
| String | Email Address | |
| star_rating | Integer | Supports (5, 6, 7) per UI |
| address | Text | Address |
| maps_url | Text | Google Maps direct link |
| is_active | Boolean | Active / Inactive |
| description | Text | Detailed hotel description |
| images | Array of URLs | PNG/JPG/GIF supported |
| created_at | timestamp | — |
| updated_at | timestamp | — |
5. Star Rating
The UI displays ratings above 5 stars, which must be supported exactly as shown.
6. Facilities & Amenities
7. Statuses
| UI Label | Enum | Meaning |
|---|---|---|
| Active (فعالة) | ACTIVE | Hotel available for trip assignment |
| Inactive (غير فعالة) | INACTIVE | Hidden from trip creation and B2C |
8. Business Rules
BR-1. Hotel must belong to its provider
No shared hotels between different providers.
BR-2. Only active hotels are selectable in trip creation
When a provider creates a new trip, only hotels with is_active = true appear.
BR-3. Star rating supports > 5 stars
The UI displays 5, 6, and 7 stars. This must be supported exactly as shown.
BR-4. Hotel must support at least one image
Uploading at least 1 hotel image is required. Allowed formats: PNG, JPG, GIF. Size limit: max 10MB
BR-5. Contact fields are required
Because UI requires: Mobile Number, Email, Manager Name
BR-6. Cannot delete hotel linked to future trips
Trips referencing the hotel prevent deletion.
Error: Cannot delete this hotel as it is linked to active trips
MAP-01. View on Map button (Slice 7)
In B2C Trip Details, 'View on Map' button visible ONLY if hotel.maps_url is not null/empty. Opens Google Maps in new tab.