README.md aktualisiert

2026-02-15 09:58:25 +00:00
parent 10f2a66e3a
commit 48648c5632
1 changed files with 336 additions and 159 deletions
--- a/README.md
+++ b/README.md
@@ -1,205 +1,382 @@
-# WP Ingame Shop Pro – NO RCON & CUSTOM CURRENCY
+# WP Ingame Shop Pro

-Vollautomatischer, Minecraft-basierter Ingame-Shop für WordPress mit Warenkorb, Daily Deal, Kategorien, Gutscheinen und eigenem Währungssystem – komplett ohne RCON, ideal für Bungee-/Proxy-Setups mit externer Ingame-Bestätigung. 
+Ein leistungsstarker, vollständig eigenständiger Ingame-Shop für WordPress, entwickelt für Minecraft-Server (Spigot/Paper).  
+Er bietet ein komfortables Warenkorb-System, Gutscheine, Daily Deals und eine benutzerdefinierte Währung – komplett ohne RCON.

-## Features
+Dieses Plugin nutzt eine eigene Datenbankstruktur für maximale Performance und vollständige Unabhängigkeit von WordPress-Beiträgen.

- 🛒 **Warenkorb-System**: Spieler können mehrere Items gleichzeitig kaufen, alles wird als eine Bestellung in der Datenbank gespeichert. 
- 💾 **Saubere Order-Struktur**: Eine Bestellung = eine Zeile in `wp_wis_orders` mit JSON-Detaildaten (Items + Gutschein). 
- 📋 **Detail-Ansicht im Backend**: Übersicht wie „1x Diamant, 64x Stein“ inkl. Gutschein und Debug-JSON. 
- 💰 **Eigene Währung**: Frei konfigurierbarer Währungsname (z. B. Coins, Tokens) statt Euro. 
- 🖼️ **Auto-Itembilder**: Bilder werden automatisch aus einer Basis-URL + Item-ID (`minecraft:diamond` → `minecraft_diamond.png`) generiert. 
- 🔥 **Angebote & Sales**: Items können als Angebot markiert und mit eigenem Angebots-Preis versehen werden. 
- 🎁 **Daily Deal**: Automatisches „Angebot des Tages“ mit frei einstellbarem prozentualem Rabatt, gesteuert über Cron. 
- 🎫 **Smart Coupons**: Gutscheine als Festbetrag oder Prozent, optional keine Wirkung auf Angebot-Items (Sale). 
- 🏷️ **Kategorien**: Eigene Taxonomie `wis_category` mit Backend-Tabs/Filter im Shop-Frontend. 
- 🏆 **Top Spender**: Statistikseite mit Summe aller abgeschlossenen/cancelled Orders pro Spieler. 
- 🌐 **REST API**: Endpoints für Orders, Pending Orders, Ausführung, Abschluss, Storno, Gutscheinprüfung und Bulk-Import. 
- 📥 **Bulk-Import**: JSON-Import von Items (z. B. von `minecraft-ids.com`) in Batches inkl. Fortschrittsanzeige. 
- 🧹 **Bulk Delete**: Massenlöschung für Items, Server und Gutscheine mit Admin-Notice. 
- 🎮 **Ingame-Integration ready**: Orders werden über REST abgeholt und serverseitig (z. B. Plugin/Bot) bestätigt, kein RCON notwendig. 
+---

-## Installation
+## ✨ Highlights

-1. Plugin-Datei (`wp-ingame-shop-pro.php` o. ä.) in den Ordner `wp-content/plugins/wp-ingame-shop-pro` legen.   
-2. Im WordPress-Backend unter „Plugins“ das Plugin **aktivieren**.  
-3. Bei Aktivierung werden automatisch die Tabellen `wp_wis_orders` und `wp_wis_coupons` erstellt sowie Cron-Events für den Daily Deal registriert.  
-4. Cron muss auf dem Server funktionieren (WP-Cron oder System-Cron, der `wp-cron.php` triggert). 
+- 🛒 **Warenkorb-System**  
+  Mehrere Items pro Bestellung.  
+  Eine Bestellung = eine saubere Datenbankzeile mit JSON-Details.

-## Admin-Bereich
+- ⚡ **Mehrfachbearbeitung (Bulk Edit)**  
+  Hunderte Items gleichzeitig bearbeiten (Preis, Server, Kategorie, Status).

-Nach der Aktivierung erscheint im Backend das Menü **„Ingame Shop“** mit mehreren Unterseiten. 
+- 💰 **Eigene Währung**  
+  „Coins“, „Tokens“ oder beliebige virtuelle Währungen.

-### Menüs
+- 🖼️ **Automatische Bildzuweisung**  
+  `minecraft:diamond` → `minecraft_diamond.png`  
+  Ideal für große Bildsammlungen (1500+ Dateien).

- **Ingame Shop (Übersicht)**  
-  - Globale Einstellungen, Feature-Übersicht, Bulk-Import. 
- **Bestellungen**  
-  - Liste aller Orders, Detailansicht, manuelles Löschen/Abschließen. 
- **Top Spender**  
-  - Rangliste nach ausgegebenen Coins (inkl. Anzahl Bestellungen). 
- **Items** (CPT `wis_item`)  
-  - Verwaltung der Shop-Items inkl. Preis, Serverzuordnung, Kategorie, Angebot, Daily Deal. 
- **Kategorien** (`wis_category`)  
-  - Hierarchische Kategorien für Items (werden im Frontend als Tabs angezeigt). 
- **Servers** (CPT `wis_server`)  
-  - Reine Serverdefinition (Name/Slug), dient zur Filterung und Zuordnung im Shop. 
- **Gutscheine** (CPT `wis_coupon`)  
-  - Verwaltung von Gutscheincodes inkl. Typ, Wert, Limit, Ablaufdatum. 
+- 🔥 **Daily Deal & Sale-System**

-### Globale Einstellungen
+- 🎫 **Smart Coupons**  
+  Prozent- oder Festbetrag, optional nicht kombinierbar mit Angeboten.

-Zu finden unter **Ingame Shop → Ingame Shop (Übersicht)**. 
+- 🌐 **REST API ohne RCON**

- **Shop Header Text**  
-  - Text im grünen Info-Balken im Frontend, leer = kein Balken. 
- **Währungsname**  
-  - Anzeigeeinheit für Preise, z. B. „Coins“. 
- **Bilder Basis-URL**  
-  - Basis-URL, an die `ITEM_ID.png` angehängt wird, z. B. `https://assets.minecraft-ids.com/1_21_10/`. 
- **Gutscheine bei Angeboten ausschließen**  
-  - Wenn aktiviert, wirken Gutscheine nur auf normale Items, nicht auf als Angebot markierte Items. 
- **Daily Deal aktivieren + Rabatt (%)**  
-  - Aktiviert den täglichen Cron, der ein zufälliges Item (mit Preis > 0, bisher kein Daily Deal) auswählt und rabattiert. 
+- 📊 **Top-Spender & Umsatzstatistik**

-## Custom Post Types & Metaboxen
+---

-### Shop Items (`wis_item`)
+## 🚀 Installation

-Unter **Ingame Shop → Items**. 
+1. Ordner `wp-ingame-shop-pro` nach:

-Metabox **„Item Einstellungen“**: 
+wp-content/plugins/

- **Status-Anzeige**  
-  - Zeigt an, ob das Item aktiv im Shop ist (publish + Preis > 0) oder inaktiv. 
- **Preis (Coins)**  
-  - Integer > 0 macht das Item automatisch aktiv (Status publish), 0 schaltet auf Entwurf. 
- **Item ID (z. B. `minecraft:diamond`)**  
-  - Wird für die Bild-URL und das JSON-Payload (Ingame-Give) verwendet. 
- **Kategorie(n)**  
-  - Checkbox-Liste aller `wis_category`-Terms, beeinflusst die Tabs im Frontend. 
- **Daily Deal (Angebot des Tages)**  
-  - Option „manuell als Angebot des Tages setzen“, überschreibt die Automatik bis Mitternacht. 
- **Angebot / Sale**  
-  - Checkbox „Als Angebot markieren 🔥“ + optionaler Angebots-Preis. 
-  - Angebots-Preis wird angezeigt, normaler Preis durchgestrichen. 
- **Beschreibung**  
-  - Langtext, der im Frontend unter dem Titel angezeigt wird. 
- **Server zuweisen**  
-  - Checkbox-Liste aller definierten `wis_server`, steuert Sichtbarkeit und Kaufbarkeit pro Server. 
+2. Plugin im WordPress Backend aktivieren.  
+3. Fertig.

-Zusätzlich existiert eine Auto-Status-Logik, die beim Speichern `publish/draft` abhängig vom Preis setzt. 
+Bei Aktivierung werden automatisch erstellt:

-### Server (`wis_server`)
+- Datenbanktabellen (`wp_wis_*`)
+- Cron-Jobs für Daily Deals

-Metabox „Server Einstellungen“ zeigt nur einen Hinweis, dass keine RCON-Daten notwendig sind. 
+---

- Der **Post-Slug** des Servers wird als Server-ID im Frontend/REST verwendet. 
+# 🖼️ Bilder-Konfiguration (Gitea Raw)

-### Gutscheine (`wis_coupon`)
+## 📂 Basis-URL für alle Item-Bilder

-Metabox **„Gutschein Einstellungen“**: 
+```
+https://git.viper.ipv64.net/M_Viper/WP-Ingame-Shop-Pro/raw/branch/main/images/
+```

- **Gutschein Code** (wird automatisch in Großbuchstaben gespeichert). 
- **Rabattart**: „Festbetrag“ oder „Prozentual“. 
- **Wert**: Coins oder Prozent, abhängig vom Typ. 
- **Nutzungslimit**: Wie oft der Gutschein eingelöst werden darf. 
- **Ablaufdatum** (optional). 
- Hinweis, wenn global eingestellt ist, dass Gutscheine bei Angeboten nicht gelten. 
+### 🔧 Eintragen im Plugin

-Beim Speichern werden die Daten zusätzlich in der Tabelle `wp_wis_coupons` gespiegelt und `used_count` synchronisiert. 
+**Ingame Shop → Einstellungen → Bilder Basis-URL**

-Beim Löschen eines Gutschein-Posts wird der Eintrag aus `wp_wis_coupons` wieder entfernt. 
+Eintragen:

-## REST API
+```
+https://git.viper.ipv64.net/M_Viper/WP-Ingame-Shop-Pro/raw/branch/main/images/
+```

-Alle Routen liegen unter `wis/v1/…`. 
+---

- `POST /wis/v1/order`  
-  - Erstellt eine neue Bestellung.   
-  - Request-Body: `{ player, cart: [{id, quantity}], server, coupon_code? }`.   
-  - Validiert Items (Preis > 0, Serverzuordnung, Angebot/Normal, Gutscheinlogik) und speichert Order inkl. JSON mit realen Item-IDs und ggf. Gutschein-Rabatt. 
- `GET /wis/v1/pending_orders?player=Name`  
-  - Liefert bis zu 10 offene Bestellungen (`status = pending`) eines Spielers. 
- `POST /wis/v1/execute_order`  
-  - Setzt Status einer Bestellung auf `processing` (z. B. wenn der Ingame-Executor mit der Ausgabe beginnt). 
- `POST /wis/v1/complete_order`  
-  - Setzt Status auf `completed`. 
- `POST /wis/v1/cancel_order`  
-  - Setzt Status auf `cancelled`. 
- `POST /wis/v1/validate_coupon`  
-  - Prüft einen Gutschein gegen aktuelle Cart-Daten (inkl. „nur normale Items“ Logik) und liefert Typ, Wert und Message. 
- `POST /wis/v1/fetch_remote_data`  
-  - Lädt JSON von externer URL (z. B. `https://minecraft-ids.com/data/1.21.10.json`) und gibt eine normalisierte Items-Liste zurück. 
- `POST /wis/v1/import_batch`  
-  - Importiert ein Items-Array als `wis_item`-Posts (draft, `_wis_item_id`, `_wis_price` = 0), überspringt Duplikate. 
+## 📌 Automatische Bildlogik

-Alle REST-Endpunkte sind aktuell ohne Authentifizierung (`permission_callback => __return_true`), für öffentliche Nutzung sollte gegebenenfalls Absicherung ergänzt werden. 
+Item-ID im Shop:

-## Frontend Shortcode
+```
+minecraft:diamond
+```

-Der Shop wird per Shortcode eingebunden: 
+Automatisch geladen wird:

-```text
+```
+https://git.viper.ipv64.net/M_Viper/WP-Ingame-Shop-Pro/raw/branch/main/images/minecraft_diamond.png
+```
+
+Regeln:
+
+- `:` wird zu `_`
+- Dateiendung = `.png`
+- Keine manuelle Bildzuweisung notwendig
+
+---
+
+# 📥 Quick JSON Import (Direkt von Gitea)
+
+## 🔗 Import-URL
+
+```
+https://git.viper.ipv64.net/M_Viper/WP-Ingame-Shop-Pro/raw/branch/main/items.json
+```
+
+---
+
+## 🛠️ Import durchführen
+
+1. **Ingame Shop → JSON Tools**
+2. **Import**
+3. URL einfügen
+4. Import starten
+
+Ideal für:
+
+- Kompletten Shop-Aufbau in Sekunden
+- Regelmäßige Synchronisation
+- Kombination mit Bulk Edit
+
+---
+
+# 🛠️ Admin-Bereich
+
+## 1️⃣ Einstellungen
+
+- Shop Header Text
+- Währungsname (z.B. Coins)
+- Bilder Basis-URL
+- Daily Deal (% Rabatt)
+- Gutscheine auf Sale-Items erlauben / verbieten
+
+---
+
+## 2️⃣ Items Verwaltung
+
+### Einzelbearbeitung
+
+- Item ID (`minecraft:diamond`)
+- Preis
+- Angebotspreis
+- Server-Zuweisung
+- Kategorie
+- Status (`publish` / `draft`)
+
+---
+
+## 🔄 Bulk Edit (Mehrfachbearbeitung)
+
+Beispiel: 100 Items einem Server zuweisen.
+
+1. Items anhaken  
+2. „Massenaktionen“ wählen:
+   - Server zuweisen
+   - Preis ändern
+   - Kategorie setzen
+   - Status ändern  
+3. Anwenden  
+4. Änderungen speichern  
+
+Überschreibt bestehende Server-/Kategorie-Zuweisungen.
+
+---
+
+## 3️⃣ Weitere Bereiche
+
+### 📦 Bestellungen
+
+- Bestellungen anzeigen
+- Manuell abschließen
+- Stornieren
+
+Status:
+
+```
+pending
+processing
+completed
+cancelled
+```
+
+---
+
+### 🌐 Server
+
+Beispiel:
+
+```
+lobby
+survival
+skyblock
+```
+
+Frontend-Filter werden automatisch generiert.
+
+---
+
+### 📂 Kategorien
+
+Beispiel:
+
+```
+Blöcke
+Waffen
+Rüstung
+Ranks
+```
+
+---
+
+### 🎫 Gutscheine
+
+- `fixed` (Festbetrag)
+- `percent` (Prozent)
+- Ablaufdatum
+- Nutzungslimit
+- Ausschluss bei Angeboten
+
+---
+
+### 📊 Top Spender
+
+Automatische Auswertung der Bestellungen.
+
+---
+
+# 🎮 Frontend Nutzung
+
+Shortcode:
+
+```
 [ingame_shop_form]
 ```

-## Layout & Funktionen
+---

- Modernes Grid mit Karten (Bild, Name, Preis, Server, Badges, Menge).  
- Filter: Suche, „Nur Angebote“, Server-Auswahl und Kategorie-Tabs.  
- Badges:  
-  - „🔥 Angebot“ für Sale-Items.  
-  - „🎁 Angebot des Tages“ für den aktiven Daily Deal.  
- Mengensteuerung je Item (Buttons + Input).  
- Warenkorb-Button (Badge mit Gesamtanzahl der Items) öffnet ein Modal.  
- Gutscheincode-Feld im Checkout mit Live-Validierung via `validate_coupon`.  
- Dynamische Berechnung:  
-  - Normaler Teil des Warenkorbs, ggf. rabattiert.  
-  - Angebots-Items, die optional von Gutscheinen ausgenommen sind.  
- Validierung:  
-  - Alle ausgewählten Items müssen für den gewählten Server freigeschaltet sein.  
-  - Spielername und Server sind Pflichtfelder.  
- Beim Abschließen des Kaufs wird `POST /wis/v1/order` aufgerufen, die Antwort wird im Modal angezeigt und der Warenkorb geleert.  
+## Spieler-Funktionen

-## Datenbank-Struktur
+- Suche
+- Server-Filter
+- Kategorie-Tabs
+- Warenkorb
+- Gutschein-Eingabe
+- Server-Validierung beim Checkout

-### Tabelle `wp_wis_orders`
+---

- `id` – Auto-Increment.  
- `player_name` – Spielername.  
- `server` – Server-Slug (`wis_server` Postname).  
- `item_id` – Hier für den Warenkorb pauschal `multi_item_cart`.  
- `item_title` – Lesbare Zusammenfassung (z. B. „Warenkorb: 1x Diamant, 64x Stein…“).  
- `price` – Endpreis nach Rabatt.  
- `quantity` – Anzahl der unterschiedlichen Items im Warenkorb.  
- `status` – `pending`, `processing`, `completed`, `cancelled`, `failed`.  
- `response` – JSON mit `items` (real Item IDs + Mengen) und optionalem `coupon`.  
- `created_at` – Timestamp.  
+# 📡 REST API

-### Tabelle `wp_wis_coupons`
+Basis:

- `id` – Auto-Increment.  
- `code` – Gutschein-Code (unique).  
- `value` – Wert (Coins oder Prozent).  
- `type` – `fixed` oder `percent`.  
- `usage_limit` – Maximal verwendbar.  
- `used_count` – Bisherige Verwendung.  
- `expiry` – Ablaufdatum.  
- `created_at` – Timestamp.  
+```
+/wp-json/wis/v1/
+```

-## Cron & Daily Deal
+---

- Beim Aktivieren wird ein tägliches Event `wis_daily_deal_event` registriert.  
- Callback `WIS_Activator::run_daily_deal()`:  
-  - Deaktiviert das aktuelle Daily-Deal-Item (`_wis_daily_deal` → 0).  
-  - Wählt ein random `wis_item` mit `_wis_price > 0` und ohne `_wis_daily_deal`-Meta.  
-  - Berechnet den Rabatt basierend auf `wis_daily_deal_discount` und setzt `_wis_is_offer` + `_wis_offer_price`.  
+## Bestellung erstellen

-## Bulk Import
+```
+POST /wis/v1/order
+```

- Im Admin-Overview vorhanden.  
- Eingabefeld für die Import-URL (Default: `https://minecraft-ids.com/data/1.21.10.json`).  
- Button „Daten laden“ → lädt via REST `fetch_remote_data` und zeigt Anzahl Items an.  
- Button „Import starten“ → ruft wiederholt `import_batch` mit Batches von 20 Items auf und zeigt Fortschritt an.  
- Vorhandene Items (gleiche `_wis_item_id`) werden übersprungen, neue Items als Draft mit Preis 0 angelegt.  
+```json
+{
+  "player": "Name",
+  "server": "survival",
+  "cart": [
+    { "id": "item_id", "quantity": 1 }
+  ],
+  "coupon_code": "CODE"
+}
+```
+
+---
+
+## Offene Bestellungen abrufen
+
+```
+GET /wis/v1/pending_orders?player=Name
+```
+
+---
+
+## Status ändern
+
+```
+POST /wis/v1/execute_order
+POST /wis/v1/complete_order
+POST /wis/v1/cancel_order
+```
+
+---
+
+## Gutschein validieren
+
+```
+POST /wis/v1/validate_coupon
+```
+
+---
+
+# 💾 Datenbank-Struktur
+
+## `wp_wis_items`
+
+| Feld | Beschreibung |
+|------|-------------|
+| item_id | minecraft:diamond |
+| name | Anzeigename |
+| price | Standardpreis |
+| offer_price | Angebotspreis |
+| is_offer | 0 / 1 |
+| servers | JSON Array |
+| categories | JSON Array |
+| status | publish / draft |
+
+---
+
+## `wp_wis_orders`
+
+| Feld | Beschreibung |
+|------|-------------|
+| player_name | Minecraft Name |
+| server | Zielserver |
+| item_title | Zusammenfassung |
+| price | Gesamtpreis |
+| response | JSON |
+| status | pending / processing / completed / cancelled |
+
+---
+
+## `wp_wis_coupons`
+
+| Feld | Beschreibung |
+|------|-------------|
+| code | Gutschein |
+| type | fixed / percent |
+| value | Rabattwert |
+| usage_limit | Limit |
+| used_count | Nutzung |
+
+---
+
+## `wp_wis_servers`
+
+Serverdefinitionen
+
+---
+
+## `wp_wis_categories`
+
+Kategoriedefinitionen
+
+---
+
+# ⚡ Performance Empfehlung
+
+Bei 1500+ PNG-Dateien:
+
+- CDN empfohlen
+- PNG verlustfrei komprimieren
+- Gitea Caching aktivieren
+- Optional WebP-Versionen erstellen
+
+---
+
+# 🔐 Sicherheitshinweis
+
+Aktuell sind API-Endpunkte öffentlich (`__return_true`).
+
+Für Produktion empfohlen:
+
+- API-Key Header
+- Bearer Token
+- IP Whitelisting
+- Nonce/Signature System
+
+---
+
+# 📦 Meta
+
+Version: 2.1.0  
+Autor: M_Viper  
+Lizenz: GPL-2.0-or-later