nexus/modules/mining-checker/docs

Mining-Checker Modul

Zweck

Das Modul erfasst DOGE-Mining-Messpunkte, analysiert OCR-Vorschlaege aus Screenshots, speichert Messreihen projektbezogen und berechnet Performance-, Kurs- und Zielmetriken.

Ordnerstruktur

modules/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
• POST /api/mining-checker/v1/projects/{projectKey}/fx-refresh
• POST /api/mining-checker/v1/projects/{projectKey}/currencies-refresh
• GET /api/mining-checker/v1/projects/{projectKey}/fx-history

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

Der Endpunkt POST /api/mining-checker/v1/projects/{projectKey}/fx-refresh holt aktuelle Fiat-Wechselkurse von currencyapi.net und speichert sie in miningcheck_fx_rates.

Empfohlene Umgebungsvariablen:

• MINING_CHECKER_FX_PROVIDER=currencyapi
• MINING_CHECKER_FX_URL=https://currencyapi.net
• MINING_CHECKER_FX_CURRENCIES_URL=https://currencyapi.net
• MINING_CHECKER_FX_API_KEY=...
• MINING_CHECKER_FX_TIMEOUT=10
• MINING_CHECKER_FX_CACHE_TTL=21600
• 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 GET /api/v2/rates?base=...&output=json&key=... abgefragt. Aus dem Response werden base, rates und updated uebernommen; valid muss true sein. Die API liefert mehr Waehrungen als benoetigt, der Mining-Checker filtert lokal auf die angeforderten Zielwaehrungen und speichert die Kurse danach normalisiert in miningcheck_fx_fetches und miningcheck_fx_rates.

Pro Abruf entsteht genau ein Datensatz in miningcheck_fx_fetches mit Basiswaehrung, Provider und Stichtag. Alle Einzelkurse dieses Abrufs liegen darunter in miningcheck_fx_rates und teilen sich dieselbe fetch_id. Dadurch lassen sich Kurse innerhalb desselben Abrufs konsistent gegeneinander umrechnen.

Wenn fuer eine benoetigte Umrechnung noch kein passender FIAT-Fetch gespeichert ist, faellt der Mining-Checker auf vorhandene Kurs-Snapshots aus den Mining-Messpunkten (measurement_rates) zurueck.

Mit POST /api/mining-checker/v1/projects/{projectKey}/currencies-refresh kann die Waehrungstabelle einmalig oder bei Bedarf aus GET /api/v2/currencies?output=json&key=... synchronisiert werden. Dabei werden Code, Name, Symbol und Sortierung in miningcheck_currencies gespeichert.

Die im Tab Waehrungen ausgewaehlten Favoriten werden in miningcheck_settings.preferred_currencies gespeichert. Dadurch ist die Auswahl geraeteuebergreifend verfuegbar. Fuer bestehende Installationen ist dafuer einmal ein Schema-Upgrade noetig.