Files

T

Benjamin Admin 306886a42b Phase 8: CSV + ICS export, print view, MkDocs docs, SBOM + dev-mode auth

Auth (Test-Mode):
  - middleware.AuthMiddleware now takes a devMode flag. In dev,
    requests without Authorization fall back to a deterministic dev
    UUID (00000000-...-001) and role=teacher. ENVIRONMENT=production
    re-enables the strict 401 path.
  - main.go wires devMode = cfg.Environment != "production".
  - page.tsx replaces the red 'Anmeldung noch nicht integriert' banner
    with a softer Testumgebung notice; the manual-token form moves
    behind a nested details block.

Export endpoints (school-service):
  - LoadExportLessons joins tt_lesson with tt_period for wall-clock
    times; one query feeds both CSV and ICS.
  - WriteCSV streams 10 columns including pinned flag.
  - WriteICS emits one VEVENT per lesson anchored to a Monday — caller
    overridable via ?start=YYYY-MM-DD. RFC 5545 escapes for ',', ';',
    '\n' in icsEscape().
  - NextMonday helper for the default anchor.
  - GET /timetable/solutions/:id/export.{csv,ics} handlers attach
    Content-Disposition: attachment so browsers download instead of
    rendering.

Frontend:
  - lib/stundenplan/api.ts downloadSolutionExport() fetches as blob,
    triggers a synthetic <a download> click, and forwards the JWT when
    present.
  - PlanView gains CSV / ICS / Drucken buttons next to the perspective
    selector. The toolbar carries class 'no-print' so window.print()
    yields only the grid.
  - globals.css @media print rule hides chrome, forces white
    background, gives the table proper borders for A4.

Docs:
  - docs-src/services/stundenplan/{index,architecture,constraints,
    solver-tuning,export}.md with nav entry in mkdocs.yml under
    Services → Stundenplaner.
  - sbom/stundenplan/README.md lists manually-verified key dependencies
    and the policy reference. scripts/stundenplan-sbom.sh generates
    full machine-readable inventories via go-licenses + pip-licenses
    + license-checker when those tools are available.

Tests:
  - internal/services/timetable_exports_test.go: 4 unit tests covering
    CSV column layout + quoting, ICS structure + DTSTART formatting,
    icsEscape special chars, NextMonday weekday math.
  - studio-v2/e2e/stundenplan-export.spec.ts split out of the main spec
    file (LOC budget) — 3 tests for button render, CSV download,
    ICS download.
  - mockSchoolApi extended with export.csv + export.ics routes.

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

2026-05-22 08:57:07 +02:00

2.6 KiB

Raw Blame History

Solver-Tuning

Timefold-Konfiguration

Der SolverFactory wird in runner.py pro Solve gebaut so dass jedes Job-Spent-Limit aus tt_solution.seconds_limit einzeln zur Geltung kommt.

SolverConfig(
    solution_class=Timetable,
    entity_class_list=[Lesson],
    score_director_factory_config=ScoreDirectorFactoryConfig(
        constraint_provider_function=define_constraints,
    ),
    termination_config=TerminationConfig(
        spent_limit=Duration(seconds=seconds),
    ),
)

Default Timeout: 60 s. Per Solve ueberschreibbar im UI (5–600 s).

Score-Modell

HardSoftScore — Hard-Komponente ist die wichtige:

hard_score < 0 → Solution ist infeasible, UI markiert in Amber.
hard_score == 0 → Solution gueltig, soft_score minimiert Praeferenz- Verletzungen.

Pinning fuer iterative Verbesserung

Workflow:

Initial-Solve laeuft → Plan A.
Rektor pinnt 5–10 Cells im UI, die ihm gefallen.
Neuer Solve mit parent_solution_id = Plan A. Der Solver nimmt die gepinnten Cells als Fixpunkte (@PlanningPin) und rechnet die restlichen Lessons neu.
Optional Sekunden-Limit erhoehen (z.B. 180 s) wenn die Solution-Qualitaet wichtiger ist als die Wartezeit.

Implementierung in repository._inherit_pinned_from_parent():

Greedy First-Fit-Matching by (class_id, subject_id)
Surplus pinned Rows aus dem Parent (z.B. weil curriculum-Stunden gekuerzt) werden silently uebersprungen
Mismatch wird in Logs ausgegeben, fuehrt aber nicht zu failed Status

Was tun wenn der Solver `infeasible` meldet

Reihenfolge der Diagnose:

Lessons-Count vs. Slots-Count: Wenn die Summe der Wochenstunden ueber alle Klassen > Anzahl Slots pro Woche × Anzahl Raeume ist, kann es physisch keine Loesung geben. Stundentafel kuerzen oder mehr Raeume.
Lehrer-Auslastung: Wenn ein Lehrer mit 28 h Cap in der Stundentafel 30 h zugewiesen bekommt, ist es unloesbar. Lehrauftraege anpassen.
Harte Constraints widerspruechlich: Mathe muss morgens UND ist excluded_room fuer alle Vormittags-Raeume → Konflikt. Constraints von Hard auf Soft umstellen wo moeglich.
Sekunden-Limit zu kurz: Bei sehr restriktiven Modellen braucht der Solver laenger zum ersten Fit-finden. 300 s probieren.

Performance-Charakteristik

Kleine Schule (3 Klassen, 8 Lehrer, 6 Faecher, ~80 Lessons): meist <5 s
Mittlere Schule (15 Klassen, 30 Lehrer, ~400 Lessons): 30–60 s fuer hard_score=0, weitere Minuten fuer soft-Optimierung
Sehr grosse Schule (>800 Lessons): Solver kommt mit 60 s Default nicht konvergent, hoeheres Limit oder Multi-Threading evaluieren (Timefold Enterprise)

2.6 KiB Raw Blame History Unescape Escape