# 1v1 Games Migration Plan (Nuxt → rebreak-native)

Status: Recon abgeschlossen 2026-05-07. Read-only Analyse, kein Code-Touch.

Author scope: Migration der bestehenden Nuxt-1v1-Implementierung (TicTacToe + Memory) aus `~/mono/trucko-monorepo/apps/rebreak/` in die neue React-Native-App `~/mono/rebreak-monorepo/apps/rebreak-native/`. Letzter Schritt vor finalem Nuxt-Cutover (DiGA).

---

## 1. Status quo Nuxt-Implementierung

### 1.1 Frontend (Vue/Nuxt)

| Datei | Zweck |
|---|---|
| `~/mono/trucko-monorepo/apps/rebreak/app/pages/app/game/[challengeId].vue` (802 LOC) | Haupt-Game-Page. Lobby (Waiting), Live-Board für TicTacToe + Memory, Status, Lyra-Bubble, Tabs (History + Ranking), Rematch, Live-Share-Toggle. Subscribed Supabase-Realtime auf `rebreak.game_challenges`-Row. |
| `~/mono/trucko-monorepo/apps/rebreak/app/components/sos/GameTicTacToe.vue` | Solo-Modus mit Lyra-AI. Enthält "Gegen echten Spieler"-Button (Z. 73-76) — POST `/api/games/challenge` + Redirect. |
| `~/mono/trucko-monorepo/apps/rebreak/app/components/sos/GameMemory.vue` | Solo-Memory mit "Gegen echten Spieler"-Button (Z. 48-52) — POST `/api/games/challenge-memory` + Redirect. |
| `~/mono/trucko-monorepo/apps/rebreak/app/components/CommunityPostCard.vue` | Rendert "Challenge annehmen"-Button für Community-Posts mit `category="challenge"` (Z. 288, 469-479). |
| `~/mono/trucko-monorepo/apps/rebreak/app/stores/community.ts` | Pinia-Store, hält `challengeId` an Posts (Z. 8, 250). |

**File-Count Frontend: 5 relevante Vue-Files (1 Page + 2 Solo-Game-Components mit 1v1-Hook + 1 PostCard + 1 Store).**

### 1.2 Backend (Nuxt-Server, Nitro)

Backend liegt **nicht** in einem separaten trucko-backend-Service, sondern im selben Nuxt-Projekt unter `apps/rebreak/server/`. Endpoints:

| Endpoint | File |
|---|---|
| `POST /api/games/challenge` | `server/api/games/challenge.post.ts` (38 LOC) — TicTacToe-Challenge erzeugen + Community-Post |
| `POST /api/games/challenge-memory` | `server/api/games/challenge-memory.post.ts` (62 LOC) — Memory-Challenge erzeugen (16 Karten, shuffled) |
| `GET /api/games/challenge/[id]` | `server/api/games/challenge/[id].get.ts` (16 LOC) — Lade Challenge-State |
| `POST /api/games/challenge/[id]/accept` | `server/api/games/challenge/[id]/accept.post.ts` (35 LOC) — Gegner tritt bei, Status: OPEN → ACTIVE |
| `POST /api/games/challenge/[id]/move` | `server/api/games/challenge/[id]/move.post.ts` (109 LOC) — TicTacToe-Move; Win-Check, Score-Update, Post-Cleanup |
| `POST /api/games/challenge/[id]/memory-move` | `server/api/games/challenge/[id]/memory-move.post.ts` (152 LOC) — Memory-Move (Flip/Match/Mismatch) |
| `POST /api/games/challenge/[id]/rematch` | `server/api/games/challenge/[id]/rematch.post.ts` (64 LOC) — Neue Challenge mit Gegner pre-set, status=ACTIVE |
| `POST /api/games/challenge/[id]/live-toggle` | `server/api/games/challenge/[id]/live-toggle.post.ts` (35 LOC) — `isLive`-Flag für Spectators |
| `GET /api/games/history` | `server/api/games/history.get.ts` (44 LOC) — Spielhistorie (alle, oder vs Gegner) |
| `GET /api/games/ranking` | `server/api/games/ranking.get.ts` (15 LOC) — Top-Spieler-Liste |

**File-Count Backend: 10 Endpoints, ~570 LOC.**

### 1.3 DB-Schema

Aus `~/mono/trucko-monorepo/apps/rebreak/prisma/schema.prisma`:

- `enum GameChallengeStatus` (Z. 424): `OPEN | ACTIVE | FINISHED | CANCELLED`
- `model GameChallenge` (Z. 433-452, Tabelle `rebreak.game_challenges`): id, challengerId, challengerName, opponentId, opponentName, status, board (TEXT, default `---------`), currentTurn, winner, postId, gameType (default "tictactoe"), isLive, memoryState (Json), timestamps.
- `model GameScore` (Z. 470, Tabelle `rebreak.game_scores`): userId PK, playerName, wins, losses, draws, points (3 für Sieg, 1 für Unentschieden).
- `model GameRating` (Z. 483) und `GameHighScore` (Z. 496) — gehören zum Solo-Mode, irrelevant für 1v1, aber bereits portiert.

Migrations-SQL:
- `~/mono/trucko-monorepo/apps/rebreak/prisma/migrations/add_game_challenges.sql` — Enum, Table, Indexes, `ALTER PUBLICATION supabase_realtime ADD TABLE rebreak.game_challenges`
- `~/mono/trucko-monorepo/apps/rebreak/prisma/migrations/add_game_challenges_rls.sql` — RLS-Policies (read/insert/update für challenger + opponent via `auth.uid()`)
- Spätere Patches haben `gameType`, `isLive`, `memoryState` hinzugefügt (in den live-DB Tabelle vorhanden, kein eigenes Migration-File gefunden — Schema-Drift-Verdacht in Nuxt).

### 1.4 State-Sync-Mechanismus (1 Satz)

**Server-authoritative State in Postgres (`rebreak.game_challenges`-Row); Frontend mutiert via REST-POST und subscribed parallel auf Supabase-Realtime `postgres_changes` UPDATE-Events der eigenen Row → keine Polling, keine WebSocket-Eigenbau.**

### 1.5 Datenflussdiagramm (ASCII)

```
        Spieler A (Challenger)                       Spieler B (Opponent)
       ─────────────────────                        ─────────────────────
              │                                              │
   POST /api/games/challenge                                 │
              │                                              │
              ▼                                              │
   ┌──────────────────────┐                                  │
   │  game_challenges     │   communityPost.challengeId      │
   │  status=OPEN         │◀────────────────────────────────┐│
   │  board=---------     │                                 ││
   └──────────┬───────────┘                                 ││
              │                                              ▼
              │                                    GET /api/community/posts
              │                                    (sees challenge card)
              │                                              │
              │                  POST /api/games/challenge/[id]/accept
              │                                              │
              ▼                                              ▼
   ┌────────────────────────────────────────────────────────────┐
   │  game_challenges  status=ACTIVE  opponent_id=B             │
   └──────────────────────────┬─────────────────────────────────┘
                              │
                              │  Supabase Realtime (postgres_changes)
                              │  channel = `game:<id>:<ts>`
                              │  filter = id=eq.<challengeId>
                              ▼
              ┌──────────────────────────────┐
              │ both clients update UI       │
              └──────────┬───────────────────┘
                         │
        loop until FINISHED:
              │
   POST /api/games/challenge/[id]/move (or memory-move)
              │
              ▼
   ┌────────────────────────────────────────────────────────────┐
   │  Server validates turn + writes new board / memoryState    │
   │  on win/draw → upsert game_scores, delete community post  │
   └──────────────────────────┬─────────────────────────────────┘
                              │ Realtime UPDATE → both clients
                              ▼
              ┌──────────────────────────────┐
              │ FINISHED screen + Rematch    │
              └──────────────────────────────┘
```

---

## 2. Migration-Plan

### Phase A — Backend-Endpoints in rebreak-monorepo

**Status: BEREITS PORTIERT.** Verifiziert per `diff`:
- `~/mono/rebreak-monorepo/backend/server/api/games/challenge.post.ts` ist byte-identisch mit Nuxt.
- `~/mono/rebreak-monorepo/backend/server/api/games/challenge/[id]/move.post.ts` ist byte-identisch.
- Alle 10 Endpoints existieren bereits unter `~/mono/rebreak-monorepo/backend/server/api/games/`.

→ **Aufwand Phase A: 0 h.** Nur ein leichter Smoke-Test (curl Request mit Bearer-Token gegen den staging-Nitro) zur Bestätigung dass die Endpoints im Nitro-Prod-Build aktiv sind.

### Phase B — DB-Migrations für game_sessions

**Status: BEREITS PORTIERT.** Schema verifiziert:
- `enum GameChallengeStatus` in `~/mono/rebreak-monorepo/backend/prisma/schema.prisma` Z. 424 vorhanden.
- `model GameChallenge`, `GameScore`, `GameRating`, `GameHighScore` alle vorhanden.

**Offene Punkte (klein):**
1. SQL-Migration unter `backend/prisma/migrations/` muss verifiziert werden — sind `gameType`, `isLive`, `memoryState`-Spalten in einer eigenen Migration angelegt? Falls nein: ein konsolidiertes `add_game_challenges.sql` nachziehen.
2. RLS-Policies und `ALTER PUBLICATION supabase_realtime ADD TABLE rebreak.game_challenges` müssen am Staging-DB-Cluster bestätigt werden (gleicher DB für Nuxt + RN-Backend, also vermutlich schon aktiv).

→ **Aufwand Phase B: 1-2 h** (SQL-Audit + ggf. ein Catch-up-Migration-File).

### Phase C — RN-UI-Komponenten

**Status: KOMPLETT NEU.** RN-App hat aktuell:
- `apps/rebreak-native/components/urge/UrgeGames.tsx` (1067 LOC) — Solo-Mode für Memory/TicTacToe/Snake/Tetris.
- `apps/rebreak-native/app/games.tsx` — Standalone-Games-Page (Solo).
- KEIN Community-Komponent, KEIN Game-Page für 1v1.

**Zu erstellen:**

1. `apps/rebreak-native/app/(app)/game/[challengeId].tsx` — Pendant zu `pages/app/game/[challengeId].vue`. RN-Expo-Router-File. Ports:
   - Loading + Lobby (`OPEN`-Status, Waiting-Screen mit Cancel-Button)
   - TicTacToe-Board (3x3 Grid, X/O-Marker, WinLine-Highlight) — `Pressable`-Cells statt `<button>`
   - Memory-Board (4x4 Grid, Score-Header, Mismatch-Reveal, Progress-Bar)
   - Lyra-Bubble (Avatar + animierter Phrase-Text, optional TTS-Toggle — bereits vorhandene `lib/sosTtsQueue.ts`-Infra wiederverwendbar)
   - Status/Result-Section + Rematch-Button
   - History-Tab + Ranking-Tab

2. `apps/rebreak-native/components/games/Game1v1Board.tsx` (optional, falls zu monolithisch) — Sub-Component für Board-Rendering.

3. **1v1-Entry-Buttons in `UrgeGames.tsx`** — analog Vue, pro TicTacToe und Memory Solo-Mode einen "Gegen echten Spieler"-Button hinzu, der `POST /api/games/challenge[-memory]` callt und auf `/game/[id]` navigiert.

4. **Community-Listing-View** — Aktuell hat RN-App keine Community-Tab. Entweder:
   - **Option a:** Existing community-Page aus Nuxt nach RN portieren (separater großer Task).
   - **Option b:** Erstmal nur eine **"Open Challenges"-Liste** unter `/game/index.tsx`, die alle `OPEN`-Challenges (eigener Endpoint nötig: `GET /api/games/challenges?status=OPEN`) listet.
   - **Option c (empfohlen):** Direkter Invite-Flow per Share-Link `/game/[id]` (Deep-Link funktioniert bereits in Expo) — kein Community-Browsing nötig für DiGA-Cutover.

→ **Aufwand Phase C: 12-20 h** (1 Page mit 2 Game-Modes + Realtime + Lyra + History-Tab + Ranking-Tab + Lobby-Flow). Größte Position.

### Phase D — Realtime-Wiring

**Status: INFRA VORHANDEN.** `apps/rebreak-native/lib/supabase.ts` hat bereits `realtime`-Konfig.

**Zu tun:**
- Im neuen `[challengeId].tsx` analog zu Vue: `supabase.channel(...).on('postgres_changes', { schema: 'rebreak', table: 'game_challenges', filter: `id=eq.${id}` })`.
- React-Native-Spezifika: AppState-Listener für Reconnect bei Background → Foreground (Vue-Variante hat nur passive Reconnect bei `CHANNEL_ERROR`).
- Auth-Token via `supabase.realtime.setAuth(session.access_token)` — identisch zu Vue.

→ **Aufwand Phase D: 2-3 h** (im Rahmen Phase C).

### Phase E — Testing + Deploy

- **Manueller 2-Device-Test** (iOS-Simulator + Android-Emulator simultan): Challenge erstellen, accepten, abwechselnd Züge, Win/Draw, Rematch.
- **Disconnect-Resilience**: Airplane-Mode toggle während ACTIVE — Realtime muss reconnecten.
- **Deep-Link-Test**: `rebreaknative://game/<id>` aus geteiltem Link.
- **EAS-Preview-Build** für Tester.

→ **Aufwand Phase E: 4-6 h** (inkl. Bugfixes).

**Gesamtaufwand: ~20-30 h Net-Coding**.

---

## 3. Architektur-Empfehlung — was wir besser machen

Die Nuxt-Implementierung ist solide (server-authoritative + Supabase-Realtime ist die richtige Wahl). Drei Verbesserungen für die RN-Variante:

1. **Kein Community-Post-Coupling.** Die Nuxt-Variante erstellt für jede Challenge automatisch einen Community-Post (`category="challenge"`) und löscht ihn beim Spielende. Das verschmiert Game-Lifecycle und Community-Layer. Empfehlung: 1v1-Challenges leben in einer eigenen Tabelle / einem eigenen "Open-Challenges"-Endpoint, ohne Cross-Coupling. Macht Phase-C-Cleanup einfacher und entkoppelt RN-Cutover von Community-Migration.

2. **Optimistic UI mit Rollback.** Aktuell wartet Vue auf den POST-Response, bevor das Board updated → 100-300 ms Lag pro Move. RN-Variante: lokal sofort renderen (gleiche Validierungslogik clientseitig spiegeln) und auf Realtime-UPDATE reconcilen. Bei Validation-Error vom Server: rollback + Toast. Macht das Spiel "snappier" auf flackrigen Mobilfunk-Verbindungen.

3. **Heartbeat / Idle-Cancel.** Nuxt hat keinen Cleanup für tote `OPEN`-Challenges. RN-Variante: Cron-Job im Backend (`backend/server/api/cron/`-Pattern existiert bereits) markiert OPEN-Challenges nach 30 min als CANCELLED, und ACTIVE-Challenges ohne Move seit 10 min ebenfalls. Entlastet die DB und verhindert Geister-Posts.

4. **Bonus**: `gameType` zum Enum machen statt `String @default("tictactoe")` — kleine Schema-Hygiene.

---

## 4. Risk-Assessment

| Risk | Severity | Mitigation |
|---|---|---|
| Realtime-Latenz auf Mobilfunk | mittel | Optimistic UI (siehe oben). 100-500 ms ist für TicTacToe/Memory ok (Async-Style). |
| Anti-Cheat / Move-Spoofing | niedrig | Server-authoritative ist bereits implementiert (Server prüft Turn + überprüft Board-State). RLS-Policies erlauben Updates nur für Teilnehmer — aber Updates passieren ohnehin via Service-Role-Backend, RLS ist nur für Realtime-Read. |
| Disconnect mid-game | mittel | Aktuell: Spiel "hängt" bis Spieler zurückkommt; kein Auto-Forfeit. Risk: Spieler quittet → Gegner stuck. Mitigation: Heartbeat + Auto-Cancel nach 10 min Inaktivität (Phase E Verbesserung) + UI-"Gegner offline"-Badge. |
| Plan-Tier-Gate | niedrig | Aktuell **kein** Plan-Check in den Endpoints — alle Auth-User können challengen. Falls Pro-Only gewünscht: in `challenge.post.ts` und `challenge-memory.post.ts` ein `requirePlan('pro')` einfügen (User-Decision). |
| Schema-Drift Nuxt vs Rebreak-Monorepo | mittel | Beide Projekte teilen physisch dieselbe DB (Schema `rebreak`). Solange beide Schemas synchron sind, kein Problem. Beim Cutover: Nuxt komplett deaktivieren, sonst race conditions auf `game_challenges`. |
| Realtime-Quota-Kosten | niedrig | Supabase Realtime hat ~200 concurrent connections im Pro-Plan. Bei 1v1 = 2 Subscriber/Match → erst ab 100 parallelen Matches problematisch. Monitoring per Supabase-Dashboard. |
| Memory-Game state.cards Größe | niedrig | 16 Cards JSON-Blob ~1 KB pro UPDATE → vernachlässigbar. |
| iOS Background WebSocket | mittel | iOS killed Realtime-Channels nach ~30 s im Background. Reconnect-on-resume zwingend (AppState-Listener). |

**Top-3 Risks:** 1) Disconnect mid-game ohne Auto-Forfeit; 2) iOS Background-WebSocket-Drop; 3) Schema-Drift während Übergangsphase Nuxt+RN parallel.

---

## 5. Open Questions an User

1. **Live oder Async?**
   Aktuelle Nuxt-Implementierung ist **Live** (Realtime + Same-Session). Empfehlung für RN: **Live beibehalten**, weil Netcode steht. Async-Wordle-Style würde komplette Re-Architektur erfordern (Push-Notifications, Move-Queue) und 2-3x Aufwand bedeuten.

2. **Random-Matchmaking vs Friends-only vs Community-Post?**
   Nuxt nutzt Community-Post (jeder kann annehmen, kein Friend-Graph). Optionen für RN:
   - **a)** Community-Post-Style portieren (braucht Community-View in RN — großer separater Task).
   - **b)** Public "Open Challenges"-Liste auf `/games`-Page (klein, schnell).
   - **c)** Share-Link-Invite (`rebreaknative://game/<id>` per Native-Share-Sheet — kein Browse nötig).
   - **d)** Random-Pool: Server-Side-Matchmaking (setzt 2 OPEN-Challenges paarweise zusammen — kein UI-Touch).
   → **User muss entscheiden.** Empfehlung: c + b kombiniert für MVP.

3. **Public Leaderboard mit Win-Rate-Stats?**
   `GameScore`-Tabelle existiert + `/api/games/ranking`-Endpoint. Frage: soll Leaderboard
   - **a)** in jedes Game integriert (aktueller Nuxt-Stand: Tab im `[challengeId].vue`),
   - **b)** als globale Page `/games/leaderboard`,
   - **c)** beides?

4. **Plan-Tier-Gate?** 1v1 für Free-Tier verfügbar oder Pro-Only? (DiGA-Relevanz unklar.)

5. **Anonymität:** Sollen Gegnernamen anonymisiert sein? Aktuell wird `nickname || username || "Anonym"` benutzt. DiGA-Datenschutz?

6. **User-Quit-Verhalten:** Wenn ein Spieler die App schließt mid-game — Forfeit nach X min, oder Spiel hängt offen? Empfehlung: Auto-Cancel nach 10 min Inaktivität, kein Forfeit (= kein Punkteabzug).

---

## 6. Migration-Aufwand-Summary

| Phase | Aufwand | Status |
|---|---|---|
| A — Backend-Endpoints | 0 h | bereits portiert |
| B — DB-Migrations | 1-2 h | Schema da, SQL-Audit nötig |
| C — RN-UI Game-Page + Lobby | 12-20 h | komplett neu |
| D — Realtime-Wiring | 2-3 h | im Rahmen C |
| E — Testing + Deploy | 4-6 h | manuelle 2-Device-Tests |
| **Gesamt** | **~20-30 h** | |

Plus optional: Community-View-Migration (separater Plan) für Community-Post-Style-Matchmaking.

---

*Doc-Version 1.0 — 2026-05-07 — `~/mono/rebreak-monorepo/ops/GAMES_1V1_MIGRATION_PLAN.md`*