Cruise Offer Management - Requirements Specification

1. Introduction

1.1 Purpose

This document defines the functional and non-functional requirements for the Cruise Offer Management module of TQPro. It serves as the basis for implementation, testing, and acceptance criteria.

1.2 Scope

The Cruise Offer Management module enables users to manage cruise offers, pricing, itineraries, and availability. The module supports the complete lifecycle from dimensional data setup through cruise instance creation to pricing configuration.

1.3 Document Conventions

• REQ-XXX-NNN: Requirement identifier where XXX is the category and NNN is the sequence number
• [M]: Mandatory requirement
• [O]: Optional requirement
• [F]: Future improvement (out of scope for initial implementation)

1.4 References

• General Requirements: Cruise-Offer-General-Requirements.md
• Database Schema: cruises.sql

---

2. Functional Requirements

2.1 Dimensional Data Management

2.1.1 Cruise Company Management

ID	Requirement	Priority
REQ-DIM-001	The system shall allow users to create a new cruise company with a unique code (max 10 characters) and name (max 50 characters).	[M]
REQ-DIM-002	The system shall allow users to view a list of all cruise companies.	[M]
REQ-DIM-003	The system shall allow users to edit an existing cruise company's code and name.	[M]
REQ-DIM-004	The system shall prevent deletion of a cruise company that has associated ships.	[M]
REQ-DIM-005	The system shall enforce uniqueness of cruise company codes.	[M]
REQ-DIM-006	The system shall allow users to set a color (hex code, max 7 characters) for a cruise company, used for visual identification in the UI.	[O]

2.1.2 Cruise Area Management

ID	Requirement	Priority
REQ-DIM-010	The system shall allow users to create a new cruise area with a unique code (max 10 characters) and description (max 50 characters).	[M]
REQ-DIM-011	The system shall allow users to view a list of all cruise areas.	[M]
REQ-DIM-012	The system shall allow users to edit an existing cruise area's code and description.	[M]
REQ-DIM-013	The system shall prevent deletion of a cruise area that has associated itineraries.	[M]
REQ-DIM-014	The system shall enforce uniqueness of cruise area codes.	[M]

2.1.3 Cruise Ship Management

ID	Requirement	Priority
REQ-DIM-020	The system shall allow users to create a new cruise ship with code (max 10 characters), name (max 50 characters), description (max 1000 characters), optional document URL (max 200 characters), and associated company.	[M]
REQ-DIM-021	The system shall allow users to view a list of all cruise ships, filterable by company.	[M]
REQ-DIM-022	The system shall allow users to edit an existing cruise ship's details.	[M]
REQ-DIM-023	The system shall prevent deletion of a cruise ship that has associated itineraries or ship cabins.	[M]
REQ-DIM-024	The system shall display the company name when listing ships.	[M]

2.1.4 Cabin Type Management

ID	Requirement	Priority
REQ-DIM-030	The system shall allow users to create a new cabin type with a unique code (max 10 characters) and name (max 50 characters).	[M]
REQ-DIM-031	The system shall allow users to view a list of all cabin types.	[M]
REQ-DIM-032	The system shall allow users to edit an existing cabin type's code and name.	[M]
REQ-DIM-033	The system shall prevent deletion of a cabin type that is assigned to any ship.	[M]

2.1.5 Ship Cabin Assignment

ID	Requirement	Priority
REQ-DIM-040	The system shall allow users to assign cabin types to a ship, specifying the maximum passenger capacity for each cabin type on that ship.	[M]
REQ-DIM-041	The system shall display all cabin types assigned to a selected ship with their maximum passenger capacity.	[M]
REQ-DIM-042	The system shall allow users to modify the maximum passenger capacity for an assigned cabin type.	[M]
REQ-DIM-043	The system shall allow users to remove a cabin type assignment from a ship.	[M]
REQ-DIM-044	When removing a cabin type assignment, the system shall warn the user if cabin charges exist for this ship cabin and require confirmation before cascading deletion.	[M]
REQ-DIM-045	The system shall provide a dialog interface showing all available cabin types as checkboxes for bulk assignment to a ship.	[M]
REQ-DIM-046	In the cabin assignment dialog, previously assigned cabin types shall be pre-selected.	[M]

2.1.6 Charge Type Management

ID	Requirement	Priority
REQ-DIM-050	The system shall allow users to create a new charge type with a unique code (max 10 characters) and name (max 50 characters).	[M]
REQ-DIM-051	The system shall allow users to view a list of all charge types.	[M]
REQ-DIM-052	The system shall allow users to edit an existing charge type's code and name.	[M]
REQ-DIM-053	The system shall prevent deletion of a charge type that is used in any cruise's other charges.	[M]
REQ-DIM-054	The system shall enforce uniqueness of charge type codes.	[M]

2.1.7 Cruise Port Management

ID	Requirement	Priority
REQ-DIM-060	The system shall allow users to create a new cruise port with a unique code (max 10 characters) and name (max 50 characters).	[M]
REQ-DIM-061	The system shall allow users to view a list of all cruise ports.	[M]
REQ-DIM-062	The system shall allow users to edit an existing cruise port's code and name.	[M]
REQ-DIM-063	The system shall prevent deletion of a cruise port that is referenced in any cruise template or cruise point.	[M]

---

2.2 Itinerary Management

2.2.1 Itinerary CRUD Operations

ID	Requirement	Priority
REQ-ITN-001	The system shall allow users to create a new itinerary with code (max 50 characters), duration (in nights), associated ship, associated cruise area, and optional image URL (max 500 characters).	[M]
REQ-ITN-002	The system shall allow users to view all itineraries in a hierarchical tree structure grouped by cruise company.	[M]
REQ-ITN-003	The system shall allow users to edit an existing itinerary's details (code, duration, ship, area, image URL).	[M]
REQ-ITN-004	The system shall allow users to delete an itinerary only if it has no associated cruises.	[M]
REQ-ITN-005	The system shall allow users to toggle the active/inactive status of an itinerary.	[M]
REQ-ITN-006	The system shall provide a filter to show/hide inactive itineraries in the tree view.	[M]
REQ-ITN-007	When an itinerary is selected, the system shall display all cruises for that itinerary ordered by start date ascending.	[M]

2.2.2 Cruise Template Management

ID	Requirement	Priority
REQ-ITN-010	The system shall allow users to create template entries for an itinerary, each containing: stop sequence, day offset for arrival, day offset for departure, arrival time, departure time, port of call, and optional description.	[M]
REQ-ITN-011	The system shall allow users to view all template entries for an itinerary sorted by stop sequence.	[M]
REQ-ITN-012	The system shall allow users to edit existing template entries.	[M]
REQ-ITN-013	The system shall allow users to delete template entries.	[M]
REQ-ITN-014	The system shall validate that arrival time and departure time are in valid time format (HH:mm).	[M]
REQ-ITN-015	The system shall validate that day offset values are non-negative integers within the itinerary duration.	[M]
REQ-ITN-016	The system shall allow reordering of template entries by modifying the stop sequence.	[O]
REQ-ITN-017	The system shall allow users to copy/clone an existing itinerary template to a new itinerary.	[O]

---

2.3 Cruise Instance Management

2.3.1 Cruise CRUD Operations

ID	Requirement	Priority
REQ-CRU-001	The system shall allow users to create a new cruise instance by selecting an itinerary and specifying a start date.	[M]
REQ-CRU-002	The system shall display all cruises for a selected itinerary as date buttons ordered by start date ascending.	[M]
REQ-CRU-003	The system shall allow users to delete a cruise instance.	[M]
REQ-CRU-004	When deleting a cruise, the system shall cascade delete all associated cruise points, cabin charges, and other charges after user confirmation.	[M]
REQ-CRU-005	The system shall allow users to change the cruise status (available, cancelled, sold-out).	[M]
REQ-CRU-006	The system shall prevent modification of start date for a cruise that has bookings (future integration point).	[O]

2.3.2 Cruise Point Generation

ID	Requirement	Priority
REQ-CRU-010	When a cruise is created, the system shall automatically generate cruise points based on the itinerary's template entries.	[M]
REQ-CRU-011	For each template entry, the system shall calculate the cruise point arrival date/time by adding the day offset to the cruise start date and combining with the template arrival time.	[M]
REQ-CRU-012	For each template entry, the system shall calculate the cruise point departure date/time by adding the departure day offset to the cruise start date and combining with the template departure time.	[M]
REQ-CRU-013	The system shall copy the port reference and description from the template entry to the generated cruise point.	[M]
REQ-CRU-014	The system shall display all cruise points for a selected cruise in chronological order.	[M]
REQ-CRU-015	If no template exists for an itinerary, the system shall display a message prompting the user to create a template first.	[M]
REQ-CRU-016	The system shall provide a button to regenerate cruise points from template, with warning about overwriting existing points.	[O]

2.3.3 Cruise Point Modification

ID	Requirement	Priority
REQ-CRU-020	The system shall allow users to manually edit cruise point arrival and departure date/times after generation.	[M]
REQ-CRU-021	The system shall allow users to change the port of call for a cruise point.	[M]
REQ-CRU-022	The system shall allow users to update the description of a cruise point.	[M]
REQ-CRU-023	The system shall allow users to add additional cruise points to an existing cruise.	[O]
REQ-CRU-024	The system shall allow users to delete individual cruise points from a cruise.	[O]

---

2.4 Pricing Management

2.4.1 Cabin Charge Management

ID	Requirement	Priority
REQ-PRC-001	The system shall allow users to set a base cabin charge for each ship cabin type on a specific cruise.	[M]
REQ-PRC-002	Each cabin charge shall include: amount, currency (3-character ISO code), and exchange rate.	[M]
REQ-PRC-003	The system shall allow users to mark a cabin as available or unavailable (sold-out) for a specific cruise.	[M]
REQ-PRC-004	The system shall display all cabin types for the cruise's ship with their respective charges.	[M]
REQ-PRC-005	The system shall allow users to edit existing cabin charges.	[M]
REQ-PRC-006	The system shall enforce that only one cabin charge exists per ship cabin per cruise.	[M]
REQ-PRC-007	When opening the pricing page for a cruise, the system shall pre-populate cabin entries for all ship cabins assigned to the cruise's ship.	[M]
REQ-PRC-008	The system shall validate that amount is a positive number and currency is a valid 3-character code.	[M]

2.4.2 Other Charges Management

ID	Requirement	Priority
REQ-PRC-020	The system shall allow users to add other charges to a cruise by selecting a charge type and specifying amount, currency, and exchange rate.	[M]
REQ-PRC-021	The system shall allow users to mark each other charge as mandatory or optional.	[M]
REQ-PRC-022	The system shall display all other charges for a cruise with their charge type name, amount, currency, and mandatory flag.	[M]
REQ-PRC-023	The system shall allow users to edit existing other charges.	[M]
REQ-PRC-024	The system shall allow users to delete other charges from a cruise.	[M]
REQ-PRC-025	The system shall allow multiple other charges of different types on the same cruise.	[M]
REQ-PRC-026	The system shall prevent duplicate charge types on the same cruise.	[M]

2.4.3 Currency Handling

ID	Requirement	Priority
REQ-PRC-030	The system shall store charges in their original currency with an exchange rate for conversion.	[M]
REQ-PRC-031	The system shall support display of prices in the original currency.	[M]
REQ-PRC-032	The system shall calculate converted amounts using the stored exchange rate when displaying in a base currency.	[O]

2.4.4 Pricing Templates

ID	Requirement	Priority
REQ-PRC-040	The system shall support cabin price templates at the itinerary level, defining default cabin pricing for each ship cabin type.	[M]
REQ-PRC-041	The system shall support other charge templates at the itinerary level, defining default other charges with indicator field.	[M]
REQ-PRC-042	When a new sailing is created, the system shall pre-populate cabin charges and other charges from the itinerary's pricing templates.	[M]
REQ-PRC-043	The system shall provide an "Init Cabins" function to auto-create cabin price templates for all ship cabins assigned to the itinerary's ship.	[M]
REQ-PRC-044	Other charges and other charge templates shall support a single-letter indicator field displayed as a badge in the UI.	[M]
REQ-PRC-045	When a currency is selected in any pricing dialog, the system shall auto-fill the exchange rate from a cached exchange rate service (24h cache). If currency equals the local currency, rate shall be set to 1.0. The field shall remain editable.	[M]

---

2.5 Search and Filtering

2.5.1 Cruise Search

ID	Requirement	Priority
REQ-SRC-001	The system shall allow users to search for cruises by cruise area.	[M]
REQ-SRC-002	The system shall allow users to filter cruises by date range (start date from/to).	[M]
REQ-SRC-003	The system shall allow users to filter cruises by cruise company.	[O]
REQ-SRC-004	The system shall allow users to filter cruises by ship.	[O]
REQ-SRC-005	The system shall allow users to filter cruises by duration range.	[O]
REQ-SRC-006	The system shall allow users to search for cruises that stop at a specific port.	[O]
REQ-SRC-007	The system shall allow users to filter cruises by price range (based on lowest cabin price).	[O]
REQ-SRC-008	The system shall allow users to filter cruises by status (available, cancelled, sold-out).	[M]

2.5.2 Booking Interface Search

ID	Requirement	Priority
REQ-SRC-020	The booking interface shall allow selection of cruise area to retrieve all itineraries for that area.	[M]
REQ-SRC-021	The booking interface shall only display cruises with start dates in the future.	[M]
REQ-SRC-022	The booking interface shall display the lowest base cabin price for each cruise in the search results.	[M]
REQ-SRC-023	Upon cruise selection, the booking interface shall display all available cabins with their base prices.	[M]
REQ-SRC-024	Upon cruise selection, the booking interface shall display all other charges (mandatory and optional).	[M]
REQ-SRC-025	The booking interface shall allow users to select a cabin and specify number of adults and children.	[M]
REQ-SRC-026	The booking interface shall calculate and display the total price based on cabin selection, passenger count, and selected optional charges.	[M]

---

2.6 User Interface Requirements

2.6.1 Three-Page Architecture

ID	Requirement	Priority
REQ-UI-001	The cruise management module shall be accessible from the main navigation menu under "Cruises".	[M]
REQ-UI-002	The cruise management module shall consist of three distinct pages: Dashboard (cruise-dash.html), Itinerary Management (cruise-itin.html), and Agent Booking (cruise-agt-book.html).	[M]
REQ-UI-003	Navigation between the three pages shall be seamless, with context (selected company, itinerary, cruise) preserved via URL parameters.	[M]

2.6.2 Dashboard Page (cruise-dash.html)

ID	Requirement	Priority
REQ-UI-010	The dashboard shall display cruise companies as an accordion, each expandable to show its itineraries.	[M]
REQ-UI-011	Each company accordion header shall display the company name with its assigned color as a visual identifier.	[M]
REQ-UI-012	The dashboard shall display five KPI summary cards showing key metrics: sailing areas, ships, itineraries, sailings, and bookings.	[M]
REQ-UI-013	Itineraries within each company shall be displayed as a card grid with itinerary image, code, duration, ship name, and next sailing date.	[M]
REQ-UI-014	Clicking an itinerary card shall navigate to the Itinerary Management page with the itinerary pre-selected.	[M]
REQ-UI-015	The dashboard shall include quick-action buttons for adding new companies and managing dimension data (ships, cabin types, charge types, ports, areas).	[M]
REQ-UI-016	The dashboard shall include a toggle to show/hide inactive itineraries.	[M]

2.6.3 Itinerary Management Page (cruise-itin.html)

ID	Requirement	Priority
REQ-UI-020	The itinerary management page shall use a two-pane layout: left pane for itinerary details and right pane for associated data.	[M]
REQ-UI-021	The left pane shall display the itinerary form (code, duration, ship, area, image URL, status) with save and delete actions.	[M]
REQ-UI-022	The right pane shall contain tabbed sections for: Template Stops, Pricing Templates (cabin price templates and other charge templates), and Sailings.	[M]
REQ-UI-023	The Sailings tab shall display cruise instances as date buttons ordered by start date ascending, with actions to add, delete, and change status.	[M]
REQ-UI-024	Selecting a sailing shall expand its details showing cruise points, cabin charges, other charges, and pre-bookings.	[M]
REQ-UI-025	The Pricing Templates tab shall display cabin price templates with an "Init Cabins" button to auto-create templates for all ship cabins.	[M]
REQ-UI-026	The Pricing Templates tab shall display other charge templates with indicator badge support.	[M]
REQ-UI-027	The itinerary management page shall include dimension data management dialogs accessible from a toolbar.	[M]

2.6.4 Agent Booking Page (cruise-agt-book.html)

ID	Requirement	Priority
REQ-UI-030	The agent booking page shall display a sailing strip at the top showing the selected cruise details (itinerary, ship, dates, status).	[M]
REQ-UI-031	The page shall display cabin availability showing each cabin type with available count, pre-booked count, and pricing.	[M]
REQ-UI-032	The page shall display a booking details section for creating and managing bookings with passenger list, cabin assignments, and add-ons.	[M]
REQ-UI-033	The booking section shall support the full booking lifecycle with status transitions and visual status indicators.	[M]
REQ-UI-034	Passenger entries shall display visa status badges and age category computed from date of birth.	[M]
REQ-UI-035	Cabin assignments shall display own/non-own badges indicating pre-booking allocation.	[M]

2.6.5 Dialog Interfaces

ID	Requirement	Priority
REQ-UI-040	Dimension data editing (ships, cabin types, charge types, ports, areas) shall be presented in modal dialogs.	[M]
REQ-UI-041	The ship cabin assignment interface shall present all cabin types as checkboxes in a dialog.	[M]
REQ-UI-042	Confirmation dialogs shall be displayed before destructive operations (delete, cascade delete).	[M]
REQ-UI-043	Error messages shall be displayed in a user-friendly format near the relevant input field or in a notification area.	[M]

---

2.7 Pre-Booking Management

2.7.1 Pre-Booking CRUD

ID	Requirement	Priority
REQ-PRE-001	The system shall allow users to pre-book cabins for a specific sailing and cabin type, creating individual pre-booking records with status "Available".	[M]
REQ-PRE-002	Each pre-booking record shall store: cruise ID, ship cabin ID, cost per cabin, price per cabin, commission percentage, status, and created date.	[M]
REQ-PRE-003	The system shall provide a managePrebookings operation that accepts a target count and uses smart add/reduce logic to match the target.	[M]
REQ-PRE-004	The managePrebookings operation shall not allow reducing the target count below the number of non-Available (Reserved + Booked) pre-bookings.	[M]
REQ-PRE-005	The managePrebookings operation shall optionally apply updated cost, price, and commission to all existing pre-bookings when "apply to all" is selected.	[M]
REQ-PRE-006	Pre-booking status shall follow the lifecycle: Available → Reserved → Booked. The transition from Available to Reserved shall occur automatically when a booked cabin is assigned with a pre-booking reference. The transition from Reserved to Booked shall occur automatically when the associated booking status reaches "Vouchered".	[M]

---

2.8 Booking Management

2.8.1 Booking CRUD

ID	Requirement	Priority
REQ-BKG-001	The system shall allow agents to create a new cruise booking for a specific sailing with a system-generated booking number in the format PT-DDMM-XXXXXXXX.	[M]
REQ-BKG-002	Each booking shall store: booking number, cruise ID, lead passenger name, total pax, total adults, total children, total infants, total amount, status, voucher URL, and created date.	[M]
REQ-BKG-003	The system shall support the following booking status lifecycle with valid transitions: Documents pending → Availability pending → Payment pending → Voucher pending → Vouchered.	[M]
REQ-BKG-004	The system shall support cancellation branches: Documents pending/Availability pending → Cancelled-NonRefundable; Payment pending → Cancelled-NonRefundable or Cancelled-RefundPending; Voucher pending/Vouchered → Cancelled-RefundPending; Cancelled-RefundPending → Cancelled-Refunded.	[M]
REQ-BKG-005	The system shall automatically recalculate booking totals (total amount) when cabins or add-ons are added or removed.	[M]
REQ-BKG-006	The system shall allow agents to delete a booking, with cascading deletion of all passengers, booked cabins, and add-ons.	[M]

2.8.2 Passenger Management

ID	Requirement	Priority
REQ-BKG-010	The system shall allow agents to add passengers to a booking with first name, last name, nationality, date of birth, passport number, passport expiry, lead passenger flag, and remarks.	[M]
REQ-BKG-011	The system shall compute age categories (Adult ≥12, Child 2-11, Infant <2) based on the passenger's date of birth relative to the sailing start date.	[M]
REQ-BKG-012	The system shall support nationality selection via autocomplete from a country list (using restcountries.com API).	[M]
REQ-BKG-013	The system shall perform visa requirement checks for each passenger against the cruise destination ports using the visa/lookuprequirement API.	[M]
REQ-BKG-014	The system shall display visa status badges (visa required, visa free, visa on arrival) for each passenger.	[M]

2.8.3 Cabin Assignment

ID	Requirement	Priority
REQ-BKG-020	The system shall allow agents to assign cabins to a booking, specifying ship cabin type, number of passengers, and price.	[M]
REQ-BKG-021	When assigning a cabin, the system shall check for available pre-bookings for the cabin type and sailing, and assign them as "own" cabins (isOwn=true) with preBookingId reference when available.	[M]
REQ-BKG-022	Cabins without available pre-bookings shall be assigned as non-own (isOwn=false).	[M]
REQ-BKG-023	The system shall display own/non-own status with visual badges in the cabin list.	[M]
REQ-BKG-024	The system shall validate that the number of passengers (numPax) per booked cabin does not exceed the cabin type's maximum capacity (maxPax). Validation shall occur both on the frontend (dynamic input max attribute) and backend (error CRU0207).	[M]
REQ-BKG-025	The system shall display a red capacity warning below the passengers section when the total number of passengers exceeds the sum of maxPax across all booked cabins.	[M]

2.8.4 Add-on Management

ID	Requirement	Priority
REQ-BKG-030	The system shall allow agents to attach optional charges (add-ons) to a booking, optionally linked to a specific passenger.	[M]
REQ-BKG-031	Each add-on shall reference a charge type with amount and currency.	[M]
REQ-BKG-032	The add-on amount shall be pre-filled from the sailing's other charge amount when selecting a charge type.	[M]
REQ-BKG-033	The system shall filter the passenger dropdown when adding an add-on based on the charge type's paxType attribute: "adult" excludes passengers under 12, "child" excludes passengers 12+, "per_cabin" disables the passenger dropdown, "all" shows all passengers.	[M]

---

3. Data Requirements

3.1 Entity Relationships

ID	Requirement	Priority
REQ-DAT-001	Cruise Company → Cruise Ship: One-to-many relationship.	[M]
REQ-DAT-002	Cruise Ship → Itinerary: One-to-many relationship.	[M]
REQ-DAT-003	Cruise Area → Itinerary: One-to-many relationship.	[M]
REQ-DAT-004	Cruise Ship ↔ Cabin Type: Many-to-many relationship via Ship Cabin.	[M]
REQ-DAT-005	Itinerary → Cruise: One-to-many relationship.	[M]
REQ-DAT-006	Itinerary → Cruise Template: One-to-many relationship.	[M]
REQ-DAT-007	Cruise → Cruise Point: One-to-many relationship.	[M]
REQ-DAT-008	Cruise Port → Cruise Point: One-to-many relationship.	[M]
REQ-DAT-009	Cruise Port → Cruise Template: One-to-many relationship.	[M]
REQ-DAT-010	Ship Cabin → Cabin Charge: One-to-many relationship (per cruise).	[M]
REQ-DAT-011	Cruise → Cabin Charge: One-to-many relationship.	[M]
REQ-DAT-012	Charge Type → Other Charge: One-to-many relationship.	[M]
REQ-DAT-013	Cruise → Other Charge: One-to-many relationship.	[M]

3.2 Data Validation Rules

ID	Requirement	Priority
REQ-DAT-020	All code fields shall be unique within their entity type.	[M]
REQ-DAT-021	All code fields shall not exceed 10 characters (except itinerary code: 50 characters).	[M]
REQ-DAT-022	All name/description fields shall not exceed their defined maximum lengths.	[M]
REQ-DAT-023	Currency codes shall be exactly 3 characters (ISO 4217 format).	[M]
REQ-DAT-024	Monetary amounts shall be positive numbers.	[M]
REQ-DAT-025	Exchange rates shall be positive numbers.	[M]
REQ-DAT-026	Cruise start dates shall be valid dates.	[M]
REQ-DAT-027	Itinerary duration shall be a positive integer.	[M]
REQ-DAT-028	Ship cabin maximum passenger capacity shall be a positive integer.	[M]
REQ-DAT-029	Template day offsets shall be non-negative integers not exceeding the itinerary duration.	[M]
REQ-DAT-030	Template times shall be in valid HH:mm format.	[M]

---

4. Non-Functional Requirements

4.1 Performance

ID	Requirement	Priority
REQ-NFR-001	The system shall load the company/itinerary tree within 2 seconds for up to 100 companies and 1000 itineraries.	[M]
REQ-NFR-002	Cruise point generation from template shall complete within 1 second for itineraries with up to 20 stops.	[M]
REQ-NFR-003	Search results shall be returned within 3 seconds for queries returning up to 500 cruises.	[M]

4.2 Usability

ID	Requirement	Priority
REQ-NFR-010	All form fields shall have appropriate labels and placeholder text.	[M]
REQ-NFR-011	Required fields shall be clearly marked.	[M]
REQ-NFR-012	The interface shall provide visual feedback during loading operations.	[M]
REQ-NFR-013	The interface shall be responsive and functional on desktop browsers (minimum 1280px width).	[M]

4.3 Security

ID	Requirement	Priority
REQ-NFR-020	Access to cruise management shall require user authentication.	[M]
REQ-NFR-021	Cruise management operations shall be restricted to users with appropriate roles.	[M]
REQ-NFR-022	All API endpoints shall validate user permissions before executing operations.	[M]

4.4 Reliability

ID	Requirement	Priority
REQ-NFR-030	Database operations shall be transactional to ensure data consistency.	[M]
REQ-NFR-031	Cascade deletions shall be atomic - either all related records are deleted or none.	[M]

---

5. Database Schema Requirements

5.1 Required Tables

The following tables are required (already implemented in cruises.sql):

Table	Purpose
cruisecompany	Stores cruise company master data
cruisearea	Stores cruise area/region definitions
cruiseship	Stores ship information linked to companies
cabintype	Stores cabin type definitions
shipcabin	Links cabin types to ships with capacity
itinerary	Stores itinerary definitions
cruisetemplate	Stores template entries for itinerary routes
cruise	Stores cruise instances
cruisepoint	Stores actual stops for cruise instances
cruiseport	Stores port of call definitions
chargetype	Stores charge type definitions
cabincharge	Stores cabin pricing per cruise
othercharge	Stores additional charges per cruise
cabinpricetemplate	Stores default cabin pricing per itinerary
otherchargetemplate	Stores default other charges per itinerary
cabinprebooking	Stores pre-booked cabin inventory per sailing
cruisebooking	Stores master booking records
cruisepassenger	Stores passenger details per booking
bookedcabin	Stores cabin assignments per booking
bookingaddon	Stores optional add-on charges per booking

5.2 Schema Enhancements Required

ID	Requirement	Priority
REQ-SCH-001	Add status column to itinerary table for active/inactive flag.	[M]
REQ-SCH-002	Add status column to cruise table for available/cancelled/sold-out status.	[M]
REQ-SCH-003	Add name column to itinerary table for display name.	[M]
REQ-SCH-004	Add description column to shipcabin table for cabin amenities.	[O]
REQ-SCH-005	Add paxtype column to othercharge table for adult/child/unified classification.	[O]
REQ-SCH-006	Add description column to cruisetemplate table for stop descriptions.	[O]
REQ-SCH-007	Add stopseq column to cruisepoint table to maintain ordering.	[O]

---

6. API Requirements

6.1 API Conventions

All Cruise API endpoints follow the TQPro API conventions:

• Base URL: /tlinq-api/cruise
• HTTP Method: All endpoints use POST only
• Content-Type: application/json for both request and response
• Request Body: JSON object containing session parameter and operation-specific parameters
• Response: Wrapped in TlinqApiResponse object with status, errorCode, errorMessage, and data fields
• IDs: Entity identifiers are passed in the request body, not in the URL path

6.2 Standard Request/Response Format

Request Structure:

{
  "session": "session-token",
  "entityId": 123,
  "field1": "value1",
  "field2": "value2"
}

Response Structure:

{
  "status": "OK",
  "errorCode": null,
  "errorMessage": null,
  "data": { ... }
}

Error Response:

{
  "status": "ERROR",
  "errorCode": "CRU0001",
  "errorMessage": "Error description",
  "data": null
}

6.3 Cruise Company Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/company/list	List all cruise companies	session, companyCode (opt), companyName (opt)	Array of CCruiseCompany
/cruise/company/read	Get company by ID	session, companyId	CCruiseCompany
/cruise/company/write	Create or update company	session, companyId (opt for create), code, name	CCruiseCompany
/cruise/company/delete	Delete company	session, companyId	Success message

6.4 Cruise Area Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/area/list	List all cruise areas	session, areaCode (opt), description (opt)	Array of CCruiseArea
/cruise/area/read	Get area by ID or code	session, areaId (opt), areaCode (opt)	CCruiseArea
/cruise/area/write	Create or update area	session, areaId (opt for create), code, description	CCruiseArea
/cruise/area/delete	Delete area	session, areaId	Success message

6.5 Cruise Ship Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/ship/list	List all ships	session, companyId (opt filter)	Array of CCruiseShip
/cruise/ship/read	Get ship by ID	session, shipId	CCruiseShip
/cruise/ship/write	Create or update ship	session, shipId (opt), code, name, description, docUrl (opt), companyId	CCruiseShip
/cruise/ship/delete	Delete ship	session, shipId	Success message

6.6 Cabin Type Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/cabintype/list	List all cabin types	session	Array of CCabinType
/cruise/cabintype/read	Get cabin type by ID	session, cabinId	CCabinType
/cruise/cabintype/write	Create or update cabin type	session, cabinId (opt), code, name	CCabinType
/cruise/cabintype/delete	Delete cabin type	session, cabinId	Success message

6.7 Ship Cabin Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/shipcabin/list	List cabin assignments for ship	session, shipId	Array of CShipCabin
/cruise/shipcabin/read	Get ship cabin by ID	session, shipCabinId	CShipCabin
/cruise/shipcabin/write	Create or update ship cabin	session, shipCabinId (opt), shipId, cabinTypeId, maxPax, description (opt)	CShipCabin
/cruise/shipcabin/delete	Delete ship cabin assignment	session, shipCabinId, confirmCascade (opt)	Success message
/cruise/shipcabin/bulkAssign	Bulk assign cabin types to ship	session, shipId, cabinTypeIds (array)	Array of CShipCabin

6.8 Charge Type Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/chargetype/list	List all charge types	session	Array of CChargeType
/cruise/chargetype/read	Get charge type by ID	session, chargeTypeId	CChargeType
/cruise/chargetype/write	Create or update charge type	session, chargeTypeId (opt), code, name	CChargeType
/cruise/chargetype/delete	Delete charge type	session, chargeTypeId	Success message

6.9 Cruise Port Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/port/list	List all cruise ports	session, portCode (opt), portName (opt)	Array of CCruisePort
/cruise/port/read	Get port by ID	session, cruisePortId	CCruisePort
/cruise/port/write	Create or update port	session, cruisePortId (opt), code, name	CCruisePort
/cruise/port/delete	Delete port	session, cruisePortId	Success message

6.10 Itinerary Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/itinerary/list	List itineraries	session, companyId (opt), areaId (opt), shipId (opt), includeInactive (opt, default false)	Array of CItinerary
/cruise/itinerary/read	Get itinerary by ID	session, itineraryId, withTemplate (opt)	CItinerary
/cruise/itinerary/write	Create or update itinerary	session, itineraryId (opt), code, name, duration, shipId, areaId, imageUrl (opt), status (opt)	CItinerary
/cruise/itinerary/delete	Delete itinerary	session, itineraryId	Success message
/cruise/itinerary/changeStatus	Toggle active/inactive	session, itineraryId, status	CItinerary
/cruise/itinerary/tree	Get hierarchical tree	session, includeInactive (opt)	Hierarchical structure by company

6.11 Cruise Template Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/template/list	List template entries for itinerary	session, itineraryId	Array of CCruiseTemplate (sorted by stopSeq)
/cruise/template/read	Get template entry by ID	session, cruiseTemplateId	CCruiseTemplate
/cruise/template/write	Create or update template entry	session, cruiseTemplateId (opt), itineraryId, stopSeq, dayOffsetArr, dayOffsetDep, arriveTime, departTime, cruisePortId, description (opt)	CCruiseTemplate
/cruise/template/delete	Delete template entry	session, cruiseTemplateId	Success message

6.12 Cruise Instance Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/cruise/list	List cruises for itinerary	session, itineraryId, includeAll (opt, default false shows future only)	Array of CCruise
/cruise/cruise/read	Get cruise by ID	session, cruiseId, withPoints (opt), withPricing (opt)	CCruise
/cruise/cruise/write	Create cruise (generates points)	session, cruiseId (opt), itineraryId, startDate	CCruise
/cruise/cruise/delete	Delete cruise (cascade)	session, cruiseId, confirmCascade (opt)	Success message
/cruise/cruise/changeStatus	Change cruise status	session, cruiseId, status (available/cancelled/sold-out)	CCruise

6.13 Cruise Point Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/cruisepoint/list	List points for cruise	session, cruiseId	Array of CCruisePoint (sorted chronologically)
/cruise/cruisepoint/read	Get cruise point by ID	session, cruisePointId	CCruisePoint
/cruise/cruisepoint/write	Update cruise point	session, cruisePointId, arrivedt, departdt, cruisePortId, description (opt)	CCruisePoint
/cruise/cruisepoint/delete	Delete cruise point	session, cruisePointId	Success message
/cruise/cruisepoint/regenerate	Regenerate points from template	session, cruiseId, confirmOverwrite (opt)	Array of CCruisePoint

6.14 Cabin Charge Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/cabincharge/list	List cabin charges for cruise	session, cruiseId	Array of CCabinCharge
/cruise/cabincharge/read	Get cabin charge by ID	session, chargeId	CCabinCharge
/cruise/cabincharge/write	Create or update cabin charge	session, chargeId (opt), cruiseId, shipCabinId, amount, currency, exrate, available	CCabinCharge
/cruise/cabincharge/delete	Delete cabin charge	session, chargeId	Success message
/cruise/cabincharge/initForCruise	Initialize charges for all ship cabins	session, cruiseId	Array of CCabinCharge

6.15 Other Charge Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/othercharge/list	List other charges for cruise	session, cruiseId	Array of COtherCharge
/cruise/othercharge/read	Get other charge by ID	session, chargeId	COtherCharge
/cruise/othercharge/write	Create or update other charge	session, chargeId (opt), cruiseId, chargeTypeId, amount, currency, exrate, mandatory	COtherCharge
/cruise/othercharge/delete	Delete other charge	session, chargeId	Success message

6.16 Search Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/searchCruises	Search cruises with filters	session, areaId (opt), companyId (opt), shipId (opt), dateRangeStart (opt), dateRangeEnd (opt), minDuration (opt), maxDuration (opt), portId (opt), status (opt)	CCruiseSearch
/cruise/getCruiseArea	Get area by ID or code	session, areaId (opt), areaCode (opt)	CCruiseArea
/cruise/listCompanies	List companies (existing)	session, companyCode (opt), companyName (opt)	Array of CCruiseCompany

6.17 Booking Interface Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/booking/getItineraries	Get itineraries for area	session, areaId	Array of CItinerary with lowest price
/cruise/booking/getCruises	Get available cruises for itinerary	session, itineraryId	Array of CCruise with lowest price
/cruise/booking/getAvailability	Get full availability and pricing	session, cruiseId	CCruiseAvailability with cabins and charges
/cruise/booking/calculatePrice	Calculate total price	session, cruiseId, shipCabinId, adults, children, optionalChargeIds (array)	CPriceCalculation

6.18 Pre-Booking Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/prebooking/list	List pre-bookings	session, cruiseId, shipCabinId (opt), status (opt)	Array of CCabinPreBooking
/cruise/prebooking/write	Create or update pre-booking	session, preBookingId (opt), cruiseId, shipCabinId, costPerCabin, pricePerCabin, commission	CCabinPreBooking
/cruise/prebooking/delete	Delete pre-booking	session, preBookingId	Success message
/cruise/prebooking/manage	Smart manage pre-booking count	session, cruiseId, shipCabinId, targetCount, cost, price, commission, applyPriceToAll	Array of CCabinPreBooking

6.19 Booking CRUD Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/booking/list	List bookings for a cruise	session, cruiseId, status (opt)	Array of CCruiseBooking
/cruise/booking/read	Read booking by ID	session, bookingId	CCruiseBooking
/cruise/booking/write	Create or update booking	session, bookingId (opt), cruiseId, bookingNumber, leadPassengerName, totalPax, totalAdults, totalChildren, totalInfants, totalAmount	CCruiseBooking
/cruise/booking/delete	Delete booking	session, bookingId	Success message
/cruise/booking/changeStatus	Change booking status	session, bookingId, status	CCruiseBooking

6.20 Passenger Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/passenger/list	List passengers for a booking	session, bookingId	Array of CCruisePassenger
/cruise/passenger/write	Create or update passenger	session, passengerId (opt), bookingId, firstName, lastName, nationality, dateOfBirth, passportNumber, passportExpiry, isLeadPassenger, remarks	CCruisePassenger
/cruise/passenger/delete	Delete passenger	session, passengerId	Success message

6.21 Booked Cabin Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/bookedcabin/list	List booked cabins for a booking	session, bookingId	Array of CBookedCabin
/cruise/bookedcabin/write	Create or update booked cabin	session, bookedCabinId (opt), bookingId, shipCabinId, numPax, isOwn, price, status, preBookingId	CBookedCabin
/cruise/bookedcabin/delete	Delete booked cabin	session, bookedCabinId	Success message

6.22 Booking Add-on Endpoints

Endpoint	Description	Request Parameters	Response
/cruise/addon/list	List add-ons for a booking	session, bookingId	Array of CBookingAddon
/cruise/addon/write	Create or update add-on	session, addonId (opt), bookingId, passengerId (opt), chargeTypeId, amount, currency	CBookingAddon
/cruise/addon/delete	Delete add-on	session, addonId	Success message

6.23 Error Codes

Code	Description
CRU0001	General error
CRU0002	Missing required parameter
CRU0003	Entity not found
CRU0004	Duplicate code - uniqueness violation
CRU0005	Cannot delete - entity has dependencies
CRU0006	Invalid date format (expected yyyy-MM-dd)
CRU0007	Invalid time format (expected HH:mm)
CRU0008	Invalid amount - must be positive
CRU0009	Invalid currency code
CRU0010	Cascade delete requires confirmation
CRU0011	Template not found for itinerary
CRU0012	Duplicate cabin charge for ship cabin on cruise
CRU0013	Duplicate charge type on cruise
CRU0014	Invalid status value
CRU0015	Cannot modify cruise with bookings

---

7. Future Improvements

The following items are identified for future implementation phases:

7.1 Bulk Operations [F]

• Bulk cruise creation for a date range (e.g., weekly cruises for an entire season)
• Bulk pricing updates across multiple cruises
• Bulk status changes

7.2 Reporting and Analytics [F]

• Revenue reporting per cruise/itinerary/ship/company
• Occupancy and availability reports
• Popular routes and ports analysis
• Pricing trend analysis
• Booking conversion reports

7.3 Advanced Features [F]

• Pricing history and versioning
• Seasonal pricing rules engine
• Early-bird and last-minute pricing automation
• Cabin inventory quantity management (beyond binary available/sold-out)
• Audit trail for all changes
• Integration with booking system for real-time availability updates

---

8. Appendix

8.1 Glossary

Term	Definition
Itinerary	A defined cruise route with specific stops, served by a particular ship
Cruise	An instance of an itinerary with a specific start date
Cruise Point	A specific stop on a cruise with arrival/departure times
Cruise Template	A reusable definition of stops for an itinerary
Ship Cabin	The association of a cabin type with a specific ship
Cabin Charge	The base price for a cabin type on a specific cruise
Other Charge	Additional fees (port taxes, gratuities, packages) for a cruise

8.2 Status Definitions

Entity	Status	Description
Itinerary	Active	Itinerary is available for cruise creation
Itinerary	Inactive	Itinerary is hidden from normal views
Cruise	Available	Cruise is open for booking
Cruise	Cancelled	Cruise has been cancelled
Cruise	Sold-out	All cabins on cruise are sold
Cabin Charge	Available	Cabin type is available for booking on this cruise
Cabin Charge	Unavailable	Cabin type is sold out for this cruise
Booking	Documents pending	Initial status upon booking creation
Booking	Availability pending	Awaiting cabin availability confirmation
Booking	Payment pending	Awaiting customer payment
Booking	Voucher pending	Payment received, awaiting voucher generation
Booking	Vouchered	Booking complete with voucher issued
Booking	Cancelled-NonRefundable	Booking cancelled, no refund applicable
Booking	Cancelled-RefundPending	Booking cancelled, refund in process
Booking	Cancelled-Refunded	Booking cancelled and refunded
Pre-Booking	Available	Pre-booking available for assignment
Pre-Booking	Reserved	Pre-booking reserved for a pending booking
Pre-Booking	Booked	Pre-booking assigned to a confirmed booking