wannsee-kram/docs/superpowers/specs/2026-05-04-erbstuecke-reservierung-design.md

# Erbstücke-Reservierung — Design-Spezifikation

**Datum:** 2026-05-04
**Status:** Freigegeben zur Implementierung
**Sprache:** Deutsch (gesamte UI)

---

## 1. Projektziel & Kontext

Eine kurzlebige Webanwendung, die Familienmitgliedern ermöglicht, Gegenstände aus dem Nachlass der Großmutter zu reservieren. Das Projekt läuft bis alle Gegenstände vergeben sind und wird dann geschlossen. Einfachheit und schnelle Umsetzung haben Vorrang vor Langlebigkeit.

**Primäre Akteure:**
- **Familienmitglieder** — reservieren Artikel, kein Konto erforderlich
- **Admins** (Marcel + Tante) — verwalten Inventar und Zugangscodes

**Nicht-Ziele:**
- Kein Text-Volltextsuche (Stöbern ist visuell)
- Keine E-Mail- oder SMS-Versandautomatik für Codes
- Keine Auktions- oder Bietfunktion
- Keine Zahlungsabwicklung
- Keine Mehrsprachigkeit (nur Deutsch)

---

## 2. Nutzerrollen & Zugang

### 2.1 Familienmitglieder (Code-basiert)

- Zugang ausschließlich per persönlichem Code
- **Primärer Weg:** Link mit Code als URL-Parameter (z. B. `?code=AB3K7MN2`) — Code wird automatisch extrahiert und in `localStorage` gespeichert
- **Fallback:** manuelle Code-Eingabe auf dem Gate Screen
- Code ist alphanumerisch, kurz genug zum manuellen Eintippen (8 Zeichen, Großbuchstaben + Ziffern)
- Jeder Code hat genau einen **Display-Namen**, der vom Admin beim Erstellen vergeben wird
- Der Display-Name wird in der App oben angezeigt: „Angemeldet als: [Name]"
- **Kein Code = kein Inhalt sichtbar** — der Gate Screen zeigt nichts außer dem Code-Eingabefeld

### 2.2 Admins (Konto-basiert)

- Eigene Login-Seite mit Benutzername und Passwort
- Zwei feste Admin-Konten (Marcel, Tante) — kein Selbstregistrierungssystem
- Admins sehen eine separate Admin-Oberfläche, nicht die Familiengalerie

---

## 3. Datenmodell

| Entität | Felder |
|---|---|
| **Artikel** | ID · Titel (optional) · Fotos (geordnete Liste, erstes = Galerie-Thumbnail) · Kategorie · Notiz (optional) · Erstelldatum |
| **Code** | ID · Code-String · Display-Name · Erstelldatum |
| **Reservierung** | ID · Artikel-ID · Code-ID · Zeitstempel |

**Kategorien (fix, nicht erweiterbar durch User):**
Bücher · Möbel · Küchenutensilien · Schmuck · Kunstwerke · Kleidung · Werkzeug · Dokumente/Erinnerungsstücke

---

## 4. Familienmitglied-Erlebnis

### 4.1 Gate Screen (kein Code vorhanden)

- Minimale Ansicht: App-Name/Icon, einzeiliger Erklärungstext, Code-Eingabefeld (zentriert, Großbuchstaben, Letter-Spacing), „Weiter"-Button
- Hinweis: „Noch kein Code? Wende dich an Marcel oder Tante."
- Falscher Code → Fehlermeldung: „Code nicht bekannt — bitte prüfe die Eingabe."
- Richtiger Code → Session wird gespeichert, direkt zur Galerie

### 4.2 Galerie

**Layout (responsiv):**
- Telefon (≤ 767 px): 1 Spalte — horizontale Karte (Foto links 72 px, Kategorie + Status rechts)
- Tablet (768–1023 px): 2 Spalten — quadratische Karten (Foto oben, Kategorie + Status unten)
- Desktop (≥ 1024 px): 2 Spalten — wie Tablet, aber in einem zentrierten Container mit horizontalem Padding (kein 3-Spalten-Layout)

**Kategorie-Filter:**
- Horizontale Tab-Leiste oben, scrollbar bei Überlauf
- Tabs: „Alle" + eine Schaltfläche pro Kategorie
- Jeweils nur ein Filter aktiv

**Status-Anzeige pro Karte:**
- Frei: grüner Text „✓ Frei"
- Reserviert von mir: grüner Badge „✓ Meine Reservierung"
- Reserviert von jemand anderem: roter Text „● [Display-Name]"

### 4.3 Artikel-Modal

Öffnet beim Antippen einer Karte. Enthält:
- Foto-Galerie (wischbar, Zähler „1 / 3 →")
- Kategorie-Badge
- Optionale Notiz (nur wenn vorhanden)
- Reservierungsstatus-Bereich (passt sich an):
  - **Frei:** „Reservieren"-Button (grün)
  - **Von mir reserviert:** Badge „✓ Meine Reservierung" + „Reservierung aufheben"-Button (Outline, rot)
  - **Von jemand anderem:** „Reserviert von [Name]" + deaktivierter Button „Nicht verfügbar"

**Reservierungslogik:**
- Erste Reservierung gewinnt (keine Konfliktvermittlung durch Admins)
- Familienmitglieder können andere kontaktieren — dafür ist der Display-Name sichtbar
- Kein „Vielleicht"/„Auf Wunschliste" — nur reserviert oder frei

---

## 5. Admin-Erlebnis

### 5.1 Navigation

- Sidebar (dunkel, linksbündig) mit vier Bereichen
- Auf Mobilgeräten: Sidebar klappt zu Hamburger-Menü
- Bereiche: Inventar · Codes · Reservierungen · Übersicht

### 5.2 Inventar

**Listenansicht:**
- Thumbnail + Kategorie + Reservierungsstatus pro Zeile
- „+ Artikel hinzufügen"-Button oben
- Artikel bearbeiten und löschen möglich
- Löschen nur wenn Artikel nicht reserviert ist (sonst Hinweis: Reservierung zuerst aufheben)

**Artikel hinzufügen / bearbeiten — Kamera-first (mobile-optimiert):**
1. Großer Kamera-Button oben → öffnet direkt Gerätekamera (kein Datei-Browser als Einstieg)
2. Aufgenommene Fotos erscheinen als Thumbnail-Streifen; weiteres Foto hinzufügen möglich
3. Erstes Foto = Galerie-Thumbnail (Reihenfolge verschiebbar)
4. Kategorie-Dropdown (Pflichtfeld)
5. Titel-Textfeld (optional)
6. Notiz-Freitextfeld (optional)
6. „Speichern" / „Abbrechen"

### 5.3 Code-Verwaltung

- Liste aller ausgestellten Codes: Display-Name · Code-String (Monospace) · Anzahl Reservierungen
- „Neuen Code erstellen": Display-Name eingeben → Code wird automatisch generiert
- „Link kopieren": kopiert fertigen Link mit Code in die Zwischenablage
- „Löschen": löscht Code und **alle zugehörigen Reservierungen** — mit Bestätigungsdialog und Warnung

### 5.4 Reservierungsübersicht

- Nach Person gruppiert
- Pro Person: Name als dunkle Kopfzeile, darunter eine Liste der reservierten Artikel
- Pro Artikel: Thumbnail (48 px) · Artikelname · Kategorie-Badge
- Personen ohne Reservierungen werden ausgegraut aber angezeigt

### 5.5 Übersicht (Dashboard)

- Kennzahlen-Zeile: Gesamtartikel · Reserviert · Frei
- Tabelle: Aufschlüsselung nach Kategorie (Spalten: Kategorie · Gesamt · Reserviert · Frei)
- Keine Charts oder Diagramme

---

## 6. Nicht-funktionale Anforderungen

| ID | Anforderung |
|---|---|
| NFR-SEC-001 | Codes sind kryptographisch zufällig generiert (nicht erratbar) |
| NFR-SEC-002 | Admin-Passwörter werden gehasht gespeichert (bcrypt o. Ä.) |
| NFR-SEC-003 | Familienmitglieder können ausschließlich ihre eigenen Reservierungen aufheben |
| NFR-SEC-004 | Admin-Bereich ist von Familienmitglied-Bereich strikt getrennt (kein Code-Zugang zum Admin) |
| NFR-PERF-001 | Galerie mit bis zu 500 Artikeln muss auf Mobilgerät flüssig scrollen |
| NFR-PERF-002 | Fotos werden serverseitig auf eine sinnvolle Maximalgröße komprimiert (max. ~800 KB pro Bild) |
| NFR-ACC-001 | WCAG 2.1 Level AA als Ziel (Kontrast, Fokus-Indikatoren, Alt-Texte auf Fotos) |
| NFR-RESP-001 | Breakpoints: Telefon ≤ 767 px · Tablet 768–1023 px · Desktop ≥ 1024 px |
| NFR-DATA-001 | Keine personenbezogenen Daten außer Display-Namen (kein DSGVO-kritischer Scope) |
| NFR-DATA-002 | Reservierungen werden atomar gespeichert — wenn zwei Personen gleichzeitig denselben Artikel reservieren, gewinnt genau eine (keine doppelte Reservierung möglich) |

---

## 7. Priorisiertes Backlog (MoSCoW)

| ID | Story | MoSCoW | Aufwand |
|---|---|---|---|
| US-AUTH-001 | Als Familienmitglied öffne ich den Link und bin sofort eingeloggt | Must | XS |
| US-AUTH-002 | Als Familienmitglied gebe ich meinen Code manuell ein | Must | XS |
| US-AUTH-003 | Als Admin melde ich mich mit Benutzername und Passwort an | Must | S |
| US-GAL-001 | Als Familienmitglied sehe ich alle Artikel als responsives Grid | Must | M |
| US-GAL-002 | Als Familienmitglied filtere ich nach Kategorie | Must | S |
| US-GAL-003 | Als Familienmitglied öffne ich ein Artikel-Modal mit allen Fotos | Must | M |
| US-RES-001 | Als Familienmitglied reserviere ich einen freien Artikel | Must | S |
| US-RES-002 | Als Familienmitglied hebe ich meine Reservierung auf | Must | XS |
| US-RES-003 | Als Familienmitglied sehe ich wer einen reservierten Artikel hat | Must | XS |
| US-ADM-001 | Als Admin füge ich einen Artikel hinzu (Kamera-first, mobile) | Must | M |
| US-ADM-002 | Als Admin bearbeite ich einen bestehenden Artikel | Must | S |
| US-ADM-003 | Als Admin lösche ich einen unreservierten Artikel | Must | XS |
| US-ADM-004 | Als Admin erstelle ich einen Code mit Display-Name | Must | S |
| US-ADM-005 | Als Admin kopiere ich den fertigen Link für einen Code | Must | XS |
| US-ADM-006 | Als Admin lösche ich einen Code (mit Warnung) | Must | XS |
| US-ADM-007 | Als Admin sehe ich die Reservierungsübersicht nach Person mit Fotos | Must | M |
| US-ADM-008 | Als Admin sehe ich das Dashboard mit Kennzahlen | Should | S |

---

## 8. Offene Fragen / TBD-Register

| ID | Frage | Relevant für |
|---|---|---|
| OQ-001 | Wo wird die App gehostet? (beeinflusst Deployment-Komplexität) | Alle US |
| OQ-002 | Wie viele Admin-Konten werden benötigt — genau 2, oder erweiterbar? | US-AUTH-003 |
| OQ-003 | Soll der App-Name „Erbstücke der Familie" lauten oder anders? | Gate Screen, Browser-Tab |
| OQ-004 | Maximale Anzahl Fotos pro Artikel? (Empfehlung: 10) | US-ADM-001 |

---

## 9. Glossar

| Begriff | Bedeutung |
|---|---|
| Code | Alphanumerischer 8-Zeichen-String, der ein Familienmitglied identifiziert |
| Display-Name | Vom Admin vergebener Anzeigename, der dem Code zugeordnet ist |
| Gate Screen | Eingabeseite für Familienmitglieder ohne aktive Session |
| Reservierung | Zuordnung eines Artikels zu einem Code (first-come-first-served) |
| Admin | Privilegierter Nutzer (Marcel oder Tante) mit Konto-basiertem Login |