Skip to content

Booking Lifecycle Management - Use Cases

Status: M1-M9 Complete -- This document covers M1 through M9.

1. Introduction

1.1 Purpose

This document defines the use cases for the Booking Lifecycle Management (BLM) module. Each use case describes a specific interaction between an actor and the system to achieve a business goal.

1.2 Scope

This document covers all use cases for M1 (Core Booking and Manual Creation) and M5 (Actions Framework). Use cases for remaining milestones are listed as placeholders with brief descriptions.

1.3 References

1.4 Actors

Actor Description
Travel Agent User who creates and manages bookings for customers. Has the agent role.
Administrator User with full access to all booking operations, including system configuration. Has the admin role.
System Automated processes such as the option expiry background job and ERP integration.

2. Use Case Overview

2.1 Use Case Diagram

                          Booking Lifecycle Management System
    +---------------------------------------------------------------------+
    |                                                                     |
    |   +------------------------+     +------------------------+        |
    |   | Booking Management     |     | Service Line           |        |
    |   | --------------------   |     | Management             |        |
    |   | UC-BK-01 Create        |     | --------------------   |        |
    |   | UC-BK-08 Search        |     | UC-BK-02 Manage        |        |
    |   | UC-BK-09 View Details  |     |   Service Lines        |        |
    |   +------------------------+     +------------------------+        |
    |              |                            |                        |
    |              v                            v                        |
    |   +------------------------+     +------------------------+        |
    |   | Status Lifecycle       |     | Passenger Management   |        |
    |   | --------------------   |     | --------------------   |        |
    |   | UC-BK-04 Change Status |     | UC-BK-03 Manage        |        |
    |   | UC-BK-05 Option Hold   |     |   Passengers           |        |
    |   +------------------------+     +------------------------+        |
    |              |                            |                        |
    |              v                            v                        |
    |   +------------------------+     +------------------------+        |
    |   | Audit & Communication  |     | Actions Framework (M5) |        |
    |   | --------------------   |     | --------------------   |        |
    |   | UC-BK-06 Activity Log  |     | UC-BK-18 Template Sets |        |
    |   | UC-BK-07 Notifications |     | UC-BK-19 Templates     |        |
    |   +------------------------+     | UC-BK-20 Generate      |        |
    |                                  | UC-BK-21 Complete      |        |
    |   +------------------------+     | UC-BK-22 Lifecycle     |        |
    |   | Vouchers + Docs (M6)   |     | UC-BK-23 Custom Action |        |
    |   | --------------------   |     | UC-BK-24 New Line Gen  |        |
    |   | UC-BK-25 Gen Voucher   |     +------------------------+        |
    |   | UC-BK-26 Upload Doc    |                                       |
    |   | UC-BK-27 Download Doc  |     +------------------------+        |
    |   | UC-BK-28 Email Doc     |     | Future Milestones      |        |
    |   | UC-BK-29 Delete Doc    |     | --------------------   |        |
    |   | UC-BK-30 Voucher Tmpl  |     | UC-BK-16 (M7)         |        |
    |   +------------------------+     | UC-BK-17 (M7)         |        |
    |                                  | UC-BK-18 (M8)         |        |
    |                                  +------------------------+        |
    |                                                                     |
    +---------------------------------------------------------------------+
           ^              ^                    ^                 ^
           |              |                    |                 |
    +------+------+ +-----+-----+      +------+------+   +-----+-----+
    |    Travel   | |   Admin-  |      |   System    |   | Customer  |
    |    Agent    | | istrator  |      |             |   | (future)  |
    +-------------+ +-----------+      +-------------+   +-----------+

2.2 Use Case Summary

ID Use Case Name Actor(s) Milestone Priority
M1 -- Core Booking
UC-BK-01 Create Booking Travel Agent, Administrator M1 High
UC-BK-02 Manage Service Lines Travel Agent, Administrator M1 High
UC-BK-03 Manage Passengers Travel Agent, Administrator M1 High
UC-BK-04 Change Booking Status Travel Agent, Administrator M1 High
UC-BK-05 Set / Extend Option Hold Travel Agent, Administrator M1 High
UC-BK-06 View Activity Log and Add Notes Travel Agent, Administrator M1 Medium
UC-BK-07 Send Notifications Travel Agent, Administrator M1 Medium
UC-BK-08 Search and Filter Bookings Travel Agent, Administrator M1 High
UC-BK-09 View Booking Details Travel Agent, Administrator M1 High
M2 -- Cart + Browse-First Flow
UC-CART-01 Browse and Add to Cart Travel Agent M2 High
UC-CART-02 Assign Customer to Cart Travel Agent M2 High
UC-CART-03 Edit Cart Items Travel Agent M2 Medium
UC-CART-04 Checkout Cart Travel Agent M2 High
UC-CART-05 Agent Rotation (Cart Transfer/Merge) Travel Agent M2 Medium
UC-CART-06 Online Hotel Search to Cart Travel Agent M2 High
UC-CART-07 Round-Trip Flight to Cart Travel Agent M2 High
M3 -- Checkout + Payment
UC-PAY-01 Initiate Checkout (Online Card) Travel Agent M3 High
UC-PAY-02 Initiate Checkout (Manual Method) Travel Agent M3 High
UC-PAY-03 Record Manual Payment Travel Agent M3 High
UC-PAY-04 Collect Balance After Deposit Travel Agent M3 High
UC-PAY-05 View Financial Summary Travel Agent M3 Medium
UC-PAY-06 Export Bookings to Excel Travel Agent M3 Medium
M3.5 -- Service Integration
UC-MERGE-01 Merge Cart into Existing Booking Travel Agent M3.5 High
UC-MERGE-02 Add Hotel Package to Cart Travel Agent M3.5 High
UC-MERGE-03 Add Offline Tickets to Cart Travel Agent M3.5 High
UC-BRIDGE-01 Standalone Hotel Package Creates BLM Record System M3.5 High
UC-BRIDGE-02 Cruise Booking Transferred to BLM for Payment Travel Agent M3.5 High
UC-BRIDGE-03 Vouchered Cruise Creates BLM Record System M3.5 Medium
M4 -- Cancellation + T&C
UC-CXL-01 Cancel Full Booking Travel Agent, Administrator M4 High
UC-CXL-02 Cancel Single Service Line Travel Agent M4 High
UC-CXL-03 Preview Cancellation Fees Travel Agent M4 Medium
UC-CXL-04 Override Cancellation Policy per Service Line Travel Agent M4 Medium
UC-CXL-05 Manage T&C Templates Administrator M4 High
UC-CXL-06 Preview Resolved Terms for Booking Travel Agent M4 Medium
M5 -- Actions Framework
UC-BK-18 Configure Action Template Sets Administrator M5 High
UC-BK-19 Configure Action Templates Administrator M5 High
UC-BK-20 Generate Actions on Booking Confirmation System M5 High
UC-BK-21 Complete Action with Result Data Travel Agent, Administrator M5 High
UC-BK-22 Manage Action Lifecycle Travel Agent, Administrator M5 Medium
UC-BK-23 Add Custom Action Travel Agent, Administrator M5 Medium
UC-BK-24 Generate Actions for Added Service Line System M5 Medium
M6 -- Vouchers + Documents
UC-BK-25 Generate Travel Voucher PDF Travel Agent, Administrator M6 High
UC-BK-26 Upload Document to Booking Travel Agent, Administrator M6 High
UC-BK-27 Download Booking Document Travel Agent, Administrator M6 Medium
UC-BK-28 Email Document to Recipient Travel Agent, Administrator M6 Medium
UC-BK-29 Delete Booking Document Travel Agent, Administrator M6 Medium
UC-BK-30 Configure Voucher Section Templates Administrator M6 High
M6.5 -- Booking Terms Tab
UC-BK-31 Access and Initialize Booking Terms Travel Agent M6.5 High
UC-BK-32 Toggle Terms Inclusion for Voucher Travel Agent M6.5 High
UC-BK-33 Add Custom Free-Text Term Travel Agent M6.5 Medium
UC-BK-34 Refresh Terms from Templates Travel Agent M6.5 Medium
UC-BK-35 Delete Custom Term Travel Agent M6.5 Medium
M7 -- TripMaker + Group Integration
UC-BK-16 Convert TripMaker Quotation to Booking Travel Agent M7 Medium
UC-BK-17 Create/Update Booking from Inbound Group Travel Agent M7 Medium
M8 -- Outbound Group Sales
UC-BK-18 Manage Group Departure Travel Agent, Administrator M8 Medium

3. M1 Use Cases -- Detailed

3.1 UC-BK-01: Create Booking

Attribute Value
ID UC-BK-01
Name Create Booking
Actors Travel Agent, Administrator
Priority High
Related Requirements BK-001, BK-002, BK-003, BK-004, BK-005, BK-006, BK-007, BK-008, BK-009

Description: The agent creates a new booking for a customer, providing customer details, travel dates, and optionally initial service lines and passengers.

Preconditions: - The agent is logged in with the agent or admin role. - The customer information is available (existing customer ID or new customer details).

Main Flow: 1. The agent opens the booking creation interface (wizard or API). 2. Step 1 -- Client: The agent provides customer information: - Either an existing customer ID, or - A new customer name, email, and phone number. 3. The agent enters travel start date, travel end date, and currency (optional; defaults to system local currency). 4. The agent optionally provides notes, source type (e.g., MANUAL, CART, TRIPMAKER), and source reference. 5. Step 2 -- Services (optional): The agent adds one or more service lines, each with a service type, description, supplier, dates, cost, and sell price. 6. Step 3 -- Passengers (optional): The agent adds one or more passengers with personal and passport details. One passenger is marked as the lead. 7. Step 4 -- Review: The agent reviews the booking summary and submits. 8. The system generates a unique booking reference (TQ-YYYY-NNNNN). 9. The system creates the booking in ENQUIRY status with UNPAID payment status. 10. The system attempts to find or create the customer in Odoo ERP and stores the ERP customer ID. 11. The system creates a CRM lead in Odoo ERP and stores the ERP lead ID. 12. The system records the initial status in the status history. 13. The system logs the creation event in the activity log. 14. The system returns the created booking with its reference number.

Alternative Flows:

  • AF-01: ERP integration fails. At step 10 or 11, if ERP communication fails, the system logs a warning and continues. The booking is created successfully without the ERP references.
  • AF-02: Single-step creation. The agent can create a booking with service lines and passengers in a single API call, bypassing the wizard steps.

Postconditions: - A new booking exists with a unique reference number in ENQUIRY status. - The status history contains the initial ENQUIRY entry. - The activity log contains a BOOKING_CREATED entry. - If successful, ERP customer and CRM lead references are stored on the booking.

3.2 UC-BK-02: Manage Service Lines

Attribute Value
ID UC-BK-02
Name Manage Service Lines
Actors Travel Agent, Administrator
Priority High
Related Requirements BK-019 through BK-028

Description: The agent adds, edits, duplicates, removes, or confirms service lines within a booking.

Preconditions: - A booking exists and is accessible to the agent. - The booking is not in COMPLETED or CANCELLED status.

Main Flow -- Add Service Line: 1. The agent selects the booking and chooses to add a service line. 2. The agent specifies the service type (HOTEL, FLIGHT, TRANSFER, ACTIVITY, CRUISE, VISA, OTHER, or SERVICE_CHARGE). 3. The agent enters the description, supplier name, date range, cost, sell price, currency, quantity, and any special requests. 4. Optionally, the agent searches for and selects an ERP product to link to the service line. 5. The system converts the cost to local currency using the exchange rate service. 6. The system creates the service line with PENDING confirmation status. 7. The system recalculates the booking totals. 8. If the booking is in CONFIRMED or AMENDED status, the system automatically records an amendment. 9. The system logs the addition in the activity log.

Alternative Flow -- Edit Service Line: 1. The agent selects an existing service line and modifies one or more fields. 2. The system updates the service line and reconverts cost to local currency if cost or currency changed. 3. The system recalculates the booking totals. 4. If the booking is in CONFIRMED or AMENDED status, the system records an amendment. 5. The system logs the update in the activity log.

Alternative Flow -- Duplicate Service Line: 1. The agent selects an existing service line and chooses to duplicate it. 2. The system creates a copy of the service line with PENDING confirmation status and no supplier reference. 3. The system does not recalculate totals (the duplicate still needs editing).

Alternative Flow -- Remove Service Line: 1. The agent selects a service line and chooses to remove it, optionally providing a reason. 2. The system deletes the service line. 3. The system recalculates the booking totals. 4. If the booking is in CONFIRMED or AMENDED status, the system records an amendment. 5. The system logs the removal in the activity log.

Alternative Flow -- Confirm Service Line: 1. The agent selects a service line with PENDING status and enters a supplier reference (confirmation number from the supplier). 2. The system updates the confirmation status to CONFIRMED and stores the supplier reference.

Postconditions: - The service line is created, updated, duplicated, removed, or confirmed as requested. - Booking totals reflect the current set of service lines. - Amendments are recorded for changes to CONFIRMED or AMENDED bookings. - Activity log entries exist for all operations.

3.3 UC-BK-03: Manage Passengers

Attribute Value
ID UC-BK-03
Name Manage Passengers
Actors Travel Agent, Administrator
Priority High
Related Requirements BK-030 through BK-033

Description: The agent adds, edits, removes passengers, sets the lead passenger, and validates passport details.

Preconditions: - A booking exists and is accessible to the agent.

Main Flow -- Add Passenger: 1. The agent selects the booking and chooses to add a passenger. 2. The agent enters the passenger's title, first name (required), last name (required), date of birth, nationality, passport number, passport expiry, gender, phone, and email. 3. Optionally, the agent marks the passenger as the lead passenger. 4. Optionally, the agent links the passenger to an existing customer profile for data pre-fill. 5. The system creates the passenger record. 6. If the passenger is marked as lead, the system updates the booking's lead passenger reference. 7. The system logs the addition in the activity log.

Alternative Flow -- Edit Passenger: 1. The agent selects an existing passenger and modifies one or more fields. 2. The system updates the passenger record.

Alternative Flow -- Remove Passenger: 1. The agent selects a passenger and chooses to remove them. 2. The system deletes the passenger record. 3. If the removed passenger was the lead, the system clears the booking's lead passenger reference. 4. The system logs the removal in the activity log.

Alternative Flow -- Set Lead Passenger: 1. The agent selects a passenger and designates them as the lead. 2. The system clears the lead flag from all other passengers on the same booking. 3. The system sets the lead flag on the selected passenger. 4. The system updates the booking's lead passenger reference.

Alternative Flow -- Validate Passport Expiry: 1. The agent requests passport validation for all passengers on a booking. 2. The system checks each passenger's passport expiry date against the booking's travel start date. 3. For any passenger whose passport expires within 6 months of the travel start date, the system returns a warning with the passenger name and expiry date.

Postconditions: - Passenger records are created, updated, or removed as requested. - The booking's lead passenger reference is consistent with the passenger data. - Activity log entries exist for add and remove operations.

3.4 UC-BK-04: Change Booking Status

Attribute Value
ID UC-BK-04
Name Change Booking Status
Actors Travel Agent, Administrator, System
Priority High
Related Requirements BK-010 through BK-014

Description: An actor changes the status of a booking. The system validates the transition, records the change in the status history, and logs the event.

Preconditions: - The booking exists and is in a status that allows the requested transition.

Main Flow: 1. The actor selects a booking and requests a status change to a new status. 2. Optionally, the actor provides notes explaining the reason for the change. 3. The system verifies the requested transition is valid according to the state machine. 4. The system updates the booking's status. 5. The system records the transition in the booking status history (previous status, new status, user, timestamp, notes). 6. The system logs the status change in the activity log. 7. The system returns the updated booking.

Alternative Flow -- Cancel Booking: 1. The actor requests cancellation of a booking from any active status. 2. The actor optionally provides a cancellation reason. 3. The system transitions the booking to CANCELLED status. 4. The system records the cancellation in the status history and activity log.

Alternative Flow -- Invalid Transition: 1. The actor requests a transition that is not in the valid transition map (e.g., ENQUIRY to COMPLETED). 2. The system rejects the request with an error message indicating the transition is invalid.

Valid Status Transitions:

From Status Allowed Transitions
ENQUIRY QUOTED, CONFIRMED, CANCELLED
QUOTED OPTION_HELD, CONFIRMED, CANCELLED
OPTION_HELD CONFIRMED, EXPIRED, CANCELLED
CONFIRMED AMENDED, TICKETED, COMPLETED, CANCELLED
AMENDED CONFIRMED, TICKETED, CANCELLED
TICKETED COMPLETED, CANCELLED
EXPIRED QUOTED, CANCELLED

Postconditions: - The booking status is updated to the new status. - A status history record exists for the transition. - An activity log entry exists for the event.

3.5 UC-BK-05: Set / Extend Option Hold

Attribute Value
ID UC-BK-05
Name Set / Extend Option Hold
Actors Travel Agent, Administrator, System
Priority High
Related Requirements BK-015 through BK-018

Description: An agent places a booking on a time-limited option hold or extends an existing hold. The system automatically expires bookings past their hold deadline.

Preconditions: - For setting: The booking is in QUOTED status. - For extending: The booking is in OPTION_HELD status and has not yet expired.

Main Flow -- Set Option Hold: 1. The agent selects a booking in QUOTED status and requests an option hold. 2. The agent specifies an expiry date and time. 3. The system stores the option expiry date on the booking. 4. The system transitions the booking to OPTION_HELD status. 5. The system records the status change and logs the activity.

Alternative Flow -- Extend Option Hold: 1. The agent selects a booking in OPTION_HELD status and requests an extension. 2. The agent specifies a new expiry date and time. 3. The system updates the option expiry date on the booking. 4. The system logs a HOLD_EXTENDED event in the activity log.

Alternative Flow -- Automatic Expiry (System): 1. The background job (OptionExpiryRunner) runs on a schedule. 2. The job acquires a distributed lock to prevent concurrent execution across cluster nodes. 3. The job queries all OPTION_HELD bookings with expiry dates in the past. 4. For each expired booking, the job transitions the status to EXPIRED and sends an expiry notification. 5. The job releases the distributed lock.

Alternative Flow -- On-Read Expiry Check: 1. When a booking in OPTION_HELD status is read via the API, the system checks the expiry date. 2. If the expiry date has passed, the system immediately transitions the booking to EXPIRED status.

Postconditions: - The booking is in OPTION_HELD status with the specified expiry date, or has been expired. - Activity log entries exist for hold set, extension, or expiry.

3.6 UC-BK-06: View Activity Log and Add Notes

Attribute Value
ID UC-BK-06
Name View Activity Log and Add Notes
Actors Travel Agent, Administrator
Priority Medium
Related Requirements BK-034 through BK-036

Description: The agent views the chronological activity log for a booking and can add manual notes.

Preconditions: - A booking exists and is accessible to the agent.

Main Flow -- View Activity Log: 1. The agent navigates to the activity log for a booking. 2. The system retrieves the most recent activity log entries (default limit: 50). 3. The system displays the entries in reverse chronological order, showing type, description, user, and timestamp for each entry.

Alternative Flow -- Add Agent Note: 1. The agent enters a note and submits it. 2. The system creates an activity log entry of type NOTE_ADDED with the note text and the agent's user ID. 3. The updated activity log is displayed.

Postconditions: - The agent can see a chronological record of all booking events. - If a note was added, it appears as a NOTE_ADDED entry in the activity log.

3.7 UC-BK-07: Send Notifications

Attribute Value
ID UC-BK-07
Name Send Notifications
Actors Travel Agent, Administrator
Priority Medium
Related Requirements BK-037, BK-038

Description: The agent triggers email notifications related to a booking.

Preconditions: - The booking exists with valid customer contact information. - Email service is configured and available.

Main Flow -- Send Booking Confirmation: 1. The agent selects a booking and requests sending a confirmation email. 2. The system composes the confirmation email with booking details. 3. The system sends the email to the customer. 4. The system logs a NOTIFICATION_SENT event in the activity log.

Alternative Flow -- Send Payment Reminder: 1. The agent selects a booking and requests sending a payment reminder. 2. The system composes the reminder email with the outstanding balance. 3. The system sends the email to the customer. 4. The system logs a NOTIFICATION_SENT event in the activity log.

Postconditions: - The email is sent to the customer. - The activity log records the notification event.

3.8 UC-BK-08: Search and Filter Bookings

Attribute Value
ID UC-BK-08
Name Search and Filter Bookings
Actors Travel Agent, Administrator
Priority High
Related Requirements BK-039, BK-040

Description: The agent searches for bookings using various filter criteria.

Preconditions: - The agent is logged in with the agent or admin role.

Main Flow: 1. The agent specifies one or more search criteria: - Booking status - Assigned agent ID - Customer ID - Booking reference (partial match supported) - Travel date range (from/to) 2. The system queries bookings matching all specified criteria. 3. The system returns the list of matching bookings.

Alternative Flow -- Read by Reference: 1. The agent provides an exact booking reference (e.g., TQ-2026-00042). 2. The system retrieves the booking matching that reference. 3. If the booking is in OPTION_HELD status, the system checks for expiry.

Postconditions: - The agent receives a list of bookings matching the search criteria, or a single booking by reference.

3.9 UC-BK-09: View Booking Details

Attribute Value
ID UC-BK-09
Name View Booking Details
Actors Travel Agent, Administrator
Priority High
Related Requirements BK-040

Description: The agent views the full details of a booking, including service lines, passengers, amendments, status history, and activity log.

Preconditions: - The booking exists and is accessible to the agent.

Main Flow: 1. The agent selects a booking by ID or reference. 2. The system retrieves the booking details. 3. If the booking is in OPTION_HELD status, the system checks for expiry. 4. The agent views the booking overview: reference, status, dates, customer, totals. 5. The agent views associated data through dedicated sub-queries: - Service lines (sorted by sort order) - Passengers (lead passenger first, then alphabetical) - Amendments (if any) - Status history - Activity log

Postconditions: - The agent has a complete view of the booking and all its associated data.

4. M2-M8 Use Cases -- Summaries and Cross-References

Detailed use cases for M2, M3.5, M5, and M6 are in sections 5-8. The following summaries cover the remaining milestones (M3, M4, M7, M8) and provide cross-references to detailed sections.

4.1 M2 -- Cart + Browse-First Flow

See section 5 below for detailed M2 use cases (UC-CART-01 through UC-CART-07).

4.2 M3 -- Checkout + Payment

See section 5b below for detailed M3 use cases (UC-PAY-01 through UC-PAY-06).

4.3 M4 -- Cancellation + T&C

See section 5c below for detailed M4 use cases (UC-CXL-01 through UC-CXL-06).

4.4 M3.5 -- Service Integration

See section 6 below for detailed M3.5 use cases (UC-MERGE-01 through UC-MERGE-03, UC-BRIDGE-01 through UC-BRIDGE-03).

4.5 M5 -- Actions Framework

See section 7 below for detailed M5 use cases (UC-BK-18 through UC-BK-24).

4.6 M6 -- Vouchers + Documents

See section 8 below for detailed M6 use cases (UC-BK-25 through UC-BK-30).

4.7 UC-BK-16: Convert TripMaker Quotation to Booking (M7)

Actor: Travel Agent

Preconditions: TripMaker project exists with at least one itinerary; project status is QUOTED.

Main Flow:

  1. Agent navigates to TripMaker Cost Review page for the project itinerary.
  2. System shows "Convert to Booking" button (visible only when status = QUOTED).
  3. Agent clicks button; system shows TQ.confirm dialog explaining that conversion will close the project.
  4. Agent confirms.
  5. System calls POST /tripmaker/project/convertToBooking with projectId and itineraryId.
  6. Backend validates project status, loads cost breakdown with margins applied.
  7. Creates BookingCreationRequest with customer from first traveler detail, services from cost components (HOTEL, FLIGHT, ACTIVITY, OTHER mapped accordingly), and lead passenger from first traveler.
  8. Delegates to BookingServiceI.createBooking() which creates the booking in ENQUIRY status with ERP customer/lead.
  9. Sets project status to CLOSED.
  10. Frontend redirects to booking-detail.html.

Alternative Flows:

  • Project not in QUOTED status: system returns an error.
  • Project not found: system returns an error.
  • Itinerary does not belong to the project: system returns an error.

Postconditions: Booking created in ENQUIRY status; project set to CLOSED; service lines and passengers imported.

4.8 UC-BK-17: Create/Update Booking from Inbound Group (M7)

Actor: Travel Agent

Preconditions: Inbound group exists (groupType = INBOUND) with services and/or passengers.

Main Flow:

  1. Agent navigates to Groups Summary page for an inbound group.
  2. System shows "Create Booking" button (visible only for INBOUND groups).
  3. Agent clicks button; system shows TQ.confirm dialog.
  4. Agent confirms.
  5. System calls POST /groups/group/createBooking with groupId.
  6. Backend checks for an existing booking (sourceType=GROUP_INBOUND, sourceRef=groupId). 7a. If no existing booking: creates a new booking with partner agency as customer, imports hotels (one service line per hotel with room costs summed), transports, services (with adult/child cost aggregation), and all passengers (first as lead). 7b. If an existing booking in ENQUIRY or QUOTED status: updates the booking header, replaces all service lines and passengers with current group state. 7c. If an existing booking is CONFIRMED or beyond: rejects with an error.
  7. Frontend redirects to booking-detail.html.

Alternative Flows:

  • Group is not INBOUND type: system returns an error.
  • Group not found: system returns an error.
  • Existing booking past QUOTED status: system returns an error with message to cancel or amend manually.

Postconditions: Booking created or updated in ENQUIRY status; all group data synced to booking.

4.9 UC-BK-18: Manage Group Departure (M8)

The agent manages an outbound group departure, including inventory allocation, passenger roster management, shared service lines, and group pricing. This supports the outbound group travel sales workflow.

5. M2 Use Cases: Cart + Browse-First Flow

5.1 UC-CART-01: Browse and Add to Cart

Actor: Travel Agent Precondition: Agent is logged in.

  1. Agent navigates to a search page (Online Hotels, Flights, or Activities).
  2. Agent performs a search with desired criteria.
  3. Agent clicks [Add to Cart] on a search result.
  4. System creates a cart if agent has no active cart (auto-parks any existing cart).
  5. System adds the item with service type, description, dates, cost, and sell price.
  6. Cart badge in the navbar updates with the item count.
  7. Agent continues browsing and adds more items from any search page.

5.2 UC-CART-02: Assign Customer to Cart

Actor: Travel Agent Precondition: Agent has an active cart with items.

  1. Agent navigates to the cart page.
  2. Agent types in the "Find Customer" autocomplete field (min 2 characters).
  3. System searches Odoo by name, email, and phone simultaneously.
  4. Matching customers appear in a dropdown (name, email, phone displayed).
  5. Agent selects a customer.
  6. System assigns customer to cart, resolves ERP customer ID, denormalizes customer info.
  7. If the customer has a previous cart (ACTIVE or PARKED from another agent), the system transfers it (if current cart is empty) or merges items into the current cart.

5.3 UC-CART-03: Edit Cart Items

Actor: Travel Agent Precondition: Agent has an active cart with items.

  1. Agent navigates to the cart page.
  2. Agent edits qty, cost, or sell price inline on any cart item.
  3. System updates the item and recalculates the cart total.
  4. Agent can also remove individual items or clear all items.

5.4 UC-CART-04: Checkout Cart

Actor: Travel Agent Precondition: Cart has items and a customer assigned.

  1. Agent clicks [Proceed to Checkout].
  2. System validates customer is assigned and cart is not empty.
  3. System creates a booking (status=ENQUIRY, source=CART) with denormalized customer info.
  4. Each cart item is converted to a booking service line.
  5. Cart status changes to CHECKED_OUT with booking reference.
  6. Agent is redirected to the booking detail page.

5.5 UC-CART-05: Agent Rotation

Actor: Multiple agents serving the same customer.

  1. Agent A creates a cart for Customer X, adds services, moves on (cart auto-parked when Agent A starts a new cart).
  2. Customer X calls back, reaches Agent B. Agent B creates a new cart, adds a service.
  3. Agent B assigns Customer X → system finds Agent A's parked cart and merges its items into Agent B's cart.
  4. Agent B can now see all items from both agents and proceed to checkout.

Actor: Travel Agent

  1. Agent navigates to Products → Online Hotels.
  2. Agent searches by city (autocomplete), dates, adults, children, rooms.
  3. Results display grouped by hotel with thumbnail, stars, price from.
  4. Agent clicks a hotel card → modal shows room options with meal plan, cancellation, price.
  5. Agent clicks [Add to Cart] → hotel added with converted price in display currency.

5.7 UC-CART-07: Round-Trip Flight to Cart

Actor: Travel Agent

  1. Agent searches flights for a round trip.
  2. Agent selects an outbound flight → return search results appear.
  3. Agent selects a return flight and clicks [Add to Cart].
  4. System adds a single cart item with both legs: description shows both routes, price is combined total, attributes store each leg's details separately.

5b. M3 Use Cases: Checkout + Payment

5b.1 UC-PAY-01: Initiate Checkout with Online Card Payment

Actor: Travel Agent Precondition: Booking has service lines with a total sell > 0. ERP Sales Order exists (created during booking creation).

  1. Agent navigates to the booking detail page and clicks Proceed to Checkout.
  2. The checkout page displays the booking summary, payment method selector, and deposit options.
  3. Agent selects payment type: Full Payment, Deposit (percentage), or Deposit (fixed amount).
  4. Agent selects CARD_ONLINE as the payment method.
  5. The system calculates the service charge (2.5% of the payment amount) and shows the grand total.
  6. Agent clicks Pay Now.
  7. The system confirms the Odoo Sales Order (draft to sale) if not already confirmed.
  8. The system adds a service charge line to the booking (isServiceCharge=true).
  9. The system creates an Odoo invoice:
  10. Full payment: method="delivered" (entire SO total).
  11. Deposit %: method="percentage" (e.g., 30% of SO total).
  12. Deposit fixed: method="fixed" (e.g., AED 1,500).
  13. The system creates a PGW payment link and stores the cartReference on the booking.
  14. The agent (or customer) is redirected to the payment gateway.
  15. On successful payment: PGW redirects to /payment/blm/success?ref={cartReference}.
  16. The system registers the payment in Odoo, syncs payment status, logs PAYMENT_RECEIVED.
  17. The agent is redirected to the booking detail page with a success notification.

Alternative Flows:

  • AF-01: PGW Decline. The customer's card is declined. PGW redirects to /payment/blm/decline. The system logs PAYMENT_DECLINED and redirects to booking detail. Payment status remains UNPAID. Agent can retry.
  • AF-02: PGW Cancel. The customer cancels on the PGW page. PGW redirects to /payment/blm/cancel. The system logs PAYMENT_CANCELLED. Same redirect behaviour as decline.

Postconditions: - Payment registered in Odoo. - paymentStatus updated: FULLY_PAID (full) or DEPOSIT_PAID (deposit). - Service charge line added.

5b.2 UC-PAY-02: Initiate Checkout with Manual Payment Method

Actor: Travel Agent Precondition: Same as UC-PAY-01.

  1. Steps 1-5 same as UC-PAY-01 but agent selects BANK_TRANSFER, CASH, POS_TERMINAL, or TABBY.
  2. The system calculates the method-specific service charge (0% for bank/cash, 2% for POS, 3% for Tabby).
  3. Agent clicks Confirm.
  4. The system confirms the SO, adds the service charge line, and creates the Odoo invoice.
  5. No PGW link is generated. The system returns the invoice reference.
  6. The confirmation screen shows the invoice number and payment instructions (bank details for transfer, or "Record payment when received" for others).
  7. Booking paymentStatus = UNPAID (invoice exists but no payment recorded yet).

Postconditions: - Odoo invoice created. - Booking awaits manual payment recording.

5b.3 UC-PAY-03: Record Manual Payment

Actor: Travel Agent Precondition: Booking has an unpaid invoice. Payment has been received outside the system (bank transfer, cash, POS terminal).

  1. Agent navigates to the booking's Financial tab.
  2. Agent clicks Record Payment.
  3. The modal shows: journal selector (Cash, Bank, POS), amount (pre-filled with balance due), reference input, and notes.
  4. Agent selects the journal matching the payment method (e.g., Bank for a wire transfer).
  5. Agent enters the payment reference (e.g., "TRF-2026-1234") and amount.
  6. Agent clicks Submit.
  7. The system registers the payment in Odoo with the selected journal and reference.
  8. The system syncs the payment status from Odoo invoices: reads amountDue, updates totalPaid, balanceDue, and derives paymentStatus.
  9. The system logs PAYMENT_REGISTERED.
  10. The Financial tab refreshes with the updated invoice and payment status.

Postconditions: - Payment recorded in Odoo. - paymentStatus updated (PARTIALLY_PAID or FULLY_PAID depending on amount).

5b.4 UC-PAY-04: Collect Balance After Deposit

Actor: Travel Agent Precondition: Booking has paymentStatus = DEPOSIT_PAID. Only the deposit invoice exists and is paid.

  1. Agent navigates to the Financial tab and clicks Collect Balance.
  2. The checkout page opens in balance mode with the remaining amount pre-filled (SO total minus deposit received).
  3. Agent selects a payment method.
  4. The system creates a final invoice in Odoo (method="delivered", deductDownPayments=true), which automatically subtracts the deposit from the total.
  5. If CARD_ONLINE: PGW flow (same as UC-PAY-01). If manual: invoice-only flow (same as UC-PAY-02).
  6. When the balance payment is confirmed: paymentStatus = FULLY_PAID.

Postconditions: - Final invoice created in Odoo. - All invoices paid, balanceDue = 0.

5b.5 UC-PAY-05: View Financial Summary

Actor: Travel Agent Precondition: Booking exists.

  1. Agent navigates to the booking's Financial tab.
  2. The system loads and displays three sections:
  3. Cost & Revenue Table: Each service line with cost, sell price, and margin (amount and %). Service charge lines shown separately. Gross margin calculated at the bottom.
  4. Invoices & Payments Table: Each Odoo invoice with number, type (Down Payment / Final), total, paid, and due amounts. Summary row with totals across all invoices.
  5. Payment Status Badge: UNPAID (red), DEPOSIT_PAID (amber), PARTIALLY_PAID (amber), or FULLY_PAID (green).
  6. Available action buttons depend on the payment status:
  7. UNPAID: Record Payment, Send Reminder.
  8. DEPOSIT_PAID: Collect Balance, Record Payment, Send Reminder.
  9. PARTIALLY_PAID: Record Payment, Send Reminder.
  10. FULLY_PAID: no payment actions.

5b.6 UC-PAY-06: Export Bookings to Excel

Actor: Travel Agent, Administrator Precondition: Bookings exist in the system.

  1. Agent navigates to the booking list page.
  2. Agent optionally filters by status, agent, or date range.
  3. Agent clicks Export.
  4. The system generates an XLSX file with columns: Booking Ref, Client Name, Status, Travel Dates, Agent, Currency, Total Cost, Total Sell, Service Charges, Total Paid, Balance Due, Payment Status, Created Date.
  5. The file downloads to the browser.

5c. M4 Use Cases: Cancellation + Terms & Conditions

5c.1 UC-CXL-01: Cancel Full Booking

Actor: Travel Agent, Administrator Precondition: Booking exists with status not in COMPLETED, CANCELLED, or EXPIRED.

  1. Agent opens the booking detail page and clicks Cancel Booking.
  2. The system calls calculateCancellationFee() to preview fees.
  3. The cancellation modal displays:
  4. Reason dropdown (Client Request, Supplier Issue, Force Majeure, Pricing Error, No Payment, Other).
  5. Optional reason text field.
  6. Fee breakdown table: one row per active service line showing description, sell price, days until travel, matched tier label, and calculated fee.
  7. Total cancellation fee.
  8. If booking is CONFIRMED or later: a warning "Requires Team Lead approval" and an approver name field.
  9. Agent selects a reason and optionally enters notes.
  10. If required, agent enters the approving team lead's name.
  11. Agent clicks Confirm Cancellation.
  12. The system:
  13. Creates a CCancellationRecord (cancellationType=FULL) with fee amount.
  14. Sets all service lines to confirmationStatus=CANCELLED.
  15. Transitions booking status to CANCELLED.
  16. Logs BOOKING_CANCELLED activity.
  17. The booking detail refreshes showing CANCELLED status.

Alternative Flows:

  • AF-01: Missing approval. If booking is CONFIRMED and approvedBy is not provided, the system rejects the request.
  • AF-02: Already cancelled. System rejects with error.

Postconditions: - Booking status = CANCELLED, all service lines cancelled. - Cancellation record created with fee details.

5c.2 UC-CXL-02: Cancel Single Service Line

Actor: Travel Agent Precondition: Booking has multiple service lines. The target service line is not already cancelled.

  1. Agent opens the Services tab and expands a service line card.
  2. Agent clicks Cancel on that service line.
  3. The system previews the fee for this line only.
  4. The modal shows: reason dropdown, optional text, fee for this line, matched tier label.
  5. Agent confirms. No team lead approval is required for per-line cancellation.
  6. The system:
  7. Creates a CCancellationRecord (cancellationType=PARTIAL) for this service line.
  8. Sets the service line's confirmationStatus to CANCELLED.
  9. Recalculates booking totals (excluding the cancelled line).
  10. If booking is CONFIRMED: creates a CBookingAmendment recording the pricing impact.
  11. Logs SERVICE_CANCELLED activity.
  12. The service line card is greyed out with a CANCELLED badge. Booking totals in the Overview tab update.

Postconditions: - Service line cancelled, booking status unchanged. - Booking totals recalculated.

5c.3 UC-CXL-03: Preview Cancellation Fees

Actor: Travel Agent Precondition: Booking has active service lines.

  1. Agent clicks Cancel Booking or Cancel on a service line.
  2. The system calls calculateCancellationFee() (read-only, no records created).
  3. The modal displays fee details per service line:
  4. Service description and type.
  5. Sell price (quantity x unit price).
  6. Days until travel.
  7. Matched cancellation tier label (e.g., "50% cancellation fee").
  8. Calculated fee amount and currency.
  9. Agent can close the modal without proceeding. No data is changed.

Fee calculation logic: - Uses the service line's custom cancellationTerms if set, otherwise the default template tiers for the service type. - Matches the first tier where daysUntilTravel falls within daysFrom-daysTo. - Fee = max(sellPrice x feePercent/100, feeFixed).

5c.4 UC-CXL-04: Override Cancellation Policy per Service Line

Actor: Travel Agent Precondition: Service line exists on a booking. Supplier has a non-standard cancellation policy.

  1. Agent opens the Services tab and expands a service line.
  2. Agent opens the Cancellation Terms section, which shows the current tiers (from the default template for this service type, e.g., CANCEL_HOTEL).
  3. Agent clicks Edit.
  4. The tiers editor opens with the current tiers pre-filled. Each row shows: Days From, Days To, Fee %, Fee Fixed, Label.
  5. Agent modifies the tiers (e.g., changes "Free >30 days" to "Free >10 days").
  6. Agent clicks Save.
  7. The custom tiers JSON is saved to serviceLine.cancellationTerms.
  8. The display updates to show "Custom override" as the source indicator.
  9. Future fee calculations for this line use the custom tiers instead of the default template.

Reset: Agent clicks Reset to Default, which sets cancellationTerms to null. The system reverts to the template tiers.

5c.5 UC-CXL-05: Manage Terms & Conditions Templates

Actor: Administrator Precondition: Admin is logged in.

  1. Admin navigates to the Terms & Conditions page.
  2. The system displays a list of all active templates grouped by type:
  3. GLOBAL (3 defaults): General T&C, Travel Insurance Advisory, Privacy & Data Handling.
  4. SERVICE (4 defaults): Hotel, Flight, Transfer, Activity standard terms.
  5. CANCELLATION (4 defaults): Hotel, Flight, Transfer, Activity cancellation tiers.
  6. Admin can filter by type (GLOBAL, SERVICE, CANCELLATION) and service type (HOTEL, FLIGHT, etc.).

Create Template: 1. Admin clicks New Template. 2. Fills in: type, service type (if SERVICE or CANCELLATION), unique code, title, HTML content with {{variable}} placeholders, optional plain text. 3. For CANCELLATION type: adds tiers using the tiers editor (Days From, Days To, Fee %, Fee Fixed, Label). 4. Clicks Save. Template is created with version=1.

Update Template: 1. Admin clicks on an existing template. 2. Edits content, tiers, title, or sort order. 3. Clicks Save. Version is incremented, updatedAt is set.

Delete Template: 1. Admin clicks Delete. The template is soft-deleted (isActive=false). It no longer appears in lists or resolves for bookings.

Supported template variables: {{bookingRef}}, {{clientName}}, {{travelStartDate}}, {{travelEndDate}}, {{agencyName}}, {{agencyPhone}}, {{agencyEmail}}, {{supplierName}}, {{startDate}}, {{endDate}}, {{checkInTime}}, {{checkOutTime}}, {{baggageAllowance}}, and others. Unresolved variables are silently removed.

5c.6 UC-CXL-06: Preview Resolved Terms for a Booking

Actor: Travel Agent Precondition: Booking has service lines.

  1. Agent calls Preview Terms (or the terms are resolved during voucher generation).
  2. The system calls resolveBookingTerms() which: a. Collects all unique service types from active (non-cancelled, non-service-charge) service lines. b. For each service type: resolves the SERVICE template (with variable substitution) and renders the CANCELLATION tiers as an HTML table. c. Appends all GLOBAL templates (with variable substitution) at the end.
  3. The result is a list of ResolvedTerms objects in order:
  4. Service-type terms (per type: service terms, then cancellation tiers)
  5. Global terms (always last)
  6. The resolved HTML is displayed to the agent with all variables substituted.

Example output order for a booking with Hotel + Flight: 1. Hotel Terms & Conditions (SERVICE, HOTEL) 2. Hotel Cancellation Policy (CANCELLATION, HOTEL) -- with tier table 3. Flight Terms & Conditions (SERVICE, FLIGHT) 4. Flight Cancellation Policy (CANCELLATION, FLIGHT) -- with tier table 5. General Terms & Conditions (GLOBAL) 6. Travel Insurance Advisory (GLOBAL) 7. Privacy & Data Handling (GLOBAL)

6. M3.5 Use Cases: Service Integration

6.1 UC-MERGE-01: Agent Merges Cart into Existing Booking

Actor: Travel Agent

  1. Agent browses and adds items to cart (hotels, flights, activities).
  2. On the cart page, agent clicks [Add to Booking].
  3. System opens a modal with a search field (pre-filtered by cart's customer).
  4. Agent searches by customer name, booking ref, email, or phone.
  5. System shows eligible bookings: UNPAID, same customer, no active payment link.
  6. Agent selects a booking.
  7. System confirms the merge, appends cart items as service lines, recalculates totals, extends travel dates if needed, marks cart as CHECKED_OUT.
  8. Agent is redirected to the booking detail page.

6.2 UC-MERGE-02: Agent Adds Hotel Package to Cart

Actor: Travel Agent

  1. Agent opens a hotel stay package and selects rooms, fills customer info, adds passengers.
  2. Agent clicks [Add to Cart] instead of [Checkout].
  3. System creates a cart item with serviceType=HOTEL, sourceModule=HOTEL_PACKAGE, and package metadata in attributes (rooms, passengers, meal plan, hotel details).
  4. Cart badge updates. Agent can continue browsing and add more services.
  5. On checkout (new or existing booking), passengers from the package are auto-imported to the booking.

6.3 UC-MERGE-03: Agent Adds Offline Tickets to Cart

Actor: Travel Agent

  1. Agent selects tickets on the offline ticket sale page.
  2. Agent clicks [Add to Cart] instead of [Create Reservation].
  3. System reserves the tickets (RESERVED, no ERP) to prevent double-sell.
  4. Cart item is created with sourceModule=OFFLINE_TICKET and ticket IDs in attributes.
  5. If cart item is removed or cart is abandoned, tickets are released back to AVAILABLE.
  6. On BLM payment completion, tickets are finalized as SOLD with download codes.

Constraint: Ticket quantity on the service line cannot be changed. Agent must remove and re-add to change the selection.

6.4 UC-BRIDGE-01: Standalone Hotel Package Creates BLM Record

Actor: System (automatic)

  1. Agent completes a standalone hotel package booking (Checkout → Payment → Confirm).
  2. On payment confirmation, the system automatically creates a COMPLETED BLM booking.
  3. BLM booking has: HOTEL service line, passengers, customer/ERP references, invoice number.
  4. The booking appears in the BLM booking list for financial reporting.

6.5 UC-BRIDGE-02: Cruise Booking Transferred to BLM for Payment

Actor: Travel Agent

  1. Agent manages a cruise booking to "Payment pending" status.
  2. Agent clicks [Transfer to Booking] on the cruise booking page.
  3. System opens a customer assignment modal with autocomplete search (pre-populated with lead passenger's last name) and a "create new customer" option.
  4. Agent selects or creates a customer.
  5. System creates a BLM booking in CONFIRMED/UNPAID state with cruise service lines and passengers.
  6. Agent is redirected to the BLM checkout page to generate a payment link.
  7. Customer pays via PGW. On success, BLM booking becomes FULLY_PAID and cruise booking advances to "Voucher pending".

6.6 UC-BRIDGE-03: Vouchered Cruise Creates BLM Record

Actor: System (automatic)

  1. Agent advances a cruise booking to "Vouchered" status.
  2. System automatically creates a COMPLETED BLM booking with cabin and add-on service lines, passengers, and the cruise booking number as sourceRef.
  3. The booking appears in the BLM booking list for financial reporting.

7. M5 Use Cases: Actions Framework

7.1 UC-BK-18: Configure Action Template Sets

Attribute Value
ID UC-BK-18
Name Configure Action Template Sets
Actors Administrator
Priority High
Related Requirements BK-050, BK-051

Description: The administrator creates, edits, or deactivates action template sets. Each template set is associated with a service type and defines a collection of action templates that will be generated when a booking with that service type is confirmed.

Preconditions: - The administrator is logged in with the admin role.

Main Flow -- Create Template Set: 1. The administrator opens the Action Templates management page. 2. The administrator clicks "New Template Set" to open the guided wizard modal. 3. The administrator enters a name, selects a service type (HOTEL, FLIGHT, TRANSFER, ACTIVITY, CRUISE, VISA, OTHER), and optionally provides a description. 4. The administrator sets the template set status to ACTIVE. 5. The system creates the template set and displays it in the list.

Alternative Flow -- Edit Template Set: 1. The administrator selects an existing template set from the list. 2. The administrator modifies the name, description, or service type. 3. The system updates the template set.

Alternative Flow -- Deactivate Template Set: 1. The administrator selects an active template set. 2. The administrator changes the status to INACTIVE. 3. The system marks the template set as inactive. It will no longer be used for action generation on new bookings, but existing actions are unaffected.

Postconditions: - The template set is created, updated, or deactivated as requested. - Active template sets are available for action generation when bookings are confirmed.

7.2 UC-BK-19: Configure Action Templates

Attribute Value
ID UC-BK-19
Name Configure Action Templates
Actors Administrator
Priority High
Related Requirements BK-052, BK-053

Description: The administrator adds, edits, or deletes individual action templates within a template set. Each template defines an action that will be generated for a service line, including its description, creation mode, deadline rules, assignee, dependencies, result fields, and notes.

Preconditions: - The administrator is logged in with the admin role. - An action template set exists.

Main Flow -- Create Action Template (7-Step Wizard): 1. The administrator selects a template set and clicks "Add Template". 2. Step 1 -- Description: The administrator enters the action description (e.g., "Send hotel confirmation to supplier") and sets the sequence number within the set. 3. Step 2 -- Creation Mode: The administrator selects the creation mode: ALWAYS (always created), CONDITIONAL (created only when a condition on the service line is met), or MANUAL (available as a suggestion but not auto-created). 4. Step 3 -- Deadline: The administrator configures the deadline rule: number of days before or after the travel start date, or a fixed number of days after booking confirmation. 5. Step 4 -- Assignee: The administrator specifies the default assignee (a user ID or role such as "operations", "ticketing"). 6. Step 5 -- Dependency: The administrator optionally selects another template in the same set as a dependency. The generated action will be blocked until the dependency action is completed. 7. Step 6 -- Result Fields: The administrator defines the expected result fields for the action (e.g., "confirmationNumber", "voucherRef"). Each field has a name, type (TEXT, DATE, NUMBER), and whether it is required. 8. Step 7 -- Notes: The administrator optionally adds instructions or notes for the agent who will complete the action. 9. The administrator reviews and saves. The system creates the action template.

Alternative Flow -- Edit Action Template: 1. The administrator selects an existing action template. 2. The administrator modifies any of the 7 wizard steps. 3. The system updates the template. Changes do not affect already-generated action items.

Alternative Flow -- Delete Action Template: 1. The administrator selects an action template and chooses to delete it. 2. If no action items reference this template, the system deletes it. 3. If action items reference this template, the system rejects the deletion with an error message suggesting deactivation instead.

Postconditions: - The action template is created, updated, or deleted as requested. - The template set contains the updated collection of templates.

7.3 UC-BK-20: Generate Actions on Booking Confirmation

Attribute Value
ID UC-BK-20
Name Generate Actions on Booking Confirmation
Actors System
Priority High
Related Requirements BK-054, BK-055, BK-056

Description: When a booking status changes to CONFIRMED, the system automatically generates action items for each non-cancelled service line based on the matching action template set for the service type.

Preconditions: - The booking status is being changed to CONFIRMED. - At least one active action template set exists matching a service line's service type.

Main Flow: 1. The booking status transitions to CONFIRMED. 2. The system iterates over each non-cancelled service line in the booking. 3. For each service line, the system looks up the active action template set matching the service line's service type. 4. If a matching template set is found, the system iterates over each action template in the set (ordered by sequence number). 5. For each template with creation mode ALWAYS, the system creates an action item with: - Description from the template. - Status set to PENDING. - Deadline calculated from the template's deadline rule and the service line's dates. - Assignee from the template's default assignee. - Reference to the source template and service line. 6. For each template with creation mode CONDITIONAL, the system evaluates the condition against the service line fields (e.g., specialRequests is not empty). If the condition is met, the action item is created; otherwise, it is skipped. 7. The system wires dependency chains: if template B depends on template A, the generated action item for B is linked to the action item for A as a blocker. 8. The system marks the action item as requiredForVoucher if the template specifies it. 9. The system logs an ACTIONS_GENERATED event in the activity log.

Alternative Flows:

  • AF-01: No matching template set. If no active template set matches a service line's service type, no actions are generated for that service line. Processing continues with the next service line.
  • AF-02: Booking already has actions. If the booking already has action items (e.g., from a previous confirmation that was amended and re-confirmed), the system does not duplicate actions for service lines that already have action items.

Postconditions: - Action items are created for each eligible service line based on the matching template set. - Dependency chains are wired between related action items. - The activity log records the action generation event.

7.4 UC-BK-21: Complete Action with Result Data

Attribute Value
ID UC-BK-21
Name Complete Action with Result Data
Actors Travel Agent, Administrator
Priority High
Related Requirements BK-057, BK-058

Description: The agent views the Actions tab on the booking detail page, selects an action to complete, enters the required result data, and marks the action as completed.

Preconditions: - A booking exists with action items. - The action item is in a non-terminal status (PENDING or IN_PROGRESS) and is not blocked by an incomplete dependency.

Main Flow: 1. The agent navigates to the booking detail page and selects the Actions tab. 2. The agent identifies an action item to complete (status is PENDING or IN_PROGRESS, no blocking dependency). 3. The agent clicks "Complete" to open the completion modal. 4. The modal displays the action description, any instructions from the template, and the required result fields. 5. The agent enters values for all result fields (e.g., confirmation number, voucher reference). 6. The agent optionally adds completion notes. 7. The agent submits the completion. 8. The system validates that all required result fields are filled. 9. The system updates the action item status to COMPLETED, stores the result data and completion timestamp. 10. The system logs an ACTION_COMPLETED event in the activity log.

Alternative Flows:

  • AF-01: Missing required field. At step 8, if a required result field is empty, the system displays a validation error and does not complete the action.
  • AF-02: Blocked by dependency. At step 2, if the action's dependency has not been completed, the system displays the action as blocked and the "Complete" button is disabled.

Postconditions: - The action item status is COMPLETED with result data stored. - The activity log records the completion event. - Any downstream actions that depended on this action are unblocked.

7.5 UC-BK-22: Manage Action Lifecycle

Attribute Value
ID UC-BK-22
Name Manage Action Lifecycle
Actors Travel Agent, Administrator
Priority Medium
Related Requirements BK-059, BK-060

Description: The agent updates an action item's status through its lifecycle, including transitioning to In Progress, failing an action, marking it as not required, or reassigning it to another team member.

Preconditions: - A booking exists with action items. - The action item is in a non-terminal status.

Main Flow -- Update Status to In Progress: 1. The agent selects a PENDING action item. 2. The agent changes the status to IN_PROGRESS. 3. The system updates the status and logs the change.

Alternative Flow -- Fail Action: 1. The agent selects a non-terminal action item. 2. The agent chooses to fail the action and provides a failure reason. 3. The system updates the status to FAILED and stores the failure reason. 4. The system logs an ACTION_FAILED event in the activity log.

Alternative Flow -- Mark as Not Required: 1. The agent selects a non-terminal action item. 2. The agent marks the action as NOT_REQUIRED. 3. The system updates the status to NOT_REQUIRED. 4. Any downstream actions that depended on this action are unblocked (treated as if the dependency was satisfied). 5. The system logs the status change.

Alternative Flow -- Reassign Action: 1. The agent selects an action item. 2. The agent changes the assignee to another user or role. 3. The system updates the assignee on the action item. 4. The system logs a reassignment event in the activity log.

Postconditions: - The action item status or assignee is updated as requested. - The activity log records all lifecycle changes.

7.6 UC-BK-23: Add Custom Action

Attribute Value
ID UC-BK-23
Name Add Custom Action
Actors Travel Agent, Administrator
Priority Medium
Related Requirements BK-061

Description: The agent creates an ad-hoc action item on a booking that is not derived from a template. This supports one-off tasks specific to a particular booking.

Preconditions: - A booking exists and is not in COMPLETED or CANCELLED status.

Main Flow: 1. The agent navigates to the booking detail page and selects the Actions tab. 2. The agent clicks "Add Custom Action". 3. The agent enters a description for the action. 4. The agent specifies the assignee (user or role). 5. The agent sets a due date. 6. The agent optionally marks whether the action is required for voucher generation. 7. The agent optionally adds notes. 8. The system creates the action item with status PENDING and no template reference. 9. The system logs a CUSTOM_ACTION_ADDED event in the activity log.

Postconditions: - A new action item exists on the booking with no template reference. - The action item participates in the voucher readiness check if marked as required.

7.7 UC-BK-24: Generate Actions for Added Service Line

Attribute Value
ID UC-BK-24
Name Generate Actions for Added Service Line
Actors System
Priority Medium
Related Requirements BK-062

Description: When a new service line is added to an already CONFIRMED booking, the system generates action items for the new service line only, based on the matching action template set.

Preconditions: - The booking is in CONFIRMED or AMENDED status. - A new service line is being added to the booking. - An active action template set exists matching the new service line's service type.

Main Flow: 1. The agent adds a new service line to a CONFIRMED or AMENDED booking. 2. The system detects that the booking is in a confirmed state. 3. The system looks up the active action template set matching the new service line's service type. 4. The system generates action items for the new service line following the same logic as UC-BK-20 (evaluating creation mode, calculating deadlines, wiring dependencies). 5. The system logs an ACTIONS_GENERATED event in the activity log, noting that it was triggered by a service line addition.

Alternative Flows:

  • AF-01: No matching template set. If no active template set matches the service line's service type, no actions are generated.

Postconditions: - Action items are created for the newly added service line. - Existing action items for other service lines are unaffected. - The activity log records the action generation event.

8. Vouchers + Document Management (M6)

UC-BK-25: Generate Voucher

Attribute Value
ID UC-BK-25
Title Generate Travel Voucher PDF
Actors Travel Agent, Administrator
Preconditions Booking is in CONFIRMED (or later) status; all required actions are COMPLETED or NOT_REQUIRED
Related Requirements BK-055, BK-059-v

Main Flow:

  1. The agent navigates to the booking's Documents tab.
  2. The system checks voucher readiness via isVoucherReady(). If ready, the Generate Voucher button is enabled.
  3. The agent clicks Generate Voucher.
  4. The system loads the booking, active service lines (excluding cancelled and service-charge lines), passengers, and completed action items.
  5. For each service type present, the system loads the matching voucher section template.
  6. The system calls resolveBookingTerms() to collect applicable terms and conditions.
  7. The system passes all data to VoucherRenderer.render(), which: a. Loads voucher-master.html from config/templates/booking/. b. Replaces company placeholders (name, logo, contact). c. Replaces booking placeholders (reference, client name, travel dates). d. Builds the passengers table. e. For each service line, resolves field values from the matching template's field definitions (serviceline, attribute, action, or attachment sources) and builds a detail table. f. Builds the terms and conditions section. g. Converts the final HTML to PDF via OpenHTMLtoPDF.
  8. The system checks completed actions for e-ticket PDFs (actionCode containing "ETICKET" with a documentId in resultData). If found, downloads the PDFs and merges them into the voucher via PdfIngestionService.mergePdfs().
  9. If a previous VOUCHER document exists for this booking, the system archives it (copies S3 object with -v{N} suffix, changes docType to VOUCHER_ARCHIVE).
  10. The system uploads the final PDF to S3 and creates a BookingDocument record (docType=VOUCHER).
  11. The system logs a VOUCHER_GENERATED activity event.
  12. The new document appears in the Documents tab list.

Alternative Flows:

  • AF-01: Not voucher-ready. If required actions are not all completed, the system rejects the request with an error message and the button remains disabled.
  • AF-02: No voucher section template. If a service line's type has no matching template, a generic section is rendered with the service line's description, supplier reference, dates, and notes.
  • AF-03: E-ticket merge failure. If merging e-ticket PDFs fails, the voucher is saved without the e-ticket pages and a warning is logged.

Postconditions: - A PDF voucher is stored in S3 and recorded as a BookingDocument. - Any prior voucher version is archived. - The activity log records the generation event.

UC-BK-26: Upload Document

Attribute Value
ID UC-BK-26
Title Upload a Document to a Booking
Actors Travel Agent, Administrator
Preconditions Booking exists
Related Requirements BK-056

Main Flow:

  1. The agent navigates to the booking's Documents tab and clicks Upload Document.
  2. The system shows the upload modal with fields: file input, document type, optional service line, optional notes.
  3. The agent selects a file (PDF, JPEG, or PNG), chooses a document type, and clicks Upload.
  4. The frontend reads the file as base64 and sends it to POST /blm/document/upload.
  5. The API decodes the base64, calls BookingDocumentStorageService.uploadDocument() which: a. Validates file size (max from SecureStorageConfig). b. Detects MIME type via Apache Tika and validates against allowed types. c. Uploads to S3 with KMS encryption.
  6. The facade creates a CBookingDocument entity and logs a DOCUMENT_UPLOADED activity.
  7. The document appears in the list.

Alternative Flows:

  • AF-01: Invalid file type. Tika detects a disallowed MIME type (e.g., executable). The system rejects with an error.
  • AF-02: File too large. The system rejects with a size limit message.

Postconditions: - The file is stored in S3 with KMS encryption. - A BookingDocument record links the file to the booking.

UC-BK-27: Download Document

Attribute Value
ID UC-BK-27
Title Download a Booking Document
Actors Travel Agent, Administrator
Preconditions Document exists
Related Requirements BK-056

Main Flow:

  1. The agent clicks the download button on a document row in the Documents tab.
  2. The frontend calls requestBlob('document/download', { documentId }).
  3. The API reads the document entity, downloads bytes from S3, and returns them as application/octet-stream with a Content-Disposition header.
  4. The browser saves the file.

UC-BK-28: Email Document

Attribute Value
ID UC-BK-28
Title Email a Document to a Recipient
Actors Travel Agent, Administrator
Preconditions Document exists
Related Requirements BK-056

Main Flow:

  1. The agent clicks the email button on a document row.
  2. The system shows the email modal, pre-filling the recipient from the booking's customer email.
  3. The agent enters or confirms the recipient email, subject, and body, then clicks Send.
  4. The facade downloads the document from S3, writes it to a temporary file, and calls MailUtil.sendMail() with the file path as an attachment.
  5. The temporary file is deleted after sending.
  6. The system logs a DOCUMENT_EMAILED activity.

Alternative Flows:

  • AF-01: No recipient email. The system rejects the request.

UC-BK-29: Delete Document

Attribute Value
ID UC-BK-29
Title Delete a Booking Document
Actors Travel Agent, Administrator
Preconditions Document exists
Related Requirements BK-056

Main Flow:

  1. The agent clicks the delete button on a document row and confirms the action.
  2. The facade deletes the S3 object, removes the database entity, and logs a DOCUMENT_DELETED activity.
  3. The document disappears from the list.

UC-BK-30: Manage Voucher Section Templates

Attribute Value
ID UC-BK-30
Title Configure Voucher Section Templates
Actors Administrator
Preconditions User has admin role
Related Requirements BK-057-v

Main Flow:

  1. The administrator navigates to the Action Templates page and scrolls to the Voucher Section Templates panel.
  2. The system lists all templates with service type, title, field count, and active status.
  3. The administrator clicks the edit button on a template.
  4. The system shows the edit modal with: service type (read-only), section title, header template (HTML), structured field rows, and an active toggle.
  5. Each field row specifies: label, source (serviceline/attribute/action/attachment), field name or path, and action code (for action/attachment sources).
  6. The administrator adds, removes, or reorders fields, then clicks Save.
  7. The system validates (title and at least one field required) and saves.

Postconditions: - The template is updated. Future voucher generations will use the new field configuration.

9. M6.5 Use Cases: Booking Terms Tab

UC-BK-31: Access and Initialize Booking Terms

Attribute Value
ID UC-BK-31
Title Access and Initialize Booking Terms
Actors Travel Agent
Preconditions Booking exists with at least one service line
Related Requirements BK-065, BK-066

Main Flow:

  1. The agent navigates to the booking detail page and clicks the Terms tab (positioned between Passengers and Amendments).
  2. The system checks if any bookingtermsitem records exist for this booking.
  3. If no records exist (first access), the system calls initializeBookingTerms() which: a. Calls resolveBookingTerms() to dynamically resolve all applicable templates. b. For each resolved term (SERVICE per type, CANCELLATION per type, GLOBAL), creates a BookingTermsItem record with isIncluded=true, isCustom=false, and sortOrder incrementing by 10. c. Links each item to its source termsTemplateId for deduplication during refresh.
  4. The system displays the terms list with columns: order arrows, include checkbox, title, type badge, service type, and actions.
  5. All items are checked (included) by default.

Alternative Flows:

  • AF-01: Subsequent access. If records already exist, the system loads and displays them directly (no re-initialization).
  • AF-02: Booking with no service lines. Only GLOBAL terms are initialized.

UC-BK-32: Toggle Terms Inclusion for Voucher

Attribute Value
ID UC-BK-32
Title Toggle Terms Inclusion for Voucher
Actors Travel Agent
Preconditions Terms tab has been initialized
Related Requirements BK-065, BK-069

Main Flow:

  1. On the Terms tab, the agent unchecks the Include checkbox on one or more terms (e.g., "Travel Insurance Advisory").
  2. Excluded items appear with strikethrough text styling.
  3. The agent clicks Save.
  4. The system calls saveBookingTermsItems() which persists all items with their current isIncluded and sortOrder values.
  5. When a voucher is generated, only items with isIncluded=true appear in the PDF.

Postconditions: - Excluded terms do not appear on generated vouchers. - Items are not deleted — they can be re-included later by checking the box again.

UC-BK-33: Add Custom Free-Text Term

Attribute Value
ID UC-BK-33
Title Add Custom Free-Text Term
Actors Travel Agent
Preconditions Terms tab initialized, fewer than 30 custom terms
Related Requirements BK-067

Main Flow:

  1. The agent clicks Add Custom Term on the Terms tab.
  2. A modal opens with title input (max 200 chars) and HTML content textarea.
  3. The agent enters a title (e.g., "Special Visa Requirements") and content.
  4. The agent clicks Add.
  5. The system validates title and content are non-empty, then creates a new BookingTermsItem with termsType="CUSTOM", isCustom=true, isIncluded=true, appended at the end of the sort order.
  6. The new item appears at the bottom of the list with a CUSTOM badge.

Alternative Flows:

  • AF-01: Max 30 reached. If 30 custom terms already exist, the system rejects with an error message.

UC-BK-34: Refresh Terms from Templates

Attribute Value
ID UC-BK-34
Title Refresh Terms from Templates
Actors Travel Agent
Preconditions Terms tab initialized. Service lines may have changed since initialization.
Related Requirements BK-068

Main Flow:

  1. The agent adds a new service line (e.g., FLIGHT) to the booking.
  2. The agent goes to the Terms tab and clicks Refresh from Templates.
  3. The system calls refreshBookingTermsFromTemplates() which: a. Re-resolves terms from current service types. b. Compares resolved terms against existing items by termsTemplateId + termsType. c. Adds only new items (e.g., FLIGHT SERVICE and FLIGHT CANCELLATION terms). d. Does NOT remove or modify existing items, custom entries, or exclude states.
  4. The new items appear at the bottom of the list, included by default.

Postconditions: - New service-type terms are added. - Existing items (including exclusions and custom terms) are preserved.

UC-BK-35: Delete Custom Term

Attribute Value
ID UC-BK-35
Title Delete Custom Term
Actors Travel Agent
Preconditions A custom term exists on the booking
Related Requirements BK-067

Main Flow:

  1. The agent clicks the delete button on a custom term row.
  2. A confirmation dialog appears.
  3. The agent confirms.
  4. The system deletes the BookingTermsItem record.
  5. The item is removed from the list.

Alternative Flows:

  • AF-01: Template-based item. Delete buttons are not shown for template-based items. If attempted via API, the system rejects with an error ("Only custom terms can be deleted").

11. M9 -- Admin Maintenance & Data Health Use Cases

UC-BK-36: Admin Monitors System Health via Dashboard

Attribute Value
ID UC-BK-36
Title Admin Monitors System Health via Dashboard
Actors Administrator
Preconditions Admin has access to the maintenance page
Related Requirements BK-094, BK-095, BK-096

Main Flow:

  1. The admin navigates to the booking maintenance page.
  2. The system calls getSystemHealthSummary() and displays dashboard cards showing: stale cart count, zombie booking count, missed expiry count, ERP sync failure count, failed notification count, and activity log total.
  3. The admin reviews the cards and clicks a tab to investigate any area with non-zero counts.

Postconditions: - Admin has an at-a-glance view of system health across all booking data domains.

UC-BK-37: Admin Cleans Up Stale Carts

Attribute Value
ID UC-BK-37
Title Admin Cleans Up Stale Carts
Actors Administrator
Preconditions Stale carts exist in the system
Related Requirements BK-070, BK-071, BK-072, BK-073

Main Flow:

  1. The admin opens the Carts tab on the maintenance page.
  2. The admin sets filters (age range, status) and clicks Search.
  3. The system displays stale carts with details: Cart ID, Customer, Agent, Status, Items, Total, Created date, Age.
  4. The admin selects one or more carts using checkboxes.
  5. The admin clicks "Expire Selected" or "Abandon Selected".
  6. The system processes the bulk action, updates cart statuses, clears items, and displays the count of carts processed.
  7. The dashboard card refreshes with updated stale cart count.

Alternative Flows:

  • AF-01: No stale carts found. The table displays an empty state message.
  • AF-02: Cart statistics view. The admin views cart statistics showing counts by status and age range.

UC-BK-38: Admin Force-Expires Missed Option Holds

Attribute Value
ID UC-BK-38
Title Admin Force-Expires Missed Option Holds
Actors Administrator
Preconditions Bookings exist with status OPTION_HELD and past expiry dates
Related Requirements BK-077, BK-078, BK-079

Main Flow:

  1. The admin sees a non-zero "Missed Expiries" count on the dashboard.
  2. The admin opens the Bookings tab and views missed expiries.
  3. The system lists bookings that should have been auto-expired but were missed (status OPTION_HELD, optionExpiryDate < now).
  4. The admin clicks "Expire" on a specific booking.
  5. The system calls manualTriggerExpiry(), transitions the booking to EXPIRED, and sends the expiry notification.
  6. The booking is removed from the missed expiries list.

Alternative Flows:

  • AF-01: Expiry runner status check. The admin views the last execution time of the option expiry background runner to determine if it failed.

UC-BK-39: Admin Audits ERP Sync Failures

Attribute Value
ID UC-BK-39
Title Admin Audits ERP Sync Failures
Actors Administrator
Preconditions Bookings exist with missing ERP customer or CRM lead references
Related Requirements BK-084, BK-085, BK-086

Main Flow:

  1. The admin opens the ERP Sync tab on the maintenance page.
  2. The system lists bookings with NULL values for erpCustomerId or erpLeadId, highlighted in red.
  3. The admin clicks "Retry Sync" on a specific booking.
  4. The system re-runs findOrCreateErpCustomer() and createCrmLead() for the selected booking.
  5. On success, the ERP fields are populated and the booking is removed from the failure list.
  6. On failure, the error message is displayed to the admin.

Alternative Flows:

  • AF-01: Batch retry. The admin clicks "Retry All" to attempt sync for all failed bookings.

UC-BK-40: Admin Reviews Failed Notifications

Attribute Value
ID UC-BK-40
Title Admin Reviews Failed Notifications
Actors Administrator
Preconditions Failed notification records exist in the notificationstatus table
Related Requirements BK-087, BK-088, BK-089, BK-090

Main Flow:

  1. The admin opens the Notifications tab on the maintenance page.
  2. The admin filters by status (FAILED) and optionally by notification type or date range.
  3. The system displays failed notifications: Booking Ref, Type, Recipient, Sent At, Status, Error Message, Retry Count.
  4. The admin clicks "Retry" on a specific failed notification.
  5. The system re-sends the notification and updates the notificationstatus record (status changes to RETRIED or SENT, retry count incremented).
  6. The admin views notification statistics showing counts by status and type.

Alternative Flows:

  • AF-01: Retry all failed. The admin clicks "Retry All Failed" to batch-retry all FAILED notifications.
  • AF-02: Investigate error. The admin expands a row to see the full error message for diagnosis.