| name | shift-schedule-pattern |
| description | Patterns for implementing and extending the Studio Shift Schedule feature. This skill should be used when working on shift CRUD, shift blocks, calendar/alignment orchestration, duty-manager coverage, operational-day boundaries, task-readiness checks, or the frontend shift schedule UX. |
Shift Schedule Pattern
Studio Shift Schedule: shift planning, duty-manager coverage, and show-task readiness for live-commerce studios.
See references/shift-schedule-details.md for block model, frontend contracts, orchestration architecture, and PR review patterns.
Business Rules
Operational Day Boundary
- Backend (
shift-alignment, run-review): timezone-agnostic and query-agnostic; queries strictly by client-supplied ISO-8601 time range boundaries to avoid date manipulation duplication on the server.
- Frontend (
dashboard, my-shifts, show-run-review): local runtime time for date inputs, serialized to absolute ISO-8601 bounds using shared operational-day range utilities.
- FE must use shared operational-day utilities, not duplicated route-local implementations.
Duty-Manager Coverage (ShiftAlignmentService.getAlignment())
- Per-show: each upcoming show overlaps ≥1 duty-manager shift block
- Per-operational-day: continuous duty-manager coverage first-show-start → last-show-end
Task Readiness
Each upcoming show checked for: has_no_tasks, unassigned_task_count, missing_required_task_types (SETUP, CLOSURE), missing_moderation_task (premium shows require ≥1 active loop-based task template).
- Under the proposed Studio Configuration & Settings architecture, these requirements (e.g. required types for
bau vs premium shows) will be dynamically defined per studio to determine what assignments a show needs to be counted as fully complete.
Studio Shows "Issues" Filter
- Same datetime scope window (
date_from/date_to) across shows table, readiness panel, and needs_attention
- FE computes bounds via
toShowScopeDateTimeBounds() with operational-day cutoff
- BE resolves with
include_past: true, match_show_scope: true
Key Implementation Rules
- Blocks always server-sorted by
startTime ascending
- FE sorts blocks before submitting to API
- Block UIDs preserved via positional matching on update
- Overlap guard runs for non-CANCELLED shifts
- Calendar component always mounted (no conditional unmount)
- Calendar timezone explicitly configured
- Cross-midnight blocks split to per-day segments for Schedule-X
- Calendar query limit derived from view/range bucket (day/week/month)
- Hourly rate re-derived only on actual user reassignment
- FE cross-midnight sequential advance gated on
prevBlockCrossedMidnight
Orchestration
ShiftCalendarController → ShiftCalendarService.getCalendar() (read-only aggregation)
→ ShiftAlignmentService.getAlignment() (planning-risk analysis)
StudioShiftController → StudioShiftService (CRUD)
Checklist
Related Skills