Nexus upgrade design and refresh

2026-04-11 01:23:28 +02:00
parent 9d5bb2d3cf
commit e83925ba64
53 changed files with 13388 additions and 60 deletions
--- a/modules/mining-checker/docs/README.md
+++ b/modules/mining-checker/docs/README.md
@@ -0,0 +1,125 @@
+# 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
+
+```text
+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:
+
+```json
+{
+  "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.