Skip to content

Local Hotel Management Module - Functional Specification

Overview

The Local Hotel Management module is an internal inventory management system designed for travel agencies to maintain a database of contracted hotels with comprehensive rate management, room inventory, and pricing calendars. This module is distinct from hotel search/booking functionality—it serves as a hotel contracting and pricing configuration tool for properties the agency has direct or indirect agreements with.

Purpose and Scope

Primary Purpose: Maintain a centralized repository of contracted hotel properties with detailed room configurations, seasonal pricing, meal plan structures, and market-specific rates to enable: - Quick price quotation for customer inquiries - Standardized rate management across multiple markets (UAE, GCC, ROW) - Efficient hotel inventory search with cost/margin calculations - Integration with group booking and quotation processes

Key Distinction: This is NOT a real-time hotel availability system—it is a contract rate management database for hotels where the agency has negotiated rates.

Core Concepts

1. Hotel Master Data

Central repository of contracted hotel properties with operational parameters.

2. Room Types

Individual room configurations within each hotel (Standard King, Deluxe Suite, Family Room, etc.) with capacity and bedding details.

3. Room Calendar (Rate Calendar)

Date-specific pricing entries for each room type containing: - Base rates (normal day pricing) - Special day rates (weekend/holiday pricing) - Rate calculation rules (absolute, percentage, additive) - Booking windows (book-from and book-to dates) - Availability status (available, stop sale, on request) - Minimum length of stay (MLOS) requirements - Market segmentation (UAE, GCC, ROW)

4. Meal Plans

Standardized meal offerings (Room Only, Bed & Breakfast, Half Board, Full Board, All Inclusive) with: - Base plan included in room rate - Supplemental costs for upgrades (adult and child rates) - Per-hotel customization

5. Markets

Geographic customer segments with differentiated pricing: - UAE Market: Local residents - GCC Market: Gulf Cooperation Council countries - ROW (Rest of World): International travelers

6. Rate Calculation Types

Flexible pricing models for supplements and special rates: - ABS (Absolute): Fixed price regardless of base rate - ADD (Additive): Fixed amount added to base rate - PCT (Percentage Add): Percentage added to base rate - PCO (Percentage Of): Percentage of base rate

Primary Use Cases

Use Case 1: Hotel Master Data Management

Actor: Agency Operations Manager

Description: Maintain master database of contracted hotels with operational details.

Preconditions: - User has employee access rights - Hotel contracted by agency (direct or via DMC)

Main Flow: 1. Navigate to hotel management interface 2. Search existing hotels by area/name or create new hotel entry 3. Enter/update hotel master information: - Full name and short name - Country, city, area/emirate - Star rating (1-5 stars) - Hotel code and product ID - Check-in/check-out times (e.g., "14:00", "12:00") - Child and infant age definitions - Release days (cancellation notice period) - Hotel fees and fee descriptions - Terms and conditions - Reservation contact emails - Hotel description (marketing text) - Contract type flags (direct contract, indirect/DMC) 4. Save hotel record

Postconditions: - Hotel appears in searchable hotel list grouped by area - Hotel available for room configuration - Hotel selectable in quotation/booking processes

Business Rules: - Hotel must have unique hotel code (shDes) - Check-in time must be before check-out time - At least one contract type must be flagged (direct or indirect) - Star rating must be between 1 and 5 - Child age definition must be greater than infant age

Use Case 2: Room Type Configuration

Actor: Agency Operations Manager

Description: Define room types for a hotel with capacity and bedding details.

Preconditions: - Hotel master record exists - User has employee access

Main Flow: 1. Select hotel from hotel list 2. Navigate to "Rooms Info" tab 3. Click "Add Room" to create new room type 4. Enter room details: - Room name (e.g., "Standard King", "Deluxe Suite") - Room description - Maximum occupancy (total persons) - Maximum adults (of the occupancy) - Extra bed availability (checkbox) - Extra bed required for additional adults (checkbox) - Bedding description (e.g., "1 King bed" or "2 Twin beds") - Room notes (restrictions, features) 5. Save room configuration 6. Room appears in room selection dropdown

Alternate Flow 2a: Edit Existing Room 1. Select room from dropdown 2. Modify room details in form 3. Click "Save changes"

Postconditions: - Room type available for rate calendar configuration - Room type appears in hotel search results

Business Rules: - Maximum adults cannot exceed maximum occupancy - If extra bed is required for additional adults, extra bed must be marked as available - Room name must be unique within the hotel - At least one room must exist before pricing can be configured

Use Case 3: Create Room Pricing Calendar

Actor: Revenue Manager

Description: Configure date-specific pricing for room types with seasonal variations, special day rates, and market segmentation.

Preconditions: - Hotel and room type exist - User has employee access - Market selected (UAE/GCC/ROW)

Main Flow: 1. Select hotel and room type 2. Select target market 3. Click "Set pricing" to open calendar creation dialog 4. Define stay period: - Stay from date (check-in range start) - Stay to date (check-in range end) 5. Define booking window: - Book from date (earliest booking date) - Book to date (latest booking date) 6. Configure rate structure: - Promo code (optional promotional identifier) - Room status: Available / Stop Sale / On Request - Rate base: Single / Double / Triple / Quadruple (occupancy basis) - Meal base: Room Only / BB / HB / FB / AI (included plan) - MLOS: Minimum length of stay (normal days) - MLOS (Holiday): Minimum length of stay for special days 7. Set base room rates: - Room rate (base rate for normal days) - Extra bed rate (supplement for extra bed) - Holiday rate (special day rate) - Holiday rate type: ABS / ADD / PCT / PCO 8. Define holiday pattern: - Weekends Only / All Days / No holidays 9. Configure additional occupant rates: - Adult rate (normal) and Adult rate (holiday) - Adult rate type: ABS / ADD / PCT / PCO - Child rate (normal) and Child rate (holiday) - Child rate type: ABS / ADD / PCT / PCO 10. Configure meal plan supplements: - Select meal plan (RO / BB / HB / FB / AI Lite / AI / AI Plus) - Enter adult supplement rates (normal and holiday) - Enter child supplement rates (normal and holiday) - Click "Add >>" to add to supplement list - Repeat for additional meal plans 11. Click "Save & Close" or "Save & Continue"

Alternate Flow 3a: Copy Rates from Another Room 1. After selecting room, choose "Copy rates from room" dropdown 2. Select source room 3. Enter date range to copy 4. Click "Copy" 5. System copies all calendar entries for that date range to current room

Alternate Flow 3b: Quick Rate Update 1. Select room and date range 2. Click "Quick rates" 3. System groups calendar into continuous periods 4. Update base rate and/or holiday rate for each period 5. Click "Save" 6. Rates updated for all days in each period

Alternate Flow 3c: Edit Existing Calendar Range 1. Click "Edit Range" on displayed calendar 2. System populates dialog with existing rate structure 3. Modify desired rates 4. Click "Save & Close" 5. All days in range updated with new rate structure

Postconditions: - Calendar entries created for each day in stay period - Days marked as special days (weekends) have special day flag set - Calendar entries visible in calendar grid view - Room searchable with calculated pricing

Business Rules: - Stay end date must be after stay start date - Booking period must start before or on stay start date - Booking end must be after booking start - Base rate must be greater than zero - MLOS must be at least 1 night - Meal supplements stored as JSON array in calendar entry - System auto-identifies weekends (Friday-Saturday for UAE/GCC markets) - Rate calculation types determine how supplements are calculated: - ABS: Use exact rate value - ADD: Base rate + supplement value - PCT: Base rate + (Base rate × supplement percentage / 100) - PCO: Base rate × (supplement percentage / 100)

Use Case 4: Manage Hotel Meal Plans

Actor: Revenue Manager

Description: Configure which meal plans are available for a hotel with their supplement costs.

Preconditions: - Hotel exists - Global meal plan list configured (RO, BB, HB, FB, AI, etc.)

Main Flow: 1. Select hotel 2. Click "Meal plans" button on Hotel Info tab 3. System displays all available meal plans with checkboxes 4. Select meal plans offered by this hotel 5. Enter adult and child supplement costs for each selected plan 6. Click "Save"

Postconditions: - Selected meal plans available for calendar configuration - Supplement costs pre-populated when creating calendar entries - Meal plans available in search filters

Business Rules: - At least one meal plan must be configured - Supplement costs can be zero (included in base rate) - Child supplements typically lower than adult supplements

Use Case 5: View Rate Calendar (Monthly Grid View)

Actor: Revenue Manager

Description: View comprehensive monthly calendar showing all room rates at a glance.

Preconditions: - Hotel has rooms with configured calendars - Market selected

Main Flow: 1. Click "Rates" button on Hotel Info tab 2. System displays hotel calendar dialog 3. Select market (UAE/GCC/ROW) 4. Select month and year 5. System displays grid with: - Rows: Room types - Columns: Days 1-31 - Cells: Base rate colored by availability status: - Green: Available - Yellow: Special day (weekend/holiday) - Red: Stop sale - Blue: On request - Gray: No rate configured 6. Hover over cell to see tooltip with: - Stay date - MLOS - Extra adult/child supplements - Meal supplements 7. Navigate months using previous/next buttons

Postconditions: - User has visual overview of rate structure - Gaps in pricing identified (gray cells) - Rate inconsistencies visible across room types

Business Rules: - Calendar displays current hotel's configured rooms only - Empty cells (no rate) shown as 'X' in gray - Market selector filters calendar entries by selected market

Use Case 6: Search Contracted Hotel Accommodation

Actor: Sales Agent / Operations Manager

Description: Search contracted hotel inventory with pricing for customer inquiries.

Preconditions: - Hotels configured with rooms and rate calendars - User provides search criteria

Main Flow: 1. Enter search parameters: - Check-in date (stay start) - Check-out date (stay end) - Adults (number of adult guests) - Children (<12 years old) - Meal plan (desired meal basis or "Any") - Margin % (agency markup percentage) - Area (emirate/region filter or "Any") - Budget (maximum price filter, optional) - Market (UAE/GCC/ROW) 2. Click "Search" 3. System calculates pricing for each available room: - Retrieves calendar entries for stay period and market - Calculates base cost based on occupancy and rate base - Adds extra adult/child supplements as needed - Adds extra bed cost if required - Adds meal plan supplements - Calculates special day premiums - Sums total cost for entire stay - Applies margin to calculate sell price 4. System displays results sorted by price (low to high): - Hotel name with lowest room price - Accordion sections per hotel - Table rows per room type showing: - Room description - Meal plan - Total cost (agency cost) - Total price (customer price with margin) - MLOS (highlighted in red if stay is shorter) - Actions: "Breakdown" and "Book" 5. User can click "Breakdown" to see daily cost calculation 6. User can click "Book" to create booking request

Alternate Flow 6a: View Price Breakdown 1. Click "Breakdown" on a search result row 2. System displays breakdown dialog showing: - Header: Room name, number of nights, MLOS warning if applicable - Table with one row per night showing: - Stay date - Calculated cost for that night - Special day indicator - Stop sale/On request warnings - Line items: Base rate, Extra adult charges, Extra child charges, Meal supplements, Extra bed 3. User reviews breakdown and closes dialog

Alternate Flow 6b: Create Booking Request from Search 1. Click "Book" on desired room 2. System displays booking dialog pre-filled with: - Hotel name and room type - Check-in and check-out dates - Meal plan - Calculated price (with margin) - Adult and child counts 3. User enters: - Number of rooms to book - Guest name for reservation - Guest email - Ages of children (if applicable) - Other special requests/notes 4. Click "Book" 5. System creates trip request (lead) with: - Trip name: Guest name + destination - Description: All booking details - Planned revenue: Price × quantity - Contact information 6. System confirms booking request created

Postconditions: - Search results cached for quick reference - User has pricing information for quotation - Optional: Booking request/lead created in CRM

Business Rules: - Room Availability: Room shown if calendar entries exist for all nights in stay period - Stop Sale Rooms: Displayed with warning, price still calculated - On Request Rooms: Displayed with "available on request only" notice - MLOS Validation: If stay nights < MLOS, MLOS shown in red, stay still bookable but flagged - Occupancy Validation: - Adults + Children ≤ MaxOccupancy - Adults ≤ MaxAdults - If Adults > MaxAdults and room has no extra bed, room excluded - If Adults > MaxAdults and extra bed available, extra bed cost added automatically - Cost Calculation (example for 2 adults, 1 child, 3 nights with DBL rate base): - Night 1 (normal): Base rate (DBL) + 0 extra adults + child supplement + meal supplement - Night 2 (normal): Base rate (DBL) + 0 extra adults + child supplement + meal supplement - Night 3 (weekend): Special day rate + 0 extra adults + child supplement (holiday rate) + meal supplement (holiday rate) - Total cost = Sum of 3 nights - Sell price = Total cost × (1 + Margin% / 100) - Meal Plan Matching: - If user selects specific meal plan, only rooms with that plan shown - If user selects "Any", all meal plans shown with their respective supplements - Budget Filter: Rooms with sell price > budget excluded - Area Filter: Only hotels in selected area/emirate shown - Market Filter: Only calendar entries for selected market used in calculation

Use Case 7: Update Room Availability Status

Actor: Revenue Manager

Description: Quickly change availability status for date ranges (e.g., close sales for holidays, open previously closed dates).

Preconditions: - Room has calendar entries configured - Market selected

Main Flow: 1. Select hotel and room 2. Select market and date range to display 3. Click "Show" to load calendar 4. Select status to set: - Available (AV) - Stop Sale (SS) - On Request (OR) - Special Day (SD) 5. Enter "From date" and "To date" for status change 6. Click "Set" 7. System updates all calendar entries in range with new status

Postconditions: - Calendar updated with new availability status - Colors in calendar view reflect changes - Search results reflect availability changes

Business Rules: - Setting "Special Day" only toggles the special day flag; does not change availability - Setting availability statuses (AV/SS/OR) does not affect special day flag - Changes affect only the selected market's calendar entries

Secondary Use Cases

Use Case 8: Manage Hotel Promotions

Actor: Revenue Manager

Description: Create promotional pricing campaigns for hotels/rooms.

Status: Partially implemented (UI placeholders visible in promo-panel tab)

Intended Functionality: - Define promotion with code, name, booking period, stay period, market - Set priority and MLOS for promotion - Associate promotion with specific room types - Configure promotional rate adjustments - Enable/disable promotions - View active promotions

Current Implementation: UI mockup exists but backend integration incomplete

Use Case 9: Hotel Lookup for Quick Selection

Actor: Any employee user

Description: Autocomplete search for hotels by name.

Main Flow: 1. User types partial hotel name in lookup field 2. System searches hotel names matching input 3. System returns list of [name, hotelId] pairs 4. User selects hotel from list 5. System navigates to hotel detail

Usage: Integrated in other modules for hotel selection (e.g., group management, quotations)

Data Entities

Hotel (CHotel)

Description: Master record for contracted hotel properties

Attribute Type Description Constraints
hotelId Integer Primary key Auto-generated
name String Full official hotel name Required
shortName String Abbreviated name for lists Required
shDes String Unique hotel code (10 chars) Required, unique
productId Integer Link to product catalog Optional
country String Country code (e.g., "UAE") Required
city String City name Optional
area String Area/Emirate code (ADB, DXB, SHJ, etc.) Required
stars Integer Star rating (1-5) Required
direct Boolean Direct contract flag Default: false
indirect Boolean Indirect/DMC contract flag Default: false
infant Integer Infant maximum age Default: 2
child Integer Child maximum age Default: 12
chkIn String Check-in time (e.g., "14:00") Optional
chkOut String Check-out time (e.g., "12:00") Optional
release Integer Release days (cancellation notice) Optional
fees Double Hotel fees amount Optional
feesDesc String Description of fees Optional
hotelDesc String Hotel description (marketing) Optional
terms String Terms and conditions Optional
reservationContact String Email addresses for reservations Optional

Business Rules: - At least one of direct or indirect must be true - Child age must be greater than infant age - ShDes (hotel code) must be unique across all hotels

HotelRoom (CHotelRoom)

Description: Room type configuration within a hotel

Attribute Type Description Constraints
roomId Integer Primary key Auto-generated
hotelId Integer Foreign key to Hotel Required
name String Room type name Required
roomDesc String Room description Optional
maxOccupancy Integer Maximum total persons Required
maxAdults Integer Maximum adults Required
extraBed Boolean Extra bed available Default: false
extraBedRequired Boolean Extra bed mandatory for add'l adults Default: false
bedding String Bedding description Optional
notes String Room notes/restrictions Optional

Business Rules: - maxAdults ≤ maxOccupancy - If extraBedRequired = true, extraBed must be true - Room name must be unique within hotel - maxOccupancy must be at least 1

RoomCalendarEntry (CRoomCalendarEntry)

Description: Daily pricing record for a room type in a specific market

Attribute Type Description Constraints
calendarEntryId Integer Primary key Auto-generated
roomId Integer Foreign key to HotelRoom Required
market String Market code (UAE/GCC/ROW) Required
stayDate Date Stay date (check-in) Required
bookFrom Date Booking window start Required
bookTo Date Booking window end Required
rateBase String Rate basis (SGL/DBL/TRPL/QPL) Required
mealBase Integer Base meal plan ID Required
baseRate Double Base room rate (normal day) Required, > 0
specDayRate Double Special day rate Optional
specialDay Boolean Is special day (weekend/holiday) Default: false
sdRateType String Special rate type (ABS/ADD/PCT/PCO) Required if specDayRate set
adultRate Double Extra adult supplement Optional
adultRateType String Adult rate type Required if adultRate set
adultSdRate Double Extra adult supplement (special day) Optional
childRate Double Extra child supplement Optional
childRateType String Child rate type Required if childRate set
childSdRate Double Extra child supplement (special day) Optional
extraBedRate Double Extra bed rate Optional
mealSupplements String (JSON) Array of meal plan supplements Required
mlos Integer Minimum length of stay (normal) Default: 1
sdmlos Integer Minimum length of stay (special day) Default: 1
available Boolean Room available for booking Default: true
stopSale Boolean Room on stop sale Default: false
onRequest Boolean Room available on request only Default: false
promo String Promotional code Optional
vendorId Integer Vendor/partner ID Optional
notes String Special notes for this date Optional
calculatedCost Double Computed total cost (transient) Calculated
breakdown String[] Cost breakdown by line item (transient) Calculated

Business Rules: - Exactly one of available, stopSale, onRequest must be true - If specialDay = true and specDayRate is null, use baseRate for pricing - bookFrom ≤ stayDate - bookTo ≥ bookFrom - Meal supplements stored as JSON array: [{"mealPlan":"BB", "adlRate":[10,15], "chldRate":[5,7]}, ...] - Rate types: ABS (absolute), ADD (add to base), PCT (percentage add), PCO (percentage of base)

MealPlan (CMealPlan)

Description: Global meal plan definitions

Attribute Type Description Constraints
planId Integer Primary key Auto-generated
plan String Plan code (RO, BB, HB, FB, AI, etc.) Required, unique
name String Display name Required
planDesc String Description Optional
planOrder Integer Sort order Optional
adultCost Double Default adult supplement cost Optional
childCost Double Default child supplement cost Optional

Standard Meal Plans: - RO: Room Only - BB: Bed & Breakfast - HB: Half Board (breakfast + dinner) - FB: Full Board (breakfast + lunch + dinner) - AIL: All Inclusive Lite - AI: All Inclusive - AIP: All Inclusive Plus

Business Rules: - Plan code must be uppercase, max 10 characters - Adult cost typically higher than child cost - Default costs can be overridden per hotel

HotelMealPlanAssociation (Implicit)

Description: Many-to-many relationship between Hotel and MealPlan with hotel-specific costs

Attributes: - hotelId (FK to Hotel) - mealPlanId (FK to MealPlan) - adultSupplement (hotel-specific adult cost) - childSupplement (hotel-specific child cost)

Business Rules: - A hotel can have multiple meal plans - Each hotel-meal plan combination has its own supplement costs - If no hotel-specific cost set, use MealPlan default cost

API Endpoints

Hotel Management APIs

POST /hotel/listHotels

Purpose: List hotels filtered by name and/or area

Request: 

{
  "session": "session-token",
  "name": "Hilton",        // Optional: partial name match
  "area": "DXB"            // Optional: area/emirate filter
}

Response: 

{
  "status": "success",
  "data": [
    {
      "hotelId": 101,
      "name": "Hilton Dubai Creek",
      "shortName": "Hilton Creek",
      "shDes": "HILDXBCRK",
      "area": "DXB",
      "city": "Dubai",
      "country": "UAE",
      "stars": 5,
      "direct": true,
      "indirect": false,
      ...
    }
  ]
}

POST /hotel/hotelLookup

Purpose: Autocomplete search for hotels by name

Request: 

{
  "session": "session-token",
  "name": "Hilt"
}

Response: 

{
  "status": "success",
  "data": [
    ["Hilton Dubai Creek", "101"],
    ["Hilton Abu Dhabi", "102"]
  ]
}

POST /hotel/getHotel

Purpose: Retrieve single hotel by ID

Request: 

{
  "session": "session-token",
  "id": 101
}

Response: 

{
  "status": "success",
  "data": {
    "hotelId": 101,
    "name": "Hilton Dubai Creek",
    ...
  }
}

POST /hotel/saveHotel

Purpose: Create or update hotel record

Request: 

{
  "session": "session-token",
  "hotel": {
    "hotelId": null,       // null for new, ID for update
    "name": "Hilton Dubai Creek",
    "shortName": "Hilton Creek",
    "shDes": "HILDXBCRK",
    "area": "DXB",
    "country": "UAE",
    "stars": 5,
    ...
  }
}

Response: 

{
  "status": "success",
  "data": {
    "hotelId": 101,
    ...
  }
}

Room Management APIs

POST /hotel/listHotelRooms

Purpose: List all rooms for a hotel

Request: 

{
  "session": "session-token",
  "hotelId": 101
}

Response: 

{
  "status": "success",
  "data": [
    {
      "roomId": 501,
      "hotelId": 101,
      "name": "Standard King",
      "roomDesc": "King bed room",
      "maxOccupancy": 3,
      "maxAdults": 2,
      "extraBed": true,
      "extraBedRequired": true,
      "bedding": "1 King bed",
      "notes": "City view"
    },
    ...
  ]
}

POST /hotel/saveRoom

Purpose: Create or update room type

Request: 

{
  "session": "session-token",
  "room": {
    "roomId": null,
    "hotelId": 101,
    "name": "Standard King",
    "maxOccupancy": 3,
    "maxAdults": 2,
    ...
  }
}

Response: 

{
  "status": "success",
  "data": {
    "roomId": 501,
    ...
  }
}

Meal Plan APIs

POST /hotel/listMealPlans

Purpose: List meal plans (global or hotel-specific)

Request (Global): 

{
  "session": "session-token"
}

Request (Hotel-Specific): 

{
  "session": "session-token",
  "hotelId": 101
}

Response: 

{
  "status": "success",
  "data": [
    {
      "planId": 1,
      "plan": "RO",
      "name": "Room Only",
      "adultCost": 0.0,
      "childCost": 0.0
    },
    {
      "planId": 2,
      "plan": "BB",
      "name": "Bed & Breakfast",
      "adultCost": 50.0,
      "childCost": 25.0
    },
    ...
  ]
}

POST /hotel/updateMealPlans

Purpose: Update hotel's meal plan associations with custom costs

Request: 

{
  "session": "session-token",
  "hotelId": 101,
  "plans": [
    {
      "mealPlanId": 2,
      "adultSupplement": 60.0,
      "childSupplement": 30.0
    },
    {
      "mealPlanId": 3,
      "adultSupplement": 100.0,
      "childSupplement": 50.0
    }
  ]
}

Response: 

{
  "status": "success",
  "data": [
    {
      "planId": 2,
      "plan": "BB",
      "name": "Bed & Breakfast",
      "adultCost": 60.0,
      "childCost": 30.0
    },
    ...
  ]
}

Calendar Management APIs

POST /hotel/createRoomCalendar

Purpose: Create calendar entries for a date range

Request: 

{
  "session": "session-token",
  "stayFrom": "01-12-2025",
  "stayTo": "31-12-2025",
  "specDays": "WE",         // WE=Weekends, ALL=All days, NO=No special days
  "template": {
    "roomId": 501,
    "market": "UAE",
    "rateBase": "DBL",
    "mealBase": 2,
    "baseRate": 500.0,
    "specDayRate": 600.0,
    "sdRateType": "ABS",
    "adultRate": 100.0,
    "adultRateType": "ABS",
    "adultSdRate": 120.0,
    "childRate": 50.0,
    "childRateType": "ABS",
    "childSdRate": 60.0,
    "extraBedRate": 80.0,
    "mlos": 1,
    "sdmlos": 2,
    "available": true,
    "stopSale": false,
    "onRequest": false,
    "bookFrom": "01-11-2025",
    "bookTo": "30-11-2025",
    "promo": "WINTER2025",
    "mealSupplements": "[{\"mealPlan\":\"BB\",\"adlRate\":[60,70],\"chldRate\":[30,35]}]"
  }
}

Response: 

{
  "status": "success",
  "data": [
    {
      "calendarEntryId": 10001,
      "roomId": 501,
      "market": "UAE",
      "stayDate": 1733097600000,  // timestamp
      "specialDay": false,
      "baseRate": 500.0,
      ...
    },
    ...  // One entry per day in range
  ]
}

POST /hotel/listRoomCalendar

Purpose: Retrieve calendar entries for date range

Request (by Room): 

{
  "session": "session-token",
  "roomId": 501,
  "market": "UAE",
  "fromDate": "01-12-2025",
  "toDate": "31-12-2025"
}

Request (by Hotel - all rooms): 

{
  "session": "session-token",
  "hotelId": 101,
  "market": "UAE",
  "fromDate": "01-12-2025",
  "toDate": "31-12-2025"
}

Response: 

{
  "status": "success",
  "data": [
    {
      "calendarEntryId": 10001,
      "roomId": 501,
      "market": "UAE",
      "stayDate": 1733097600000,
      "baseRate": 500.0,
      "specialDay": false,
      "available": true,
      "stopSale": false,
      "onRequest": false,
      "mlos": 1,
      ...
    },
    ...
  ]
}

POST /hotel/updateRoomCalendar

Purpose: Update existing calendar entries for a date range

Request: 

{
  "session": "session-token",
  "stayFrom": "15-12-2025",
  "stayTo": "25-12-2025",
  "template": {
    "roomId": 501,
    "baseRate": 800.0,       // Only fields present will be updated
    "specDayRate": 1000.0,
    "stopSale": true
  }
}

Response: Same format as createRoomCalendar

POST /hotel/copyRoomCalendar

Purpose: Copy calendar from one room to another

Request: 

{
  "session": "session-token",
  "fromRoom": 501,
  "toRoom": 502,
  "market": "UAE",
  "fromDate": "01-12-2025",
  "toDate": "31-12-2025"
}

Response: 

{
  "status": "success",
  "data": {
    "recordsCopied": 31
  }
}

POST /hotel/readRoomPeriods

Purpose: Get summary of rate periods (continuous date ranges with same rate)

Request: 

{
  "session": "session-token",
  "roomId": 501,
  "market": "UAE",
  "fromDate": "01-12-2025",
  "toDate": "31-12-2025"
}

Response: 

{
  "status": "success",
  "data": [
    {
      "periodStart": 1733097600000,
      "periodEnd": 1734825600000,
      "roomId": 501,
      "market": "UAE",
      "baseRate": 500.0,
      "specDayRate": 600.0
    },
    ...
  ]
}

Search & Booking APIs

POST /hotel/searchAccommodation

Purpose: Search contracted hotels with pricing calculation

Request: 

{
  "session": "session-token",
  "checkin": "15-12-2025",
  "checkout": "18-12-2025",
  "adults": 2,
  "children": 1,
  "meals": "BB",            // Optional: null or "NA" for any
  "area": "DXB",            // Optional: null or "ANY" for all
  "market": "UAE",
  "maxBudget": 2000.0,      // Optional
  "extraBed": false,
  "context": "config"       // "config" for employee view, omit for customer
}

Response: 

{
  "status": "success",
  "data": {
    "input": { ... },       // Echo of search input
    "results": [
      {
        "hotel": {
          "hotelId": 101,
          "name": "Hilton Dubai Creek",
          "shortName": "Hilton Creek",
          "area": "DXB",
          "stars": 5,
          ...
        },
        "rooms": [
          {
            "roomId": 501,
            "roomName": "Standard King",
            "roomDesc": "King bed room with city view",
            "notes": "Extra bed available",
            "mealPlanName": "BB",
            "price": 1650.0,       // Total cost for entire stay
            "mlos": 1,
            "stopSale": false,
            "onRequest": false,
            "calendar": [         // Daily breakdown
              {
                "stayDate": 1734220800000,
                "baseRate": 500.0,
                "specialDay": false,
                "calculatedCost": 550.0,
                "breakdown": [
                  "Base rate (DBL): 500.00",
                  "Meal supplement (BB): 50.00"
                ],
                "available": true,
                "stopSale": false,
                "onRequest": false,
                "mlos": 1
              },
              ...  // One per night
            ],
            "mealSupplements": [
              {
                "mealPlan": "BB",
                "adultSupplement": 60.0,
                "childSupplement": 30.0
              },
              {
                "mealPlan": "HB",
                "adultSupplement": 100.0,
                "childSupplement": 50.0
              }
            ]
          },
          ...  // Other room types
        ]
      },
      ...  // Other hotels
    ]
  }
}

Calculation Logic: 1. For each hotel → for each room type → for each night: 2. Check calendar entry exists for (roomId, market, stayDate) 3. Skip room if any night missing calendar entry 4. For each night, calculate: - Identify rate base (SGL/DBL/TRPL/QPL) - Get base rate (use specDayRate if specialDay=true, else baseRate) - Calculate extra adults: adults - base occupancy - Calculate extra children: children count - Add extra adult charges (if > 0): Apply adultRate/adultRateType calculation - Add extra child charges (if > 0): Apply childRate/childRateType calculation - Add extra bed charge if required - Add meal supplement: Lookup meal plan in mealSupplements JSON, apply costs - Sum all charges = night cost 5. Sum all nights = room total cost 6. If context="config": Return cost as-is (agency cost) 7. If context ≠ "config": Apply sell price markup (not shown in this API, done in frontend) 8. Sort results by room price (ascending)

POST /hotel/createBookingRequest

Purpose: Create trip request (lead) from hotel search

Request: 

{
  "session": "session-token",
  "tripRequest": {
    "customerName": "John Smith",
    "tripName": "John Smith, Dubai",
    "description": "Hotel booking request details...",
    "requestCode": "TR-2025-001",
    "origin": "UAE",
    "destination": "Dubai",
    "startDate": 1734220800000,
    "endDate": 1734480000000,
    "userId": 5,
    "numAdults": 2,
    "numChildren": 1,
    "childAges": "8",
    "contactName": "John Smith",
    "contactEmail": "john@example.com",
    "contactType": "EMAIL",
    "quantity": 1,
    "plannedRevenue": 2000.0
  }
}

Response: 

{
  "status": "success",
  "data": {
    "tripRequestId": 1001,
    "requestCode": "TR-2025-001",
    "customerName": "John Smith",
    ...
  }
}

User Interface Structure

Main Layout

Left Sidebar (25% width): - Search Accordion Panel: - Check-in/Check-out date pickers - Adults/Children number inputs - Meal plan dropdown - Margin % input - Area dropdown - Budget input - Market dropdown (UAE/GCC/ROW) - "Search" button

  • Hotel List Accordion (grouped by area):
  • Expandable area sections (Abu Dhabi, Dubai, Sharjah, etc.)
  • Hotel name buttons within each area
  • Click hotel name → load hotel detail

Main Content Area (75% width): - Hotel Detail Tabs (visible when hotel selected): 1. Hotel Info Tab: - Hotel master data form fields - Buttons: "Add New", "Meal plans", "Rates", "Save"

  1. Rooms Info Tab:

    • Room selector dropdown
    • Room details form
    • Market selector
    • Date range for calendar
    • "Calendar" button → show/hide calendar
    • Calendar grid display area
    • Calendar management tools:
    • "Add Room" → open new room dialog
    • "Save changes" → save room edits
    • "Set pricing" → open calendar creation dialog
    • "Copy rates from room" dropdown + "Copy" button
    • "Quick rates" button
    • Calendar status controls:
    • Status dropdown (Available, Stop Sale, On Request, Special Day)
    • "Set" button

  2. Hotel Promotions Tab (placeholder):

    • Promotion list table
    • Room applicability table
    • Promotion rate configuration form
    • Meal supplements table

  3. Search Results Area (visible after search):

  4. Results grouped by hotel (accordion sections)
  5. Hotel name with lowest room price shown
  6. Expandable sections showing room tables
  7. Each row: Room type, Meal plan, Cost, Price, MLOS, Actions

Dialogs

1. New Room Dialog

Purpose: Create new room type

Fields: - Room name (text) - Description (text) - Occupancy (number) - Max Adults (number) - Extra Bed available (checkbox) - Extra Bed required for add'l adults (checkbox) - Room notes (textarea) - Room bedding description (textarea)

Buttons: "Save", "Cancel"

2. Calendar Creation/Edit Dialog (Large)

Purpose: Configure rate calendar for date range

Sections: 1. Date Configuration: - Stay From/To (date pickers) - Book From/To (date pickers) - Promo Code (text) - Market (dropdown: UAE/GCC/ROW) - Room Status (dropdown: Available/Stop Sale/On Request)

  1. Rate Structure:
  2. Rate base (dropdown: SGL/DBL/TRPL/QPL)
  3. Meal base (dropdown: RO/BB/HB/FB/AI)
  4. MLOS normal (number)

  5. MLOS holiday (number)

  6. Base Rates:

  7. Room Rate (number)
  8. Extra Bed Rate (number)
  9. Holiday Rate (number)
  10. Holiday Days (dropdown: Weekends Only/All Days/No holidays)

  11. Holiday Rate Type (dropdown: ABS/ADD/PCT/PCO)

  12. Additional Rates:

  13. Adult Rate (normal) (number)
  14. Adult Rate (holiday) (number)
  15. Adult Rate Type (dropdown)
  16. Child Rate (normal) (number)
  17. Child Rate (holiday) (number)

  18. Child Rate Type (dropdown)

  19. Meal Supplements:

  20. Meal plan selector (dropdown)
  21. Adult normal/holiday rates (numbers)
  22. Child normal/holiday rates (numbers)
  23. "Add >>" button
  24. Text area showing added supplements

Buttons: "Save & Close", "Save & Continue", "Cancel"

3. Hotel Calendar Dialog (Large)

Purpose: View monthly rate calendar for all rooms

Controls: - Market selector (UAE/GCC/ROW) - Month dropdown (Jan-Dec) - Year input - Previous/Next month buttons - "Show" button - "Close" button

Display: - Table with rows = room types, columns = days 1-31 - Cells show base rate, color-coded by status - Hover tooltip shows rate details

4. Quick Rates Dialog

Purpose: Update rates by period

Display: - Table with columns: Period (from-to), Normal Rate, Holiday Rate - Each row has editable number inputs - Automatically grouped by continuous rate periods

Buttons: "Save", "Close"

5. Meal Plans Dialog

Purpose: Configure hotel's meal plans

Display: - Table with columns: Plan (checkbox + name), Adult Cost, Child Cost - All global meal plans listed - Checked plans = available at this hotel - Cost inputs editable

Buttons: "Save", "Close"

6. Price Breakdown Dialog

Purpose: Show daily cost calculation for search result

Display: - Header: Room name, number of nights, MLOS warning - Table with columns: Date, Price Breakdown - Each row shows one night with: - Date and total cost - Special day indicator - Stop sale/on request warnings - Line items for rate components

Button: "Close"

7. Booking Dialog

Purpose: Create booking request from search result

Fields: - Hotel name (read-only) - Room type (read-only) - Meal plan (read-only) - Check-in/Check-out dates (read-only) - Price (read-only) - Number of rooms (number input, default: 1) - Adults (read-only) - Children (read-only) - Ages of children (text input) - Guest name (textarea) - Guest email (textarea) - Other info for hotel (textarea)

Buttons: "Book", "Cancel"

Business Logic & Validation Rules

Hotel Validation

  1. Hotel name and short name required
  2. Hotel code (shDes) must be unique, max 10 characters
  3. At least one contract type (direct/indirect) must be selected
  4. Star rating 1-5
  5. Child age > Infant age
  6. Check-in time < Check-out time

Room Validation

  1. Room name required and unique within hotel
  2. Max occupancy ≥ 1
  3. Max adults ≤ Max occupancy
  4. If extra bed required for adults, extra bed must be available
  5. Max occupancy and max adults must be positive integers

Calendar Validation

  1. Stay end date > Stay start date
  2. Booking period start ≤ Stay start date
  3. Booking period end ≥ Booking start date
  4. Base rate must be > 0
  5. MLOS ≥ 1
  6. Meal base must reference existing meal plan
  7. Only one availability status can be true (available/stopSale/onRequest)
  8. If special day rate set, special day rate type required
  9. If adult rate set, adult rate type required
  10. If child rate set, child rate type required

Search Validation

  1. Check-in date required
  2. Check-out date required and > check-in date
  3. Adults ≥ 1
  4. Children ≥ 0
  5. Market required (UAE/GCC/ROW)
  6. Budget must be ≥ 0 if specified

Search Filtering Logic

  1. Room Availability: Include room only if calendar entry exists for each night in stay period
  2. Occupancy Fit: Include room only if adults ≤ maxAdults (or maxAdults+1 if extra bed available) AND adults+children ≤ maxOccupancy (or maxOccupancy+1 if extra bed available)
  3. Meal Plan Match: If specific meal plan requested, include only rooms where that meal plan is in mealSupplements array
  4. Area Filter: If area specified (not "ANY"), include only hotels where hotel.area = requested area
  5. Budget Filter: If budget specified, include only rooms where calculated price ≤ budget
  6. Stop Sale: Include rooms on stop sale but flag with warning
  7. On Request: Include on-request rooms but flag with notice
  8. MLOS Warning: Include rooms even if stay < MLOS, but flag MLOS in red

Price Calculation Algorithm

Input: Hotel, Room, CheckIn, CheckOut, Adults, Children, Market, Margin%

Steps: 1. Determine rate base: Map room occupancy to rate base - Single (1 adult, 0 children) → SGL - Double (2 adults, 0 children) → DBL - Triple (3 adults OR 2 adults + children) → TRPL - Quadruple (4 people) → QPL

  1. For each night in [CheckIn, CheckOut): a. Retrieve calendar entry for (roomId, market, stayDate) b. If entry missing → skip this room entirely c. Select base rate:

    • If entry.specialDay = true AND entry.specDayRate is not null → use specDayRate
    • Else → use baseRate d. Calculate extra adults:
    • extraAdults = adults - base occupancy for rate base
    • If extraAdults > 0:
      • Get adultRate and adultRateType (use adultSdRate if specialDay)
      • Apply rate type:
      • ABS: extra = adultRate × extraAdults
      • ADD: extra = adultRate × extraAdults
      • PCT: extra = (baseRate × adultRate / 100) × extraAdults
      • PCO: extra = (baseRate × adultRate / 100) × extraAdults e. Calculate child charges:
    • If children > 0:
      • Get childRate and childRateType (use childSdRate if specialDay)
      • Apply rate type (same logic as adult)
      • extra = calculated child rate × children f. Calculate extra bed charge:
    • If adults > maxAdults AND room.extraBed = true:
      • Add entry.extraBedRate g. Lookup meal supplement:
    • Parse entry.mealSupplements JSON
    • Find meal plan matching requested meal (if specified)
    • If specialDay: use adlRate[1] and chldRate[1]
    • Else: use adlRate[0] and chldRate[0]
    • mealCost = (adultRate × adults) + (childRate × children) h. Night total = baseRate + extraAdultCharges + childCharges + extraBedCharges + mealCost i. Store night total in calendar[i].calculatedCost j. Store breakdown line items in calendar[i].breakdown

  2. Sum all nights = Total cost

  3. Apply margin (if context ≠ "config"):

  4. sellPrice = totalCost × (1 + margin / 100)

  5. Return: Room with price, calendar array, breakdown

User Workflows

Workflow 1: Set Up New Hotel

Actors: Operations Manager

Steps: 1. Click "Add New" button on Hotel Info tab 2. Enter hotel master data: - Name: "Atlantis The Palm" - Short name: "Atlantis Palm" - Hotel code: "ATLDXBPLM" - Country: UAE - Area: DXB - City: Dubai - Stars: 5 - Direct: true - Check-in: 15:00 - Check-out: 12:00 - Child age: 12 - Infant age: 2 - Release days: 7 - Fees: 50 AED per night (Tourism Dirham) - Fees description: "Tourism Dirham - payable at hotel" - Reservation contact: reservations@atlantis.com 3. Click "Save" 4. Hotel saved and appears in hotel list under Dubai

Workflow 2: Configure Rooms for Hotel

Actors: Operations Manager

Preconditions: Hotel exists

Steps: 1. Select hotel from list 2. Navigate to "Rooms Info" tab 3. Click "Add Room" 4. Enter room 1 details: - Name: "Imperial Club King" - Description: "King bed with Burj view" - Max occupancy: 3 - Max adults: 2 - Extra bed: Yes - Extra bed required: Yes - Bedding: "1 King bed, extra bed available" - Notes: "Club lounge access included" 5. Click "Save" 6. Repeat for additional room types: - "Imperial Club Twin" (2 twin beds) - "One Bedroom Suite" - "Two Bedroom Suite" 7. Rooms now available for pricing

Workflow 3: Configure Meal Plans

Actors: Revenue Manager

Preconditions: Hotel and rooms configured

Steps: 1. Select hotel 2. Click "Meal plans" button 3. Check available meal plans: - ☑ Room Only (0 / 0) - ☑ Bed & Breakfast (80 / 40) - ☑ Half Board (150 / 75) - ☑ Full Board (200 / 100) - ☑ All Inclusive (350 / 175) 4. Enter adult/child costs for each 5. Click "Save" 6. Meal plans now available in calendar configuration

Workflow 4: Create Rate Calendar

Actors: Revenue Manager

Preconditions: Hotel, rooms, and meal plans configured

Steps: 1. Select hotel 2. Navigate to "Rooms Info" tab 3. Select room: "Imperial Club King" 4. Select market: UAE 5. Click "Set pricing" 6. Configure winter season (Dec 1 - Feb 28): - Stay from: 01-12-2025 - Stay to: 28-02-2026 - Book from: 01-10-2025 - Book to: 31-01-2026 - Status: Available - Rate base: DBL (double occupancy) - Meal base: BB (breakfast included) - MLOS: 1 (normal), 2 (holidays) - Room rate: 1200 AED - Holiday rate: 1500 AED - Holiday rate type: ABS (absolute) - Holiday days: Weekends Only - Extra bed: 200 AED - Adult rate (normal): 150 AED (ABS) - Adult rate (holiday): 200 AED (ABS) - Child rate (normal): 100 AED (ABS) - Child rate (holiday): 150 AED (ABS) 7. Configure meal supplements: - Meal plan: Half Board - Adult (normal/holiday): 120 / 150 - Child (normal/holiday): 60 / 75 - Click "Add >>" - Repeat for Full Board (180/220 adult, 90/110 child) 8. Click "Save & Close" 9. System creates 90 calendar entries (one per day) 10. Calendar displays in grid view showing rates

Result: Room "Imperial Club King" now has pricing for Dec-Feb in UAE market

Workflow 5: Copy Rates to Other Rooms

Actors: Revenue Manager

Preconditions: One room fully configured with calendar

Steps: 1. Select hotel 2. Navigate to "Rooms Info" tab 3. Select room: "Imperial Club Twin" (target room) 4. Select market: UAE 5. Select "Copy from room" dropdown: "Imperial Club King" 6. Enter date range: 01-12-2025 to 28-02-2026 7. Click "Copy" 8. System confirms: "90 requested, 90 copied. Showing first 31 days." 9. Calendar for "Imperial Club Twin" now populated 10. Edit specific rates if needed (e.g., adjust base rate) 11. Click "Save changes"

Result: "Imperial Club Twin" now has calendar based on "Imperial Club King" with any customizations applied

Workflow 6: Update Rates for High Season

Actors: Revenue Manager

Preconditions: Calendar exists for target period

Steps: 1. Select room with existing calendar 2. Select market 3. Enter date range: 20-12-2025 to 10-01-2026 4. Click "Show" to display calendar 5. Click "Quick rates" button 6. System groups dates into periods (e.g., 20-31 Dec, 1-10 Jan) 7. Update base rates: - 20-31 Dec: 1500 → 2000 (normal), 1800 → 2500 (holiday) - 1-10 Jan: 1200 → 1800, 1500 → 2200 8. Click "Save" 9. System updates all affected calendar entries 10. Refresh calendar to verify changes

Result: High season rates updated efficiently without editing individual days

Workflow 7: Close Sales for Maintenance Period

Actors: Operations Manager

Preconditions: Calendar exists

Steps: 1. Select hotel and room 2. Select market 3. Enter date range to display: 15-01-2026 to 31-01-2026 4. Click "Show" 5. Select status to set: "Stop Sale" 6. Enter range: 20-01-2026 to 25-01-2026 7. Click "Set" 8. Calendar updates showing days 20-25 in red (stop sale) 9. Close calendar view

Result: Room unavailable for bookings Jan 20-25 (shown in red), pricing retained for when sales reopen

Workflow 8: Search for Customer Inquiry

Actors: Sales Agent

Preconditions: Hotels configured with calendars

Steps: 1. Customer inquiry: "Family of 2 adults + 2 children (ages 8 and 10), Dubai, 3 nights, Dec 20-23, Breakfast included" 2. Enter search criteria: - Check-in: 20-12-2025 - Check-out: 23-12-2025 - Adults: 2 - Children: 2 - Meals: BB (Bed & Breakfast) - Margin: 15% - Area: DXB (Dubai) - Budget: (leave blank) - Market: UAE 3. Click "Search" 4. System calculates: - For each hotel in Dubai with BB meal plan - For each room type that fits 2 adults + 2 children - For each of 3 nights (Dec 20, 21, 22): - Base rate (DBL or TRPL depending on room config) - Extra child charges (2 children × child rate) - BB meal supplement (2 adults × adult BB rate + 2 children × child BB rate) - Special day premium if Friday/Saturday - Sum 3 nights = Total cost - Sell price = Cost × 1.15 5. Results displayed sorted by price: - Hotel A: Room X, BB, 4500 AED cost, 5175 AED price, MLOS: 1 - Hotel A: Room Y, BB, 4800 AED cost, 5520 AED price, MLOS: 1 - Hotel B: Room Z, BB, 5200 AED cost, 5980 AED price, MLOS: 2 (in red) 6. Agent clicks "Breakdown" on Hotel A, Room X 7. Breakdown shows: - Dec 20 (Thu): 1450 AED (Base 1000 + 2 children 200 + BB adults 160 + BB children 90) - Dec 21 (Fri - Special): 1700 AED (Base 1200 + 2 children 300 + BB adults 200 + BB children 100) - Dec 22 (Sat - Special): 1700 AED - TOTAL: 4850 AED 8. Agent quotes customer: 5175 AED (price includes 15% margin)

Result: Agent has accurate pricing in seconds, customer receives quote

Workflow 9: Create Booking Request

Actors: Sales Agent

Preconditions: Customer approves quote

Steps: 1. From search results, click "Book" on selected room 2. Booking dialog opens pre-filled: - Hotel: Atlantis The Palm - Room: Imperial Club King - Base: Bed & Breakfast - Check-in: 20-12-2025 - Check-out: 23-12-2025 - Price: AED 5,175.00 - Adults: 2 (read-only) - Children: 2 (read-only) 3. Agent fills additional details: - Number of rooms: 1 - Ages of children: 8, 10 - Guest name: "Mr. John Smith" - Guest email: "john.smith@email.com" - Other info: "Early check-in if possible, king bed preferred" 4. Click "Book" 5. System creates trip request: - Request code: TR-2025-123 - Customer name: Mr. John Smith - Destination: Atlantis The Palm, Dubai - Description: Full booking details in text format - Planned revenue: 5175 AED - Status: New 6. Confirmation: "New reservation request created." 7. Trip request appears in CRM for follow-up

Result: Booking request logged in system, assigned to agent for processing

Integration Points

1. Group Management Module

Integration: Hotel search results can be added directly to group bookings

Usage: - When creating group accommodation in group management - Agent searches hotels using hotel management search - Selected room/rate added to group's hotel list - Pricing automatically populated

2. Quotation Module

Integration: Hotels from local database appear in quotations

Usage: - Quotation builder can include hotel inventory items - Hotel rates pulled from calendar - Automatic cost/price calculation - Itemized quote generation

3. CRM / Trip Request Module

Integration: Booking requests create trip request records

Usage: - Hotel search → Book button → Creates trip request - Trip request includes all booking details - Assigned to sales agent for follow-up - Tracks revenue pipeline

4. Product Catalog

Integration: Hotels can be linked to product catalog items

Usage: - Hotel master record has productId field - Links hotel to product for inventory management - Enables product-level reporting - Cross-module consistency

Non-Functional Requirements

Performance

  • Hotel list load: < 1 second for up to 500 hotels
  • Room calendar creation: < 3 seconds for 90-day range
  • Hotel search: < 2 seconds for up to 50 hotels with 5 rooms each
  • Calendar view load: < 2 seconds for monthly view (all rooms)

Security

  • All endpoints require valid employee session token
  • Non-employee users cannot access configuration features
  • Hotel search can be accessed by non-employees (context parameter)
  • Session validation on every API call

Data Integrity

  • Calendar entries cannot overlap (unique constraint: roomId + market + stayDate)
  • Hotel code (shDes) must be globally unique
  • Room names unique within hotel
  • Foreign key constraints enforced (room → hotel, calendar → room)

Usability

  • Intuitive area-based hotel grouping
  • Visual calendar representation with color coding
  • Responsive feedback for all user actions
  • Toast notifications for success/error
  • Confirmation dialogs for destructive actions
  • Keyboard shortcuts for date pickers

Scalability

  • Support up to 1000 hotels
  • Support up to 50 rooms per hotel
  • Support up to 1095 calendar entries per room (3 years × 365 days)
  • Efficient queries using indexed fields (hotelId, roomId, market, stayDate)

Maintainability

  • Modular JavaScript architecture (ES6 modules)
  • RESTful API design with standard patterns
  • Consistent naming conventions
  • Comprehensive entity models
  • Logging at API level

Future Enhancements

1. Advanced Promotions (Partially Implemented)

Status: UI exists but backend incomplete

Features: - Promotional campaigns with codes - Date-specific promotional pricing - Room-specific promotion applicability - Priority-based promotion stacking - Automatic discount calculation - Promotion reporting

2. Real-Time Availability Integration

Description: Connect to hotel channel managers or GDS for live availability

Benefits: - Real-time room inventory - Automated booking confirmations - Reduced manual coordination - Overbooking prevention

3. Dynamic Pricing Engine

Description: Automated rate adjustments based on demand, competitor rates, and occupancy

Features: - Machine learning price optimization - Competitor rate monitoring - Demand forecasting - Automated rate updates - Revenue management analytics

4. Multi-Currency Support

Description: Support for multiple currencies with exchange rate management

Features: - Currency per hotel or market - Real-time exchange rates - Multi-currency pricing display - Currency conversion in quotations - Historical exchange rate tracking

5. Contract Management

Description: Track hotel contracts with renewal reminders and terms

Features: - Contract upload and storage - Contract expiration alerts - Rate commitment tracking - Allotment management - Negotiated rates archival

6. Reporting & Analytics

Description: Business intelligence for hotel inventory performance

Reports: - Revenue by hotel/room type - Booking patterns by season - Average daily rate (ADR) trends - Occupancy rates - Profitability analysis - Market segment performance

7. Bulk Operations

Description: Efficiency tools for large-scale updates

Features: - Bulk rate updates across multiple rooms - Bulk calendar copy across markets - Batch hotel imports - Excel upload for rate calendars - Template-based rate structures

8. Mobile Interface

Description: Mobile-optimized interface for on-the-go access

Features: - Responsive design - Quick hotel search - Rate lookups - Booking requests - Simplified calendar view

9. Amadeus Hotel Integration (Partially Implemented)

Status: API endpoints exist for Amadeus hotel search

Endpoints: - /hotel/searchOffers - Search hotel offers via Amadeus - /hotel/fetchOfferResults - Paginated results retrieval - /hotel/searchByName - Autocomplete hotel search - /hotel/getByCity - Hotels by city code

Purpose: Supplement contracted inventory with GDS availability for hotels not in local database

Glossary

Term Definition
Rate Base Occupancy level on which base rate is calculated (SGL/DBL/TRPL/QPL)
Meal Base Meal plan included in the base room rate
Meal Supplement Additional cost to upgrade from base meal plan to higher-tier plan
Special Day Weekend or holiday with different pricing
MLOS Minimum Length of Stay - minimum nights required for booking
Stop Sale Room not available for new bookings (maintenance, allocation, etc.)
On Request Room available but requires manual confirmation
Direct Contract Hotel contracted directly by agency
Indirect Contract Hotel available via DMC or wholesaler
Market Geographic customer segment (UAE/GCC/ROW)
Rate Type Calculation method for supplements (ABS/ADD/PCT/PCO)
Booking Window Period during which reservations can be made for specific stay dates
Extra Bed Additional bed added to room for extra occupancy
Release Days Notice period required for cancellations
Margin Agency markup percentage applied to cost to determine sell price
Cost Agency's contracted rate with hotel
Price Customer-facing rate (cost + margin)
Calendar Entry Single day's pricing record for a room in a market

Implementation Notes

Technology Stack

  • Frontend: JavaScript ES6 Modules, jQuery 3.x, Foundation 6.x CSS framework
  • Backend: Java 17, Jakarta EE (JAX-RS), Custom EntityFacade ORM
  • Data Format: JSON for API requests/responses
  • Date Format: dd-mm-yyyy (Web), timestamps for storage

Key JavaScript Classes

  • hotelmgmt.js module (1428 lines) containing:
  • Hotel list management
  • Room configuration
  • Calendar creation/editing
  • Search functionality
  • Booking request creation

Key Java Classes

  • HotelApi.java - RESTful API endpoints (1246 lines)
  • CHotel - Hotel entity
  • CHotelRoom - Room entity
  • CRoomCalendarEntry - Calendar entry entity
  • CMealPlan - Meal plan entity
  • CHotelSearchResult - Search results container

Database Schema (Inferred)

  • hotels table: Hotel master records
  • hotel_rooms table: Room type configurations
  • room_calendar table: Daily pricing records
  • meal_plans table: Global meal plan definitions
  • hotel_meal_plans table: Hotel-specific meal plan associations

This functional specification describes the Local Hotel Management module as an internal contract rate management tool for travel agencies, enabling efficient configuration and search of contracted hotel inventory with sophisticated pricing calendars, market segmentation, and integration with quotation and booking processes.