private/desktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
422331b32e9e3a8c997e18c22674e60f4d185474
desktop/custom/apps/mining-checker/docs/README.md
Lars Gebhardt-Kusche 422331b32e
All checks were successful
Deploy / deploy-staging (push) Successful in 1m6s
Details
Deploy / deploy-production (push) Has been skipped
Details
upgrade
2026-09-12 23:55:58 +02:00

14 KiB
Raw Blame History

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

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:

{
  "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. Der angezeigte bisherige Wert trennt variable Werte (Coins im Mining-Tool und Wallet zum aktuellen Kurs) von fixen Werten (bereits mit Krypto bezahlte Miner zum Ausgabezeitpunkt). Die Gesamtsumme besteht aus beiden Kategorien.
  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.

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.
Reference in New Issue View Git Blame Copy Permalink