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

9.3 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

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.

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, wird der ausgegebene Coin-Betrag mit dem fest vereinbarten Fallback 0,07 EUR pro Coin bewertet und dauerhaft gespeichert.
  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.

Verbindliche Fachregeln: Zielminer-ETA

  1. Die Zielminer-ETA basiert ausschliesslich auf dem letzten Mining-Upload, dessen Coin-Bestand und dessen durchschnittlicher Tagesrate (doge_per_day_interval, 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