diff --git a/README.md b/README.md index d032dfa..705c2d2 100644 --- 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