Pricing Traveler Semantics Refactor Design

Date: 2026-04-13
Status: Approved approach (Approach 2: dual-read, new-write)

Goal

Refactor pricing traveler semantics so that:

• childrenWithoutBed becomes children (naming change only; pricing behavior unchanged)
• childrenWithBed becomes extraMattressCount (pricing-only count)

extraMattressCount must not be treated as traveler count and must not participate in traveler display/count semantics.

Scope

In-scope:

• GET /v1/itinerary/:id/price-details query parsing + response fields
• Booking pricingSelection traveler payload handling in POST /v1/bookings
• Itinerary pricing computation path and persisted travelerDetails
• Pricing API markdown contract updates (docs/pricing-apis.md)

Out-of-scope:

• Unrelated itinerary/business logic changes
• Pricing formula changes beyond semantic remap requested

API Contract Design

New primary keys

• children (actual child travelers)
• extraMattressCount (pricing-only)

Backward-compatible input support (transition)

Temporarily accept both old and new keys in requests/query:

• children fallback to childrenWithoutBed
• extraMattressCount fallback to childrenWithBed

Response normalization

Return only new semantics in pricing selection/traveler sections:

• include children
• include extraMattressCount as a separate pricing field (outside travelerDetails)
• omit childrenWithoutBed and childrenWithBed

Computation & Data Flow

1. Parse incoming counts from query/payload using dual-read mapping.
2. Compute traveler-related values:
   • Traveler count for slabs: adults + children
   • Traveler details count: adults, children, infants
3. Compute pricing components:
   • Child price continues existing child-without-bed behavior, now driven by children
   • Extra bed/mattress price continues existing extra-bed behavior, now driven by extraMattressCount
4. Dinner supplement applies to actual travelers only (adults + children).
5. Persist traveler details without mattress count while allowing read fallback from legacy data where needed.

Internal Mapping Rules

Read-time normalization

• normalizedChildren = children ?? childrenWithoutBed ?? max(childrenInput - extraMattressCount, 0)
• normalizedExtraMattressCount = extraMattressCount ?? childrenWithBed ?? 0

Write-time normalization

Persist and emit:

• children
• extraMattressCount (outside travelerDetails)

Do not emit legacy key names in new API responses.

Error Handling

• Keep existing validations: integer and Min(0) constraints
• If both old and new keys are supplied with conflicting values, prefer new keys (children, extraMattressCount)
• Preserve current API error envelope and status behavior

Testing Strategy

Add/adjust tests for:

1. Query parsing: new keys accepted; old keys still accepted.
2. Slab selection: extraMattressCount does not affect slab banding.
3. Pricing calculation: child and mattress pricing remain aligned with prior price behavior.
4. Response shape: returns new fields only for pricing traveler sections.
5. Booking pricingSelection mapping: accepts new keys and still supports old input aliases.

Files Expected to Change

• src/shared/interfaces/traveler-counts.interface.ts
• src/modules/itinerary/dto/price-details-query.dto.ts
• src/modules/itinerary/dto/pricing-selection.dto.ts
• src/modules/itinerary/interface/traveler-details.interface.ts
• src/modules/itinerary/itinerary.controller.ts
• src/modules/itinerary/itinerary.repository.ts
• src/modules/itinerary/itinerary.service.ts
• src/modules/bookings/dto/create-booking.dto.ts (if exposed docs/schema needs alignment)
• src/modules/bookings/bookings.service.ts
• src/modules/bookings/bookings.repository.ts (traveler text fallback)
• docs/pricing-apis.md

Rollout Notes

• This is a contract transition via dual-read compatibility.
• Frontend should migrate to children + extraMattressCount immediately.
• Legacy keys can be removed in a future cleanup release after client migration.