S18 Added OR Tools rules for scheduling show

show-scheduling-rules.md

@@ -0,0 +1,89 @@
+# Show scheduling rules
+
+A show is the complete event, including every dated daypart. It may span several
+calendar dates. Counts do not restart on a new date.
+
+## Required performances
+
+The manager chooses **x**, the desired number of distinct dayparts, per show.
+It defaults to two, or one for a show with only one daypart. A show can be saved
+without dayparts but cannot be scheduled. If dayparts are removed, x is retained
+and must be corrected before scheduling when it exceeds the remaining count.
+
+Every nonempty regular, selection and pre-education group performs in exactly x
+dayparts, once in each. Each preschool group performs exactly once in the whole
+show. Every showcase performs once in every daypart. Groups without dancers are
+skipped completely, including for showcase positions and balancing.
+
+With at least two showcases, one opens and another closes every daypart. Any
+additional showcases may appear between them. The opening and closing groups can
+change between dayparts. A single showcase may open or close, but never performs
+twice in the same daypart. Without showcases there is no opening/closing rule.
+
+## People and changing clothes
+
+An ordinary dancer must perform in no more than x distinct dayparts across all
+of their groups. The same dancer registration must be used in every group.
+
+Showcase participants necessarily perform in every daypart. For their other
+performances, exceeding x dayparts is allowed but discouraged. We count their
+non-showcase dayparts, subtract x, and count only positive excesses. The planner's
+first preference is to minimize the sum of these excesses across dancers.
+
+A coach registration must be explicitly linked to the corresponding dancer;
+names are not used to guess identity. Coaches are available throughout the show
+and are exempt from both the x limit and the excess penalty. A coach only performs
+with a group if included in its dancer membership. Being a group's coach alone
+never adds a performance or forces that group into extra dayparts.
+
+Between any two performances involving the same person, at least two other
+performances must intervene in which that person does not dance. This includes
+coaches accompanying preschoolers, coaches dancing in other groups, and showcases.
+There are no exceptions. Between dayparts we assume sufficient changing time,
+so the gap rule restarts even if the dayparts are on the same date.
+
+## Balance and preferences
+
+All performances count equally, including preschool groups and showcases. The
+busiest daypart may have at most two more performances than the quietest. Zero
+is ideal. Preschool groups can cause a difference but have no special exemption.
+
+Among schedules satisfying every mandatory rule, optimize in this strict order:
+
+1. Minimize non-showcase daypart excess for showcase participants, excluding coaches.
+2. Minimize the difference in performance counts between dayparts.
+3. Minimize similarity of consecutive performances within each daypart.
+
+A lower priority cannot worsen a higher priority. OR-Tools solves these objectives
+in sequence, fixing each proven optimum before working on the next. If it finds
+only a feasible result at a priority, it returns that valid result without
+claiming that the complete schedule is optimal.
+
+For variety, style similarity is the fraction of shared styles among all distinct
+styles of the two groups. Two groups without styles have no style penalty.
+Age similarity is one for equal average ages, falling linearly to zero at a
+five-year difference and remaining zero above that difference. Style and age
+have equal weight. Each component is rounded to millionths for CP-SAT's integer
+objective. Showcases count in this comparison. Average age includes every dancing
+member equally, including coaches, measured in completed years on the first date
+of the show. Empty groups are already excluded.
+
+## Results, drafts and final schedules
+
+Scheduling can take up to thirty minutes in total across the optimization stages.
+A feasible result is accepted even when optimality is unproven. Every mandatory
+rule still applies. Proven infeasibility and reaching the time limit without a
+result are reported differently. Failures preserve the saved assignments and
+order. Concurrent runs are rejected and changed inputs invalidate pending results.
+
+Automatic results are drafts for manager review. Managers can also move, add,
+remove and reorder performances manually and save incomplete or invalid drafts.
+The application lists the rules those drafts violate. An explicit finalization
+action checks all mandatory rules; only a valid schedule can become final.
+Preferences alone never block finalization.
+
+Manual edits and relevant membership, dancer-age, coach-link or show-setting
+changes return final schedules to draft. Existing schedules and imported schedules
+are drafts. Import retains assignment order and recalculates violations. Export
+is available for both statuses and records status, x and coach identity links;
+reimport always requires a fresh finalization.