# Mining-Checker Modul ## Zweck Das Modul erfasst Mining-Messpunkte der aktuell konfigurierten Kryptowaehrung, analysiert OCR-Vorschlaege aus Screenshots, speichert Messreihen projektbezogen und berechnet Performance-, Kurs- und Zielmetriken. `DOGE` ist lediglich die aktuelle Konfiguration, nicht eine fest verdrahtete Fachregel. Im Startseiten-Ueberblick zeigt die Kachel `DOGE Bestand` den direkten Wallet-Bestand, den nach Transfers bereinigten Miner-Bestand, deren Summe sowie den letzten Coin/USD-Kurs. Bei einer geaenderten Mining-Waehrung werden Beschriftung und Werte entsprechend dieser Waehrung gefuehrt. Der Kursverlauf verwendet pro Upload dessen gespeicherten Kurs und zugeordnete historische FX-Referenz. Uploads ohne Kurs werden nicht als Kurs `0` dargestellt. ## Ordnerstruktur ```text custom/apps/mining-checker/ |-- api/ |-- assets/ | |-- css/ | `-- js/ |-- config/ |-- docs/ |-- pages/ |-- partials/ |-- sql/ | `-- migrations/ |-- src/ | |-- Api/ | |-- Domain/ | |-- Infrastructure/ | `-- Support/ |-- storage/uploads/ |-- bootstrap.php `-- module.json ``` ## API-Endpunkte - `GET /api/mining-checker/v1/health` - `GET /api/mining-checker/v1/projects/{projectKey}/bootstrap` - `GET /api/mining-checker/v1/projects/{projectKey}/measurements` - `POST /api/mining-checker/v1/projects/{projectKey}/measurements` - `POST /api/mining-checker/v1/projects/{projectKey}/ocr-preview` - `GET /api/mining-checker/v1/projects/{projectKey}/settings` - `PUT /api/mining-checker/v1/projects/{projectKey}/settings` - `GET /api/mining-checker/v1/projects/{projectKey}/targets` - `POST /api/mining-checker/v1/projects/{projectKey}/targets` - `PATCH /api/mining-checker/v1/projects/{projectKey}/targets/{targetId}` - `GET /api/mining-checker/v1/projects/{projectKey}/dashboards` - `POST /api/mining-checker/v1/projects/{projectKey}/dashboards` - `GET /api/mining-checker/v1/projects/{projectKey}/dashboard-data` - `POST /api/mining-checker/v1/projects/{projectKey}/seed-import` - `GET /api/mining-checker/v1/projects/{projectKey}/schema-status` - `POST /api/mining-checker/v1/projects/{projectKey}/initialize` - `POST /api/mining-checker/v1/projects/{projectKey}/upgrade` - `GET /api/mining-checker/v1/projects/{projectKey}/connection-test` - `GET /api/mining-checker/v1/projects/{projectKey}/fx-history` - `POST /api/mining-checker/v1/projects/{projectKey}/legacy-fx-migrate` - `DELETE /api/mining-checker/v1/projects/{projectKey}/purchased-miners/{minerId}` ## Integration 1. SQL aus dem passenden Dialekt-Schema ausfuehren: - MySQL/MariaDB: `sql/schema.mysql.sql` - PostgreSQL: `sql/schema.pgsql.sql` - `sql/schema.sql` bleibt der Rueckfall fuer bestehende Setups 2. Das Modul nutzt bewusst dieselbe Projekt-Datenbank wie die Anwendung und legt seine Tabellen mit dem Praefix `miningcheck_` an. 3. Modulroute ueber `/module/mining-checker` aufrufen. 4. REST-API wird ueber `/api/mining-checker/...` vom Hauptprojekt geroutet. Hinweis: Wenn beim ersten API-Zugriff noch keine `miningcheck_*` Tabellen vorhanden sind, importiert das Modul automatisch das zum aktiven PDO-Treiber passende Schema. Seed-Daten werden dabei nicht automatisch eingespielt. Fuer eine manuelle Initialisierung, ein inkrementelles Upgrade oder einen Reset gibt es zusaetzlich `schema-status`, `upgrade` und `initialize`. Mit `{ "drop_existing": true }` werden vorhandene `miningcheck_*` Tabellen inklusive Daten geloescht und das Schema neu angelegt. ## OCR-Hinweis Das Modul unterstuetzt einen OCR-Provider-Stack. Standardmaessig wird zuerst `ocr.space` verwendet und danach optional auf lokales `tesseract` zurueckgefallen. Empfohlene Umgebungsvariablen: - `MINING_CHECKER_OCR_PROVIDERS=ocrspace,tesseract` - `MINING_CHECKER_OCR_SPACE_URL=https://api.ocr.space/parse/image` - `MINING_CHECKER_OCR_SPACE_API_KEY=...` - `MINING_CHECKER_OCR_SPACE_LANGUAGE=eng` - `MINING_CHECKER_OCR_SPACE_ENGINE=2` - `MINING_CHECKER_OCR_SPACE_SCALE=true` - `MINING_CHECKER_OCR_SPACE_DETECT_ORIENTATION=true` - `MINING_CHECKER_OCR_SPACE_IS_TABLE=false` - `MINING_CHECKER_OCR_SPACE_TIMEOUT=25` - `MINING_CHECKER_TESSERACT_BIN=/usr/bin/tesseract` - `MINING_CHECKER_TESSERACT_LANG=eng` Laut OCR.space-Doku wird `POST https://api.ocr.space/parse/image` mit `file`, Header-`apikey`, optional `language`, `scale`, `detectOrientation`, `isTable` und `OCREngine` verwendet. Der Modulparser wertet die OCR.space-Felder `ParsedResults`, `ParsedText`, `IsErroredOnProcessing`, `ErrorMessage` und `OCRExitCode` aus. Quellen: https://ocr.space/ocrapi ## Wechselkurse und Waehrungen Der Mining-Checker speichert keine eigenen FX-Snapshots mehr, sondern referenziert die `fetch_id` aus `fx-rates`. Auch der Waehrungskatalog und die bevorzugten Waehrungen kommen ausschliesslich aus `fx-rates`. Der Mining-Checker fuehrt keine eigene Waehrungstabelle und keine eigene Alias-Verwaltung mehr im Laufzeitpfad. - `MINING_CHECKER_FX_AUTO_FETCH_ON_MISS=false` Optionaler JSON-Body: - `base`: Standard `EUR` - `symbols`: wird aktuell ignoriert; der Mining-Checker speichert immer den kompletten Waehrungssatz des Fetches Beispiel: ```json { "base": "EUR" } ``` `currencyapi.net` wird ueber das Modul `fx-rates` abgefragt. Aus dem Response werden `base`, `rates` und `updated` uebernommen; `valid` muss `true` sein. Die eigentlichen Fetches und Raten liegen im Modul `fx-rates`. Pro Abruf entsteht genau ein Datensatz in `fx-rates` mit Basiswaehrung, Provider und Stichtag. Neue Mining-Messpunkte pruefen beim Speichern, ob ein neuer FX-Fetch noetig ist; falls nicht, wird nur ein Snapshot innerhalb des zulaessigen Zeitfensters wiederverwendet. Ein historischer Messpunkt darf niemals auf einen heutigen oder sonst zeitlich fernen Fetch verweisen. Falls noch historische Mining-Checker-Fetches in `miningcheck_fx_fetches` und `miningcheck_fx_rates` liegen, kann `POST /api/mining-checker/v1/projects/{projectKey}/legacy-fx-migrate` diese nach `fx-rates` ueberfuehren. Danach werden bestehende Messpunkte soweit moeglich auf die passende `fx_fetch_id` aktualisiert. Fuer Auswertungen, Berichte und Listen speichert der Mining-Checker pro Messpunkt die damals passende `fx_fetch_id`. Historische Umrechnungen laufen damit gegen genau den zugeordneten `fx-rates`-Snapshot. ## Miner-Basis und Zielminer Die Angebotsberechnung fuer Krypto-Miner nutzt eine konfigurierbare Basis fuer `50 kH/s` und `3 Monate`. Standard ist `5.49 USD`, kann aber in den Modul-Settings angepasst werden. Unabhaengig von aktiven Angebots-, Wallet-, Preis- oder Laufzeitfiltern bleibt der Krypto-Server mit `50 kH/s` und `36 Monaten` als Referenzangebot in der Miner-Angebotsliste sichtbar. Die Angebotsvorschau wird auch fuer die Startseite geladen; die Zielminer-Kachel verwendet deshalb denselben Angebotsdatensatz und dessen direkt berechneten Krypto-Preis. Der Walletbestand begrenzt weder Angebotsanzeige noch die Aktion `Mieten`, weil der Mietbetrag vor dem Speichern manuell angepasst werden kann. Zusaetzlich koennen in den Settings diese Leitwerte hinterlegt werden: - minimale gewuenschte Mietlaufzeit in Monaten - Zielminer-Hashrate in `kH/s` - Zielminer-Laufzeit in Monaten Die Uebersicht berechnet daraus automatisch den theoretischen Preis des Zielminers, den benoetigten Krypto-Gegenwert und die Resttage bis zur theoretischen Anmietung auf Basis des letzten Uploads. ## Verbindliche Fachregeln: Wallet, Miner und Wertentwicklung Diese Regeln sind bei jeder Erweiterung der Wallet-, Miner- oder Uebersichtslogik einzuhalten. 1. Ein Miner wird zu einem festen Zeitpunkt gemietet. Fiat-Mieten koennen bei Ablauf zum gleichen Preis verlaengert werden; Krypto-Mieten haben eine feste Laufzeit. 2. Erwirtschaftete Coins bleiben zuerst im Mining-Tool. Erst ein erfasster Transfer aus dem Mining-Tool erhoeht den Bestand des hier verfolgten Wallets. 3. Solange Coins im Mining-Tool oder im Wallet liegen, wird ihr Gegenwert mit dem aktuellen Kurs der jeweiligen Waehrung bewertet. 4. Wird ein Miner mit der Kryptowaehrung bezahlt, reduziert der Kauf den Walletbestand um den gezahlten Coin-Betrag. Gleichzeitig wird dessen Gegenwert zum Kaufzeitpunkt als feste Buchung gespeichert. Dieser Betrag darf durch spaetere Kursaenderungen nicht mehr beeinflusst werden. 5. Ein Wallet-Screenshot ist fuer seinen Zeitstempel autoritativ. Sein erkannter Hauptbestand ueberschreibt die rechnerische Wallet-Historie bis zu diesem Zeitpunkt; erst danach werden weitere Transfers, Krypto-Minerkaeufe und externe Wallet-Auszahlungen verrechnet. 6. Jede erfasste Auszahlung aus dem Mining-Tool muss den Walletbestand automatisch fortschreiben. Externe Auszahlungen aus dem hier verfolgten Wallet reduzieren ihn. 7. `Bisher verdient gesamt` trennt variable Werte (Coins im Mining-Tool und Wallet zum aktuellen Kurs) von fixen Werten (historischer Gegenwert bereits ausgezahlter und fuer Reinvest verwendeter Coins). Eine Krypto-Miete bleibt zugleich eine Ausgabe; ihr fixer Gegenwert darf in den Ausgaben und im fixen Verdienstteil jeweils nur einmal erscheinen. 8. Jede neue feste Krypto-Buchung referenziert die `fetch_id` des Moduls `fx-rates`. Der Mining-Checker fuehrt keine eigene Kurstabelle. Umrechnungen in andere Berichtswährungen verwenden fuer fixe Werte denselben historischen API-Snapshot. 9. Wird ein gemieteter Miner geloescht, wird sein kompletter Datensatz entfernt: Mietkosten, feste Krypto-Bewertung, FX-Referenz und der daraus abgeleitete Wallet-Abzug entfallen. Der Miner beeinflusst danach weder Walletbestand noch Ausgaben, Reinvest, Hashrate oder Break-even. Basis-Angebote, Mining-Uploads und andere Wallet-Buchungen bleiben unveraendert. 10. `Kosten/kH/s/Tag` ist ein laufzeitbereinigter Vergleichswert: feste historische Gesamtkosten geteilt durch die gesamte Hashrate einschliesslich Bonus und die exakten Kalendertage zwischen Mietzeitpunkt und Laufzeitende. Das Laufzeitende entsteht durch das Addieren der gebuchten Kalendermonate; bei kuerzeren Zielmonaten wird auf deren letzten Kalendertag begrenzt. Fuer Krypto-Mieten sind das `settled_value_amount / (Basis-Hashrate + Bonus-Hashrate) / Laufzeittage` in `settled_value_currency`; der aktuelle Coin-Kurs und ein Angebots-Referenzpreis duerfen diese Kennzahl nicht beeinflussen. Fuer FIAT-Mieten gilt derselbe Quotient mit dem tatsaechlich gezahlten FIAT-Betrag und dessen Zahlungswaehrung. 11. Die Startseitenkennzahl `Tageskosten` verteilt jede aktive Miete auf ihre exakte Kalenderlaufzeit (`Gesamtkosten / Kalendertage`) und beruecksichtigt keine bereits abgelaufenen Miner. Bei Krypto-Mieten verwendet sie den festen Mietwert und dessen zugeordnete historische `fx-rates.fetch_id`, nicht den aktuellen Coin-Kurs. Ein Tageswert fuer ein Angebot ohne Mietdatum wird nicht angezeigt, weil seine exakte Kalenderlaufzeit erst bei der Anmietung feststeht. ### Historische Krypto-Miner Beim Schema-Upgrade werden vorhandene Krypto-Miner einmalig bewertet: 1. Gibt es einen Referenzpreis in einer anderen Waehrung als der gezahlten Kryptowaehrung, wird dieser als historisch nachvollziehbarer, fester Gegenwert verwendet. 2. Fehlt eine belastbare historische Referenz, gilt verbindlich der Fallback `1 Coin = 0,07 USD`. Fuer die Euroanzeige ohne historischen Snapshot gilt verbindlich `1 Coin = 0,068 EUR`. Diese beiden Fallbacks sind feste historische Werte und duerfen nicht mit einem aktuellen Wechselkurs weitergerechnet werden. 3. Die feste Bewertung wird in `settled_value_amount`, `settled_value_currency` und bei neuen Buchungen zusaetzlich in `settled_fx_fetch_id` des jeweiligen gekauften Miners gespeichert. Das Schema-Upgrade ist nach dem Deployment auszufuehren. ### Pflicht fuer neue Finanzdaten Jede neu gespeicherte Buchung, die einen Kurs oder eine Waehrungsumrechnung benoetigt, muss die verwendete `fx-rates.fetch_id` gemeinsam mit Betrag, Quellwaehrung und Zielwaehrung speichern. Ein aktueller Kurs darf ausschliesslich fuer variable, noch gehaltene Bestaende verwendet werden. Fehlt fuer eine neue feste Buchung ein FX-Snapshot, muss der Speichervorgang fehlschlagen; ein stiller Fallback ist nicht erlaubt. ### Historische Nachtraege Ein belegter, nachtraeglich erfasster Mining-Stand verwendet seinen tatsaechlichen Zeitpunkt, nicht den Speicherzeitpunkt. Der manuelle Messpunkt besitzt deshalb ein optionales Feld `Zeitpunkt`; bleibt es leer, wird der aktuelle Zeitpunkt verwendet. Fuer eine unvollstaendige Upload-Phase werden die belegbaren Ereignisse einzeln und chronologisch erfasst: 1. Krypto-Miete mit Zeitpunkt, tatsaechlichem Coin-Preis, Laufzeit, Hashrate inklusive Bonus und dem historischen FX-Snapshot. 2. Transfer aus dem Mining-Tool in das Wallet mit Zeitpunkt und Coin-Menge. 3. Wallet-Snapshot mit dem tatsaechlichen Wallet-Bestand; dieser ist ab seinem Zeitpunkt autoritativ. 4. Mining-Messpunkt mit Screenshot-Zeitpunkt, Miner-Bestand und dem im Screenshot angezeigten Kurs. Fehlt ein exakter historischer FX-Snapshot, darf eine feste Krypto-Ausgabe nicht mit einem aktuellen Kurs gespeichert werden. Der fehlende historische Snapshot muss zuerst aus einer nachpruefbaren externen Quelle in `fx-rates` vorliegen; der Beleg oder Screenshot bleibt als Notiz am Nachtrag erhalten. Fuer zusammenhaengende, belegbare Ausfaelle steht der Bereich `Nachtragen` bereit. Er legt zuerst einen historischen `fx-rates`-Snapshot an und speichert danach in fester Reihenfolge Krypto-Miete, Mining-Tool-Transfer, Wallet-Snapshot und Mining-Messpunkt. Wiederholte Ausfuehrung des Assistenten verwendet den FX-Snapshot mit identischem Zeitpunkt erneut. Die fachlichen Buchungen selbst duerfen nach einer erfolgreichen Ausfuehrung nicht erneut gestartet werden, damit keine doppelten Miner oder Transfers entstehen. Kursnotierung und Speicherung werden getrennt behandelt: Die Eingabe `DOGE/USD` ist USD pro DOGE. Ein `fx-rates`-Snapshot mit Basis USD speichert dagegen DOGE pro USD, also den Kehrwert. Der Nachtrag-Assistent erledigt diese Umrechnung vor dem Speichern. `Nur historischen FX/Miner korrigieren` repariert ausschliesslich diesen Snapshot und die feste Bewertung eines bereits angelegten passenden Miners; Transfers und Messpunkte werden dabei nicht erneut angelegt. ## Break-even Der Gesamt-Break-even verwendet die Summe aus Fiat-Investitionen und `Reinvest fix` gegen aktuelle, noch gehaltene Miner- und Walletbestaende. Krypto-Reinvestitionen muessen immer den historischen festen Gegenwert aus dem zugeordneten `fx-rates`-Snapshot verwenden; eine Bewertung zum aktuellen Coin-Kurs ist unzulässig. ## Verbindliche Fachregeln: Zielminer-ETA 1. Die Zielminer-ETA basiert ausschliesslich auf dem letzten Mining-Upload, dessen Coin-Bestand und dem Durchschnitt seit dem letzten Transfer (`doge_per_day_since_last_payout`, technisch historisch benannt). 2. Die absolute ETA lautet: `Zeitpunkt letzter Upload + (am Upload fehlende Coins / durchschnittliche Coins pro Tag)`. 3. Die angezeigte Restzeit ist die Differenz zwischen dieser festen ETA und der aktuellen Zeit. Sie muss bis zum naechsten Upload weiter herunterlaufen und darf nicht durch eine Neuberechnung ab der aktuellen Zeit nach hinten verschoben werden. 4. Ein neuer Upload ersetzt die Berechnungsbasis durch seinen dann aktuellen Bestand und seinen neu ermittelten Durchschnitt. 5. Die Begriffe `DOGE pro Tag` in historischen Feldern sind technische Altbezeichnungen. Fachlich beziehen sie sich immer auf die aktuell konfigurierte Mining-Kryptowaehrung.