Phase 5: Timefold timetable-solver-service + solution persistence

school-service additions:
  - tt_solution + tt_lesson migration. tt_lesson carries three UNIQUEs
    (solution+class, solution+teacher, solution+room per slot) so the
    DB itself rejects any double-booking the solver might emit by
    mistake.
  - Solution CRUD + GET solutions/:id/lessons endpoint with joined
    class/subject/teacher/room names for display.
  - POST /timetable/solutions creates the row then fires off the
    solver-service via HTTP (5s timeout, mark failed if unreachable).
  - SOLVER_SERVICE_URL config wired through main.go/handlers.

New service timetable-solver-service:
  - Python 3.11 + FastAPI + Timefold Solver 1.21 (Apache-2.0). Dockerfile
    bundles OpenJDK 17 since Timefold for Python is a JPype bridge.
  - app/domain.py — Timefold @planning_entity Lesson with timeslot+room
    as PlanningVariables; @planning_solution Timetable holds problem
    facts (rooms/teachers/etc.) AND rule-fact collections.
  - app/rules.py — frozen dataclasses mirroring 6 of the 15 tt_
    constraint_* tables initially.
  - app/constraints.py — ConstraintProvider with 3 universal hard
    constraints (no double-booking) + 5 DB-driven constraints
    (teacher_unavailable_day/window, teacher_excluded_room,
    room_unavailable, room_requires_type) + 1 quality soft constraint
    (subject_preferred_period). Remaining 9 constraint types ready to
    plug in via the same join pattern.
  - app/repository.py — async loaders for stammdaten + rules; builds
    one Lesson per (curriculum row × weekly_hours), skipping rows
    without a tt_assignment teacher.
  - app/runner.py — runs solver in ThreadPoolExecutor so the FastAPI
    event loop stays responsive. Updates tt_solution status
    pending→running→completed|infeasible|failed.
  - app/main.py — POST /api/v1/solve (202 Accepted, background task),
    GET /api/v1/jobs/{id}, /health. School-service polls tt_solution
    directly instead of GET /jobs for the typical case.
  - docker-compose.yml adds the service on port 8095, depending on
    core-health-check.

Tests:
  - school-service: validator test for CreateTimetableSolutionRequest
    (allows empty name).
  - solver-service: tests/test_domain.py + tests/test_rules.py cover
    construction + hashability of the planning facts. Full solve flow
    deferred to Phase 8 integration with seed data.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

school-service/internal/handlers/timetable_solution_handlers.go

@@ -0,0 +1,91 @@
+package handlers
+
+import (
+	"net/http"
+
+	"github.com/breakpilot/school-service/internal/models"
+	"github.com/gin-gonic/gin"
+)
+
+// ---------- Solutions ----------
+
+func (h *Handler) CreateTimetableSolution(c *gin.Context) {
+	uid := getUserID(c)
+	if uid == "" {
+		respondError(c, http.StatusUnauthorized, "User not authenticated")
+		return
+	}
+	var req models.CreateTimetableSolutionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		respondError(c, http.StatusBadRequest, "Invalid request: "+err.Error())
+		return
+	}
+	sol, err := h.timetableService.CreateSolution(c.Request.Context(), uid, &req)
+	if err != nil {
+		respondError(c, http.StatusInternalServerError, "Failed to create solution: "+err.Error())
+		return
+	}
+	// Fire-and-forget the solver invocation; the row is persisted regardless.
+	if err := h.timetableService.TriggerSolve(c.Request.Context(), h.solverServiceURL, sol.ID.String(), uid); err != nil {
+		// Don't fail the request — the solution row already shows status=failed.
+		// The client will see error_message via GET /solutions/:id.
+		respondCreated(c, sol)
+		return
+	}
+	respondCreated(c, sol)
+}
+
+func (h *Handler) ListTimetableSolutions(c *gin.Context) {
+	uid := getUserID(c)
+	if uid == "" {
+		respondError(c, http.StatusUnauthorized, "User not authenticated")
+		return
+	}
+	out, err := h.timetableService.ListSolutions(c.Request.Context(), uid)
+	if err != nil {
+		respondError(c, http.StatusInternalServerError, "Failed to list solutions: "+err.Error())
+		return
+	}
+	respondSuccess(c, out)
+}
+
+func (h *Handler) GetTimetableSolution(c *gin.Context) {
+	uid := getUserID(c)
+	if uid == "" {
+		respondError(c, http.StatusUnauthorized, "User not authenticated")
+		return
+	}
+	sol, err := h.timetableService.GetSolution(c.Request.Context(), c.Param("id"), uid)
+	if err != nil {
+		respondError(c, http.StatusNotFound, "Solution not found")
+		return
+	}
+	respondSuccess(c, sol)
+}
+
+func (h *Handler) ListTimetableLessons(c *gin.Context) {
+	uid := getUserID(c)
+	if uid == "" {
+		respondError(c, http.StatusUnauthorized, "User not authenticated")
+		return
+	}
+	out, err := h.timetableService.ListLessons(c.Request.Context(), c.Param("id"), uid)
+	if err != nil {
+		respondError(c, http.StatusInternalServerError, "Failed to list lessons: "+err.Error())
+		return
+	}
+	respondSuccess(c, out)
+}
+
+func (h *Handler) DeleteTimetableSolution(c *gin.Context) {
+	uid := getUserID(c)
+	if uid == "" {
+		respondError(c, http.StatusUnauthorized, "User not authenticated")
+		return
+	}
+	if err := h.timetableService.DeleteSolution(c.Request.Context(), c.Param("id"), uid); err != nil {
+		respondError(c, http.StatusInternalServerError, "Failed to delete solution: "+err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Solution deleted"})
+}