160 lines
9.9 KiB
Markdown
160 lines
9.9 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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, 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.
|
|
|
|
## 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.
|