masaruk Logo

Use Cases & Acceptance Criteria

File: 02-product/use-cases-and-acceptance-criteria.md

This document defines all functional use cases for MASARUK across: B2C Web & Mobile, B2B Provider Portal, Admin / Super Admin, and Finance Module.

1. B2C (End User) Use Cases

UC-B2C-01

Browse Trips

Purpose: Allow users to discover available trips (Tourism / Umrah)
Actors: End User (Web + Mobile)
Pre-Conditions:
  • Trips exist in the system
  • Trip status = Active
Main Flow:
  1. User opens 'Home'
  2. Sees banners, search bar, companies, and recommended destinations
  3. Navigates to 'Trips'
  4. Filters by: All Trips / Tourism / Umrah
  5. Opens trip details by tapping a card
Acceptance Criteria:
  • Filter buttons correctly show only matching trips
  • Trips with inactive status do not appear
  • Trip cards must show: Trip duration, Destination, Price, Book Trip button
UC-B2C-02

View Trip Details

Purpose: Display full trip information to help the user decide
Main Flow:
  1. User opens trip details
  2. Navigates between tabs: Trip Overview / Details / Daily Program
  3. Reviews: What's included, Accommodation details, Transportation, Rest stops, Terms
Acceptance Criteria:
  • All fields must match Provider inputs exactly
  • Tabs must switch without page reload
  • 'Book Now' must always be visible or fixed at bottom
UC-B2C-04

Enter Traveller Data

Required Fields:
First nameLast nameID/Iqama numberGenderPhone numberDate of birthEmail
Acceptance Criteria:
  • Missing required fields trigger inline validation
  • Email must be valid format
  • ID/Iqama number must be numeric
  • Number of travellers must match number of input forms
UC-B2C-05

Complete Payment

Supported Payment Methods:
Credit Card / MadaSTC PaySADAD
Post-Conditions:
  • PaymentTransaction created
  • Booking created with status = Confirmed / Paid
Acceptance Criteria:
  • Invalid card details display error
  • Successful payment navigates to confirmation screen
  • PaymentTransaction stores: amount, payment_method, date, status
UC-B2C-07

View 'My Bookings'

Purpose: Allow users to see past and upcoming trips
Flow:
  1. User opens My Bookings
  2. Selects: All Bookings / Upcoming / Completed
  3. Opens specific booking
Acceptance Criteria:
  • Booking status must match admin mapping: Confirmed, Cancelled, Completed
  • Dates must reflect trip schedule
UC-B2C-08

Rate Trip

Flow:
  1. User receives popup after trip completion
  2. Rates trip overall
  3. Rates details (optional): Program, Hotel, Bus, Driver, Rest stops
  4. Submits form
Acceptance Criteria:
  • Rating saved with per-category structure
  • User cannot rate same trip twice
UC-B2C-09

Cancel Booking

Pre-Conditions:
  • Booking status = CONFIRMED or UPCOMING
  • Trip start date has not passed
Post-Conditions:
  • Booking doesn't appear in 'Upcoming trips'
  • Booking appears in 'Cancelled' tab
  • Refund processed according to policy
Acceptance Criteria:
  • User receives cancellation confirmation
  • Cancelled booking cannot be rated

2. Provider (B2B) Use Cases

UC-PROV-01

Manage Trips

Flow:
  1. Provider opens Trips Management
  2. Views trips list
  3. Creates/edits/deletes trips
  4. Sets status: Active / Inactive
Acceptance Criteria:
  • Trip cannot be created without required fields
  • Status change hides/shows trip immediately in B2C apps
UC-PROV-02

Manage Buses

Fields:
Plate numberModelSeat capacityAmenitiesDriver
Statuses: Active / Inactive / Under Maintenance
Acceptance Criteria:
  • Bus in 'Under Maintenance' should not appear in trip creation
UC-PROV-03

Manage Hotels

Fields:
Hotel nameCityStar ratingAmenitiesLocation
Acceptance Criteria:
  • Hotel in 'Inactive' should not appear in trip creation dropdowns
  • Hotel star rating must be 5, 6, or 7 (per UI options)
  • Google Maps link must be valid URL format
UC-PROV-05

Create Ad Campaigns

Flow:
  1. Provider opens Ad Management
  2. Clicks 'Create Ad Campaign'
  3. Selects trip
  4. Sets: Budget, Start date, End date
  5. Completes payment
Acceptance Criteria:
  • Ad not created unless payment succeeds
  • Status transitions: Scheduled → Active → Ended or Paused

3. Admin Use Cases

UC-ADMIN-01

Manage Bookings

Flow:
  1. Admin opens Bookings Management
  2. Views bookings table
  3. Opens booking details modal
  4. Sends message to customer if needed
  5. Prints booking
Acceptance Criteria:
  • BookingPassenger list must match B2C inputs
  • Payment data must match transaction
UC-ADMIN-02

Review Financial Reports

Flow:
  1. Opens Financial Reports
  2. Reviews cards: Total sales, Platform commission, Total ad revenue, Net profit
  3. Reviews transactions
  4. Exports file
Acceptance Criteria:
  • Export file contains table data exactly
  • Status must match: In Balance, Transferred, Refunded

4. Authentication Use Cases

UC-AUTH-01

Sign Up

Flow:
  1. User fills registration form
  2. Optional: Sign up with Google/Facebook
  3. Account created
Acceptance Criteria:
  • Duplicate email or phone blocked
  • Password confirmation must match
UC-AUTH-02

Login

Flow:
  1. Enters email/phone + password
  2. Clicks 'Login'
Acceptance Criteria:
  • Invalid credentials return clear error
  • Successful login creates session/token
UC-AUTH-03

Forgot Password / Reset

Flow:
  1. User clicks 'Forgot password?'
  2. System requests email or phone
  3. User receives OTP or reset link
  4. User enters new password and confirms
  5. System updates password
Acceptance Criteria:
  • OTP/reset link expires after defined period
  • New password must meet security requirements
  • User redirected to login after success

5. Cross-Module Use Cases

Use CaseModulesAcceptance Criteria
BookingTrips, Payments, FinancialsPayment must complete before booking creation; booking status must map correctly between Arabic UI labels and internal enums
Ad CampaignTrips, PaymentsPayment required; status must auto-update based on campaign dates and payment result
RatingTrips, Ratings, Hotels, Buses, RestStopsOnly completed trips can be rated; ratings linked to relevant resources
Financial ReportsBookings, Payments, AdCampaignsAll values must match calculated formulas and VAT rules once confirmed
Info

Cross-References:

  • • 01-overview/product-identity-and-scope.md
  • • 01-overview/stakeholders-and-personas.md
  • • 02-product/core-user-journeys.md
  • • 03-domain-model/domain-entities-and-relationships.md
  • • 03-domain-model/statuses-and-lifecycles.md
  • • 04-functional-spec/*
  • • 05-ux-and-flows/ux-flows-b2c-web-and-mobile.md
  • • 05-ux-and-flows/ux-flows-admin-and-provider.md