257 lines
8.0 KiB
Markdown
257 lines
8.0 KiB
Markdown
# 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
|