diff --git a/README.md b/README.md index 116ae3c..8e80c32 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,207 @@ -# WP-Ingame-Shop-Pro +# WP Ingame Shop Pro – NO RCON & CUSTOM CURRENCY +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. + +## Features + +- 🛒 **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 + +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). + +## Admin-Bereich + +Nach der Aktivierung erscheint im Backend das Menü **„Ingame Shop“** mit mehreren Unterseiten. + +### Menüs + +- **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. + +### Globale Einstellungen + +Zu finden unter **Ingame Shop → Ingame Shop (Übersicht)**. + +- **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. + +## Custom Post Types & Metaboxen + +### Shop Items (`wis_item`) + +Unter **Ingame Shop → Items**. + +Metabox **„Item Einstellungen“**: + +- **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. + +Zusätzlich existiert eine Auto-Status-Logik, die beim Speichern `publish/draft` abhängig vom Preis setzt. + +### Server (`wis_server`) + +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. + +### Gutscheine (`wis_coupon`) + +Metabox **„Gutschein Einstellungen“**: + +- **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. + +Beim Speichern werden die Daten zusätzlich in der Tabelle `wp_wis_coupons` gespiegelt und `used_count` synchronisiert. + +Beim Löschen eines Gutschein-Posts wird der Eintrag aus `wp_wis_coupons` wieder entfernt. + +## REST API + +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. + +Alle REST-Endpunkte sind aktuell ohne Authentifizierung (`permission_callback => __return_true`), für öffentliche Nutzung sollte gegebenenfalls Absicherung ergänzt werden. + +## Frontend Shortcode + +Der Shop wird per Shortcode eingebunden: + +```text +[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. + +## Datenbank-Struktur + +### 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. + +### Tabelle `wp_wis_coupons` + +- `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. + +## 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`. + +## Bulk Import + +- 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. + +Für eine GitHub-README kannst du diesen Text direkt verwenden oder nur einzelne Abschnitte übernehmen und oben ggf. Screenshots/GIFs ergänzen.