S18 Added OR Tools rules for scheduling show

README.md

@@ -154,23 +154,35 @@ dancers; deleting a school also deletes its dancers, groups and shows.
 
 Shows have a name, zero to six dated dayparts (`MORNING`, `AFTERNOON`, `EVENING`),
 with unique date/type combinations. The displayed date range comes from these
-dayparts. Each show stores `appearances` for every group type. Omitting counts
-initializes defaults on creation or the initial daypart configuration; later
-edits preserve saved counts and reject counts outside 1..N. With no dayparts,
-shows remain unscheduled and saved counts are retained.
+dayparts. Each show stores `preferredDayParts` (x), defaulting to two or one for
+one daypart. Ordinary groups, including PRE_EDUCATION, perform in exactly x
+dayparts; preschool groups once; showcases every daypart. See
+[show-scheduling-rules.md](show-scheduling-rules.md) for the full hard constraints,
+coach exceptions, ordering and optimization rules.
 
-`POST /api/dance-schools/{schoolId}/shows/{showId}/schedule` uses OR-Tools to
-assign every current school group to its required number of distinct dayparts,
-minimizing the busiest/quietest appearance gap. It replaces assignments only on
-a valid, current result. The response distinguishes optimal balance from a valid
-result whose optimality is unproven. Concurrent runs return `409`; changed inputs
-also reject the result with `409`. Failed runs preserve existing assignments.
-Scheduling runs synchronously with a 30-minute solver limit; development and
-production proxies allow 31 minutes. The UI warns before edits that may invalidate
-existing schedules and offers explicit scheduling again afterward.
+`POST /api/dance-schools/{schoolId}/shows/{showId}/schedule` generates an ordered
+draft using OR-Tools with a total thirty-minute time limit. A feasible result is
+accepted without claiming optimality. Concurrent runs and stale results return
+`409`; failures retain existing assignments. Development and production proxies
+allow 31 minutes.
 
-School JSON exports use format version **2**, including dated dayparts, assignments,
-and all appearance counts. Version 1 files are intentionally unsupported.
+`PUT .../shows/{showId}/assignments` accepts `{"assignments":[[1,2],[3]]}`, an
+ordered list of group IDs per daypart. Incomplete or invalid drafts can be saved;
+unknown IDs and malformed lists are rejected. `POST .../shows/{showId}/finalize`
+checks every hard rule before marking a schedule final. Show responses include
+`preferredDayParts`, `finalized` and `violations`. Relevant edits invalidate final
+status. The UI supports ordering and moving performances, and displays violations.
+
+`GET .../coaches` lists coach registrations. `POST .../coaches` with
+`{"dancerId":1}` registers a dancer as a coach. `PUT .../coaches/{coachId}` uses
+the same body to link an existing coach. `DELETE .../coaches/{coachId}/dancer`
+removes the identity link. The dancers screen supports maintaining these links.
+
+School JSON exports use format version **3**, including x, schedule status and
+coach-to-dancer links. Version 2 remains importable; its schedules migrate to
+drafts with default x. Version 1 is unsupported. Legacy `appearances` fields are
+retained for file compatibility; S18 scheduling uses x and fixed type exceptions.
+The REST `appearances` input is deprecated; use `preferredDayParts`.
 
 Run the HTTP integration tests with: