private/desktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
49ea6bde76abc9cbd45352f053ff092481825833
desktop/custom/apps/mining-checker/docs/README.md
Lars Gebhardt-Kusche 49ea6bde76
All checks were successful
Deploy / deploy-staging (push) Successful in 32s
Details
Deploy / deploy-production (push) Has been skipped
Details
ysdsd
2026-08-21 23:58:03 +02:00

12 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.

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 die letzte passende fetch_id wiederverwendet.

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.

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 Laufzeit in Tagen (Monate x 30,4375). 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 Laufzeit (Gesamtkosten / Laufzeittage) 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.

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.

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