zeugnix.ch – MVP
Schweizer Arbeitszeugnis-Plattform: erstellen, mit kryptografischem Hash
absichern, später prüfbar und verständlich machen.
Dieses Repository enthält das MVP-Skelett der Plattform: Landingpage,
Auth, Dashboard, Zeugnis-Erstellungs-Workflow, Hash-Engine, Verify-Endpoint,
Analyse-Engine (Stub) und Stripe-Stubs.
Was lauffähig ist
- Landingpage (
/)
- Magic-Link-Login via Supabase (
/login, /auth/callback)
- Geschützter App-Bereich (
/app/*)
- Firmenverwaltung
- Zeugnis-Erstellung (Mitarbeiterdaten, Aufgaben, Typ)
- Manager-Beurteilung über Token-Link (kein Account nötig)
- Baustein-basierte Zeugnistext-Generierung
- SHA-256-Finalisierung mit kanonisiertem Inhalt
- PDF-Generierung mit Hash-Block und QR-Code
- Verify-Seite mit Browser-seitiger PDF-Text-Extraktion und Hash-Vergleich
- Klartext-Analyse (regelbasiert, MVP-Stub)
- Stripe-Routen als Stub (echte Bezahlung muss konfiguriert werden)
Was bewusst NICHT enthalten ist
- Vollständige Bausteinbibliothek (aktuell ~45 Bausteine als Beispiel –
produktiv sollten 300–500 von einem HR-Profi/Arbeitsrechtler stammen)
- E-Mail-Versand für Manager-Einladungen (Resend ist vorbereitet, aber im
MVP wird der Einladungslink stattdessen als API-Antwort zurückgegeben)
- LLM-basierte Zeugnis-Analyse (aktuell nur regelbasiert)
- OCR für gescannte Zeugnis-PDFs
- Live-Stripe-Checkout
Setup
Schritt 1 – Abhängigkeiten installieren
npm install
Schritt 2 – Supabase-Projekt anlegen
- Auf https://supabase.com ein neues Projekt erstellen (Region Frankfurt
eu-central-1 empfohlen für DSG-Konformität).
- SQL-Editor öffnen und die zwei Migrationen nacheinander ausführen:
supabase/001_initial_schema.sql – legt alle Tabellen, Enums,
Trigger und RLS-Policies an.supabase/002_seed_phrases.sql – seed der Bausteinbibliothek.
- Storage Buckets anlegen (Dashboard → Storage → "New bucket"):
company-logos (public)certificates (private)uploads (private)reports (private)
Schritt 3 – Environment Variables setzen
.env.example zu .env.local kopieren und ausfüllen:
cp .env.example .env.local
Mindestens diese drei Variablen sind Pflicht:
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...
NEXT_PUBLIC_SITE_URL=http://localhost:3000
Die Werte stehen in Supabase unter Project Settings → API.
Schritt 4 – Lokal starten
npm run dev
# → http://localhost:3000
Schritt 5 – Hash-Engine-Tests
npm run test:hash
Es laufen 21 Tests gegen die Kanonisierung und SHA-256-Erzeugung.
Diese sollten bei jedem Code-Change grün bleiben.
Vercel-Deployment
- GitHub-Repository pushen.
- Auf Vercel → "Add New Project" → Repo auswählen.
- Im Vercel-Dashboard unter Settings → Environment Variables alle
Werte aus
.env.local setzen, plus NEXT_PUBLIC_SITE_URL auf die
Vercel-Domain (z.B. https://zeugnix.vercel.app oder https://zeugnix.ch).
- Wichtig: In Supabase unter Authentication → URL Configuration
die Vercel-URL als Site URL und Redirect URLs eintragen.
- Deploy starten.
Workflow im Bild
┌──────────┐ ┌──────────────┐ ┌───────────────┐ ┌─────────┐
│ HR legt │────▶│ Manager wird │────▶│ HR generiert │────▶│ Zeugnis │
│ Zeugnis │ │ eingeladen, │ │ Text aus │ │ wird │
│ an │ │ beurteilt │ │ Beurteilungen │ │ final. │
└──────────┘ └──────────────┘ └───────────────┘ └────┬────┘
│
▼
┌─────────────────┐
│ SHA-256-Hash + │
│ PDF + QR-Code │
└─────────────────┘
Architektur
- Next.js 15 App Router, Server Components als Default
- Supabase für Auth, Postgres und Storage
- Row-Level-Security auf allen Tabellen
- Token-basierte Manager-Einladungen (kein Account für Führungskräfte)
- Hash-Engine: deterministische Kanonisierung → SHA-256 (Web Crypto API)
- PDF:
@react-pdf/renderer server-seitig
- Verify: PDF-Text-Extraktion mit
pdfjs-dist im Browser, Hash-Vergleich
in API-Route gegen certificates.hash
Roadmap zum Production-Launch
Kritisch (vor Live-Schaltung)
- Bausteinbibliothek auf 300+ professionelle Schweizer Formulierungen
ausbauen (Empfehlung: HR-Profi oder Arbeitsrechtler beauftragen)
- Resend-E-Mail-Templates für Manager-Einladungen
- Stripe-Live-Konfiguration für die vier Bezahlstufen
- DSG-konforme Datenschutzerklärung und AGB (Anwalt einbeziehen)
- Realistische Bewertungs-Tonalitäten (sehr_gut/gut/genuegend/ungenuegend
je Kategorie und Geschlecht müssen konsistent sein)
Wichtig
- Logo-Upload mit Storage-Anbindung
- Mehrbenutzer-Verwaltung pro Firma (HR-Team)
- E-Mail-Versand bei finalen Zeugnissen an Mitarbeitende
- LLM-basierte Klartext-Analyse statt Regel-Heuristik
- OCR für gescannte Zeugnisse (Tesseract oder cloud OCR)
Nice-to-have
- Verified Certificate Employer Badge auf der Webseite des Arbeitgebers
- Recruiter-Bulk-Verifikation
- Auswertungs-Dashboard für HR (Zeugnisse pro Quartal, durchschnittliche
Bewertungs-Verteilung etc.)
- Mehrsprachigkeit (FR, IT, EN)
Lizenzen / Drittanbieter
- Schriftarten Inter Tight, Fraunces, JetBrains Mono via Google Fonts
- Icons: Inline-SVG, eigene Implementierung
- pdfjs-dist (Apache 2.0), @react-pdf/renderer (MIT), Supabase (Apache 2.0)
