# Sommer Stickerheft (Silkroad)

Ein digitales "Stickerheft" fuer den Silkroad-Server. Spieler sammeln durch
**In-Game-Aktionen** Sticker, die sich zu Heft-Seiten zusammensetzen. Ist eine
Seite voll, kann der Spieler die Belohnung **abholen** – dabei wird eine
hinterlegte **Stored Procedure mit der CharID** ausgefuehrt.

Technisch baut das Projekt 1:1 auf der Architektur des WM2026-Tippspiels auf
(PHP + MS SQL Server, Identitaets-View, Key-Login bei jedem Request,
Admin-Panel ueber CharID-Whitelist).

## Aufbau

```
config/config.php        Zugangsdaten, Branding, DEV-Modus, Identity-View
src/app.php              Request-Zustand (Config, User, Admin)
src/db.php               PDO/sqlsrv-Verbindung + Query-Helfer
src/identity.php         Key -> CharID -> UserJID -> Name (ueber die View)
src/helpers.php          Ausgabe, URLs, CSRF, Flash, Bild-Helfer
src/stickers.php         Kernlogik: sync(), loadBook(), claim()
public/index.php         Das Stickerheft (Seiten, Sticker, Belohnung abholen)
public/admin.php         Seiten/Sticker verwalten, Vergabe testen, Claims, Accounts
public/assets/           CSS, JS, Upload-Ordner fuer Bilder
sql/01..04               Datenbank, View, Sticker-Bruecke, Beispieldaten
```

## Wie ein Sticker ins Heft kommt

1. Eine In-Game-Aktion (Quest/Boss/Kauf ...) ruft im Spiel auf:

   ```sql
   EXEC SummerBook.dbo.sp_GrantSticker @CharID = 1234,
                                       @StickerCode = 'beach_ball',
                                       @Source = N'Boss XY';
   ```

2. Das traegt eine Zeile in `dbo.sticker_grants` ein.
3. Beim naechsten Aufruf des Hefts uebernimmt `Stickers::sync()` den Sticker
   in das Heft des Spielers (`dbo.user_stickers`).

`@StickerCode` muss dem Feld `dbo.stickers.code` entsprechen (im Admin-Panel
je Sticker vergeben).

## Wie die Belohnung vergeben wird

Pro Seite hinterlegst du im Admin-Panel den **Namen einer Stored Procedure**
(Feld *Reward-Prozedur*, z.B. `dbo.sp_Reward_Page1`). Beim Abholen ruft das
Heft sie mit der CharID als erstem Parameter auf:

```sql
EXEC dbo.sp_Reward_Page1 1234;   -- 1234 = CharID
```

Die Prozedur muss als **ersten Parameter die CharID (INT)** entgegennehmen.
Trage darin deine echte Belohnungs-Logik ein (Item ins Inventar/Lager, Silk
gutschreiben, Gift-Code erzeugen ...). Eine lauffaehige Vorlage
(`sp_Reward_Page1`, schreibt nur einen Log-Eintrag) liegt in
`sql/03_grant_bridge.sql`.

Sicherheiten beim Abholen:
- nur moeglich, wenn die Seite serverseitig wirklich vollstaendig ist,
- nur **einmal** pro Spieler/Seite (`UNIQUE(user_id, page_id)`),
- wirft die Prozedur einen Fehler, wird **kein** Claim gesetzt – der Spieler
  kann es erneut versuchen.

## Einrichtung

1. **Datenbank anlegen** – die SQL-Skripte in Reihenfolge ausfuehren (SSMS, als `sa`):
   ```
   sql/01_create_database.sql   -- DB + Tabellen
   sql/02_identity_view.sql     -- Identitaets-View (Cross-DB-Join)
   sql/03_grant_bridge.sql      -- sp_GrantSticker + Reward-Vorlage
   sql/04_seed_example.sql      -- optional: 6 Beispielseiten
   ```
   Falls die Spalten der Spiel-Tabellen abweichen, in `02_identity_view.sql`
   die markierten Spalten anpassen.

2. **config/config.php** pruefen: DB-Zugang, `site_name`, `admin_char_ids`.
   Fuer den Produktivbetrieb `dev_mode => false` setzen.

3. **IIS-Site** mit physischem Pfad auf den Ordner `public/` zeigen lassen
   (so liegen `config/`, `src/`, `sql/` ausserhalb des Web-Roots).
   Der Anwendungspool braucht Schreibrechte auf `public/assets/uploads/`,
   damit der Bild-Upload funktioniert.

4. **Test** im DEV-Modus: `index.php?Key=DEV-1001` oeffnen. Im Admin-Tab
   „Sticker testen" lassen sich Sticker vergeben, um das Heft durchzuspielen.

## Anpassen

- **Seiten & Sticker**: komplett ueber das Admin-Panel (Anzahl Sticker pro
  Seite ist frei – Seite 1 = 3, Seite 5 = 6 usw.).
- **Reward-Foto**: pro Seite hochladen oder als URL/Pfad angeben.
- **Sticker-Bilder**: optional je Sticker hinterlegen (sonst Platzhalter mit
  Anfangsbuchstabe).