md / trips / 20260421_trips-plan-guide.md
Molino⺢Pro

20260421_trips-plan-guide

Master Codebase Guidebook
Markdown + HTML Dev-Docs Renderer - Frontend Client Module

Default Index
Open README.md
Root: README.mdtrips
Milestones
⬆ Parent folder📁 archive📁 fh📁 next-steps📝 20260421_trips-plan-guide📝 20260430_city-agenda-session-engine📝 booking-bundle📝 calendar-agenda📝 closure📝 human-layer-checklist📝 README📝 trip-join
H1Next Steps
  1. Keep TripPlannerContext and normalizeStops as the core planner base.
  2. Move to inline TripDetail editing.
  3. Derive hotel policy from trip start date.
  4. Introduce BookingBundle.
  5. Add Apps Script export endpoints.
  6. Keep FareHarbor manual until validation is solid.
H1Trips Next Steps

Status: locked execution plan

This note captures the shortest safe implementation path for the current Trips stage.

Unblock the UX.

  • Keep the current sidebar temporarily
  • Build an inline editor inside TripDetail
  • Reuse TripPlannerContext and normalizeStops
  • Add an edit mode toggle

Result:

  • same logic
  • better UX
  • no regression risk

Lock the hotel rule.

Derived field:

hotelPolicy =
  | "managed_blocked_inventory"
  | "estimate_only"
  | "external_links_only"

Logic:

if (daysUntilStart > 40) {
  hotelPolicy = "managed_blocked_inventory";
} else {
  hotelPolicy = "external_links_only";
}

UI:

  • show room allocation only when managed
  • show booking links only when external

Create the booking layer.

  • Add BookingBundle
  • Add a Request Booking action
  • Create the bundle before execution
  • Move status to pending after the request

Ship Apps Script highway endpoints.

  • /export/pdf
  • /export/email
  • /export/calendar
  • /export/booking-doc

Flow:

Next.js action -> API route -> Apps Script -> Google output -> metadata -> Prisma

Use FareHarbor manual execution by default.

  • Treat FareHarbor as an execution tool, not the backbone
  • Confirm bookings in the dashboard
  • Update status in the app after confirmation

Add FareHarbor calendar validation later.

  • Check availability
  • Validate schedulability
  • Do not automate booking yet
H1Trips Plan - Guidebook

Status: merged guide for the Trips area

Scope:

  • dev-spec-docs/trips only
  • canonical merge of the current trips notes
  • organized by concern and implementation order
H11. Canonical identity

Trips is the public and commercial travel surface of Molino.

Externally:

  • Al-Andalus Experience
  • trips
  • city experiences
  • shared departures
  • local sessions
  • travel planning
  • partner network

Internally:

  • Trip is the bundle
  • SessionCard / Experience / GroupSession are the underlying commercial units
  • Planner is the deterministic authoring surface
  • Booking is execution, not trip truth
H12. Canonical domain order

The merged domain model is:

ConceptCard -> Experience -> GroupSession -> Trip -> LineItems -> Offer -> Order -> Projection

Rules:

  • ConceptCards define how it is understood.
  • Experiences define what is sold.
  • GroupSessions define when it happens.
  • Trips define how it is bundled.
  • Trip truth must not be overwritten by execution systems.
H13. Development order by concern
H2Concern A. Semantic model

This is already established in the older Trips & Itineraries note.

Keep:

  • Sessions are primary
  • Trips are composed
  • A trip reuses existing sessions
  • Trip and non-trip participants may share the same sessions

Keep also:

  • timeline normalization
  • public language simplification
  • channel-manager-safe mapping
H2Concern B. Planner UX

The planner notes converge on one result:

  • current pattern = deterministic form, normalized stops, pricing engine, persisted trip
  • refactor target = inline builder, single surface editing, no step fragmentation

Canonical planner shape:

  • /trips/new is the real builder
  • the sidebar is temporary
  • the final UI is inline sections
  • stops are the single source of truth

Inline sections:

  • Basics
  • Route
  • Services
  • Hotels
  • Options
H2Concern C. Execution

The execution notes add the missing boundary:

  • Trip is planning
  • BookingBundle is fulfillment
  • execution modes are derived, not user promises

Canonical execution model:

  • BookingBundle is separate from Trip
  • hotelPolicy is derived from daysUntilStart
  • FareHarbor is manual-first or validation-first, not system backbone
  • Apps Script handles exports and office outputs
H2Concern D. Public product surface

The guidebook plan remains valid as the external Trips surface:

  • landing page
  • featured/shared trips
  • custom planner
  • trip detail
  • schedule
  • partners
  • cities and experiences discovery

The landing page section map is still canonical:

  • trip_hero
  • trip_pathways
  • trip_how_it_works
  • trip_featured_group_trips
  • trip_featured_cities
  • trip_featured_experiences
  • trip_plan_your_trip
  • trip_for_partners
  • trip_updates
  • trip_final_cta
H2Concern E. Next steps

The locked execution path is:

  1. Fix planner UX
  2. Lock hotel policy
  3. Add BookingBundle
  4. Ship Apps Script highway
  5. Use manual FareHarbor execution by default
  6. Add FareHarbor calendar validation later
H14. Merged canonical rules
  • SessionCard stays atomic for access, pricing, printing, and export.
  • Trip does not define session existence.
  • Planner normalization is pure and deterministic.
  • UI steps are abstraction only, not domain truth.
  • Hotel logic is pluggable and optional.
  • Booking is separate from trip truth.
  • External projections never define internal model boundaries.
  • Public surface and internal model remain separate concerns.
H15. Conflict notes
H2Conflict 1: sessions-first vs trips-first

Resolution:

  • sessions remain the operational primitive
  • trips remain the bundled commercial product
  • the merged guides and trip group costs, keeps both without collapsing them into one model
H2Conflict 2: sidebar planner vs inline planner

Resolution:

  • current pattern documents the existing sidebar flow
  • refactor target defines the future inline builder
  • the unified guide treats the inline builder as the destination
H2Conflict 3: hotel policy variants

Resolution:

  • keep one derived hotelPolicy
  • use managed_blocked_inventory, estimate_only, and external_links_only
  • derive behavior from trip timing, not manual promises
H2Conflict 4: FareHarbor role

Resolution:

  • FareHarbor is a projection / execution bridge
  • it is not truth
  • it stays manual-first until calendar validation is stable
H2Conflict 5: planner vs booking

Resolution:

  • planner produces intent
  • booking bundle captures fulfillment
  • do not mix them in the same surface
H16. Source notes merged

These notes were consolidated into this guide:

  • archive/20260220_trips-sessions-MLV.md
  • archive/20260419_trip.specs.md
  • archive/20260420_trip-planner.current-pattern.md
  • archive/20260420_trip-planner.refactor-target.md
  • archive/20260420_trips-plan.md
  • archive/20260420_trips-guidebook-plan.md
  • archive/20260421_trip-execution-bundle.md
  • archive/20260421_trips-next-steps.locked.md