# Spec #2 – KAT-05 Katalogdaten laden und aktuell halten

| | |
|---|---|
| Issue | #2 (KAT-05) |
| Status | Entwurf, wartet auf Freigabe durch Chris |
| Autor | architect |
| Stand | 2026-11-03 |
| Etappe | R1.1 (Teil 2a: Datenmodell, Rechte, Startbestand), R1.2 (Teil 2b: Admin-Pflege per Studio; Teil 2c: Meldungen bearbeiten); Import (Krit. 1, 3, 6, Quellenteil von 2) erst mit Lizenz |
| Abhängigkeiten | keine (Fundament). Abhängig von #2: #3 KAT-01, #13 KAT-04, #25 SAM-08 |
| Quellen | `requirements/20-r1-akzeptanzkriterien.md` § KAT-05 und § Querschnitt, `requirements/r1-klaerungen.md` (3, 4, 5, 6, 7, 10, 24, 25/44, 26, 27, 39, 48, N11, N12, N12a), `requirements/backlog.md` (Abschnitt „Datenmodell-Änderungen für architect“), `docs/datenmodell-r1.md`, `supabase/migrations/20261102100000_base.sql`, `…100200_catalog.sql`, `…100300_collection.sql`, `…100400_plays.sql`, `supabase/tests/database/02_catalog.test.sql`, `supabase/seed.sql`, `supabase/config.toml`, ADR-0001, ADR-0002 |

## 1. Ziel

Der Katalog ist das Fundament aller anderen Stories: Suche (KAT-01), Detailseite (KAT-02), Sammlung, Partien und Meldungen verweisen auf `games`. KAT-05 sorgt in R1 dafür, dass

- das Datenmodell alles enthält, was Admin-Pflege und ein späterer Import brauchen (ausgeblendet, zusammengeführt, manuell gepflegte Felder, Quelle mit Anzeige-Erlaubnis; Klärung 7), ohne dass der Import später eine Migration braucht,
- nur der Admin den Katalog und Meldungen ändern kann, und zwar in R1 ausschließlich über Supabase Studio/SQL (Klärungen 25/44),
- zum Start von R1 ein manuell gepflegter Startbestand von etwa 200 Spielen vorliegt, der nur Fakten enthält, ohne fremde Cover und fremde Beschreibungstexte (Klärung 24, N11),
- der Ablauf der Admin-Pflege im Repo dokumentiert ist (Krit. 8).

Ein Import-Job (BGG oder eine andere Quelle) ist **nicht** Teil dieser Spec. Es gibt keine Edge Function und keine Admin-Oberfläche in der App.

### Kernentscheidungen (Kurzfassung)

| # | Entscheidung | Begründung |
|---|---|---|
| E1 | **Ein Issue #2, drei PRs:** 2a (R1.1) Datenmodell, Rechte, Startbestand-Lieferweg, Platzhalter-Cover; 2b (R1.2) Zusammenführen und Runbook; 2c (R1.2) Meldungstabelle und Bearbeiten von Meldungen. 2a und 2b referenzieren `Refs #2`, 2c `Closes #2`. | Entspricht dem Etappenschnitt im Issue. 2a blockiert KAT-01 (#3), 2c muss vor der Umsetzung von KAT-04 (#13) gemergt sein. Eigene Issues würden nur Abhängigkeiten verschieben. |
| E2 | **Größe neu bewertet: L statt XL.** 2a ≈ 2–3 Tage (davon der Großteil Migration und pgTAP), 2b ≈ 1–2 Tage, 2c ≈ 1 Tag. Das Einpflegen der ~200 Spiele durch Chris ist nicht eingerechnet. | Import, Edge Function und Admin-UI entfallen (Klärungen 24, 44). Das Label `size/xl` ändert nur Chris. |
| E3 | **Ausblenden über `games.hidden_at`, Zusammenführen über `games.merged_into_id`.** Die Lese-Policy von `games` bleibt unverändert. „Nicht mehr auffindbar“ (Krit. 4) wird über die neue View `catalog_games` umgesetzt, die ausgeblendete und zusammengeführte Einträge nicht enthält. Suche und Entdecken (KAT-01) lesen nur diese View. | Würde RLS ausgeblendete Spiele verbergen, liefen bestehende Sammlungs-, Favoriten- und Partie-Zeilen ins Leere (Joins liefern `null`, die `with check`-Klausel von `collection_items` schlägt beim Bearbeiten fehl). Ob ausgeblendete Einträge zusätzlich über die rohe API gesperrt werden sollen, ist Frage F2. |
| E4 | **Manuell gepflegte Felder als Liste `games.manual_fields text[]`**, gepflegt von einem Trigger: Jedes Feld eines Katalogspiels, das ein Mensch (Studio/SQL) setzt oder ändert, landet automatisch in der Liste. Nur ein späterer Import setzt in seiner Transaktion `set local shuffle.catalog_import = 'on'` und wird dann nicht markiert. Zuordnungen (Genre, Mechanik, Kategorie, Verlag) zählen als Pseudo-Felder (`genres`, `mechanics`, `categories`, `publishers`). | Der Admin muss in Studio nichts zusätzlich pflegen, die Kennzeichnung kann nicht vergessen werden (Krit. 4). Der Import (Krit. 1) überschreibt später genau die Felder nicht, die in der Liste stehen. Eine Liste statt einer Boolean-Spalte je Feld hält das Schema klein; ein Check begrenzt die erlaubten Schlüssel. Wie der Startbestand markiert wird, ist Frage F4. |
| E5 | **Quellen als eigene Tabelle `catalog_sources`** (Schlüssel, Name, Quellenangabe, Anzeige-Erlaubnis für Bilder und Texte je Quelle) und je Spiel `source_id`, `source_ref` (Kennung in der Quelle), `source_url`, `source_synced_at`. Die Migration legt die Quelle `bgg` mit `images_allowed = false`, `texts_allowed = false` an. | Klärung 7 und Krit. 2, 6: Felder und Erlaubnis je Quelle ab R1 vorhanden. `games.bgg_id` bleibt unverändert der Abgleichsschlüssel für SAM-08 (auch bei privaten Spielen); `source_*` beschreibt, woher die Katalogdaten stammen (Quellenangabe). Die Doppelung bei BGG ist bewusst; die Konsistenz (`source_ref = bgg_id::text` bei Quelle `bgg`) stellt der Import sicher (Spec des Imports). Eine Quelle je Spiel reicht, bis es eine zweite Quelle gibt. |
| E6 | **Die View `catalog_games` setzt die Anzeige-Erlaubnis schon jetzt serverseitig um:** `description` und `image_path` erscheinen nur, wenn das Feld manuell gepflegt ist, das Spiel keine Quelle hat oder die Quelle die Anzeige erlaubt. | Vorbereitung von Krit. 6 ohne Mehraufwand im Client. Im Startbestand hat kein Spiel eine Quelle, die Regel wirkt also erst mit dem Import. |
| E7 | **Verlage (Klärung 4) entstehen in dieser Spec** (`publishers`, `game_publishers`), nicht erst in KAT-01. Alternative Titel (Klärung 3, #3) und Basisspiel-Verweis (Klärung 5, #12) bleiben in ihren Stories; das Pflegeformat des Startbestands hat dafür aber schon Spalten (siehe 4.3), damit Chris die ~200 Spiele nicht zweimal anfassen muss. | Krit. 10 verlangt den Verlag im Startbestand. Alternative Titel und Erweiterungen sind für den Startbestand nicht Pflicht und werden in #3 bzw. #12 modelliert und getestet. |
| E8 | **Sprache des Kurztexts als Spalte `games.description_locale`** (`de`/`en`, optional), schon in 2a. | Der Startbestand füllt sie; KAT-02 Krit. 7 (Klärung 48) zeigt damit den Sprachhinweis. Die Sprache des Titels gehört zu den alternativen Titeln (#3). |
| E9 | **Startbestand ist keine Migration und nicht Teil von `seed.sql`**, sondern eine versionierte, idempotente SQL-Datei `supabase/catalog/startbestand.sql` mit festen IDs. Lokal und in CI lädt sie `supabase db reset` über `[db.seed] sql_paths`; auf Staging und Produktion spielt Chris sie nach den Migrationen einmalig per Studio-SQL-Editor oder `psql` ein (Runbook). | Migrationen sind unveränderlich und nur additiv, Katalogdaten werden bis zum Start aber laufend korrigiert. `seed.sql` ist ausdrücklich nur für die lokale Entwicklung. Wie die Datei entsteht (Pflegeformat), ist Frage F6. |
| E10 | **In R1 gibt es kein App-Konto mit Admin-Rolle.** Chris pflegt ausschließlich über Studio bzw. `psql` als Datenbankrolle `postgres` (umgeht RLS). Die bestehenden `is_admin()`-Policies (JWT `app_metadata.role = 'admin'`) bleiben für QUE-08 (R4) stehen. Die neuen Admin-Funktionen sind für `anon` und `authenticated` **nicht** ausführbar, auch nicht mit Admin-Claim. | Klärung 44: Admin-Rolle nur als Datenbankrolle. Kein Admin-JWT heißt weniger Angriffsfläche. Krit. 9 wird dadurch gegen die Rollen `anon` und `authenticated` getestet (mit und ohne gefälschten Claim). |
| E11 | **Zusammenführen und Meldungsergebnis laufen über SQL-Funktionen**, nicht über Hand-SQL im Studio: `admin_merge_games(source, target)` und `admin_resolve_report(report, status, target)`, beide nutzen die interne Funktion `repoint_game_references(from, to)`. | Zusammenführen ist kein einzelnes UPDATE: Varianten mit zusammengesetzten Fremdschlüsseln, `unique (owner_id, game_id)` in `collection_items`, `unique (profile_id, game_id)` in `favorite_games` und künftig ein Wertungsbogen je Spiel (Klärung 39). Hand-SQL wäre fehleranfällig. Freigabe einer Meldung (KAT-04 Krit. 4) braucht dasselbe Umhängen, das ist der zweite Anwendungsfall. |
| E12 | **Die Meldungstabelle `game_reports` entsteht in 2c (diese Spec), vollständig mit den Spalten, die KAT-04 und SAM-08 brauchen** (Herkunft Nutzer/Import, BGG-Kennung, vorläufiger Eintrag). Anlegen durch Nutzer (Insert-Policy, Tageslimit 10, Ähnlichkeitsprüfung) liefert #13. | #13 hängt in Forgejo von #2 ab. Läge die Tabelle in #13, wäre 2c von #13 blockiert und #2 nicht abschließbar. Die Spalten ergeben sich vollständig aus den Klärungen 6, 26, 27, N12 und N12a. |
| E13 | **Keine neuen Pakete, keine Edge Function, keine Supabase-Cloud-Funktionen.** Alles ist reines PostgreSQL 17 (Trigger, Views mit `security_invoker`, Spaltenrechte, Custom-GUC), PostgREST und Studio, die es im Self-Hosting gibt (ADR-0002). `[db.seed] sql_paths` ist eine Funktion der lokalen CLI. | Vorgabe aus CLAUDE.md und ADR-0002. |

## 2. Akzeptanzkriterien

Übernommen aus Issue #2 / `20-r1-akzeptanzkriterien.md` § KAT-05. Referenz in Tests und PRs: „KAT-05 Kriterium n“.

1. *Zurückgestellt bis zur Lizenz (Klärung 24):* Gegeben eine zugelassene Quelle, wenn der Import läuft, dann werden neue Spiele angelegt und geänderte aktualisiert, ohne manuell gepflegte Felder zu überschreiben.
2. Gegeben ein Katalogeintrag, dann hat er eine eigene Shuffle-ID (F2). *Zurückgestellt bis zur Lizenz (Klärung 24):* optional die Kennung der Quelle (zum Beispiel BGG) samt Quellenangabe; die Felder dafür sind ab R1 im Datenmodell vorhanden (Klärung 7).
3. *Zurückgestellt bis zur Lizenz (Klärung 24):* Gegeben die Quelle ist nicht erreichbar oder liefert fehlerhafte Daten, dann bleibt der Katalog unverändert, der Fehler wird protokolliert und die App funktioniert normal weiter.
4. Gegeben der Admin bearbeitet, blendet aus oder führt Einträge zusammen (in R1 über Supabase Studio/SQL), dann sind ausgeblendete Einträge in der App nicht mehr auffindbar, und manuell gepflegte Felder sind als solche gekennzeichnet, damit ein späterer Import sie nicht überschreibt (Klärungen 7, 44).
5. Gegeben Meldungen aus KAT-04, dann kann der Admin sie über Supabase Studio/SQL freigeben, mit einem Eintrag zusammenführen oder ablehnen; Status (offen, freigegeben, abgelehnt, zusammengeführt) und gegebenenfalls der Zieleintrag werden gespeichert (Klärungen 6, 44).
6. *Zurückgestellt bis zur Lizenz (Klärung 24):* Gegeben Cover und Texte einer Quelle, dann werden sie nur angezeigt, wenn deren Nutzungsbedingungen es erlauben; die Erlaubnis ist je Quelle vermerkt. Das Feld für die Erlaubnis je Quelle ist ab R1 im Datenmodell vorhanden (Klärung 7).
7. Gegeben R1 geht live, dann enthält der Katalog einen manuell gepflegten Startbestand von etwa 200 Spielen, den der Admin (Chris) per Supabase Studio bzw. Seed einpflegt (Klärung 24, N11).
8. Gegeben die Admin-Pflege über Supabase Studio/SQL, dann ist der Ablauf für Bearbeiten, Ausblenden, Zusammenführen und das Bearbeiten von Meldungen im Repo dokumentiert (Klärung 44).
9. Gegeben ein Nutzer ohne Admin-Rolle, wenn er über die App oder direkt über die Schnittstelle Katalogeinträge oder fremde Meldungen ändern will, dann wird der Zugriff verweigert; die Admin-Rolle existiert in R1 nur als Datenbankrolle (Klärung 44).
10. Gegeben ein Spiel aus dem Startbestand, dann enthält es nur Fakten (Titel, Verlag, Erscheinungsjahr, Spielerzahl, Spieldauer, Mindestalter, Genre, Mechanik); fremde Cover und fremde Beschreibungstexte werden nicht übernommen, stattdessen zeigt die App ein Platzhalter-Cover und einen eigenen Kurztext (N11).

**Zuordnung zu den PRs**

| PR | Etappe | Kriterien | Bei zurückgestellten Kriterien: nur Datenmodell |
|---|---|---|---|
| 2a | R1.1 | 2, 7 (Lieferweg und Werkzeug; der Datenbestand selbst kommt von Chris), 9 (Katalog), 10 | 1 (Kennzeichnung `manual_fields`), 2 (Quellenteil), 6 (Erlaubnis je Quelle) |
| 2b | R1.2 | 4, 8 (Bearbeiten, Ausblenden, Zusammenführen) | – |
| 2c | R1.2 | 5, 8 (Meldungen), 9 (fremde Meldungen) | – |

Krit. 3 hat keinen Anteil am Datenmodell und wird vollständig mit dem Import spezifiziert.

**Relevante Querschnittskriterien**

- **Sicherheit der Daten Kriterium 2:** Katalog ohne Anmeldung lesbar (`catalog_games`, `catalog_sources`, `publishers` für `anon`), nie durch Nutzer veränderbar (O6).
- **Sicherheit der Daten Kriterium 1 und 3:** `game_reports` enthält Nutzerdaten; nur der Meldende liest seine Meldungen, pgTAP prüft fremden Zugriff.
- **Datenschutz (QUE-04):** Meldungen werden beim Konto-Löschen hart gelöscht (`on delete cascade`, Klärung 10). Der Startbestand enthält keine personenbezogenen Daten.
- **Sprachen (QUE-05) Kriterium 2:** Die Semantics-Beschriftung des Platzhalter-Covers kommt aus ARB (de/en). Begriffe (Genre, Mechanik) haben `name_de`/`name_en`.
- **Barrierefreiheit (QUE-06) Kriterien 1, 2:** Platzhalter-Cover mit sinnvoller Beschriftung und Kontrast AA (Kontrast der Grafik zum Hintergrund mindestens 3:1).
- **Plattformen Kriterium 1:** Das Platzhalter-Cover ist ein reines Flutter-Widget ohne Plattformcode.

## 3. Datenmodell

### 3.1 Bestand gegen die Kriterien

| Bedarf | Bestand | Abgleich | Handlung |
|---|---|---|---|
| Eigene Shuffle-ID (Krit. 2) | `games.id uuid primary key default gen_random_uuid()`, `set_updated_at` schützt `id` | passt | keine; pgTAP-Test als Nachweis |
| Kennung + Quellenangabe (Krit. 2, Quellenteil) | nur `games.bgg_id` | Quellenangabe fehlt | `catalog_sources`, `games.source_*` (3.2) |
| Ausblenden (Krit. 4) | – | fehlt | `games.hidden_at`, View `catalog_games` |
| Zusammenführen (Krit. 4) | – | fehlt | `games.merged_into_id`, Funktion `admin_merge_games` (2b) |
| Manuell gepflegte Felder (Krit. 1, 4) | – | fehlt | `games.manual_fields`, Trigger |
| Erlaubnis je Quelle (Krit. 6) | – | fehlt | `catalog_sources.images_allowed`, `texts_allowed` |
| Verlag (Krit. 10) | – | fehlt (Klärung 4) | `publishers`, `game_publishers` |
| Genre, Mechanik (Krit. 10) | `genres`, `mechanics`, Zuordnungstabellen | passt | Vokabular für den Startbestand festlegen (F8) |
| Kurztext + Sprache (Krit. 10, KAT-02 Krit. 7) | `games.description` (≤ 5000), keine Sprache | Sprache fehlt | `games.description_locale` |
| Kein fremdes Cover (Krit. 10) | `games.image_path` nullable | passt | Startbestand setzt kein `image_path`; Platzhalter in der App |
| Meldungen (Krit. 5) | – | fehlt (Klärung 6) | `game_reports` (2c) |
| Schreibrechte (Krit. 9) | Katalog nur `is_admin()`; Nutzer dürfen eigene private Spiele vollständig ändern (Tabellenrecht `update` für `authenticated`) | Nutzer könnten an eigenen privaten Spielen `hidden_at`, `manual_fields`, `source_*`, `merged_into_id` setzen | Spaltenrechte statt Tabellenrechte für `insert`/`update` auf `games` (3.2) |

### 3.2 Migration 2a `supabase/migrations/<ts>_catalog_foundation.sql` (R1.1)

Nur additiv. Bestehende Dateien bleiben unverändert; die Änderung der Rechte auf `games` erfolgt über `revoke`/`grant` in der neuen Datei.

**Neue Tabelle `catalog_sources`**

| Spalte | Typ | Hinweis |
|---|---|---|
| `id` | uuid | PK, `gen_random_uuid()` |
| `key` | text | not null, unique, `^[a-z0-9_]{2,30}$` (z. B. `bgg`) |
| `name` | text | not null, 1–100 Zeichen (z. B. „BoardGameGeek“) |
| `attribution_text` | text | nullable, ≤ 200 (z. B. „Powered by BGG“, KAT-02 Krit. 5) |
| `attribution_url` | text | nullable, ≤ 500, Check `^https://` |
| `images_allowed` | boolean | not null, default `false` (Krit. 6) |
| `texts_allowed` | boolean | not null, default `false` (Krit. 6) |
| `terms_url` | text | nullable, ≤ 500, Nutzungsbedingungen der Quelle |
| `terms_checked_at` | date | nullable, wann die Erlaubnis zuletzt geprüft wurde |
| `created_at`, `updated_at` | timestamptz | Standard, Trigger `set_updated_at` |

Die Migration fügt eine Zeile ein: `key = 'bgg'`, `name = 'BoardGameGeek'`, `attribution_text = 'Powered by BGG'`, `attribution_url = 'https://boardgamegeek.com'`, beide Erlaubnisse `false`. Das ist Referenzdaten-Pflege, keine Katalogdaten.

**Neue Spalten in `games`**

| Spalte | Typ | Hinweis |
|---|---|---|
| `description_locale` | text | nullable, Check `in ('de','en')` (E8) |
| `hidden_at` | timestamptz | nullable; gesetzt = ausgeblendet (Krit. 4) |
| `merged_into_id` | uuid | nullable, FK → `games (id)`; gesetzt = in den Zieleintrag zusammengeführt. Check `merged_into_id <> id`; Check `merged_into_id is null or hidden_at is not null` |
| `manual_fields` | text[] | not null, default `'{}'`. Check `manual_fields <@ array['title','description','description_locale','year','min_players','max_players','min_minutes','max_minutes','min_age','image_path','genres','mechanics','categories','publishers']`. Neue Schlüssel (z. B. alternative Titel in #3, Basisspiel in #12) ergänzt die jeweilige Story per neuer Migration (Check ersetzen). |
| `source_id` | uuid | nullable, FK → `catalog_sources (id)` |
| `source_ref` | text | nullable, 1–100, Kennung des Spiels in der Quelle |
| `source_url` | text | nullable, ≤ 500, Check `^https://` |
| `source_synced_at` | timestamptz | nullable, letzter erfolgreicher Abgleich (Import) |

Weitere Checks: `(source_id is null) = (source_ref is null)`; `source_url` und `source_synced_at` nur mit `source_id`.

Indizes: `unique (source_id, source_ref) where visibility = 'catalog' and source_id is not null`; `games_merged_into_id_idx` auf `merged_into_id`; `games_catalog_listed_idx` auf `(lower(title)) where visibility = 'catalog' and hidden_at is null and merged_into_id is null` (Suche baut KAT-01 darauf aus).

**Neue Tabellen `publishers` und `game_publishers`** (Klärung 4, E7)

| Tabelle | Spalte | Typ | Hinweis |
|---|---|---|---|
| `publishers` | `name` | text | not null, 1–200; eindeutig über `unique index on lower(name)` |
| `game_publishers` | `game_id` | uuid | not null, FK → `games` `on delete cascade` |
| `game_publishers` | `publisher_id` | uuid | not null, FK → `publishers` `on delete cascade`; `unique (game_id, publisher_id)`; Index auf `publisher_id` |

Beide mit `id`, `created_at`, `updated_at` und Trigger `set_updated_at`. Ein Spiel kann mehrere Verlage haben (KAT-01 Krit. 3).

**Trigger `games_mark_manual_fields`** (E4)

- `before insert or update on public.games`, nur wenn `new.visibility = 'catalog'`.
- Wenn `coalesce(current_setting('shuffle.catalog_import', true), '') <> 'on'`:
  - bei INSERT: jedes Feld aus der Schlüsselliste, das nicht `null` ist, wird ergänzt (siehe F4, Option A; bei Option B nur `description` und `image_path`),
  - bei UPDATE: jedes Feld aus der Schlüsselliste, dessen Wert sich ändert (`is distinct from`), wird ergänzt.
- Eine Änderung nur an `manual_fields` selbst wird nicht verändert, damit der Admin eine Markierung bewusst entfernen kann.
- Sortiert und ohne Duplikate speichern (`array(select distinct unnest(...) order by 1)`), damit Tests stabil vergleichen können.

**Trigger `game_links_mark_manual`** auf `game_genres`, `game_mechanics`, `game_categories`, `game_publishers`: `after insert or delete`, wenn das Spiel ein Katalogspiel ist und kein Import läuft, ergänzt er `genres` / `mechanics` / `categories` / `publishers` in `manual_fields` des Spiels. Funktion `security invoker`, `search_path = ''`.

Ein Nutzer kann `shuffle.catalog_import` nicht setzen: PostgREST stellt `set_config` nicht bereit, und Katalogspiele kann er ohnehin nicht schreiben.

**View `catalog_games`** (`with (security_invoker = true)`, E3, E6)

- Zeilen: `games` mit `visibility = 'catalog' and hidden_at is null and merged_into_id is null`.
- Spalten: `id`, `title`, `year`, `min_players`, `max_players`, `min_minutes`, `max_minutes`, `min_age`, `bgg_id`, `description_locale`, `created_at`, `updated_at`, dazu
  - `description` = `case when g.source_id is null or 'description' = any(g.manual_fields) or s.texts_allowed then g.description end`,
  - `image_path` = gleiche Regel mit `'image_path'` und `s.images_allowed`,
  - `source_key`, `source_name`, `source_attribution_text`, `source_attribution_url`, `source_url` aus `catalog_sources` (Left Join).
- `grant select on public.catalog_games to anon, authenticated`. Weil `security_invoker` gesetzt ist, gelten die RLS-Regeln von `games` und `catalog_sources` für den Aufrufer.
- KAT-01 und KAT-02 lesen Katalogdaten nur über diese View (bzw. über eine RPC, die darauf aufbaut). Der Direktzugriff auf `games` bleibt für eigene private Spiele und für bestehende Verweise (Sammlung, Partien) nötig.

**Rechte auf `games` neu schneiden** (Krit. 9)

```
revoke insert, update on public.games from authenticated;
grant insert (owner_id, title, description, description_locale, year, min_players, max_players,
              min_minutes, max_minutes, min_age, image_path, bgg_id, visibility)
  on public.games to authenticated;
grant update (title, description, description_locale, year, min_players, max_players,
              min_minutes, max_minutes, min_age, image_path, bgg_id, visibility)
  on public.games to authenticated;
```

`delete` und `select` bleiben wie bisher. Die Policies regeln weiterhin, welche Zeilen (eigene private Spiele bzw. Admin). Damit kann kein Nutzer `hidden_at`, `merged_into_id`, `manual_fields` oder `source_*` setzen, auch nicht an eigenen privaten Spielen (Fehler 42501). Hinweis für QUE-08 (R4): Ein Admin über die API wäre davon ebenfalls betroffen; die Admin-UI nutzt dann RPCs.

**RLS in Klartext (2a)**

| Tabelle/Objekt | Lesen | Schreiben |
|---|---|---|
| `catalog_sources` | alle, auch ohne Anmeldung | nur Admin (`is_admin()`-Policy, für R4); in R1 nur Studio/`postgres` |
| `publishers` | alle, auch ohne Anmeldung | nur Admin |
| `game_publishers` | wie das Spiel (wer das Spiel sehen darf) | Admin oder Ersteller des privaten Spiels (gleiches Muster wie `game_genres`) |
| `games` | unverändert: Katalog für alle, private Spiele nur der Ersteller; ausgeblendete und zusammengeführte Katalogspiele bleiben per ID lesbar (E3, F2) | unverändert per Policy; zusätzlich Spaltenrechte |
| `catalog_games` | alle, auch ohne Anmeldung, nur sichtbare Katalogspiele | nicht schreibbar (View ohne Insert/Update-Rechte) |

### 3.3 Migration 2b `supabase/migrations/<ts>_catalog_merge.sql` (R1.2)

**Interne Funktion `public.repoint_game_references(p_from uuid, p_to uuid)`**

`language plpgsql`, `security invoker`, `search_path = ''`; `revoke execute ... from public, anon, authenticated`. Hängt alle Verweise von `p_from` auf `p_to` um, in einer Transaktion:

1. **Varianten:** Für jede Variante von `p_from` wird eine Kopie (`name`, `year`, `language`, `bgg_id`) an `p_to` angelegt; eine Zuordnungstabelle alt → neu (temporär) entsteht. Grund: Die zusammengesetzten Fremdschlüssel `(variant_id, game_id)` in `collection_items` und `plays` erlauben kein direktes Umhängen von `game_variants.game_id`. Ein UPDATE, das `game_id` und `variant_id` in derselben Zeile gemeinsam setzt, ist zulässig.
2. **`collection_items`:** Hat derselbe Nutzer schon einen Eintrag zu `p_to`, gilt die Kollisionsregel aus F1. Sonst `game_id := p_to`, `variant_id := neu`.
3. **`favorite_games`:** Hat der Nutzer `p_to` schon als Favorit, wird die Zeile zu `p_from` gelöscht (die Lücke in `position` ist zulässig). Sonst `game_id := p_to`.
4. **`plays`:** `game_id := p_to`, `variant_id := neu`.
5. **`score_sheets`:** `game_id := p_to`. Sobald PAR-04 (#18) „ein Bogen je Spiel und Nutzer“ (Klärung 39) erzwingt, muss #18 hier eine Kollisionsregel ergänzen (Hinweis in 9.4).
6. Alte Varianten von `p_from` löschen (sie sind jetzt unreferenziert).
7. Zuordnungen (Genre, Mechanik, Kategorie, Verlag) von `p_from` bleiben unverändert am ausgeblendeten Quell-Eintrag; der Zieleintrag behält seine eigenen.

Rückgabe: `jsonb` mit Zählern je Tabelle (z. B. `{"collection_items": 3, "collection_conflicts": 1, "plays": 7, …}`), damit der Admin im Studio sieht, was passiert ist.

**Funktion `public.admin_merge_games(p_source uuid, p_target uuid) returns jsonb`**

`security invoker`, `search_path = ''`; `revoke execute ... from public, anon, authenticated` (E10). Prüft zusätzlich zu Beginn `current_user in ('postgres', 'supabase_admin') or public.is_admin()` (Schutz in der Tiefe).

| Prüfung | Fehler (`raise exception … using errcode = 'P0001'`) |
|---|---|
| `p_source = p_target` | `merge_same_game` |
| Quelle oder Ziel existiert nicht | `merge_game_not_found` |
| Quelle oder Ziel ist kein Katalogspiel | `merge_not_catalog` |
| Ziel ist ausgeblendet oder selbst zusammengeführt | `merge_target_not_listed` |
| Quelle ist bereits zusammengeführt | `merge_source_already_merged` |

Ablauf: `repoint_game_references(p_source, p_target)`; `p_source.merged_into_id := p_target`, `hidden_at := coalesce(hidden_at, now())`; Ketten glätten (`update games set merged_into_id = p_target where merged_into_id = p_source`). Ab 2c zusätzlich: `game_reports.target_game_id` von `p_source` auf `p_target`. Die Quelle wird **nicht** gelöscht: Ihre Shuffle-ID bleibt gültig, die App kann alte Links (Web-URLs, Deep Links) auf den Zieleintrag weiterleiten (KAT-02).

**Ausblenden** braucht keine Funktion: `update public.games set hidden_at = now() where id = …` (Wieder einblenden: `hidden_at = null`). Das Runbook (4.4) enthält die Anweisungen.

### 3.4 Migration 2c `supabase/migrations/<ts>_game_reports.sql` (R1.2)

**Neue Tabelle `game_reports`** (Klärungen 6, 10, 26, 27, N12, N12a; E12)

| Spalte | Typ | Hinweis |
|---|---|---|
| `id` | uuid | PK |
| `owner_id` | uuid | not null, FK → `profiles` `on delete cascade` (meldender Nutzer; Klärung 10: hart löschen) |
| `origin` | text | not null, default `'user'`, Check `in ('user','import')` (N12) |
| `title` | text | not null, 1–200 (KAT-04 Krit. 1) |
| `publisher_name` | text | nullable, ≤ 200 (Freitext des Nutzers) |
| `year` | smallint | nullable, 1800–2100 |
| `link` | text | nullable, ≤ 500, Check `^https?://` |
| `bgg_id` | integer | nullable (N12, Deduplizierung) |
| `provisional_game_id` | uuid | nullable, FK → `games` `on delete set null` (vorläufiger privater Eintrag, KAT-04 Krit. 3) |
| `status` | text | not null, default `'open'`, Check `in ('open','approved','rejected','merged')` |
| `target_game_id` | uuid | nullable, FK → `games` |
| `resolved_at` | timestamptz | nullable |
| `created_at`, `updated_at` | timestamptz | Standard, Trigger `set_updated_at` |

Checks: `(status = 'open') = (resolved_at is null)`; `status <> 'open' or target_game_id is null`; `status not in ('approved','merged') or target_game_id is not null`.

Indizes: `(owner_id, created_at)` für das Tageslimit (#13); `unique (owner_id, bgg_id) where origin = 'import' and status = 'open' and bgg_id is not null` (N12a: höchstens eine offene Import-Meldung je Nutzer und BGG-Spiel); `(created_at) where status = 'open'` für die Admin-Liste.

**RLS in Klartext**

- `enable row level security`; `revoke all … from anon, authenticated`; `grant select on game_reports to authenticated`.
- Lesen: Der Meldende sieht seine eigenen Meldungen (für den Ergebnishinweis, KAT-04 Krit. 4–6); Admin-Policy `is_admin()` für R4. `anon` sieht nichts.
- Anlegen: **in 2c nicht möglich** (kein Insert-Recht). #13 ergänzt Insert-Recht, Insert-Policy (`owner_id = auth.uid()`, `origin = 'user'`, `status = 'open'`, `target_game_id is null`, `provisional_game_id` nur ein eigenes privates Spiel) und den Limit-Trigger (10 je Nutzer und Tag, nur `origin = 'user'`).
- Ändern, Löschen: kein Recht für `anon` und `authenticated` (Krit. 9). Der Admin ändert in R1 nur über `admin_resolve_report` im Studio.

**Funktion `public.admin_resolve_report(p_report uuid, p_status text, p_target uuid default null) returns jsonb`**

Rechte wie `admin_merge_games`.

| Prüfung | Fehler |
|---|---|
| Meldung existiert nicht | `report_not_found` |
| Meldung ist nicht `open` | `report_not_open` |
| `p_status` nicht in `approved`, `merged`, `rejected` | `report_status_invalid` |
| `approved`/`merged` ohne `p_target` | `report_target_required` |
| `p_target` ist kein sichtbares Katalogspiel | `report_target_not_listed` |

Ablauf: `status`, `target_game_id`, `resolved_at = now()` setzen. Hat die Meldung einen vorläufigen Eintrag, dann

- bei `approved`: `repoint_game_references(provisional, target)`; der vorläufige Eintrag bekommt `merged_into_id = target`, `hidden_at = now()` (KAT-04 Krit. 4: der Katalogeintrag ersetzt ihn, eigene Angaben bleiben erhalten),
- bei `merged` und bei `rejected` mit Ziel: Verhalten nach F3,
- bei `rejected` ohne Ziel: keine Änderung am vorläufigen Eintrag (KAT-04 Krit. 6).

„Freigeben“ heißt in R1: Der Admin legt im Studio zuerst den Katalogeintrag an (bzw. wählt ihn aus) und ruft dann die Funktion mit `approved` auf. Unterschied zu `merged`: `approved` = der Eintrag ist wegen dieser Meldung neu entstanden, `merged` = er war schon vorhanden.

Die Migration ersetzt `admin_merge_games` per `create or replace`, sodass beim Zusammenführen auch `game_reports.target_game_id` umgehängt wird.

### 3.5 Doku zum Datenmodell

`docs/datenmodell-r1.md` wird in jedem der drei PRs nachgezogen (neue Tabellen, Spalten, View, Funktionen, Regeln). Dabei wird der doppelte Abschnitt „Tabellenstruktur (aus den Migrationen)“ (steht zweimal im Dokument) zusammengeführt. `supabase/README.md` bekommt einen Abschnitt „Katalog (KAT-05)“.

## 4. Backend

### 4.1 Überblick

| Objekt | Art | PR | Aufrufbar von |
|---|---|---|---|
| `catalog_sources`, `publishers`, `game_publishers`, neue Spalten `games` | Tabellen | 2a | Lesen: alle; Schreiben: Studio (`postgres`) |
| `catalog_games` | View | 2a | `anon`, `authenticated` (lesen) |
| `games_mark_manual_fields`, `game_links_mark_manual` | Trigger | 2a | automatisch |
| `repoint_game_references` | interne Funktion | 2b | nur `postgres` |
| `admin_merge_games` | Funktion | 2b | nur `postgres` (Studio/`psql`) |
| `game_reports` | Tabelle | 2c | Lesen: eigene; Schreiben: Studio |
| `admin_resolve_report` | Funktion | 2c | nur `postgres` |

Keine Edge Functions, keine RPCs für die App in dieser Spec.

### 4.2 Admin-Zugang (self-hosted)

- **Studio läuft als Datenbankrolle `postgres`** und umgeht RLS. Die `is_admin()`-Policies sind deshalb nicht der Studio-Pfad; Schutz bietet allein der Zugang zu Studio.
- **Studio darf nicht öffentlich erreichbar sein.** Im Self-Hosting gibt es in Studio keine Benutzerverwaltung, nur die Basic-Auth des Gateways (`DASHBOARD_USERNAME`/`DASHBOARD_PASSWORD`). Vorgabe für devops (D1): Studio und der Postgres-Port sind nur über SSH-Tunnel oder VPN erreichbar; Basic-Auth bleibt als zweite Schicht mit starkem Passwort. Gilt ebenso für Staging.
- **`app_metadata.role = 'admin'`** wird in R1 niemandem gesetzt (E10). Falls doch nötig (R4), geht das nur serverseitig: `update auth.users set raw_app_meta_data = raw_app_meta_data || '{"role":"admin"}' where id = …` als `postgres`; der Nutzer muss sich danach neu anmelden. Das Runbook dokumentiert das als „nicht in R1“.

### 4.3 Startbestand (Krit. 7, 10; E9)

**Lieferweg**

| Umgebung | Weg |
|---|---|
| lokal, CI | `supabase/config.toml`: `[db.seed] sql_paths = ["./seed.sql", "./catalog/vocabulary.sql", "./catalog/startbestand.sql"]`; `supabase db reset` spielt alles ein |
| Staging, Produktion | Nach den Migrationen spielt Chris `vocabulary.sql` und `startbestand.sql` per Studio-SQL-Editor oder `psql` ein (Runbook § „Startbestand einspielen“). Die Dateien sind idempotent und dürfen wiederholt laufen. |

**Dateien**

- `supabase/catalog/vocabulary.sql`: Genres und Mechaniken (de/en) mit festen UUIDs, `insert … on conflict (id) do update set name_de = excluded.name_de, name_en = excluded.name_en`. Das Vokabular legt Chris fest (F8). Die Begriffe aus `seed.sql` sind nur Beispieldaten für die Entwicklung; `seed.sql` wird so angepasst, dass es keine Begriffe mehr anlegt, die mit dem Vokabular kollidieren (Unique auf `name_de`/`name_en`).
- `supabase/catalog/startbestand.sql`: je Spiel ein Eintrag in `games` (`visibility = 'catalog'`, `image_path = null`, `source_id = null`) mit fester UUID sowie Zuordnungen zu Verlagen, Genres, Mechaniken. Upsert auf `id` (`on conflict (id) do update`). Am Anfang `begin;`, am Ende `commit;`.
- Wie die Datei entsteht, entscheidet F6. Empfohlen ist eine Tabelle `supabase/catalog/startbestand.csv`, die Chris pflegt, und ein kleines Skript `supabase/catalog/build_startbestand.ts` (Deno, ohne Fremdpakete außer der Standardbibliothek), das CSV prüft und daraus `startbestand.sql` erzeugt. Die UUID eines Spiels ergibt sich deterministisch (UUID v5) aus einer Spalte `key` (z. B. `azul`), damit Korrekturen dieselbe Zeile treffen.

**CSV-Format (bei F6 Option A)**

| Spalte | Pflicht | Inhalt |
|---|---|---|
| `key` | ja | stabiler Schlüssel, `^[a-z0-9-]{2,60}$`, eindeutig |
| `title` | ja | Haupttitel |
| `publishers` | ja | ein oder mehrere Verlage, getrennt durch `;` |
| `year` | ja | Erscheinungsjahr |
| `min_players`, `max_players` | ja | Spielerzahl |
| `min_minutes`, `max_minutes` | ja | Spieldauer |
| `min_age` | ja | Mindestalter |
| `genres` | ja | ein oder mehrere Genres aus dem Vokabular (`name_de`), getrennt durch `;` |
| `mechanics` | ja | eine oder mehrere Mechaniken aus dem Vokabular, getrennt durch `;` |
| `description` | nach F5 | eigener Kurztext |
| `description_locale` | wenn `description` | `de` oder `en` |
| `alt_titles` | nein | reserviert für KAT-01 (#3), Format `de:Titel;en:Title`; das Skript ignoriert die Spalte, bis #3 die Tabelle hat |
| `base_game_key` | nein | reserviert für KAT-03 (#12), `key` des Basisspiels; wird ignoriert, bis #12 die Spalte hat |

Das Skript bricht mit Zeilennummer und Grund ab bei: fehlender Pflichtangabe, unbekanntem Genre/Mechanik, doppeltem `key`, `max < min`, Werten außerhalb der DB-Checks, Kurztext ohne Sprache. Es gibt **keine** Spalte für ein Cover und keine Quellen-Spalten (Krit. 10). So kann ein unvollständiges Spiel gar nicht erst in die SQL-Datei gelangen; CI bleibt grün, auch während Chris noch einpflegt.

**Prüfabfrage vor dem Go-live** (`supabase/catalog/checks.sql`, Teil der Release-Checkliste): Anzahl sichtbarer Katalogspiele (Ziel nach F8), Spiele ohne Verlag, Genre, Mechanik oder Kurztext, Katalogspiele mit `image_path` oder `source_id` (müssen 0 sein, Krit. 10).

**Daten werden nicht von Agents erfunden.** Agents liefern Werkzeug, Format, Prüfungen und höchstens offensichtlich fiktive Testzeilen in Fixtures (z. B. „Testspiel A“). Den Inhalt liefert Chris (Krit. 7).

### 4.4 Runbook `docs/katalog-pflege.md` (Krit. 8)

Ein Dokument, wachsend über die PRs:

| Abschnitt | PR | Inhalt |
|---|---|---|
| Zugang | 2a | Studio über SSH-Tunnel/VPN, Rolle `postgres`, „immer in einer Transaktion arbeiten“ (`begin; … commit;`), vor größeren Änderungen Backup-Stand prüfen |
| Startbestand einspielen und korrigieren | 2a | Reihenfolge Migrationen → `vocabulary.sql` → `startbestand.sql`; Prüfabfrage `checks.sql`; Korrekturen vor dem Go-live in der CSV, danach im Studio (siehe F6) |
| Spiel anlegen und bearbeiten | 2a | Tabelleneditor oder SQL; Zuordnungen zu Verlag, Genre, Mechanik; Hinweis: jede Änderung wird automatisch in `manual_fields` vermerkt; Markierung bewusst entfernen nur per SQL |
| Ausblenden und wieder einblenden | 2b | `hidden_at` setzen bzw. leeren; Wirkung: nicht mehr in Suche/Entdecken, bestehende Sammlungen und Partien bleiben |
| Zusammenführen | 2b | Duplikat finden (Abfrage nach normalisiertem Titel + Jahr), `select public.admin_merge_games('<quelle>', '<ziel>');`, Ergebnis-JSON lesen, Fehlertexte und ihre Bedeutung |
| Meldungen bearbeiten | 2c | offene Meldungen abfragen (älteste zuerst), Ähnliche im Katalog suchen, Entscheidung: freigeben (erst Katalogeintrag anlegen, dann `admin_resolve_report(…, 'approved', '<ziel>')`), zusammenführen (`'merged'`), ablehnen mit oder ohne Verweis (`'rejected'`); Fehlertexte |
| Admin-Rolle in der App | 2a | in R1 nicht vergeben (E10), Vorgehen für R4 |

Jeder SQL-Baustein im Runbook wird in pgTAP mindestens einmal genau so ausgeführt (siehe 7.1), damit das Runbook nicht veraltet.

## 5. Frontend

KAT-05 hat in R1 keine eigenen Screens (keine Admin-UI, Klärung 44). Die App-Anteile der Kriterien entstehen in den Stories, die Katalogdaten anzeigen:

| Kriterium | App-Anteil | Wo umgesetzt |
|---|---|---|
| Krit. 4 („nicht auffindbar“) | Suche und Entdecken lesen nur `catalog_games` | KAT-01 (#3), Spec #3 |
| Krit. 4 (zusammengeführt) | Detailseite eines zusammengeführten Eintrags leitet auf den Zieleintrag weiter; ausgeblendete Einträge nach F2 | KAT-02 (#4) |
| Krit. 10 (Platzhalter-Cover) | Platzhalter, wenn `image_path` leer | **Widget in 2a**, Einsatz in #3/#4 |
| Krit. 10 (eigener Kurztext) | Anzeige von `description`, Sprachhinweis über `description_locale` | KAT-02 (#4) |
| Krit. 5 (Ergebnis einer Meldung) | Hinweis am vorläufigen Eintrag | KAT-04 (#13) |

**In 2a:** Widget `GameCover` in `app/lib/core/widgets/game_cover.dart` (wird von Katalog, Sammlung, Dashboard und Partien genutzt, deshalb `core/`).

- Eingaben: `imageUrl` (nullable; die Auflösung des Storage-Pfads liefert später die Dateizugriffsschicht), `title` (für die Beschriftung), `size` (klein für Listen, groß für die Detailseite).
- Zustände: kein Bild → Platzhalter; Bild lädt → Platzhalter mit dezenter Ladeanzeige; Fehler beim Laden → Platzhalter (kein Fehlerzustand, ein fehlendes Cover ist kein Fehler).
- Platzhalter: eigene, mit Flutter gezeichnete Grafik (Fläche in Theme-Farbe, neutrales Symbol), keine Bilddatei von Dritten, kein neues Paket. Variante nach F9.
- Semantics: Bild ausgeblendet aus dem Semantics-Baum, wenn der Titel daneben steht (`excludeSemantics`-Variante); sonst Beschriftung aus ARB `gameCoverPlaceholderLabel` („Kein Cover für {title}“ / „No cover for {title}“).
- Keine Geschäftslogik, keine Domänenmodelle in 2a. Das Domänenmodell `CatalogGame` (freezed) und das Repository legt KAT-01 (#3) an, auf Basis der Spalten von `catalog_games`.

## 6. Plattform-Besonderheiten

- **iOS, Android, Web:** keine Unterschiede. Das Platzhalter-Cover ist Flutter-Code, keine Plattform-API.
- **Offline:** nicht betroffen. Katalogsuche braucht eine Verbindung (PAR-01 Krit. 6).
- **Dateien/Kamera/Push:** nicht betroffen. Cover-Uploads gibt es in R1 nicht (N11); Storage-Buckets für Spielbilder entstehen erst, wenn ein Cover erlaubt ist.
- **Self-Hosting:** Studio-Zugang nur über Tunnel/VPN (4.2); Startbestand per SQL-Datei (4.3).

## 7. Teststrategie

Werkzeuge: pgTAP (`supabase test db`), Deno-Tests für das Erzeugungsskript (falls F6 Option A), `flutter_test` für das Widget. Testnamen enthalten die Referenz („KAT-05 Kriterium n“).

**Neue pgTAP-Dateien**

- `06_catalog_foundation.test.sql` (2a): Spalten, Checks, Spaltenrechte, Trigger `manual_fields`, View `catalog_games`, `catalog_sources`, Verlage.
- `07_catalog_merge.test.sql` (2b): `repoint_game_references`, `admin_merge_games`, Ausblenden; Fremdschlüssel-Wächter.
- `08_game_reports.test.sql` (2c): Tabelle, RLS, `admin_resolve_report`.

Die Tests müssen auch mit eingespieltem Startbestand grün sein: Sie legen eigene Fixtures mit festen Test-UUIDs an und zählen nur diese (Filter auf die Fixture-IDs), statt den gesamten Katalog zu löschen. `02_catalog.test.sql` löscht weiterhin alles (`delete from public.games` innerhalb der zurückgerollten Transaktion); das funktioniert auch mit dem Startbestand, weil der Startbestand keine Verweise aus Nutzertabellen hat.

**Fremdschlüssel-Wächter (2b):** Ein Test liest aus `pg_constraint` alle Fremdschlüssel, die auf `public.games` zeigen, und vergleicht sie mit der Liste, die `repoint_game_references` behandelt (bzw. bewusst auslässt: Zuordnungstabellen, `games.merged_into_id`, `game_reports`). Legt eine spätere Story eine neue Tabelle mit Verweis auf `games` an, wird der Test rot und erzwingt die Erweiterung der Funktion.

### 7.1 Abdeckungsmatrix

| AK | Unit | Widget | Integration/E2E | RLS/pgTAP | Task |
|---|---|---|---|---|---|
| KAT-05 Krit. 1 (nur Modell) | – | – | – | `06`: Update eines Katalogspiels als `postgres` → Feld in `manual_fields`; mit `set local shuffle.catalog_import = 'on'` → nicht markiert; Insert markiert nach F4; Zuordnung Genre/Verlag → `genres`/`publishers` markiert; unbekannter Schlüssel in `manual_fields` → 23514 | B1, B2 |
| Krit. 2 | – | – | – | `06`: `games.id` ist uuid-PK mit Standard; ID bleibt bei Update unverändert (bestehender Trigger); `source_id` ohne `source_ref` → 23514; `(source_id, source_ref)` im Katalog eindeutig → 23505; Quelle `bgg` vorhanden | B1, B2 |
| Krit. 3 | – | – | – | – (zurückgestellt, kein Modellanteil) | – |
| Krit. 4 | – | – | (KAT-01: Suche findet ausgeblendete Spiele nicht, E2E in #3) | `06`: `catalog_games` ohne ausgeblendete und zusammengeführte Spiele, für `anon` und `authenticated`; ausgeblendetes Spiel bleibt per ID in `games` lesbar (nach F2); Sammlungseintrag eines Nutzers zu einem ausgeblendeten Spiel bleibt lesbar. `07`: Ausblenden/Einblenden per Runbook-SQL; `admin_merge_games` hängt Sammlung, Favoriten, Partien (mit Variante) und Wertungsbögen um, Kollisionen nach F1, Quelle danach `merged_into_id`/`hidden_at` gesetzt, Ketten geglättet; alle Fehlerfälle (`merge_same_game` … `merge_source_already_merged`); Fremdschlüssel-Wächter | B1, B2, B5, B6 |
| Krit. 5 | – | – | – | `08`: Checks der Status-Kombinationen; `admin_resolve_report` für `approved` (vorläufiger Eintrag umgehängt und zusammengeführt), `merged` und `rejected` mit Ziel (nach F3), `rejected` ohne Ziel (vorläufiger Eintrag unverändert); `report_not_open` bei zweitem Aufruf; `report_target_required`, `report_target_not_listed`; N12a-Index: zweite offene Import-Meldung desselben Nutzers zur selben BGG-ID → 23505, bei anderem Nutzer erlaubt; Konto löschen → Meldungen weg | B8, B9 |
| Krit. 6 (nur Modell) | – | – | – | `06`: `catalog_games.description`/`image_path` sind `null` bei Quelle ohne Erlaubnis, sichtbar mit Erlaubnis, sichtbar bei manuell gepflegtem Feld, sichtbar ohne Quelle | B1, B2 |
| Krit. 7 | Deno: Skript erzeugt aus einer Fixture-CSV die erwartete SQL (Snapshot), gleiche `key` → gleiche UUID, Fehler mit Zeilennummer je Prüfregel | – | CI: `supabase db reset` mit `vocabulary.sql` + `startbestand.sql` läuft durch; CI-Schritt „erzeugte SQL ist aktuell“ (Skript erneut ausführen, `git diff --exit-code`) | – | B3, T1 |
| Krit. 8 | – | – | – | `07`/`08`: jeder SQL-Baustein aus `docs/katalog-pflege.md` wird im Test genau so ausgeführt (Kommentar mit Abschnittsverweis); Review prüft Vollständigkeit | B4, B7, B10 |
| Krit. 9 | – | – | API-Test optional (PostgREST `PATCH /rest/v1/games` mit Nutzer-JWT → 0 Zeilen bzw. 401/403), nur falls test-engineer ihn für nötig hält; pgTAP deckt dieselben Rollen ab | `06`: `anon` und Nutzer (auch mit gefälschtem `user_metadata.role = 'admin'`) können Katalogspiele, `catalog_sources`, `publishers`, `game_publishers` (Katalog) nicht anlegen, ändern, löschen; Nutzer kann an eigenem privaten Spiel `hidden_at`, `merged_into_id`, `manual_fields`, `source_id` nicht setzen (42501), wohl aber `title`; View nicht schreibbar. `07`/`08`: `admin_merge_games`, `admin_resolve_report`, `repoint_game_references` für `anon`/`authenticated` nicht ausführbar (42501), auch mit `app_metadata.role = 'admin'`; `game_reports`: Nutzer B liest A's Meldungen nicht, niemand außer `postgres` ändert oder löscht Meldungen, `anon` liest nichts | B2, B6, B9 |
| Krit. 10 | Deno: CSV ohne Pflicht-Fakten → Fehler; CSV hat keine Cover-/Quellen-Spalte | `GameCover`: ohne `imageUrl` → Platzhalter; Ladefehler → Platzhalter; Semantics-Label de/en; Kontrast und `textScaler` 2.0 ohne Überlauf | (KAT-02: Detailseite zeigt Platzhalter und Kurztext, in #4) | `06`: Fixture-Spiele aus dem Startbestands-Format haben `image_path is null`, `source_id is null`; Prüfabfrage `checks.sql` liefert 0 Verstöße auf dem lokalen Bestand | B3, U1, T1, T2 |
| Sicherheit Krit. 2 | – | – | – | `06`: `anon` liest `catalog_games`, `catalog_sources`, `publishers`, `game_publishers` (Katalog), schreibt nichts | B2 |
| Sicherheit Krit. 3 | – | – | – | `08`: fremder Zugriff auf `game_reports` | B9 |
| QUE-05 Krit. 2, QUE-06 Krit. 1–3 | – | `GameCover` in de/en, a11y-Guidelines | – | – | U1, T2 |

**Nicht automatisiert testbar, manuelle Prüfung:** Studio nicht öffentlich erreichbar (Staging/Prod, D1); Einspielen des Startbestands auf Staging/Prod und Prüfabfrage (Release-Checkliste); Umfang „etwa 200“ (Prüfabfrage, Abnahme durch Chris); inhaltliche Richtigkeit der Fakten und Kurztexte (Chris).

## 8. Aufgaben

### 8.1 PR 2a – Fundament (R1.1), Branch `feature/2-katalog-fundament`

| # | Agent | Aufgabe | abhängig von |
|---|---|---|---|
| B1 | backend-dev | Migration `<ts>_catalog_foundation.sql` nach 3.2: `catalog_sources` (+ Zeile `bgg`), neue Spalten in `games` mit Checks und Indizes, `publishers`, `game_publishers`, Trigger `games_mark_manual_fields` und `game_links_mark_manual` (Variante nach F4), View `catalog_games`, Spaltenrechte auf `games`, RLS und Grants für alle neuen Tabellen | Freigabe Spec; F4 |
| B2 | backend-dev | pgTAP `06_catalog_foundation.test.sql` nach 7.1 (Krit. 1, 2, 4, 6, 9, 10, Sicherheit Krit. 2); bestehende Tests mit Startbestand lauffähig halten | B1 |
| B3 | backend-dev | Startbestand-Werkzeug nach 4.3 und F6: `supabase/catalog/vocabulary.sql` (Gerüst; Inhalt nach F8), Format/Skript `build_startbestand.ts` mit Prüfregeln und Deno-Tests, `startbestand.sql` (zunächst leer bzw. nur Kopf), `checks.sql`, `config.toml` `[db.seed] sql_paths`, `seed.sql` bereinigen (keine kollidierenden Begriffe) | B1; F6, F8 |
| B4 | backend-dev | Doku: `docs/katalog-pflege.md` Abschnitte Zugang, Startbestand, Spiel anlegen/bearbeiten, Admin-Rolle (4.4); `docs/datenmodell-r1.md` (neue Objekte, doppelten Abschnitt zusammenführen); `supabase/README.md` | B1, B3 |
| U1 | ui-designer | `GameCover` in `core/widgets/` nach 5 (Platzhalter nach F9, Größen, Ladezustand, Semantics, ARB-Schlüssel de/en) | F9 |
| T1 | test-engineer | Review der pgTAP-Abdeckung gegen 7.1; Deno-Tests des Skripts ergänzen; CI-Schritt „erzeugte SQL ist aktuell“ mit devops abstimmen | B2, B3 |
| T2 | test-engineer | Widget-Tests `GameCover` (Platzhalter, Ladefehler, de/en, a11y-Guidelines, `textScaler` 2.0) | U1 |
| D1 | devops | Studio-/Postgres-Zugang auf Staging/Prod nur über SSH-Tunnel/VPN, Basic-Auth gesetzt (Doku in `docs/`, kein Eingriff ohne Freigabe); CI: Deno für das Skript bereitstellen, Schritt „erzeugte SQL aktuell“ | B3 |
| C1 | Chris | Startbestand einpflegen (~200 Spiele, Kurztexte, Vokabular freigeben) im Format nach F6; vor dem Go-live Prüfabfrage abnehmen | B3 |

### 8.2 PR 2b – Admin-Pflege (R1.2), Branch `feature/2-katalog-pflege`

| # | Agent | Aufgabe | abhängig von |
|---|---|---|---|
| B5 | backend-dev | Migration `<ts>_catalog_merge.sql` nach 3.3: `repoint_game_references`, `admin_merge_games`, Rechte (`revoke execute`) | 2a gemergt; F1 |
| B6 | backend-dev | pgTAP `07_catalog_merge.test.sql` inkl. Fremdschlüssel-Wächter | B5 |
| B7 | backend-dev | Runbook: Abschnitte Ausblenden und Zusammenführen (SQL-Bausteine identisch zu den Tests) | B5, B6 |

### 8.3 PR 2c – Meldungen (R1.2), Branch `feature/2-katalog-meldungen`

| # | Agent | Aufgabe | abhängig von |
|---|---|---|---|
| B8 | backend-dev | Migration `<ts>_game_reports.sql` nach 3.4: Tabelle, Checks, Indizes, RLS (nur Lesen der eigenen), `admin_resolve_report`, `admin_merge_games` erweitert | 2b gemergt; F3 |
| B9 | backend-dev | pgTAP `08_game_reports.test.sql` | B8 |
| B10 | backend-dev | Runbook: Abschnitt Meldungen bearbeiten | B8, B9 |

### 8.4 Reihenfolge und Parallelität

```
R1.1  Freigabe → B1 → B2 | B3 → B4, T1, D1     parallel: U1 → T2     danach: C1 (Chris, laufend bis Go-live)
      2a gemergt → #3 KAT-01 kann starten
R1.2  B5 → B6 → B7 (2b)  →  B8 → B9 → B10 (2c)  →  #13 KAT-04 Umsetzung
```

2c muss vor der Umsetzung von #13 gemergt sein (E12); die Spec von #13 kann parallel entstehen und baut auf 3.4 auf. Merge nur durch Chris.

## 9. Risiken & offene Fragen

### 9.1 Risiken

| # | Risiko | Auswirkung | Gegenmaßnahme |
|---|---|---|---|
| R1 | **Studio umgeht RLS** und hat im Self-Hosting keine eigene Benutzerverwaltung | Wer Studio erreicht, kann alles lesen und ändern, auch private Nutzerdaten | Studio und Postgres nur über SSH-Tunnel/VPN (D1), Basic-Auth als zweite Schicht; Runbook: immer in Transaktionen, Funktionen statt Hand-SQL für Zusammenführen und Meldungen |
| R2 | **EU-Datenbankrecht und Nutzungsbedingungen:** Werden die Fakten für ~200 Spiele in großem Umfang aus BGG oder einer anderen Datenbank übernommen, kann das das Schutzrecht des Datenbankherstellers bzw. deren Nutzungsbedingungen verletzen, auch wenn Einzelfakten nicht geschützt sind | Rechtliches Risiko für den Start | Frage F7; Empfehlung: Fakten aus Verlagsseiten, Spielschachtel und eigener Kenntnis, nicht systematisch aus einer fremden Datenbank kopieren; vor dem Release mit der rechtlichen Prüfung (R11 in Spec #1) klären |
| R3 | Spätere Tabellen mit Verweis auf `games` werden beim Zusammenführen vergessen | Verwaiste Verweise auf ausgeblendete Quell-Einträge | Fremdschlüssel-Wächter in `07` (7) |
| R4 | Ausgeblendete Spiele bleiben über die rohe API per ID lesbar (E3) | Ein aus rechtlichen Gründen ausgeblendeter Eintrag wäre weiter abrufbar | Frage F2; bei Bedarf eigener Status „gesperrt“ mit RLS-Filter |
| R5 | Startbestand weicht zwischen CSV/SQL-Datei und Produktion ab, sobald Chris nach dem Go-live im Studio korrigiert | Erneutes Einspielen der Datei überschreibt Studio-Korrekturen (Upsert) | Regel im Runbook (F6): bis zum Go-live ist die Datei maßgeblich, danach nur Studio; die Datei wird danach nicht mehr eingespielt |
| R6 | `manual_fields` nach Option A (F4) markiert den ganzen Startbestand als manuell | Ein späterer Import ergänzt nur leere Felder und korrigiert keine Fakten | Bewusste Wahl in F4; Admin kann Markierungen per SQL entfernen (Runbook) |
| R7 | `game_reports` wird in #2 angelegt, die Regeln zum Anlegen kommen erst mit #13 | Zwischen 2c und #13 gibt es Meldungen nur per Studio (für Tests) | Kein Insert-Recht für Nutzer in 2c, deshalb kein offener Zwischenzustand |
| R8 | Spaltenrechte auf `games` schränken auch einen künftigen Admin über die API ein | QUE-08 (R4) braucht eigene RPCs | Bewusst; Hinweis in 3.2 |
| R9 | ~200 Spiele einpflegen ist viel Handarbeit für Chris | Startbestand zum R1-Start unvollständig | Pflegeformat mit Prüfungen (F6), Go-live-Abnahme mit Mindestzahl (F8); Prüfabfrage zeigt Fortschritt |

### 9.2 Offene Fragen an Chris

Fachliche Fragen, die ich nicht selbst entscheiden kann. Jede mit Optionen und Empfehlung. Die Umsetzung von 2a hängt nur an F4, F6, F8, F9 (und F5 für das CSV-Format); F1 blockiert 2b, F3 blockiert 2c; F2 und F7 blockieren keinen PR, wohl aber KAT-01/KAT-02 bzw. das Release.

| # | Frage | Optionen | Empfehlung | Wirkung |
|---|---|---|---|---|
| F1 | **Zusammenführen bei Doppelbesitz:** Ein Nutzer hat beide Spiele (Quelle und Ziel) in Sammlung oder Listen. Was passiert mit seinen zwei Einträgen? | **A:** Zieleintrag bleibt; leere Felder des Ziels (z. B. Notiz, Kaufdatum) werden aus dem Quell-Eintrag gefüllt; Liste: Sammlung schlägt Wunsch- und Einkaufsliste (wie Klärung 34 „besessen und gewünscht → Sammlung“); Quell-Eintrag wird gelöscht. **B:** Zieleintrag bleibt unverändert, Quell-Eintrag wird gelöscht. **C:** Zusammenführen bricht ab, Admin klärt vorher manuell. | **A** – keine Angaben gehen verloren, Regel ist schon aus Klärung 34 bekannt; der Fall ist bei einem handgepflegten Katalog selten | 3.3 Schritt 2, B5, `07` |
| F2 | **Ausgeblendete Einträge:** Reicht „nicht in Suche und Entdecken“ (Krit. 4), oder sollen sie auch per Direktaufruf (Detailseite, API) verschwinden? | **A:** Nur aus Suche/Entdecken; Detailseite und bestehende Sammlungen/Partien zeigen sie weiter, mit Hinweis „nicht mehr im Katalog“. **B:** Zusätzlich per RLS für alle gesperrt, die das Spiel nicht in Sammlung/Partien haben. **C:** Wie A, und später ein eigener Status „gesperrt“ für rechtliche Fälle. | **A**, bei Bedarf C – einfach, keine kaputten Verweise; ein Eintrag mit Rechtsproblem wird zusammengeführt oder inhaltlich geleert | E3, R4, KAT-02 (#4) |
| F3 | **Meldung „zusammengeführt“ oder „abgelehnt mit Verweis“:** Soll der vorläufige Eintrag des Meldenden automatisch auf den Zieleintrag umgehängt werden (wie bei „freigegeben“)? | **A:** „zusammengeführt“ hängt automatisch um; „abgelehnt mit Verweis“ setzt nur den Verweis, der Nutzer entscheidet in der App (KAT-04). **B:** Beide hängen automatisch um. **C:** Keiner hängt um, nur Verweis und Hinweis. | **A** – „zusammengeführt“ heißt „das ist dasselbe Spiel“, Umhängen ist dann richtig; „abgelehnt mit Verweis“ kann auch „ähnlich, aber anders“ bedeuten (z. B. Edition), das soll der Nutzer bestätigen | 3.4, B8, Spec #13 |
| F4 | **Kennzeichnung des Startbestands:** Gelten alle Felder der ~200 Spiele als „manuell gepflegt“, oder nur der eigene Kurztext? | **A:** Alle beim Einpflegen gesetzten Felder sind manuell; ein späterer Import ergänzt nur leere Felder. **B:** Nur `description` (eigener Kurztext) ist manuell; Fakten darf ein lizenzierter Import korrigieren, spätere Studio-Änderungen werden trotzdem markiert. | **A** – entspricht dem Wortlaut von Krit. 4 und N11 („von Chris gepflegt“), ist die vorsichtige Wahl; einzelne Markierungen lassen sich später gezielt entfernen | E4, 3.2 Trigger, R6 |
| F5 | **Eigene Kurztexte:** In welcher Sprache, wer schreibt sie, sind sie Pflicht zum Go-live? | Sprache: **A** nur Deutsch, **B** nur Englisch, **C** beide (widerspricht „eine Sprache je Spiel“ im Datenmodell, bräuchte eine Übersetzungstabelle). Autor: Chris selbst, oder KI-Entwürfe, die Chris prüft und freigibt. Pflicht: ja für alle Startbestandsspiele, oder optional (fehlende werden weggelassen, KAT-02 Krit. 2). | Deutsch (A), KI-Entwürfe mit Prüfung durch Chris sind zulässig, Pflicht für alle Startbestandsspiele (die Prüfabfrage meldet fehlende) – englische Oberflächen zeigen dann den Sprachhinweis (Klärung 48) | E8, 4.3 CSV, `checks.sql` |
| F6 | **Pflegeformat des Startbestands:** Wie trägst du die ~200 Spiele ein? | **A:** Tabelle (CSV, z. B. aus einer Tabellenkalkulation) im Repo, ein Skript erzeugt daraus die SQL-Datei und prüft alles. **B:** Direkt im Studio-Tabelleneditor (lokal oder Staging), danach Export per `pg_dump --data-only` in die SQL-Datei. **C:** SQL-Datei von Hand nach Vorlage. Zusätzlich: Ist die Datei nach dem Go-live eingefroren (Korrekturen nur noch im Studio)? | **A** und „nach dem Go-live eingefroren“ – Tabellen sind für 200 Zeilen mit mehreren Genres/Mechaniken/Verlagen am bequemsten, Fehler fallen sofort auf; B ist für Zuordnungstabellen mit UUIDs mühsam | E9, 4.3, B3, R5 |
| F7 | **Herkunft der Fakten:** Woher nimmst du Verlag, Jahr, Spielerzahl, Dauer, Alter, Genre und Mechanik? | **A:** Verlagsseiten, Spielschachtel, eigene Kenntnis. **B:** Einzeln von BGG abgelesen. **C:** Wikipedia/Wikidata (Wikidata ist CC0). | **A**, ergänzend C (Wikidata) – vermeidet das Risiko R2 (Datenbankrecht, BGG-Nutzungsbedingungen) am ehesten; endgültig mit der rechtlichen Prüfung vor dem Release klären | R2, Release-Checkliste |
| F8 | **Umfang, Abnahme und Vokabular:** Was heißt „etwa 200“ für die Abnahme, wer legt die Genre- und Mechanik-Liste fest, und gehören Erweiterungen in den Startbestand? | Abnahme: Mindestzahl (z. B. 180) oder fester Bereich (180–220). Vokabular: Agents schlagen eine Liste vor (ca. 12–15 Genres, 20–30 Mechaniken, de/en), du gibst frei; oder du legst sie selbst fest. Erweiterungen: ja (Basisspiel in der Spalte `base_game_key` vormerken, Verknüpfung kommt mit #12), oder erst ab R1.2. | Mindestens 180 sichtbare Katalogspiele mit allen Pflicht-Fakten zum Go-live; Vorschlagsliste durch Agents, Freigabe durch dich; Erweiterungen erlaubt und vorgemerkt | 4.3, B3, `checks.sql`, C1 |
| F9 | **Platzhalter-Cover:** Ein einheitlicher Platzhalter oder je Genre unterschiedlich? | **A:** Ein neutraler Platzhalter für alle (Theme-Farbe, Symbol). **B:** Farbe/Symbol je Haupt-Genre. **C:** Wie A, zusätzlich Anfangsbuchstabe des Titels. | **A** – einfach, ruhig in Listen mit vielen Spielen ohne Cover (in R1 alle); B/C lassen sich später ohne Datenänderung nachrüsten | 5, U1 |

### 9.3 Ausstehende Prozessschritte

- Spec-Freigabe durch Chris; danach Antworten F1–F9 in diese Spec einarbeiten (Änderungsprotokoll).
- Label `size/xl` → `size/l` (E2) ändert nur Chris.
- Spec #13 (KAT-04) baut auf 3.4 auf: Insert-Policy, Tageslimit, Ähnlichkeitsprüfung, Hinweis am vorläufigen Eintrag, Herkunft „aus Import“ (N12).
- Kein ADR nötig: Die Entscheidungen bleiben innerhalb von ADR-0001/0002 und sind ohne großen Aufwand änderbar (Startbestand ist eine Datei, `manual_fields` eine Spalte).

### 9.4 Hinweise für andere Stories, nicht Teil von #2

- **KAT-01 (#3):** Suche über `catalog_games` (bzw. eine RPC darauf); Tabelle für alternative Titel (Klärung 3) mit neuem `manual_fields`-Schlüssel; Spalte `alt_titles` der Startbestands-CSV auswerten.
- **KAT-02 (#4):** Weiterleitung bei `merged_into_id`; Verhalten bei `hidden_at` nach F2; Quellenangabe aus `source_*` (KAT-02 Krit. 5); Sprachhinweis über `description_locale`.
- **KAT-03 (#12):** Basisspiel-Verweis (Klärung 5) mit `manual_fields`-Schlüssel; `base_game_key` der CSV auswerten; `repoint_game_references` für die neue Spalte prüfen (Fremdschlüssel-Wächter).
- **PAR-04 (#18):** Sobald ein Wertungsbogen je Spiel und Nutzer erzwungen wird, Kollisionsregel in `repoint_game_references` ergänzen.
- **SAM-08 (#25):** Import setzt `set local shuffle.catalog_import = 'on'`, pflegt `source_*` und `source_synced_at`, legt Import-Meldungen mit `origin = 'import'` an (N12, N12a).
- **KTO-05 (#23):** `game_reports` wird per `on delete cascade` mit dem Profil gelöscht; im Export enthalten.

## 10. Änderungsprotokoll

### 2026-11-03 – Entwurf

Erste Fassung durch architect, wartet auf Freigabe und Antworten zu F1–F9.