Phase 7: pinning, plan versions, solver budget + UX polish

Backend (school-service):
  - tt_solution gains parent_solution_id (self-FK, ON DELETE SET NULL)
    and seconds_limit columns via ALTER TABLE IF NOT EXISTS.
  - CreateTimetableSolutionRequest accepts optional parent_solution_id
    and seconds_limit (5-600s) with binding validation.
  - CreateSolution checks parent ownership before INSERT so users can't
    fork another tenant's plan.
  - New PUT /timetable/lessons/:id/pin endpoint; ownership enforced via
    the lesson's solution.created_by_user_id JOIN.

Solver:
  - Lesson.pinned now carries @PlanningPin so Timefold leaves locked
    cells untouched during the search.
  - build_problem() takes optional parent_solution_id; if set, copies
    pinned (class_id, subject_id, day, period, room) tuples onto fresh
    Lesson objects via greedy first-fit matching. Surplus pinned rows
    from curriculum changes are silently dropped.
  - _build_factory(seconds) replaces the module-level factory so each
    job honours its tt_solution.seconds_limit override.
  - persist_solution writes lesson.pinned back so subsequent re-solves
    inherit it.

Frontend (studio-v2):
  - SolutionList grows three knobs in the create-form: Basieren auf
    (parent dropdown, only completed solutions, disabled when none),
    Sekunden-Limit (5-600), and the existing Name.
  - PlanView cells get a pin/unpin button with optimistic update and
    rollback on error. Pinned cells gain an amber ring.
  - types.ts + api.ts mirror the new fields; lessonsApi.pin(id, bool).
  - HelpPanel: collapsible 6-step Bedienungsanleitung explaining the
    setup-to-plan workflow. Anchored at the top of /stundenplan above
    the dev token banner.
  - page.tsx switches to the same gradient + animated-blob background
    used on /korrektur so /stundenplan stops looking like a slate-900
    test page.
  - JWT dev banner gets a step-by-step explanation of how to grab the
    token from DevTools and a non-blocking success indicator (no more
    alert()).

Tests:
  - school-service: 6 new validator cases for parent_solution_id +
    seconds_limit boundaries. 73 subtests total, all green.
  - studio-v2: mockSchoolApi adds PUT /lessons/:id/pin route. 5 new
    Playwright tests across two suites (parent-selector visibility +
    options, seconds-limit input, pin button render, pin-icon flip).
    Existing tests adjusted to the new help panel + JWT banner wording.

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

studio-v2/app/stundenplan/_components/HelpPanel.tsx

@@ -0,0 +1,76 @@
+'use client'
+
+import { useState } from 'react'
+import { useTheme } from '@/lib/ThemeContext'
+
+const STEPS: { title: string; body: string }[] = [
+  {
+    title: '1. Klassen, Lehrer, Faecher, Raeume anlegen',
+    body: 'Stammdaten zuerst — der Solver kann nur scheduln was er kennt. Ohne mindestens 1 Klasse, 1 Fach, 1 Raum und 1 Lehrer wird der Plan leer.',
+  },
+  {
+    title: '2. Zeitraster definieren',
+    body: 'Wochentag + Stundennummer + Start/Ende fuer jeden Slot. Pausen anhaken; der Solver belegt sie nicht.',
+  },
+  {
+    title: '3. Stundentafel + Lehrauftraege',
+    body: 'Stundentafel: pro Klasse, wie viele Wochenstunden welches Fach. Lehrauftraege: welcher Lehrer unterrichtet welches Fach in welcher Klasse. Ohne Lehrauftrag wird die Lesson uebersprungen.',
+  },
+  {
+    title: '4. Regeln (Constraints) — optional',
+    body: 'Lehrer-Abwesenheiten, Fach-Bevorzugungen, Raum-Sperren. Hart-Regeln muss der Solver einhalten, Soft-Regeln werden gewichtet.',
+  },
+  {
+    title: '5. Plan generieren',
+    body: 'Zurueck auf den Plan-Tab → "Neuen Plan generieren". Der Solver laeuft im Hintergrund (bis zu 60 s) und schreibt das Ergebnis direkt in die Datenbank. Status erscheint live in der Liste.',
+  },
+  {
+    title: '6. Cells anpinnen + Re-Solve',
+    body: 'Im Wochengrid einzelne Stunden anpinnen (Schloss-Icon). Beim naechsten Solve mit dem Plan als "Basieren auf"-Quelle bleiben die gepinnten Cells stehen, alles andere wird neu gerechnet.',
+  },
+]
+
+export function HelpPanel() {
+  const { isDark } = useTheme()
+  const [open, setOpen] = useState(false)
+
+  return (
+    <div
+      className={`mb-4 rounded-2xl border backdrop-blur-xl ${
+        isDark ? 'bg-white/10 border-white/20 text-white' : 'bg-white/80 border-black/10 text-slate-900'
+      }`}
+      data-testid="help-panel"
+    >
+      <button
+        onClick={() => setOpen(o => !o)}
+        className="w-full flex items-center justify-between px-4 py-3 text-left"
+      >
+        <span className="flex items-center gap-2 font-medium">
+          <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5}
+                  d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+          </svg>
+          Bedienungsanleitung
+          <span className={`text-xs ${isDark ? 'text-white/50' : 'text-slate-500'}`}>
+            (6 Schritte vom Setup bis zum fertigen Stundenplan)
+          </span>
+        </span>
+        <span className={`text-sm transition-transform ${open ? 'rotate-180' : ''}`}>▾</span>
+      </button>
+      {open && (
+        <div className={`px-4 pb-4 space-y-3 border-t ${isDark ? 'border-white/10' : 'border-black/10'}`}>
+          {STEPS.map((s, i) => (
+            <div key={i} className="pt-3">
+              <h4 className={`text-sm font-semibold ${isDark ? 'text-white' : 'text-slate-900'}`}>{s.title}</h4>
+              <p className={`text-sm mt-1 ${isDark ? 'text-white/60' : 'text-slate-600'}`}>{s.body}</p>
+            </div>
+          ))}
+          <p className={`pt-3 text-xs italic ${isDark ? 'text-white/40' : 'text-slate-500'}`}>
+            Tipp: Solver-Probleme im Status-Feld der Plan-Liste — &quot;Keine Lessons&quot; heisst meistens fehlende
+            Lehrauftraege; &quot;Nicht loesbar&quot; heisst harte Constraints widersprechen sich.
+          </p>
+        </div>
+      )}
+    </div>
+  )
+}

studio-v2/app/stundenplan/_components/plan/PlanView.tsx

@@ -2,7 +2,7 @@
 
 import { useState, useEffect, useCallback, useMemo } from 'react'
 import { useTheme } from '@/lib/ThemeContext'
-import { solutionsApi, subjectsApi } from '@/lib/stundenplan/api'
+import { solutionsApi, subjectsApi, lessonsApi } from '@/lib/stundenplan/api'
 import type { TimetableLesson, TimetableSubject } from '@/app/stundenplan/types'
 
 interface PlanViewProps {
@@ -109,6 +109,19 @@ export function PlanView({ solutionId }: PlanViewProps) {
   const cellLesson = (day: number, periodIdx: number): TimetableLesson | undefined =>
     visibleLessons.find(l => l.day_of_week === day && l.period_index === periodIdx)
 
+  const togglePin = useCallback(async (lesson: TimetableLesson) => {
+    // Optimistic update so the lock icon flips immediately even if the
+    // server is slow.
+    setLessons(prev => prev.map(l => l.id === lesson.id ? { ...l, pinned: !l.pinned } : l))
+    try {
+      await lessonsApi.pin(lesson.id, !lesson.pinned)
+    } catch (e) {
+      // Revert on failure and surface the error.
+      setLessons(prev => prev.map(l => l.id === lesson.id ? { ...l, pinned: lesson.pinned } : l))
+      setError(e instanceof Error ? e.message : 'Pin fehlgeschlagen')
+    }
+  }, [])
+
   const cardClass = isDark ? 'bg-white/10 border-white/20 text-white' : 'bg-white/80 border-black/10 text-slate-900'
   const selectClass = isDark ? 'bg-white/10 border-white/20 text-white' : 'bg-white border-slate-300 text-slate-900'
 
@@ -177,11 +190,23 @@ export function PlanView({ solutionId }: PlanViewProps) {
                     return (
                       <td key={d.v} className="px-2 py-1">
                         <div
-                          className="rounded-md p-2 text-xs space-y-0.5"
+                          className={`rounded-md p-2 text-xs space-y-0.5 relative ${lesson.pinned ? 'ring-2 ring-amber-400/70' : ''}`}
                           style={{ backgroundColor: color + (isDark ? '40' : '30'), borderLeft: `3px solid ${color}` }}
                           data-testid={`cell-${d.v}-${idx}`}
                         >
-                          <div className="font-semibold">{lesson.subject_name || '?'}</div>
+                          <button
+                            onClick={() => togglePin(lesson)}
+                            data-testid={`pin-${lesson.id}`}
+                            title={lesson.pinned ? 'Lesson loesen' : 'Lesson anpinnen'}
+                            className={`absolute top-1 right-1 text-xs leading-none px-1 py-0.5 rounded ${
+                              lesson.pinned
+                                ? 'text-amber-300 hover:text-amber-200'
+                                : 'opacity-30 hover:opacity-100'
+                            }`}
+                          >
+                            {lesson.pinned ? '🔒' : '📌'}
+                          </button>
+                          <div className="font-semibold pr-5">{lesson.subject_name || '?'}</div>
                           {perspective !== 'class' && lesson.class_name && (
                             <div className="opacity-80">{lesson.class_name}</div>
                           )}

studio-v2/app/stundenplan/_components/plan/SolutionList.tsx

@@ -33,6 +33,8 @@ export function SolutionList({ onView, selectedId }: SolutionListProps) {
   const [error, setError] = useState<string | null>(null)
   const [submitting, setSubmitting] = useState(false)
   const [name, setName] = useState('')
+  const [parentId, setParentId] = useState<string>('')
+  const [secondsLimit, setSecondsLimit] = useState<number | ''>('')
   const pollingRef = useRef<ReturnType<typeof setInterval> | null>(null)
 
   const load = useCallback(async () => {
@@ -70,8 +72,14 @@ export function SolutionList({ onView, selectedId }: SolutionListProps) {
     setSubmitting(true)
     setError(null)
     try {
-      await solutionsApi.create({ name: name || `Plan ${new Date().toLocaleString('de-DE')}` })
+      await solutionsApi.create({
+        name: name || `Plan ${new Date().toLocaleString('de-DE')}`,
+        parent_solution_id: parentId || null,
+        seconds_limit: secondsLimit === '' ? null : Number(secondsLimit),
+      })
       setName('')
+      setParentId('')
+      setSecondsLimit('')
       await load()
     } catch (err) {
       setError(err instanceof Error ? err.message : 'Solve fehlgeschlagen')
@@ -93,14 +101,49 @@ export function SolutionList({ onView, selectedId }: SolutionListProps) {
   const cardClass = isDark ? 'bg-white/10 border-white/20 text-white' : 'bg-white/80 border-black/10 text-slate-900'
   const inputClass = isDark ? 'bg-white/10 border-white/20 text-white placeholder-white/40' : 'bg-white border-slate-300 text-slate-900 placeholder-slate-400'
 
+  const completedParents = items.filter(s => s.status === 'completed')
+
   return (
     <div className="space-y-4" data-testid="solution-list">
       <div className={`p-4 rounded-2xl border backdrop-blur-xl ${cardClass}`}>
-        <div className="flex items-end gap-3">
-          <div className="flex-1">
+        <div className="grid grid-cols-1 md:grid-cols-4 gap-3">
+          <div className="md:col-span-2">
             <label className="block text-sm mb-1 opacity-70">Name (optional)</label>
             <input value={name} onChange={e => setName(e.target.value)} placeholder="z.B. Schuljahr 26/27 Variante 1" className={`w-full px-3 py-2 rounded-lg border ${inputClass}`} />
           </div>
+          <div>
+            <label className="block text-sm mb-1 opacity-70">Basieren auf (optional)</label>
+            <select
+              value={parentId}
+              onChange={e => setParentId(e.target.value)}
+              disabled={completedParents.length === 0}
+              data-testid="parent-selector"
+              className={`w-full px-3 py-2 rounded-lg border disabled:opacity-50 ${inputClass}`}
+            >
+              <option value="">— ohne Vorlage —</option>
+              {completedParents.map(p => (
+                <option key={p.id} value={p.id}>{p.name || p.id.slice(0, 8)}</option>
+              ))}
+            </select>
+          </div>
+          <div>
+            <label className="block text-sm mb-1 opacity-70">Sekunden-Limit</label>
+            <input
+              type="number"
+              min={5}
+              max={600}
+              value={secondsLimit}
+              onChange={e => setSecondsLimit(e.target.value === '' ? '' : parseInt(e.target.value))}
+              placeholder="60"
+              data-testid="seconds-limit"
+              className={`w-full px-3 py-2 rounded-lg border ${inputClass}`}
+            />
+          </div>
+        </div>
+        <div className="mt-3 flex items-center justify-between">
+          <p className={`text-xs ${isDark ? 'text-white/40' : 'text-slate-500'}`}>
+            Mit Vorlage uebernimmt der Solver alle gepinnten Cells aus dem Quellplan.
+          </p>
           <button
             onClick={handleSolve}
             disabled={submitting}
@@ -110,9 +153,6 @@ export function SolutionList({ onView, selectedId }: SolutionListProps) {
             {submitting ? 'Startet…' : 'Neuen Plan generieren'}
           </button>
         </div>
-        <p className={`mt-2 text-xs ${isDark ? 'text-white/40' : 'text-slate-500'}`}>
-          Solver laeuft im Hintergrund (bis zu 60 Sekunden). Status erscheint in der Liste.
-        </p>
       </div>
 
       {error && <div className="p-3 rounded-xl bg-red-500/20 border border-red-500/40 text-red-300">{error}</div>}