crr-shifts/docs/DOMAIN.md

Domain model

Schedules vs assignments

A schedule describes when a duty exists and how its initial assignee is chosen. An assignment is the actual duty on a concrete date. Once an assignment exists, it is not recalculated from the schedule.

This distinction is intentional: editing a rotation must not retroactively change an already published month.

Seeded schedules

Night

• Exists every day (Monday through Sunday).
• Type: fixed.
• Generation creates an unassigned row for every date.
• An administrator assigns a person for each date in Manage month.
• Once assigned, it remains fixed until explicitly edited or transferred through an approved change request.

Saturday Lunch

• Saturdays only.
• Type: rotation.
• Has its own ordered member list.
• Uses an anchor date to continue the rotation across month boundaries.

Sunday Lunch

• Sundays only.
• Type: rotation.
• Has its own ordered member list, independent of Saturday.

The data model supports a schedule matching multiple weekdays even though the seeded lunch schedules each use one day.

Rotation generation

For a rotation schedule, the member is chosen from the ordered active rotation members using the number of matching schedule days from the anchor date to the target date modulo member count.

Only missing assignments are generated. Existing rows are never rewritten.

Change request state machine

open → pending_approval → approved

Other terminal states: rejected, cancelled.

• A member can offer one of their future/current assignments to a specific active member or to anyone.
• The requester cannot accept their own request.
• A targeted request can only be accepted/rejected by that target.
• An open request can be accepted by any other active member.
• If the schedule requires manager approval, acceptance moves to pending_approval.
• Approval transfers the assignment and sets its source to swap.
• If the requester no longer owns the assignment, the request must not be applied.

Notifications

Email is optional per user and per installation.

Events include:

• assignment updated/removed by admin;
• change requested;
• change accepted;
• manager approval required;
• change approved/rejected;
• shift reminder.

An email error is logged but must not undo a scheduling action.