S9 OR Tools basic scheduling

README.md

@@ -117,7 +117,7 @@ Request bodies (dates use ISO `yyyy-MM-dd`):
 ```
 
 ```json
-{"name": "Annual show", "date": "2027-06-12"}
+{"name": "Annual show", "dayParts": [{"date": "2027-06-12", "type": "AFTERNOON"}]}
 ```
 
 Names and categories must be nonblank. Birth dates cannot be in the future.
@@ -138,9 +138,25 @@ Both operations return `204` and are idempotent for existing groups and dancers.
 Deleting a dancer removes all their memberships; deleting a group retains the
 dancers; deleting a school also deletes its dancers, groups and shows.
 
-Shows have a name, a date and three automatically created day parts: `MORNING`,
-`AFTERNOON`, `EVENING`. Each day part has an empty `danceGroupIds` list; assigning
-groups is not exposed yet. Multiple shows per year are allowed.
+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.
+
+`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.
+
+School JSON exports use format version **2**, including dated dayparts, assignments,
+and all appearance counts. Version 1 files are intentionally unsupported.
 
 Run the HTTP integration tests with: