# Phase: Booking Engine

| Field | Value |
| --- | --- |
| Identifier | `beauty-business-14-1` |
| Status | Planned |
| Owner | Platform |
| Module(s) | `beauty_business.schedules`, `beauty_business.appointments`, `beauty_business.waiting_list` |
| Service(s) | `beauty_business` |
| Depends On | `beauty-business-14-0` |
| ADR(s) | TBD |
| Manifest | [phase-manifest.yaml](../../ai-framework/phase-manifest.yaml) |
| Framework | [ADR-013](../../architecture/adr/ADR-013.md) · [ADR-018](../../architecture/adr/ADR-018.md) · [ADR-019](../../architecture/adr/ADR-019.md) |

## Objective

Deliver the beauty-specific **booking engine**: staff schedules, availability windows, appointment types, appointment lifecycle (request → confirm → check-in → complete / cancel / no-show), conflict detection, and waiting list — without owning Communication delivery, Accounting postings, or full customer CRM profiles.

## Enterprise Phase Discovery

> **Required before Implementation.**

| Field | Value |
| --- | --- |
| Discovery date | Pending |
| Inputs reviewed | Phase 14.0 handover · [beauty-business-roadmap.md](../../beauty-business-roadmap.md) · Sports Center / Healthcare booking patterns (reference only) |

### Target Responsibility (this phase when Complete)

- Schedules and availability per staff and branch
- Appointment aggregate with state machine and audit trail
- Waiting list when slots unavailable
- Events: `beauty_business.appointment.*`, `beauty_business.schedule.*`
- Permissions: `beauty_business.appointments.*`, `beauty_business.schedules.*`

### Explicitly Excluded

- Service catalog pricing (14.3) — appointment may reference service ref UUID only
- Customer profile management (14.4) — customer ref only
- SMS/email reminders (Communication client in 14.7)
- Payment capture (Accounting intents later)
- Healthcare appointment types

## Business Analysis

| Item | Detail |
| --- | --- |
| Actors | Receptionist, stylist, customer (via portal API later) |
| Business capabilities | Book, reschedule, cancel, check-in, no-show handling |
| Success metrics | No double-booking; tenant isolation; lifecycle audit |
| Non-goals | Multi-vertical generic scheduling platform |

## Scope

### In Scope

- StaffSchedule, StaffAvailability, ScheduleException
- AppointmentType, Appointment, AppointmentStatusHistory
- WaitingListEntry
- Conflict rules (staff + optional room ref from 14.2)
- List APIs with pagination, filter, sort, search

### High-Level Entities

| Entity | Purpose |
| --- | --- |
| StaffSchedule | Recurring working pattern |
| StaffAvailability | Bookable slots |
| AppointmentType | Consultation, service, follow-up |
| Appointment | Core booking aggregate |
| WaitingListEntry | Queue for full slots |

### Events (Planned)

| Event | When |
| --- | --- |
| `beauty_business.appointment.created` | New booking |
| `beauty_business.appointment.confirmed` | Confirmed |
| `beauty_business.appointment.checked_in` | Customer arrived |
| `beauty_business.appointment.completed` | Service done |
| `beauty_business.appointment.cancelled` | Cancelled |
| `beauty_business.appointment.no_show` | No-show marked |

## Out of Scope

- Salon rooms/stations management (14.2)
- Service definitions and pricing (14.3)
- Customer preferences and history (14.4)
- Package session deduction (14.5)
- Commission calculation (14.6)
- Marketing reminders (14.7)

## Completion Criteria

- [ ] Booking lifecycle complete with tests
- [ ] No Communication/Accounting implementation inside booking service layer
- [ ] Healthcare module untouched

## Related Documents

- [Phase 14.0](phase-14-0-beauty-foundation.md)
- [Beauty Business Roadmap](../../beauty-business-roadmap.md)
- [Phase area README](README.md)