analysis/04-functional-spec/trips-module.md

Trips Management

Trips Module – Functional Specification

1. Purpose

The Trips Module is the core of the MASARUK system. It defines how tourism programs (trips) are created, managed, displayed, booked, and synchronized across:

Provider Portal (B2B)
Admin Panel
B2C Web Platform
Mobile Apps (Flutter)
REST API Layer

2. Involved Entities

2.1 Primary Entity

Entity	Description
Trip	Main tourism program containing all details required for booking, pricing, transportation, accommodation, itinerary, services, and activation status.

2.2 Related Entities

Entity	Relationship
Hotel	Trip → belongs_to
Bus	Trip → belongs_to
RestStop	Trip → has_many (go & return lists)
Provider	Trip → belongs_to provider
Booking	Trip → has_many bookings
AdCampaign	Trip → may have_zero_or_many campaigns
Rating	Trip → receives ratings after completion

4. Trip Data Model

4.1 Basic Trip Information

Field (English)	Arabic UI Label	Type
trip_name	اسم الرحلة	string
trip_type	نوع الرحلة (عمرة/سياحية)	enum
nights_count	عدد الليالي	integer
days_count	عدد الأيام	integer
visited_cities	المدن المزارة	string
departure_date	تاريخ المغادرة	date
return_date	تاريخ العودة	date
departure_city	مدينة المغادرة	string
arrival_city	مدينة الوصول	string
base_price	السعر	decimal
currency	العملة	string (SAR fixed)
max_capacity	العدد الأقصى للحجوزات	integer
description	تفاصيل البرنامج	longtext
status	الحالة	enum

4.2 Accommodation (Hotel)

Field	Arabic Label	Type
hotel_id	الفندق	FK (hotel)
hotel_room_type	نوع الغرفة	string
stay_duration	مدة الإقامة	integer
hotel_image_list	صور الفندق	array/files

4.3 Transportation (Bus + Driver)

Field	Arabic Label	Type
bus_id	وسيلة النقل	FK (bus)
driver_name	اسم السائق	derived from bus
driver_mobile	رقم الجوال	derived from bus
bus_features	الخدمات المتوفرة	array

4.4 Rest Stops (Go & Return)

Field	Description
rest_stop_id	Rest stop FK
sequence	Order in trip
type	GO / RETURN

4.5 Media & Assets

Field	Description
image_list	Trip images (PNG, JPG, GIF – max 10MB each)

5. Trip Status & Lifecycle

UI Label	Enum	Meaning
نشطة	ACTIVE	Visible + bookable
غير نشطة	INACTIVE	Hidden from B2C
ملغاه	CANCELLED	Not bookable
منتهية	COMPLETED	End date passed

Derived Transitions

INACTIVE → ACTIVE
ACTIVE → CANCELLED
ACTIVE → COMPLETED (auto by date)
CANCELLED → INACTIVE (optional manual)

6. Functional Requirements

6.1 CRUD Operations

Operation	Provider	Admin
Create Trip	✅	✅
Edit Trip	✅ (own only)	✅
Delete Trip	✅ (own only)	✅
View All Trips	❌ (own only)	✅
Change Status	✅	✅

6.2 B2C Display Requirements

Trips List

• Filter by trip type (عمرة / سياحية)
• Sort by price, popularity, date
• Search by destination
• Show only ACTIVE trips

Trip Details (Slice 7 + 8 SSOT)

3 Tabs + Date Selection — No Random Dates:

• عرض الرحلة (Overview): Hero images, summary, price, duration
• التفاصيل (Details): Hotel + 'View on Map', Transport, Rest Stops, Terms
• عن البرنامج (About Program): Program intro + Daily itinerary (NOT under transport)
• Date Selector (Slice 8): Dropdown/list of scheduled dates ONLY — NO calendar picker

Scheduled Dates (Slice 8 SSOT)

CRITICAL: No arbitrary date selection in B2C

• DEC-S8-01: No calendar/date picker in booking flow
• DEC-S8-02: User selects from provider-defined dates only
• DEC-S8-04: Dropdown shows: Date + Status + Remaining capacity
• AC-S8-05: CTA disabled if no dates available
• Booking binds to: scheduled_date_id (FK)

Scheduled Dates Management (Slice 9 SSOT) ✅ OFFICIAL

Admin/Provider can manage dates. B2C is read-only. All decisions OFFICIAL.

• CRUD: Create single, Bulk generate, Edit, Delete, Status change
• Statuses: ACTIVE (🟢), INACTIVE (⚪), SOLD_OUT (🟠), CANCELLED (🔴)
• DEC-S9-01: Approval inherits from Trip (no separate approval)
• DEC-S9-02: CANCELLED dates hidden in B2C (not shown)
• DEC-S9-03: cutoff_hours range: 0..168
• DEC-S9-04: capacity: NULL=unlimited, ≥1=valid, 0=INVALID
• DEC-S9-05: Auto SOLD_OUT on booking confirmation
• DEC-S9-06: CANCELLED is terminal (no reactivation)
• DEC-S9-07: Manual SOLD_OUT allowed (audit logged)
• Validation: S9-V-01..S9-V-08 (see trips-module.md §12.9)
• RBAC: PROVIDER_STAFF cannot bulk/delete/cancel

7. UI Bugs Noted

UI Bugs Preserved Verbatim

Field	Expected Placeholder	Actual (Bug)
عدد الليالي	ادخل عدد الليالي	ادخل رقم الهوية/الإقامة
نوع الغرفة	ادخل نوع الغرفة	ادخل رقم الطوارئ

These bugs are documented in admin-provider-ui-inventory.md.