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

8.0 KiB
Raw Blame History

Epic 3: Booking & Consultation System

Epic Goal

Implement a complete consultation booking system with calendar-based availability, admin approval workflow, consultation type assignment (free/paid), and automated reminders.

Epic Description

Business Context

Clients book consultations through a calendar interface. Each consultation is 45 minutes with a 15-minute buffer. The admin reviews requests, determines if free or paid, and approves/rejects. Clients are limited to 1 consultation per day. Payment is handled offline.

Technical Context

  • Duration: 45 minutes consultation + 15 minutes buffer = 1 hour slot
  • Limit: Maximum 1 consultation per client per day
  • Types: Free or Paid (determined by admin)
  • Payment: Offline only (no gateway)
  • Calendar: Real-time availability display

Success Criteria

  • Calendar displays available time slots
  • Clients can submit booking requests
  • 1 consultation per day per client enforced
  • Admin can approve/reject bookings
  • Admin assigns free/paid status
  • Email notifications at each stage
  • Consultation reminders (24hr, 2hr)
  • Calendar file (.ics) generation
  • Admin can mark as completed/no-show/cancelled

Stories

Story 3.1: Working Hours Configuration

Description: Allow admin to configure available working hours for each day of the week.

Acceptance Criteria:

  • Set available days (enable/disable each day)
  • Set start and end time for each day
  • Support different hours for different days
  • 15-minute buffer automatically applied between appointments
  • Changes take effect immediately
  • Existing approved bookings not affected by changes
  • Visual preview of weekly schedule
  • 12-hour time format (AM/PM)

Technical Notes:

  • Store in working_hours table
  • Fields: day_of_week, start_time, end_time, is_active
  • Consider timezone handling

Story 3.2: Time Slot Blocking

Description: Allow admin to block specific dates/times for personal events or holidays.

Acceptance Criteria:

  • Block entire days
  • Block specific time ranges within a day
  • Add reason/note for blocked time
  • View list of all blocked times
  • Edit/delete blocked times
  • Blocked times show as unavailable in calendar
  • Prevent booking on blocked times
  • Future blocked times don't affect existing bookings

Technical Notes:

  • Store in blocked_times table
  • Fields: block_date, start_time, end_time, reason
  • Query both working_hours and blocked_times for availability

Story 3.3: Availability Calendar Display

Description: Display real-time calendar with available time slots for booking.

Acceptance Criteria:

  • Calendar view showing available dates
  • Time slots based on working hours configuration
  • Unavailable slots clearly indicated:
    • Already booked (by other clients)
    • Outside working hours
    • Blocked by admin
  • 1-hour slots (45min + 15min buffer)
  • Visual distinction between available/unavailable
  • Responsive design (mobile-friendly)
  • Language-appropriate date formatting
  • Prevent double-booking

Technical Notes:

  • Consider FullCalendar.js or similar
  • Real-time availability check on slot selection
  • Account for 15-minute buffer between appointments

Story 3.4: Booking Request Submission

Description: Allow logged-in clients to submit consultation booking requests.

Acceptance Criteria:

  • Client must be logged in
  • Select date from calendar
  • Select available time slot
  • Provide detailed problem summary (required, textarea)
  • System validates: no more than 1 booking per day for this client
  • Confirmation before submission
  • Booking enters "pending" status
  • Admin receives email notification
  • Client sees "Pending Review" status
  • Client receives submission confirmation email

Technical Notes:

  • Store in consultations table
  • Status: 'pending' initially
  • Validate against existing bookings for same client/day

Story 3.5: Admin Booking Review & Approval

Description: Admin workflow to review, categorize, and approve/reject booking requests.

Acceptance Criteria:

  • View list of pending booking requests
  • See client details and problem summary
  • Determine consultation type:
    • Free consultation
    • Paid consultation (with amount)
  • Set payment amount and instructions (if paid)
  • Approve booking:
    • Status changes to 'approved'
    • Client notified via email
    • Calendar file (.ics) attached
    • Payment instructions included (if paid)
  • Reject booking:
    • Optional rejection reason
    • Client notified via email
  • Quick action buttons for approve/reject
  • Filter by date range, client

Technical Notes:

  • Update consultation status and type
  • Trigger appropriate email notifications
  • Generate .ics file on approval

Story 3.6: Calendar File Generation (.ics)

Description: Generate downloadable calendar files for approved consultations.

Acceptance Criteria:

  • Generate valid .ics file on booking approval
  • Include:
    • Event title: "Consultation with Libra Law Firm"
    • Date and time
    • Duration: 45 minutes
    • Location (if applicable)
    • Description with booking reference
  • Attach to approval email
  • Available for download from client dashboard
  • Compatible with major calendar apps (Google, Apple, Outlook)
  • Bilingual event details based on client preference

Technical Notes:

  • Use maennchen/zipstream-php or spatie/icalendar-generator
  • Follow iCalendar specification (RFC 5545)

Story 3.7: Consultation Management

Description: Admin tools to manage consultations through their lifecycle.

Acceptance Criteria:

  • View all consultations with filters:
    • Status (pending/approved/completed/cancelled/no-show)
    • Type (free/paid)
    • Date range
    • Payment status
    • Client name
  • Mark consultation as completed
  • Mark consultation as no-show
  • Cancel booking on behalf of client
  • Reschedule appointment:
    • Select new date/time
    • Notify client via email
  • Mark payment as received (for paid)
  • Add admin notes (internal only)
  • View consultation history per client

Technical Notes:

  • Status enum: pending, approved, completed, cancelled, no_show
  • Payment status: pending, received, not_applicable
  • Admin notes stored separately from client-visible data

Story 3.8: Consultation Reminders

Description: Automated reminder emails before scheduled consultations.

Acceptance Criteria:

  • Send reminder 24 hours before consultation
  • Send reminder 2 hours before consultation
  • Reminder includes:
    • Consultation date and time
    • Type (free/paid)
    • Payment reminder (if paid and not received)
    • Any instructions
  • Reminders in client's preferred language
  • No reminder for cancelled consultations
  • Scheduled job for sending reminders

Technical Notes:

  • Use Laravel scheduler for reminder jobs
  • Check consultation status before sending
  • Depends on Epic 8 for email infrastructure

Dependencies

Epic Dependency
Epic 1 Authentication, database schema, bilingual support
Epic 2 User accounts must exist to book
Epic 8 Email notifications (approval, reminders)

Risks & Mitigations

Risk Impact Mitigation
Double-booking race condition High Database-level locking, unique constraints
Timezone confusion Medium Store UTC, display in local time
Reminder job failures Medium Queue monitoring, retry logic
Calendar file compatibility Low Test with major calendar apps

Definition of Done

  • All stories completed with acceptance criteria met
  • Tests for booking flow end-to-end
  • Tests for 1-per-day constraint
  • Tests for availability calculation
  • Calendar file validated with multiple apps
  • Email notifications working
  • Reminder jobs scheduled and tested
  • Bilingual support verified
  • Code formatted with Pint