feat: scaffold holiday booking project

04-booking-availability-and-pricing.md

@@ -0,0 +1,96 @@
+# 04. Booking, Availability, and Pricing
+
+## Purpose
+
+Define the booking journey and the rules that control availability and price calculation.
+
+## Scope
+
+- Booking flow from property selection through checkout.
+- Booking form fields and validation rules.
+- Booking statuses and state transitions.
+- Availability checks and date handling.
+- Price calculation inputs and outputs.
+- Pet-related conditional logic.
+
+## Proposed Booking Rules
+
+### Booking Flow
+
+1. Select property.
+2. Select arrival date.
+3. Select departure date.
+4. Select guest counts.
+5. Confirm availability.
+6. Review price.
+7. Enter customer details.
+8. Accept terms and conditions.
+9. Proceed to Stripe Checkout.
+10. Complete payment.
+11. Return to the site.
+12. See confirmation or failure state.
+13. Receive confirmation email if payment succeeds.
+
+### Booking Fields
+
+- First name
+- Last name
+- Email address
+- Phone number
+- Arrival date
+- Departure date
+- Number of adults
+- Number of children
+- Special requests/message
+- Terms acceptance
+- Number of pets when the property allows pets
+- Optional address, country, estimated arrival time, and marketing consent
+
+### Booking Status Model
+
+- Pending Payment
+- Payment Received
+- Confirmed
+- Cancelled
+- Failed
+
+### Availability Logic
+
+- Availability checks happen before payment.
+- Unavailable dates prevent a booking from proceeding.
+- Availability must respect both published availability blocks and already confirmed bookings.
+- The system must be able to show a calendar or date-state view on the property page.
+
+### Pricing Logic
+
+- Price is shown before checkout.
+- Price must be calculated from the selected property, dates, guest count, and any relevant seasonal or override pricing rules.
+- The displayed price and the charged price must match.
+- Any deposit or fee rules must be explicit if introduced later.
+
+## What Needs to Be Done
+
+- Define the booking lifecycle.
+- Define when a booking becomes pending, confirmed, cancelled, or failed.
+- Define how availability is checked and reserved.
+- Define what data is required before checkout.
+- Define how price is calculated and displayed.
+- Define the exact handoff point between the booking form and Stripe Checkout.
+- Define how long a hold lasts if a booking is started but not completed.
+
+## Acceptance Criteria
+
+- The booking flow is explicit from first selection to final confirmation.
+- The status model is clear enough to implement later without guessing.
+- Availability rules and pricing rules are documented separately.
+- Edge cases are called out, especially around partial completion and failed payment.
+- The document makes it clear which step owns truth for booking state.
+
+## Dependencies
+
+- Public website and search planning.
+- Content architecture and data model.
+
+## Notes
+
+- This document should be the source of truth for any later booking implementation.