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>
This commit is contained in:
@@ -0,0 +1,70 @@
|
||||
# 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.
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
1. Initial-Solve laeuft → Plan A.
|
||||
2. Rektor pinnt 5–10 Cells im UI, die ihm gefallen.
|
||||
3. Neuer Solve mit `parent_solution_id = Plan A`. Der Solver nimmt die
|
||||
gepinnten Cells als Fixpunkte (`@PlanningPin`) und rechnet die restlichen
|
||||
Lessons neu.
|
||||
4. 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:
|
||||
|
||||
1. **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.
|
||||
2. **Lehrer-Auslastung**: Wenn ein Lehrer mit 28 h Cap in der Stundentafel
|
||||
30 h zugewiesen bekommt, ist es unloesbar. Lehrauftraege anpassen.
|
||||
3. **Harte Constraints widerspruechlich**: Mathe muss morgens UND ist
|
||||
`excluded_room` fuer alle Vormittags-Raeume → Konflikt. Constraints von
|
||||
Hard auf Soft umstellen wo moeglich.
|
||||
4. **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)
|
||||
Reference in New Issue
Block a user