Initial Commit
This commit is contained in:
215
openspec/changes/enterprise-booking/proposal.md
Normal file
215
openspec/changes/enterprise-booking/proposal.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# OpenSpec Change: enterprise-booking
|
||||
|
||||
- **Change ID**: enterprise-booking
|
||||
- **Package**: `@suaveplan/booking`
|
||||
- **Category**: universal
|
||||
- **Target path**: `universal/commerce/booking`
|
||||
- **Status**: IN PROGRESS
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/booking.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/booking` on the genesis branch from scratch at enterprise quality. The package provides a universal booking engine: resource definitions (time-slotted and non-time-slotted), availability calendars with customisable rule sets (working hours, blackout dates, capacity limits), booking lifecycle state machine (`pending` → `confirmed` → `completed` / `cancelled` / `no_show`), cancellation and rescheduling policies (free window, penalty fees), waiting-list management, calendar synchronisation hooks (provider-agnostic), recurring bookings, and an in-memory `BookingStore` reference adapter. The main-branch version sat at 99.06% coverage. Genesis adds structured errors, Zod schemas, OTel instrumentation, `AbortSignal`, idempotency enforcement, and property-based tests.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet — this is a fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `BookingError`; `BOOKING.*` error codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock`, `EventBusLike` |
|
||||
| `@suaveplan/events` (`workspace:^`) | Booking lifecycle event bus |
|
||||
| `@suaveplan/datetime` (`workspace:^`) | Business-day arithmetic, timezone-aware slot generation |
|
||||
| `@suaveplan/idempotency` (`workspace:^`) | Per-booking idempotency guard |
|
||||
| `@suaveplan/fsm` (`workspace:^`) | FSM interpreter for booking state machine |
|
||||
| `zod` (`catalog:forms`) | Schema validation |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||||
|
||||
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check` (all `catalog:testing`).
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
### Core types
|
||||
|
||||
```ts
|
||||
type BookingStatus = 'pending' | 'confirmed' | 'completed' | 'cancelled' | 'no_show'
|
||||
|
||||
interface Resource {
|
||||
id: string
|
||||
name: string
|
||||
type: 'time_slot' | 'all_day' | 'unit'
|
||||
capacity: number // default 1
|
||||
rules: AvailabilityRule[]
|
||||
metadata: Record<string, unknown>
|
||||
}
|
||||
|
||||
interface AvailabilityRule {
|
||||
type: 'working_hours' | 'blackout' | 'capacity_override'
|
||||
daysOfWeek?: number[] // 0=Sun…6=Sat
|
||||
startTime?: string // HH:MM
|
||||
endTime?: string // HH:MM
|
||||
dates?: string[] // ISO date strings for blackouts
|
||||
capacity?: number
|
||||
timezone?: string
|
||||
}
|
||||
|
||||
interface Booking {
|
||||
id: string
|
||||
resourceId: string
|
||||
guestId: string
|
||||
status: BookingStatus
|
||||
start: Date
|
||||
end?: Date // optional for all_day and unit resources
|
||||
quantity: number // default 1
|
||||
policy: BookingPolicy
|
||||
history: BookingTransition[]
|
||||
metadata: Record<string, unknown>
|
||||
createdAt: Date
|
||||
updatedAt: Date
|
||||
}
|
||||
|
||||
interface BookingPolicy {
|
||||
cancellationWindowMs: number // free cancellation period from booking time
|
||||
cancellationFeeMinorUnits?: number
|
||||
rescheduleWindowMs?: number
|
||||
requiresConfirmation?: boolean // default false (auto-confirms)
|
||||
}
|
||||
|
||||
interface TimeSlot {
|
||||
start: Date
|
||||
end: Date
|
||||
available: number // remaining capacity
|
||||
}
|
||||
```
|
||||
|
||||
### `BookingEngine`
|
||||
|
||||
```ts
|
||||
class BookingEngine {
|
||||
constructor(options: BookingEngineOptions)
|
||||
addResource(resource: Resource): void
|
||||
getAvailability(resourceId: string, from: Date, to: Date, options?: AvailabilityOptions): TimeSlot[]
|
||||
book(options: BookOptions): Promise<Booking>
|
||||
confirm(bookingId: string): Promise<Booking>
|
||||
cancel(bookingId: string, options?: CancelOptions): Promise<Booking>
|
||||
reschedule(bookingId: string, newStart: Date, newEnd?: Date): Promise<Booking>
|
||||
complete(bookingId: string): Promise<Booking>
|
||||
markNoShow(bookingId: string): Promise<Booking>
|
||||
get(bookingId: string): Booking | undefined
|
||||
listByResource(resourceId: string, filter?: BookingFilter): Booking[]
|
||||
waitingList(resourceId: string, slot: Date): string[]
|
||||
addToWaitingList(resourceId: string, slot: Date, guestId: string): void
|
||||
notifyWaitingList(resourceId: string, slot: Date): string[]
|
||||
}
|
||||
|
||||
interface BookingEngineOptions {
|
||||
store?: BookingStore
|
||||
clock?: Clock
|
||||
logger?: LoggerLike
|
||||
bus?: EventBusLike
|
||||
}
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type BookingErrorCode =
|
||||
| 'BOOKING_NOT_FOUND'
|
||||
| 'BOOKING_RESOURCE_NOT_FOUND'
|
||||
| 'BOOKING_UNAVAILABLE'
|
||||
| 'BOOKING_INVALID_TRANSITION'
|
||||
| 'BOOKING_CANCELLATION_WINDOW_EXPIRED'
|
||||
| 'BOOKING_RESCHEDULE_FAILED'
|
||||
| 'BOOKING_CAPACITY_EXCEEDED'
|
||||
| 'BOOKING_IDEMPOTENCY_CONFLICT'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Genesis additions
|
||||
|
||||
1. **`BookingError`** extends `SuaveplanError` with eight stable codes.
|
||||
2. **Zod schemas** for `Resource`, `AvailabilityRule`, `Booking`, `BookingPolicy`, `TimeSlot`, `BookOptions`, `CancelOptions`.
|
||||
3. **Waiting-list management** — when a slot reaches capacity, new bookings join the waiting list; on cancellation, `notifyWaitingList` returns the next guest IDs to offer the freed slot.
|
||||
4. **Cancellation policy enforcement** — checks clock against `createdAt + cancellationWindowMs`; throws `BOOKING_CANCELLATION_WINDOW_EXPIRED` when outside the free window.
|
||||
5. **OTel instrumentation** — span `booking.transition` with attributes `booking.resource_id`, `booking.from_status`, `booking.to_status`; counter `booking.transition_total`; histogram `booking.availability_query_duration_ms`.
|
||||
6. **Property-based tests** — availability slot generation is monotonic (no overlaps, correct ordering) for arbitrary working-hours rules; state machine transition invariants.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/commerce/booking/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
booking-engine/
|
||||
booking-engine.ts
|
||||
booking-engine.md
|
||||
booking-engine.types.ts
|
||||
booking-engine.test.ts
|
||||
index.ts
|
||||
booking-fsm/
|
||||
booking-fsm.ts
|
||||
booking-fsm.md
|
||||
booking-fsm.test.ts
|
||||
index.ts
|
||||
availability/
|
||||
availability-calculator/
|
||||
availability-calculator.ts
|
||||
availability-calculator.md
|
||||
availability-calculator.test.ts
|
||||
index.ts
|
||||
rule-evaluator/
|
||||
rule-evaluator.ts
|
||||
rule-evaluator.md
|
||||
rule-evaluator.test.ts
|
||||
index.ts
|
||||
waiting-list/
|
||||
waiting-list/
|
||||
waiting-list.ts
|
||||
waiting-list.md
|
||||
waiting-list.test.ts
|
||||
index.ts
|
||||
store/
|
||||
memory-store/
|
||||
memory-store.ts
|
||||
memory-store.md
|
||||
memory-store.test.ts
|
||||
index.ts
|
||||
__benchmarks__/
|
||||
booking.bench.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream consumers**: `@suaveplan/payment` integration for booking deposits; any scheduling/reservation UI.
|
||||
|
||||
**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/datetime`, `@suaveplan/idempotency`, `@suaveplan/fsm`.
|
||||
72
openspec/changes/enterprise-booking/tasks.md
Normal file
72
openspec/changes/enterprise-booking/tasks.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# Tasks: enterprise-booking
|
||||
|
||||
**Change ID**: enterprise-booking
|
||||
**Package**: `@suaveplan/booking`
|
||||
**Target path**: `universal/commerce/booking`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/datetime`, `@suaveplan/idempotency`, `@suaveplan/fsm`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create `universal/commerce/booking/` with `src/`, `tests/`, `src/__benchmarks__/` and all feature subdirectories per the layout in `proposal.md`.
|
||||
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, correct `exports` map, `dependencies`, and `devDependencies`.
|
||||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||||
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Types + errors
|
||||
|
||||
- [ ] `src/types/common.ts` — `BookingStatus`, `Resource`, `AvailabilityRule`, `Booking`, `BookingPolicy`, `BookingTransition`, `TimeSlot`, `BookOptions`, `CancelOptions`, `BookingFilter`, `AvailabilityOptions`, `BookingStore` (interface), `BookingEngineOptions`.
|
||||
- [ ] `src/types/common.md` (≥200 words, both examples, API reference).
|
||||
- [ ] `src/error-codes.ts` — `BookingErrorCode` (8 codes), metadata, register, eager call.
|
||||
- [ ] `src/types/schemas.ts` + `schemas.md` — Zod schemas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Core modules
|
||||
|
||||
- [ ] **`src/availability/rule-evaluator/`** — `evaluateRule(rule, date, time): boolean`: checks if a given datetime is within a `working_hours` rule (day-of-week + time range), blocked by a `blackout` rule (specific dates), or override capacity. Tests: each rule type, timezone edge cases (via injectable clock).
|
||||
- [ ] **`src/availability/availability-calculator/`** — `calculateSlots(resource, from, to, options): TimeSlot[]`: expands `AvailabilityRule[]` over date range to produce time slots with remaining capacity. Tests: single-day slots, multi-day, blackout removes slot, capacity override, no rules returns empty.
|
||||
- [ ] **`src/core/booking-fsm/`** — `BookingFsm`: wraps `@suaveplan/fsm`; legal transitions: `pending→confirmed`, `pending→cancelled`, `confirmed→completed`, `confirmed→cancelled`, `confirmed→no_show`, `completed→[terminal]`. Tests: all legal paths, two illegal transitions.
|
||||
- [ ] **`src/store/memory-store/`** — `createMemoryBookingStore()`: in-memory `BookingStore`. Tests: CRUD, `listByResource` filter, waiting list operations.
|
||||
- [ ] **`src/waiting-list/waiting-list/`** — `WaitingList(store)`: `add(resourceId, slot, guestId)`, `get(resourceId, slot): string[]`, `notifyNext(resourceId, slot, count): string[]`. Tests: add/get, notifyNext removes from list and returns correct guest IDs.
|
||||
- [ ] **`src/core/booking-engine/`** — `BookingEngine`: `addResource`, `getAvailability`, `book`, `confirm`, `cancel`, `reschedule`, `complete`, `markNoShow`, `get`, `listByResource`, `waitingList`, `addToWaitingList`, `notifyWaitingList`. `book` checks slot availability, capacity, wraps with idempotency guard, runs FSM transition. `cancel` checks cancellation window policy. `reschedule` cancels old slot and creates new booking. Tests: book/confirm/complete happy path, overbooking → joins waiting list, cancellation within window, cancellation outside window throws, reschedule, no-show.
|
||||
|
||||
---
|
||||
|
||||
## 4. OTel instrumentation
|
||||
|
||||
- [ ] Span `booking.transition` with attributes `booking.resource_id`, `booking.from_status`, `booking.to_status`; counter `booking.transition_total`; histogram `booking.availability_query_duration_ms`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Property-based tests (`tests/property.test.ts`)
|
||||
|
||||
- [ ] Slot generation monotonicity: for arbitrary working-hours rules, slots in the returned list are strictly ordered by `start` and no two slots overlap.
|
||||
- [ ] FSM: any path from `pending` reaches a terminal state (`completed`, `cancelled`, `no_show`) in ≤3 transitions.
|
||||
|
||||
---
|
||||
|
||||
## 6. Benchmarks (`src/__benchmarks__/booking.bench.ts`)
|
||||
|
||||
- [ ] `calculateSlots` for 30-day range with hourly slots.
|
||||
- [ ] `BookingEngine.book` 10 000 sequential bookings.
|
||||
|
||||
---
|
||||
|
||||
## 7. Docs + verify
|
||||
|
||||
- [ ] One `.md` per implementation file (≥200 words, both examples, API reference). Root `README.md`.
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/booking` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/booking` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/booking`.
|
||||
- [ ] Archive: `openspec/archive/2026-04-24-enterprise-booking/`.
|
||||
Reference in New Issue
Block a user