Allocation Usage
1. Overview
| Property | Value |
|---|---|
| ID | FEAT-SALE-ALLOC |
| Status | Stable |
| Owner | sale-team |
| Depends on | AllocationUnit, AllocationZone, AllocationLayout (allocation schema), SaleOrder, Reservation |
Allocation occupancy uses a polymorphic AllocationUsage(usageType, usageId) row that ties an AllocationUnit (table/seat/locker) to either a SaleOrder or a Reservation. One usage row per allocated unit; same lifecycle for both parents. See ADR-0004.
2. Entity Model
Field details — see Domain Model §3.5.
3. Lifecycle
| From | Event | To |
|---|---|---|
ACTIVE | SaleOrder payment success | SUCCESS |
ACTIVE | order/reservation cancel | CANCELLED |
ACTIVE | reservation reservedTo passed without check-in | EXPIRED |
4. Operations
AllocationUsageService (allocation-usage.service.ts — 841 lines).
| Method | Signature | Purpose |
|---|---|---|
startForOrder | { saleOrderId, merchantId, allocationUnitId, type, assigneeId? } | Create ACTIVE usage tied to SaleOrder |
complete | { usageId } | ACTIVE → SUCCESS (called from payment-success handler) |
moveUsagesToOrder | { fromOrderId, toOrderId } | Used during order merge to retarget existing usages |
resolvePrincipalIdsByAllocation | { unitId, zoneId, ... } | Resolve order/reservation FROM unit/zone for routing |
| Batch cancel / complete | per-spec endpoints | Bulk transitions |
5. REST Endpoints
| Verb | Path | Auth | Permission | Handler |
|---|---|---|---|---|
| 6× CRUD | /allocation-usages | JWT/BASIC | AllocationUsage.<crud> | merchant-scoped |
GET | /allocation-usages?zoneId=...&unitId=... | JWT/BASIC | AllocationUsage.find | filter by zone/unit |
| Batch ops | /allocation-usages/batch/... | JWT/BASIC | (per op) | AllocationUsageService.* |
Live OpenAPI:
/v1/api/sale/doc/openapi.json.
6. Events
Outbound (WebSocket):
| Topic | When | Action enum | Rooms |
|---|---|---|---|
observation/allocation/allocation-usage | startForOrder | USAGE_CREATED | getAllocationUsageRooms (merchant + unit + zone hierarchy) |
| same | complete | USAGE_COMPLETED | same |
| same | cancel | USAGE_CANCELLED | same |
Outbound (Kafka): none directly — payment-success Kafka emit is owned by SaleOrderPaymentWebhookService.
7. Related Pages
- Reservation — co-author of usage rows
- Sale Order
- Domain Model
- ADR-0004 Polymorphic AllocationUsage