naser
/
libra
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
libra/docs/epics/epic-11-guest-booking.md

4.3 KiB
Raw Blame History

Epic 11: Guest Booking

Epic Goal

Enable website visitors to request consultation bookings without requiring a user account, expanding accessibility while maintaining system integrity and admin control over the booking approval process.

Epic Description

Existing System Context

  • Current functionality: Booking system fully implemented for authenticated clients at /client/consultations/book
  • Technology stack: Laravel 12, Livewire 3/Volt, Flux UI, existing AvailabilityService
  • Integration points: Consultation model, email notifications, admin booking review workflow
  • Current constraint: consultations.user_id is a required foreign key to users table

Enhancement Details

What's being added:

  • Public booking form at /booking for unauthenticated visitors
  • Guest contact information capture (name, email, phone)
  • Custom captcha system (no third-party services)
  • 1-per-day booking limit for guests (enforced by email)
  • Guest-specific email notifications
  • Admin visibility of guest bookings in existing workflow

How it integrates:

  • Reuses existing AvailabilityService and availability-calendar component
  • Extends Consultation model to support nullable user_id with guest fields
  • Fits into existing admin booking review workflow
  • Uses existing email infrastructure

Success criteria:

  • Guests can submit booking requests from public /booking page
  • Guests limited to 1 booking request per day (by email)
  • Custom captcha prevents automated spam
  • Admin sees guest bookings in pending queue with contact info
  • Guests receive email confirmations
  • Existing client booking flow unchanged

Stories

Story 11.1: Database Schema & Model Updates

Extend consultation system to support guest bookings with new database fields and model logic.

Story 11.2: Public Booking Form with Custom Captcha

Create guest booking interface at /booking with availability calendar, contact form, custom captcha, and 1-per-day limit.

Story 11.3: Guest Email Notifications & Admin Integration

Implement guest email notifications and update admin interface to handle guest bookings.

Story 11.4: Documentation Updates

Update PRD and other documentation files to reflect guest booking functionality.

Compatibility Requirements

  • Existing client booking flow remains unchanged
  • Existing APIs remain unchanged
  • Database schema changes are backward compatible (nullable field, new columns)
  • UI changes follow existing patterns (Flux UI, Volt components)
  • Admin workflow enhanced, not replaced

Technical Considerations

Database Changes

consultations table:
- user_id: bigint -> bigint NULLABLE
- guest_name: varchar(255) NULLABLE
- guest_email: varchar(255) NULLABLE
- guest_phone: varchar(50) NULLABLE

Validation Rules

  • Either user_id OR (guest_name + guest_email + guest_phone) required
  • Guest email format validation
  • Guest phone format validation
  • 1 booking request per guest email per day

Custom Captcha System

  • Simple math-based or image-based captcha
  • No external services (no Google reCAPTCHA, no Cloudflare Turnstile)
  • Server-side validation with session-stored answer
  • Accessible design with refresh option

Spam Protection

  • 1-per-day limit: Maximum 1 booking request per email address per 24 hours
  • Rate limit: 5 booking requests per IP per 24 hours (backup protection)
  • Custom captcha: Required for all guest submissions

Email Templates

  • Reuse existing email layout/branding
  • Guest emails use provided email address
  • Include all booking details + contact instructions

Risk Mitigation

  • Primary Risk: Spam/abuse from anonymous submissions
  • Mitigation: Custom captcha + 1-per-day email limit + IP rate limiting + admin approval required
  • Rollback Plan: Revert migration, restore placeholder page

Definition of Done

  • All stories completed with acceptance criteria met
  • Existing client booking tests still pass
  • New tests cover guest booking scenarios
  • Admin can manage guest bookings through existing interface
  • Guest receives appropriate email notifications
  • Custom captcha working correctly
  • 1-per-day limit enforced
  • No regression in existing features
  • Bilingual support (Arabic/English) for guest form and emails
  • PRD and documentation updated