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>
2026-05-22 00:16:52 +02:00
parent 082a5bb68c
commit f042f2896b
25 changed files with 1431 additions and 2 deletions
@@ -28,6 +28,9 @@ type Config struct {

 	// LLM Gateway (for AI features)
 	LLMGatewayURL string
+
+	// Timetable solver service (Python/FastAPI, port 8095)
+	SolverServiceURL string
 }

 // Load loads configuration from environment variables
@@ -43,6 +46,7 @@ func Load() (*Config, error) {
 		RateLimitRequests: getEnvInt("RATE_LIMIT_REQUESTS", 100),
 		RateLimitWindow:   getEnvInt("RATE_LIMIT_WINDOW", 60),
 		LLMGatewayURL:     getEnv("LLM_GATEWAY_URL", "http://backend:8000/llm"),
+		SolverServiceURL:  getEnv("SOLVER_SERVICE_URL", "http://timetable-solver-service:8095"),
 	}

 	// Parse allowed origins
@@ -218,6 +218,9 @@ func Migrate(db *DB) error {
 	// Append timetable constraint migrations (see timetable_constraints_migrations.go)
 	migrations = append(migrations, TimetableConstraintMigrations()...)

+	// Append timetable solution migrations (see timetable_solution_migrations.go)
+	migrations = append(migrations, TimetableSolutionMigrations()...)
+
 	for _, migration := range migrations {
 		_, err := db.Pool.Exec(ctx, migration)
 		if err != nil {
@@ -0,0 +1,49 @@
+package database
+
+// TimetableSolutionMigrations creates tt_solution + tt_lesson for the solver
+// pipeline. One run of the solver produces exactly one tt_solution row plus
+// many tt_lesson rows (one per scheduled class-subject hour).
+//
+// Status flow:
+//   pending → running → completed | failed | infeasible
+//
+// hard_score / soft_score come straight from Timefold's HardSoftScore. Lower
+// (more negative) hard_score means more hard-constraint violations; the UI
+// only ever offers solutions with hard_score == 0 as "valid".
+func TimetableSolutionMigrations() []string {
+	return []string{
+		`CREATE TABLE IF NOT EXISTS tt_solution (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+			created_by_user_id UUID NOT NULL,
+			name VARCHAR(120),
+			status VARCHAR(20) NOT NULL DEFAULT 'pending',
+			hard_score INT,
+			soft_score INT,
+			error_message TEXT,
+			started_at TIMESTAMPTZ,
+			finished_at TIMESTAMPTZ,
+			created_at TIMESTAMPTZ DEFAULT NOW()
+		)`,
+
+		`CREATE TABLE IF NOT EXISTS tt_lesson (
+			id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+			solution_id UUID NOT NULL REFERENCES tt_solution(id) ON DELETE CASCADE,
+			class_id UUID NOT NULL REFERENCES tt_class(id) ON DELETE CASCADE,
+			subject_id UUID NOT NULL REFERENCES tt_subject(id) ON DELETE CASCADE,
+			teacher_id UUID NOT NULL REFERENCES tt_teacher(id) ON DELETE CASCADE,
+			room_id UUID REFERENCES tt_room(id) ON DELETE SET NULL,
+			day_of_week INT NOT NULL CHECK (day_of_week BETWEEN 1 AND 7),
+			period_index INT NOT NULL CHECK (period_index BETWEEN 1 AND 12),
+			pinned BOOLEAN NOT NULL DEFAULT false,
+			created_at TIMESTAMPTZ DEFAULT NOW(),
+			UNIQUE(solution_id, class_id, day_of_week, period_index),
+			UNIQUE(solution_id, teacher_id, day_of_week, period_index),
+			UNIQUE(solution_id, room_id, day_of_week, period_index)
+		)`,
+
+		`CREATE INDEX IF NOT EXISTS idx_tt_solution_user ON tt_solution(created_by_user_id)`,
+		`CREATE INDEX IF NOT EXISTS idx_tt_lesson_solution ON tt_lesson(solution_id)`,
+		`CREATE INDEX IF NOT EXISTS idx_tt_lesson_class ON tt_lesson(class_id)`,
+		`CREATE INDEX IF NOT EXISTS idx_tt_lesson_teacher ON tt_lesson(teacher_id)`,
+	}
+}
@@ -17,10 +17,11 @@ type Handler struct {
 	certificateService *services.CertificateService
 	aiService          *services.AIService
 	timetableService   *services.TimetableService
+	solverServiceURL   string
 }

 // NewHandler creates a new Handler with all services
-func NewHandler(db *pgxpool.Pool, llmGatewayURL string) *Handler {
+func NewHandler(db *pgxpool.Pool, llmGatewayURL, solverServiceURL string) *Handler {
 	classService := services.NewClassService(db)
 	examService := services.NewExamService(db)
 	gradeService := services.NewGradeService(db)
@@ -37,6 +38,7 @@ func NewHandler(db *pgxpool.Pool, llmGatewayURL string) *Handler {
 		certificateService: certificateService,
 		aiService:          aiService,
 		timetableService:   timetableService,
+		solverServiceURL:   solverServiceURL,
 	}
 }

@@ -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"})
+}
@@ -0,0 +1,49 @@
+package models
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// TimetableSolution is one run of the solver — exactly one row per solve.
+// Lessons attached via tt_lesson.solution_id.
+type TimetableSolution struct {
+	ID              uuid.UUID  `json:"id" db:"id"`
+	CreatedByUserID uuid.UUID  `json:"created_by_user_id" db:"created_by_user_id"`
+	Name            string     `json:"name,omitempty" db:"name"`
+	Status          string     `json:"status" db:"status"`
+	HardScore       *int       `json:"hard_score,omitempty" db:"hard_score"`
+	SoftScore       *int       `json:"soft_score,omitempty" db:"soft_score"`
+	ErrorMessage    string     `json:"error_message,omitempty" db:"error_message"`
+	StartedAt       *time.Time `json:"started_at,omitempty" db:"started_at"`
+	FinishedAt      *time.Time `json:"finished_at,omitempty" db:"finished_at"`
+	CreatedAt       time.Time  `json:"created_at" db:"created_at"`
+}
+
+// TimetableLesson is one scheduled class-period in a solution.
+type TimetableLesson struct {
+	ID          uuid.UUID  `json:"id" db:"id"`
+	SolutionID  uuid.UUID  `json:"solution_id" db:"solution_id"`
+	ClassID     uuid.UUID  `json:"class_id" db:"class_id"`
+	SubjectID   uuid.UUID  `json:"subject_id" db:"subject_id"`
+	TeacherID   uuid.UUID  `json:"teacher_id" db:"teacher_id"`
+	RoomID      *uuid.UUID `json:"room_id,omitempty" db:"room_id"`
+	DayOfWeek   int        `json:"day_of_week" db:"day_of_week"`
+	PeriodIndex int        `json:"period_index" db:"period_index"`
+	Pinned      bool       `json:"pinned" db:"pinned"`
+	CreatedAt   time.Time  `json:"created_at" db:"created_at"`
+
+	// Joined fields for display
+	ClassName   string `json:"class_name,omitempty"`
+	SubjectName string `json:"subject_name,omitempty"`
+	TeacherName string `json:"teacher_name,omitempty"`
+	RoomName    string `json:"room_name,omitempty"`
+}
+
+// CreateTimetableSolutionRequest kicks off a solve. The solver-service is
+// invoked async — this endpoint only registers the solution row and queues
+// the job.
+type CreateTimetableSolutionRequest struct {
+	Name string `json:"name"`
+}
@@ -0,0 +1,149 @@
+package services
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/breakpilot/school-service/internal/models"
+)
+
+// TimetableSolutionService persists solver runs and forwards solve requests
+// to the timetable-solver-service. The solver writes lesson rows back to the
+// same DB once it finishes, so listing solutions = simple SELECTs here.
+
+func (s *TimetableService) CreateSolution(ctx context.Context, userID string, req *models.CreateTimetableSolutionRequest) (*models.TimetableSolution, error) {
+	var sol models.TimetableSolution
+	err := s.db.QueryRow(ctx, `
+		INSERT INTO tt_solution (created_by_user_id, name, status)
+		VALUES ($1, $2, 'pending')
+		RETURNING id, created_by_user_id, COALESCE(name, ''), status, hard_score, soft_score,
+		          COALESCE(error_message, ''), started_at, finished_at, created_at
+	`, userID, req.Name).Scan(
+		&sol.ID, &sol.CreatedByUserID, &sol.Name, &sol.Status,
+		&sol.HardScore, &sol.SoftScore, &sol.ErrorMessage,
+		&sol.StartedAt, &sol.FinishedAt, &sol.CreatedAt,
+	)
+	return &sol, err
+}
+
+func (s *TimetableService) ListSolutions(ctx context.Context, userID string) ([]models.TimetableSolution, error) {
+	rows, err := s.db.Query(ctx, `
+		SELECT id, created_by_user_id, COALESCE(name, ''), status, hard_score, soft_score,
+		       COALESCE(error_message, ''), started_at, finished_at, created_at
+		FROM tt_solution WHERE created_by_user_id = $1 ORDER BY created_at DESC
+	`, userID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []models.TimetableSolution
+	for rows.Next() {
+		var sol models.TimetableSolution
+		if err := rows.Scan(&sol.ID, &sol.CreatedByUserID, &sol.Name, &sol.Status,
+			&sol.HardScore, &sol.SoftScore, &sol.ErrorMessage,
+			&sol.StartedAt, &sol.FinishedAt, &sol.CreatedAt); err != nil {
+			return nil, err
+		}
+		out = append(out, sol)
+	}
+	return out, nil
+}
+
+func (s *TimetableService) GetSolution(ctx context.Context, id, userID string) (*models.TimetableSolution, error) {
+	var sol models.TimetableSolution
+	err := s.db.QueryRow(ctx, `
+		SELECT id, created_by_user_id, COALESCE(name, ''), status, hard_score, soft_score,
+		       COALESCE(error_message, ''), started_at, finished_at, created_at
+		FROM tt_solution WHERE id = $1 AND created_by_user_id = $2
+	`, id, userID).Scan(
+		&sol.ID, &sol.CreatedByUserID, &sol.Name, &sol.Status,
+		&sol.HardScore, &sol.SoftScore, &sol.ErrorMessage,
+		&sol.StartedAt, &sol.FinishedAt, &sol.CreatedAt,
+	)
+	if err != nil {
+		return nil, err
+	}
+	return &sol, nil
+}
+
+func (s *TimetableService) ListLessons(ctx context.Context, solutionID, userID string) ([]models.TimetableLesson, error) {
+	rows, err := s.db.Query(ctx, `
+		SELECT l.id, l.solution_id, l.class_id, l.subject_id, l.teacher_id, l.room_id,
+		       l.day_of_week, l.period_index, l.pinned, l.created_at,
+		       cl.name, sub.name, t.last_name || ', ' || t.first_name,
+		       COALESCE(r.name, '')
+		FROM tt_lesson l
+		JOIN tt_solution s ON l.solution_id = s.id
+		JOIN tt_class cl ON l.class_id = cl.id
+		JOIN tt_subject sub ON l.subject_id = sub.id
+		JOIN tt_teacher t ON l.teacher_id = t.id
+		LEFT JOIN tt_room r ON l.room_id = r.id
+		WHERE s.id = $1 AND s.created_by_user_id = $2
+		ORDER BY l.day_of_week, l.period_index
+	`, solutionID, userID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []models.TimetableLesson
+	for rows.Next() {
+		var l models.TimetableLesson
+		if err := rows.Scan(&l.ID, &l.SolutionID, &l.ClassID, &l.SubjectID, &l.TeacherID, &l.RoomID,
+			&l.DayOfWeek, &l.PeriodIndex, &l.Pinned, &l.CreatedAt,
+			&l.ClassName, &l.SubjectName, &l.TeacherName, &l.RoomName); err != nil {
+			return nil, err
+		}
+		out = append(out, l)
+	}
+	return out, nil
+}
+
+func (s *TimetableService) DeleteSolution(ctx context.Context, id, userID string) error {
+	_, err := s.db.Exec(ctx, `DELETE FROM tt_solution WHERE id = $1 AND created_by_user_id = $2`, id, userID)
+	return err
+}
+
+// TriggerSolve hands the freshly-created solution off to the solver-service.
+// The solver writes back to tt_solution/tt_lesson directly once finished, so
+// from this side we just need to fire-and-forget and let the client poll.
+func (s *TimetableService) TriggerSolve(ctx context.Context, solverURL, solutionID, userID string) error {
+	payload := map[string]string{
+		"solution_id":      solutionID,
+		"created_by_user_id": userID,
+	}
+	body, _ := json.Marshal(payload)
+
+	// 5s timeout — solver should accept the job in milliseconds and run async.
+	reqCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(reqCtx, "POST", solverURL+"/api/v1/solve", bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		// Mark solution as failed so the user sees something went wrong.
+		_, _ = s.db.Exec(ctx, `
+			UPDATE tt_solution SET status = 'failed', error_message = $1, finished_at = NOW()
+			WHERE id = $2
+		`, "solver-service unreachable: "+err.Error(), solutionID)
+		return err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode >= 400 {
+		_, _ = s.db.Exec(ctx, `
+			UPDATE tt_solution SET status = 'failed', error_message = $1, finished_at = NOW()
+			WHERE id = $2
+		`, fmt.Sprintf("solver returned HTTP %d", resp.StatusCode), solutionID)
+		return fmt.Errorf("solver returned HTTP %d", resp.StatusCode)
+	}
+	return nil
+}
@@ -0,0 +1,27 @@
+package services
+
+import (
+	"testing"
+
+	"github.com/breakpilot/school-service/internal/models"
+)
+
+func TestCreateTimetableSolutionRequest_NoBindingTags(t *testing.T) {
+	// CreateSolution accepts an empty name; the binding tag is intentionally
+	// absent. Both states (with + without name) must pass validation.
+	tests := []struct {
+		name    string
+		req     models.CreateTimetableSolutionRequest
+		wantErr bool
+	}{
+		{"empty", models.CreateTimetableSolutionRequest{}, false},
+		{"with name", models.CreateTimetableSolutionRequest{Name: "Schuljahr 26/27 Test"}, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if (validate.Struct(tt.req) != nil) != tt.wantErr {
+				t.Errorf("unexpected validation outcome")
+			}
+		})
+	}
+}