# S12 — Asynchronous feedback for scheduling

Status: REFINED

Agreed after the grill-me interview; shared understanding confirmed.

## User story

As a dance-school maintainer, I want feedback after starting Schedule Groups,
so that I can see whether the backend is still calculating, when it finishes
and what the outcome is, including when I leave and return to the show page.

## Background execution and concurrency

- Start scheduling in the backend without keeping the initiating HTTP request
  open until the calculation finishes. Navigation, page reloads and disconnected
  clients must not stop the calculation.
- The backend owns the current scheduling status for each show. All open
  screens see the same status, including screens that did not start the run.
- Allow at most one active calculation per show. Disable Schedule Groups while
  it is running and reject duplicate starts in the backend as well.
- Different shows may calculate concurrently. A global capacity limit and a
  waiting queue are outside S12.
- Retain the existing 30-minute solver limit and scheduling rules.

## Progress and outcomes

- While running, show elapsed time, the current optimization phase (attendance,
  spread or variety), and whether a valid solution has been found.
- Report a valid solution as soon as the solver discovers one, including during
  a phase. Extend solver progress reporting rather than waiting for the phase
  to finish. Do not apply intermediate solutions.
- Do not present a completion percentage or estimated finish time: the phases
  do not represent proportional parts of the calculation time.
- Keep the latest status and outcome per show until a new calculation starts.
  Show the finish time and distinguish an optimal solution from a valid solution
  whose optimality was not proven within the time limit.
- For a successful result, show a concise summary with concrete results for
  attendance, spread and variety, using understandable labels.
- Clearly distinguish invalid input, infeasibility, solver failure, time limit
  without a valid solution, rejection because inputs changed, and interruption
  by a backend restart. Explain why no result was applied and that existing
  assignments were preserved.

## Applying results

- Retain the confirmation before starting that explains replacement of existing
  assignments. A successful completed calculation automatically replaces them;
  no preview/apply step is introduced.
- A valid solution may be applied when the time limit expires even if optimality
  has not been proven.
- Preserve the existing scheduling input revision check. A result based on
  outdated inputs must not replace the current assignments.
- Failed, infeasible, interrupted, stale and no-solution calculations preserve
  existing assignments.
- Report success only after the resulting assignments have been saved. Keep
  status and saved results consistent.

## Server-sent events and connection recovery

- Use server-sent events (SSE) for backend-to-frontend status updates.
- On initial connection and reconnection, provide the current backend status.
  Correctness must not depend on receiving every previous event.
- Maintain updates across navigation within the application so completion
  notifications can appear outside the show page.
- If the connection is lost, indicate that displayed status may be outdated
  while the backend calculation continues. Reconnect and reconcile with the
  current status when connectivity returns.
- Configure the application's proxy for streaming so updates reach the client
  promptly rather than being buffered until completion.

## Completion notifications

- Show an application-wide snackbar when a calculation completes or fails,
  including when the user has navigated to another application page.
- Include the show name, a short outcome and a View show action.
- Phase changes update progress without generating snackbars.
- After temporary connection loss, show a missed completion notification once
  when the connection recovers. Reconnection must not repeatedly notify for
  the same completion.
- Do not replay old snackbars on page reload or reopening the application;
  show the retained status on the show page instead.
- Email, browser notifications and notifications outside the application are
  outside S12.

## Persistence and backend restarts

- Retain the latest scheduling status and outcome across backend restarts,
  aligned with the PostgreSQL persistence specified in
  `S16_store-state-in-persistent-storage`.
- Calculations interrupted by a backend restart become recognizably Interrupted
  rather than remaining Running indefinitely. Do not resume them automatically;
  allow the user to start again.
- Previously saved results survive restart. Volatile in-memory status alone
  does not satisfy S12; its implementation must integrate with S16 storage.
- Target the single active backend instance defined by S16. Distributed
  execution and scheduling on another PC remain in S13.

## Out of scope

- Cancelling a calculation or applying an intermediate solution.
- History of earlier calculations beyond the latest status and outcome.
- Global capacity limits, queues and remote workers.
- Changes to scheduling objectives or constraints.
- This specification grants no coding-standards waiver.

## Acceptance criteria

- [ ] Starting Schedule Groups returns without waiting for solver completion;
      leaving or reloading the page does not interrupt the calculation.
- [ ] Opening a show in another screen recovers its current backend status;
      duplicate runs for the same show are prevented in frontend and backend,
      while different shows can run concurrently.
- [ ] Running status shows elapsed time, phase and discovery of a valid solution
      during a phase, without a fabricated completion percentage or ETA.
- [ ] SSE delivers status changes promptly through the deployed proxy. Initial
      connection and reconnection reconcile the current state, and loss of
      connectivity visibly marks status as potentially outdated.
- [ ] Successful runs automatically apply their result after the existing start
      confirmation, retain stale-input protection and distinguish proven optimal
      results from valid results at the time limit.
- [ ] The final display includes finish time and concrete attendance, spread and
      variety results when successful; unsuccessful outcomes are distinguishable
      and explain that previous assignments were preserved.
- [ ] An application-wide snackbar reports completion or failure with the show
      name and View show action, including after navigation to another page.
- [ ] Connection recovery notifies once for a missed completion; phase changes,
      repeated reconnection and reopening do not replay old snackbars.
- [ ] The latest status and outcome survive navigation, reload and backend
      restart through persistent storage integrated with S16.
- [ ] After backend restart, interrupted calculations are marked Interrupted,
      do not resume automatically and can be started again; saved results remain.

## Implementation handoff

This specification records the agreed design and behavior. Backend and frontend
changes, persistence integration, proxy configuration and validation are
subsequent implementation work. S12 replaces S9's synchronous request behavior
while retaining the existing scheduling and result-application protections.
