# 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