feat: implement onboarding phase with form and info views, including onboarding status checks

src/app/actions/onboarding.ts

@@ -0,0 +1,92 @@
+'use server';
+
+import db from '@/lib/db';
+import { participant } from '@/lib/model/participant';
+import { eq, and } from 'drizzle-orm';
+import { auth } from '@/lib/auth';
+import { headers } from 'next/headers';
+
+export async function isOnboardingDone(experimentId: number): Promise<boolean> {
+  const session = await auth.api.getSession({ headers: await headers() });
+  if (!session) throw new Error('Nicht angemeldet');
+
+  try {
+    const participantRecord = await db
+      .select()
+      .from(participant)
+      .where(
+        and(
+          eq(participant.experimentId, experimentId),
+          eq(participant.userId, session.user.id)
+        )
+      )
+      .limit(1);
+
+    // If no participant record exists, onboarding is not done
+    if (participantRecord.length === 0) {
+      return false;
+    }
+
+    // Check if onboarding answers are filled
+    const onboardingAnswers = participantRecord[0].onboardingAnswers as Record<string, any> | null;
+    return onboardingAnswers !== null && Object.keys(onboardingAnswers).length > 0;
+  } catch (error) {
+    console.error('Error checking onboarding status:', error);
+    throw new Error('Failed to check onboarding status');
+  }
+}
+
+export async function getOnboardingAnswers(experimentId: number) {
+  try {
+    const session = await auth.api.getSession({ headers: await headers() });
+    if (!session) throw new Error('Nicht angemeldet');
+
+    const participantRecord = await db
+      .select()
+      .from(participant)
+      .where(
+        and(
+          eq(participant.experimentId, experimentId),
+          eq(participant.userId, session.user.id)
+        )
+      )
+      .limit(1);
+
+    if (participantRecord.length === 0) {
+      return { success: true, data: null };
+    }
+
+    return { success: true, data: participantRecord[0].onboardingAnswers };
+  } catch (error) {
+    console.error('Error fetching onboarding answers:', error);
+    throw new Error('Failed to fetch onboarding answers');
+  }
+}
+
+export async function saveOnboardingAnswers(
+  experimentId: number,
+  answers: Record<string, any>
+): Promise<void> {
+  const session = await auth.api.getSession({ headers: await headers() });
+  if (!session) throw new Error('Nicht angemeldet');
+
+  try {
+    // Upsert participant record with onboarding answers
+    await db
+      .insert(participant)
+      .values({
+        experimentId,
+        userId: session.user.id,
+        onboardingAnswers: answers,
+      })
+      .onConflictDoUpdate({
+        target: [participant.experimentId, participant.userId],
+        set: {
+          onboardingAnswers: answers,
+        },
+      });
+  } catch (error) {
+    console.error('Error saving onboarding answers:', error);
+    throw new Error('Failed to save onboarding answers');
+  }
+}

src/app/annotate/[experimentId]/page.tsx

@@ -4,8 +4,10 @@ import Link from 'next/link';
 import { auth } from '@/lib/auth';
 import { getAnnotationEntries} from '@/app/actions/annotations';
 import { isCalibrationDone } from '@/app/actions/calibration-scoring';
+import { isOnboardingDone } from '@/app/actions/onboarding';
 import { getExperimentById } from '@/app/actions/experiment';
 import AnnotationPageView from '@/components/AnnotationViews/AnnotationPageView';
+import OnboardingPhase from '@/components/OnboardingViews/OnboardingPhase';
 import CalibrationPhase from '@/components/CalibrationViews/CalibrationPhase';
 
 interface Props {
@@ -30,6 +32,12 @@ export default async function AnnotatePage({ params }: Props) {
     );
   }
 
+  // Check if onboarding is required and not yet done
+  const onboardingDone = await isOnboardingDone(experimentId);
+  if (!onboardingDone) {
+    return <OnboardingPhase experimentId={experimentId} />;
+  }
+
   // Check if calibration is required and not yet done
   const calibrationDone = await isCalibrationDone(experimentId);
   if (!calibrationDone) {

src/components/OnboardingViews/OnboardingFormView.tsx

@@ -0,0 +1,399 @@
+'use client';
+
+import { useState, useTransition } from 'react';
+import { useRouter } from 'next/navigation';
+import { saveOnboardingAnswers } from '@/app/actions/onboarding';
+import { DIALECT_LABELS_WITHOUT_DE } from '@/lib/dialects';
+
+interface OnboardingFormViewProps {
+  experimentId: number;
+}
+
+interface ResidenceEntry {
+  region: string;
+  years: string;
+}
+
+interface FormData {
+  age?: string;
+  residences?: ResidenceEntry[];
+  dialectQualities?: Record<string, string>;
+  listeningExperience?: string;
+  additionalNotes?: string;
+}
+
+type Step = 1 | 2 | 3;
+
+export default function OnboardingFormView({ experimentId }: OnboardingFormViewProps) {
+  const router = useRouter();
+  const [isPending, startTransition] = useTransition();
+  const [currentStep, setCurrentStep] = useState<Step>(1);
+  
+  // Initialize dialect qualities with default value of '3' for each dialect
+  const initializeDialectQualities = (): Record<string, string> => {
+    const qualities: Record<string, string> = {};
+    Object.keys(DIALECT_LABELS_WITHOUT_DE).forEach(key => {
+      qualities[key] = '3';
+    });
+    return qualities;
+  };
+  
+  const [formData, setFormData] = useState<FormData>({
+    age: '',
+    residences: [{ region: '', years: '' }],
+    dialectQualities: initializeDialectQualities()
+  });
+  const [error, setError] = useState<string | null>(null);
+
+  const handleChange = (field: keyof FormData, value: string) => {
+    setFormData((prev) => ({
+      ...prev,
+      [field]: value,
+    }));
+  };
+
+  const handleDialectQualityChange = (region: string, value: string) => {
+    setFormData((prev) => ({
+      ...prev,
+      dialectQualities: {
+        ...prev.dialectQualities,
+        [region]: value,
+      },
+    }));
+  };
+
+  const handleResidenceChange = (
+    index: number,
+    field: keyof ResidenceEntry,
+    value: string
+  ) => {
+    setFormData((prev) => ({
+      ...prev,
+      residences: prev.residences?.map((r, i) =>
+        i === index ? { ...r, [field]: value } : r
+      ),
+    }));
+  };
+
+  const addResidence = () => {
+    setFormData((prev) => ({
+      ...prev,
+      residences: [...(prev.residences || []), { region: '', years: '' }],
+    }));
+  };
+
+  const removeResidence = (index: number) => {
+    setFormData((prev) => ({
+      ...prev,
+      residences: prev.residences?.filter((_, i) => i !== index),
+    }));
+  };
+
+  const validateStep = (step: Step): boolean => {
+    switch (step) {
+      case 1:
+        if (!formData.age) {
+          setError('Bitte wählen Sie eine Altersgruppe aus.');
+          return false;
+        }
+        break;
+      case 2:
+        const hasValidResidence = formData.residences?.some(
+          (r) => r.region && r.years
+        );
+        if (!hasValidResidence) {
+          setError('Bitte fügen Sie mindestens einen Wohnort mit Jahresangabe hinzu.');
+          return false;
+        }
+        break;
+      case 3:
+        const allDialects = Object.keys(DIALECT_LABELS_WITHOUT_DE);
+        const hasAllDialectQualities = allDialects.every(
+          (region) => formData.dialectQualities?.[region]
+        );
+        if (!hasAllDialectQualities) {
+          setError('Bitte bewerten Sie Ihre Fähigkeit für alle Dialekte.');
+          return false;
+        }
+        break;
+    }
+    return true;
+  };
+
+  const handleNext = () => {
+    setError(null);
+    if (validateStep(currentStep)) {
+      if (currentStep < 3) {
+        setCurrentStep((currentStep + 1) as Step);
+      }
+    }
+  };
+
+  const handlePrevious = () => {
+    setError(null);
+    if (currentStep > 1) {
+      setCurrentStep((currentStep - 1) as Step);
+    }
+  };
+
+  const handleSubmit = () => {
+    setError(null);
+
+    startTransition(async () => {
+      try {
+        await saveOnboardingAnswers(experimentId, formData);
+        // Redirect to the experiment annotation page to trigger a refresh
+        router.refresh();
+      } catch (err) {
+        console.error('Error saving onboarding answers:', err);
+        setError('Fehler beim Speichern des Formulars. Bitte versuchen Sie es erneut.');
+      }
+    });
+  };
+
+  const stepTitles: Record<Step, string> = {
+    1: 'Persönliche Informationen',
+    2: 'Aufenthaltsorte',
+    3: 'Selbsteinschätzung',
+  };
+
+  return (
+    <div className="flex flex-col h-full bg-white">
+      <div className="flex-1 flex items-center justify-center px-4 py-8">
+        <div className="max-w-2xl w-full">
+          {/* Progress Bar */}
+          <div className="mb-8">
+            <div className="flex justify-between items-center mb-2">
+              <h2 className="text-sm font-semibold text-gray-600">
+                Schritt {currentStep} von 3
+              </h2>
+              <div className="text-sm text-gray-500">{Math.round((currentStep / 3) * 100)}%</div>
+            </div>
+            <div className="w-full h-2 bg-gray-200 rounded-full overflow-hidden">
+              <div
+                className="h-full bg-blue-600 transition-all duration-300"
+                style={{ width: `${(currentStep / 3) * 100}%` }}
+              />
+            </div>
+          </div>
+
+          {/* Header */}
+          <div className="text-center mb-8">
+            <h1 className="text-3xl font-bold text-gray-900 mb-2">{stepTitles[currentStep]}</h1>
+          </div>
+
+          {/* Form */}
+          <form className="space-y-6">
+            {/* Error Message */}
+            {error && (
+              <div className="bg-red-50 border border-red-200 rounded-lg p-4">
+                <p className="text-red-800 text-sm">{error}</p>
+              </div>
+            )}
+
+            {/* Step 1: Persönliche Informationen */}
+            {currentStep === 1 && (
+              <div>
+                <label htmlFor="age" className="block text-sm font-medium text-gray-900 mb-2">
+                  Altersgruppe <span className="text-red-600">*</span>
+                </label>
+                <select
+                  id="age"
+                  value={formData.age}
+                  onChange={(e) => handleChange('age', e.target.value)}
+                  className="w-full px-4 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+                >
+                  <option value="">-- Bitte wählen --</option>
+                  <option value="18-">Unter 18 Jahre</option>
+                  <option value="18-25">18-25 Jahre</option>
+                  <option value="26-35">26-35 Jahre</option>
+                  <option value="36-45">36-45 Jahre</option>
+                  <option value="46-55">46-55 Jahre</option>
+                  <option value="56-65">56-65 Jahre</option>
+                  <option value="66+">66+ Jahre</option>
+                </select>
+              </div>
+            )}
+
+            {/* Step 2: Aufenthaltsorte */}
+            {currentStep === 2 && (
+              <div className="space-y-6">
+                <p className="text-sm text-gray-600 mb-4">
+                  Bitte geben Sie die Regionen an, in denen Sie länger als 1 Jahr gelebt haben, sowie die Anzahl der Jahre. Diese Informationen helfen uns, Ihre Dialektkenntnisse besser einzuschätzen.
+                </p>
+                {/* Map Placeholder */}
+                <div className="bg-gray-100 border-2 border-dashed border-gray-300 rounded-lg p-12 flex items-center justify-center min-h-[300px]">
+                  <div className="text-center">
+                    <div className="text-4xl mb-2">🗺️</div>
+                    <p className="text-gray-500 font-medium">Karte kommt hier (mit Dialektregionen)</p>
+                  </div>
+                </div>
+
+                {/* Residence Entries */}
+                <div>
+                  <label className="block text-sm font-medium text-gray-900 mb-4">
+                    Aufenthaltsorte, die länger als 1 Jahr waren <span className="text-red-600">*</span>
+                  </label>
+
+                  <div className="space-y-4">
+                    {formData.residences?.map((residence, index) => (
+                      <div key={index} className="flex gap-3 items-end">
+                        <div className="flex-1">
+                          <label className="block text-xs font-medium text-gray-700 mb-1">
+                            Region
+                          </label>
+                          <select
+                            value={residence.region}
+                            onChange={(e) =>
+                              handleResidenceChange(index, 'region', e.target.value)
+                            }
+                            className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent text-sm"
+                          >
+                            <option value="">-- Wählen --</option>
+                            {Object.entries(DIALECT_LABELS_WITHOUT_DE).map(
+                              ([key, label]) => (
+                                <option key={key} value={key}>
+                                  {label}
+                                </option>
+                              )
+                            )}
+                          </select>
+                        </div>
+
+                        <div className="w-24">
+                          <label className="block text-xs font-medium text-gray-700 mb-1">
+                            Jahre
+                          </label>
+                          <input
+                            type="number"
+                            min="0"
+                            max="120"
+                            value={residence.years}
+                            onChange={(e) =>
+                              handleResidenceChange(index, 'years', e.target.value)
+                            }
+                            placeholder="z.B. 10"
+                            className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent text-sm"
+                          />
+                        </div>
+
+                        <button
+                          type="button"
+                          onClick={() => removeResidence(index)}
+                          disabled={(formData.residences?.length || 0) <= 1}
+                          className="px-3 py-2 bg-red-100 hover:bg-red-200 disabled:bg-gray-100 text-red-600 disabled:text-gray-400 font-medium rounded-lg transition-colors text-sm"
+                        >
+                          ✕
+                        </button>
+                      </div>
+                    ))}
+                  </div>
+
+                  <button
+                    type="button"
+                    onClick={addResidence}
+                    className="mt-4 px-4 py-2 bg-blue-100 hover:bg-blue-200 text-blue-600 font-medium rounded-lg transition-colors text-sm"
+                  >
+                    + Weiterer Ort
+                  </button>
+                </div>
+              </div>
+            )}
+
+            {/* Step 3: Selbsteinschätzung */}
+            {currentStep === 3 && (
+              <div className="space-y-6">
+                <div>
+                  <p className="text-sm text-gray-600 mb-6">
+                    Bewerten Sie Ihre Fähigkeit, die folgenden Dialekte zu identifizieren, auf einer Skala von "sehr schlecht" bis "sehr gut". Diese Selbsteinschätzung hilft uns, Ihre nachfolgendenKalibrierungsergebnisse besser zu interpretieren.
+                  </p>
+
+                  <div className="space-y-5">
+                    {Object.entries(DIALECT_LABELS_WITHOUT_DE).map(([key, label]) => {
+                      const qualityLabels: Record<string, string> = {
+                        '1': 'Sehr schlecht',
+                        '2': 'Schlecht',
+                        '3': 'Weder noch',
+                        '4': 'Gut',
+                        '5': 'Sehr gut',
+                      };
+                      const currentValue = formData.dialectQualities?.[key] || '3';
+                      return (
+                        <div key={key}>
+                          <div className="flex justify-between items-center mb-2">
+                            <label className="text-sm font-medium text-gray-900">
+                              {label}
+                            </label>
+                            <span className="text-sm font-semibold text-blue-600 bg-blue-50 px-3 py-1 rounded-full">
+                              {qualityLabels[currentValue]}
+                            </span>
+                          </div>
+                          <div>
+                            <input
+                              type="range"
+                              min="1"
+                              max="5"
+                              step="1"
+                              value={currentValue}
+                              onChange={(e) =>
+                                handleDialectQualityChange(key, e.target.value)
+                              }
+                              className="w-full h-2 bg-gray-200 rounded-lg appearance-none cursor-pointer accent-blue-600"
+                            />
+                          </div>
+                          <div className="flex justify-between text-xs text-gray-600 mt-2 font-medium">
+                            <span>Sehr schlecht</span>
+                            <span>Sehr gut</span>
+                          </div>
+                        </div>
+                      );
+                    })}
+                  </div>
+                </div>
+              </div>
+            )}
+
+            {/* Navigation Buttons */}
+            <div className="flex gap-4 justify-between pt-8">
+              <button
+                type="button"
+                onClick={handlePrevious}
+                disabled={currentStep === 1 || isPending}
+                className="px-6 py-3 bg-gray-300 hover:bg-gray-400 disabled:bg-gray-200 text-gray-800 font-semibold rounded-lg transition-colors"
+              >
+                ← Zurück
+              </button>
+
+              {currentStep < 3 ? (
+                <button
+                  type="button"
+                  onClick={handleNext}
+                  disabled={isPending}
+                  className="px-6 py-3 bg-blue-600 hover:bg-blue-700 disabled:bg-blue-400 text-white font-semibold rounded-lg transition-colors"
+                >
+                  Weiter →
+                </button>
+              ) : (
+                <button
+                  type="button"
+                  onClick={handleSubmit}
+                  disabled={isPending}
+                  className="px-8 py-3 bg-green-600 hover:bg-green-700 disabled:bg-green-400 text-white font-semibold rounded-lg transition-colors"
+                >
+                  {isPending ? 'Wird gespeichert...' : 'Abschließen'}
+                </button>
+              )}
+            </div>
+          </form>
+
+          {/* Info */}
+          <div className="bg-blue-50 border border-blue-200 rounded-lg p-4 mt-8">
+            <p className="text-blue-800 text-sm">
+              Die mit <span className="text-red-600">*</span> gekennzeichneten Felder sind erforderlich.
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/OnboardingViews/OnboardingInfoView.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+interface OnboardingInfoViewProps {
+  onContinue: () => void;
+  hasExistingAnswers: boolean;
+}
+
+export default function OnboardingInfoView({
+  onContinue,
+  hasExistingAnswers,
+}: OnboardingInfoViewProps) {
+  const handleContinue = () => {
+    onContinue();
+  };
+
+  return (
+    <div className="flex flex-col h-full bg-white">
+      <div className="flex-1 flex items-center justify-center px-4">
+        <div className="max-w-2xl w-full">
+          {/* Header */}
+          <div className="text-center mb-4">
+            <h1 className="text-3xl font-bold text-gray-900 mb-2">Willkommen</h1>
+          </div>
+
+          {/* Info Section */}
+          <div className="bg-blue-50 border border-blue-200 rounded-lg p-8 mb-8">
+            <h2 className="text-xl font-semibold text-gray-900 mb-4">Was ist das Ziel?</h2>
+            <p className="text-gray-700 mb-4">
+              Vielen Dank, dass Sie an diesem Experiment teilnehmen. Bevor Sie mit der Annotation beginnen, möchten wir gerne ein paar grundlegende Informationen über Sie und Ihre Erfahrung mit Dialekten sammeln.
+            </p>
+            <p className="text-gray-700 mb-4">
+              Diese Informationen helfen uns, Ihre Annotationsergebnisse besser zu verstehen und zu bewerten. Alle Angaben werden vertraulich behandelt.
+            </p>
+          </div>
+
+          {/* Instructions Section */}
+          <div className="mb-8">
+            <h3 className="text-lg font-semibold text-gray-900 mb-4">Wie funktioniert es?</h3>
+            <ol className="space-y-3 text-gray-700">
+              <li className="flex gap-3">
+                <span className="flex-shrink-0 w-6 h-6 bg-blue-600 text-white rounded-full flex items-center justify-center text-sm font-semibold">
+                  1
+                </span>
+                <span>Sie beantworten ein kurzes Umfrage-Formular</span>
+              </li>
+              <li className="flex gap-3">
+                <span className="flex-shrink-0 w-6 h-6 bg-blue-600 text-white rounded-full flex items-center justify-center text-sm font-semibold">
+                  2
+                </span>
+                <span>Die Antworten werden gespeichert</span>
+              </li>
+              <li className="flex gap-3">
+                <span className="flex-shrink-0 w-6 h-6 bg-blue-600 text-white rounded-full flex items-center justify-center text-sm font-semibold">
+                  3
+                </span>
+                <span>Danach geht es zur Kalibrierungsphase</span>
+              </li>
+              <li className="flex gap-3">
+                <span className="flex-shrink-0 w-6 h-6 bg-blue-600 text-white rounded-full flex items-center justify-center text-sm font-semibold">
+                  4
+                </span>
+                <span>Anschließend können Sie mit der Annotation beginnen</span>
+              </li>
+            </ol>
+          </div>
+
+          {/* Status */}
+          {hasExistingAnswers && (
+            <div className="bg-green-50 border border-green-200 rounded-lg p-6 mb-8">
+              <p className="text-green-800 text-sm">
+                ✓ Sie haben diesen Teil bereits ausgefüllt. Klicken Sie auf "Weiter", um fortzufahren.
+              </p>
+            </div>
+          )}
+
+          {/* Continue Button */}
+          <div className="flex justify-center">
+            <button
+              onClick={handleContinue}
+              className="px-8 py-3 bg-blue-600 hover:bg-blue-700 text-white font-semibold rounded-lg transition-colors"
+            >
+              Weiter zum Formular
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/OnboardingViews/OnboardingPhase.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { getOnboardingAnswers } from '@/app/actions/onboarding';
+import OnboardingInfoView from './OnboardingInfoView';
+import OnboardingFormView from './OnboardingFormView';
+
+interface OnboardingPhaseProps {
+  experimentId: number;
+}
+
+export default function OnboardingPhase({ experimentId }: OnboardingPhaseProps) {
+  const [showInfoPage, setShowInfoPage] = useState(true);
+  const [hasExistingAnswers, setHasExistingAnswers] = useState(false);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    const load = async () => {
+      try {
+        // Load existing answers to check if user has completed onboarding before
+        const answersResult = await getOnboardingAnswers(experimentId);
+        if (answersResult.success && answersResult.data) {
+          const answers = answersResult.data as Record<string, any> | null;
+          if (answers && Object.keys(answers).length > 0) {
+            setHasExistingAnswers(true);
+          }
+        }
+      } catch (err) {
+        console.error(err);
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    load();
+  }, [experimentId]);
+
+  // Show loading view
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center min-h-screen">
+        <div className="text-center">
+          <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4"></div>
+          <p className="text-gray-600">Loading onboarding...</p>
+        </div>
+      </div>
+    );
+  }
+
+  // Show info page first
+  if (showInfoPage) {
+    return (
+      <OnboardingInfoView
+        onContinue={() => setShowInfoPage(false)}
+        hasExistingAnswers={hasExistingAnswers}
+      />
+    );
+  }
+
+  // Show onboarding form page
+  return <OnboardingFormView experimentId={experimentId} />;
+}