primo commit

2026-09-23 18:59:27 +02:00
parent 029e9f67fb
commit bd900099a0
451 changed files with 143273 additions and 2 deletions
@@ -1,3 +1,132 @@
-# ogame_db
+# OGame Galaxy Viewer

-Piattaforma web come il vecchio galaxy tool
+> 📖 Documentazione tecnica completa (architettura, sorgenti, funzioni e metodi): **[DOCUMENTAZIONE.md](DOCUMENTAZIONE.md)**
+
+Visualizzatore di galassie per OGame con archivio dei rapporti di spionaggio.
+
+- Universo configurato: **Rosalind `s170-ar`** (galassie 1-7, sistemi 1-499)
+- Dati pubblici (pianeti, giocatori, alleanze) scaricati ogni giorno
+- Import di rapporti di spionaggio tramite **API string** del gioco
+  (`sr-ar-170-<40 hex>`) con salvataggio su disco (JSON) e consultazione
+  cliccando sul pianeta nella galassia
+
+## Come funziona il protocollo dei rapporti (scoperto dalla documentazione ufficiale OGame "Origin")
+
+In gioco, ogni rapporto (CR/SR/RR/MR) ha un pulsante **"API"** nel tooltip che
+permette di copiare una stringa del tipo:
+
+```
+sr-ar-170-98018ad723cb4fdba047f78728fb831cd28b3ca5
+```
+
+composta da: tipo (`sr` = spionaggio) · community (`ar`) · server (`170`) · id (40 hex).
+
+I dati vengono recuperati tramite il **community proxy ufficiale** (niente API key
+da richiedere, metodo standard dal 2026):
+
+```
+GET https://ogapi.faw-kes.de/v1/report/sr-ar-170-<id>/1
+```
+
+Limite del proxy: ~10 richieste/minuto. Il proxy restituisce il rapporto in JSON
+(risorse, edifici, navi, difese, ricerca, attività del bersaglio).
+
+Riferimenti: [forum Origin — OGame API](https://forum.origin.ogame.gameforge.com/forum/thread/44-ogame-api/)
+e [procedura accesso](https://forum.origin.ogame.gameforge.com/forum/thread/319-api-access-applications-required-procedure-updated/)
+
+## Struttura
+
+```
+/opt/ogame_db/
+├── app.py                 # backend Flask (porta 8899) + API
+├── update_data.py         # aggiornamento dati giornaliero + classifiche (--highscore-only)
+├── report_store.py        # import/archivio rapporti di spionaggio
+├── technames.py           # nomi edifici/navi/ricerche/difese
+├── config.json            # configurazione (universo, proxy, id giocatore)
+├── data/
+│   ├── latest/            # snapshot correnti + world.json (indici + classifiche)
+│   ├── snapshots/         # storico giornaliero (30 giorni)
+│   └── reports/           # rapporti di spionaggio importati (JSON)
+└── static/                # frontend: common.js + galassia + classifiche
+```
+
+## Installazione / avvio come servizio
+
+Il servizio è già installato come **systemd utente** (gira al boot grazie a
+`loginctl enable-linger`):
+
+```bash
+systemctl --user status ogame-galaxy.service      # web app su :8899
+systemctl --user status ogame-data-update.timer   # aggiornamento giornaliero 03:30
+systemctl --user status ogame-highscore.timer     # classifiche ogni ora (:17)
+systemctl --user restart ogame-galaxy.service     # riavvio
+journalctl --user -u ogame-galaxy.service -f      # log
+```
+
+Update manuale dei dati: `python3 /opt/ogame_db/update_data.py`
+Classifiche manuali: `python3 /opt/ogame_db/update_data.py --highscore-only`
+
+## Uso
+
+1. Apri `http://<host>:8899` nel browser.
+2. Naviga galassia/sistema (frecce o campi numerici): accanto al nome di ogni
+   giocatore trovi la posizione in classifica (🏆 generale · ⚔️ armamenti).
+   **Clicca sul nome del giocatore** per aprire una finestra con tutti i suoi
+   pianeti e tutti i rapporti di spionaggio disponibili su di lui, senza doverli
+   cercare pianeta per pianeta.
+3. **Classifiche**: apri `http://<host>:8899/rankings` (o il pulsante 🏆 in alto).
+   Tre tab (Generale / Armamenti / Top Flotte) con filtro per stato (**tutti / attivi /
+   inattivi**), range di posizione e ricerca per nome/alleanza. Cliccando su un
+   giocatore salti al suo pianeta nella galassia.
+4. Per archiviare uno spionaggio: in gioco apri il rapporto → pulsante **API** →
+   copia la stringa → incollala nella barra "Importa rapporto".
+5. Clicca sul pianeta (o sulla luna) nella galassia: trovi tutti i rapporti
+   salvati, ordinati per data, con dettagli completi.
+
+## Configurazione (`config.json`)
+
+```json
+{
+  "server_number": 170,
+  "community": "ar",
+  "domain": "s170-ar.ogame.gameforge.com",
+  "my_player_id": 100634,
+  "my_player_name": "MaNaki",
+  "proxy_base": "https://ogapi.faw-kes.de",
+  "refresh_hours": 24,
+  "keep_snapshots": 30
+}
+```
+
+- `my_player_id`: i tuoi pianeti vengono evidenziati in verde nella galassia
+  (lo trovi nell'URL delle tue pagine in gioco o dal pulsante API dei tuoi rapporti:
+  nell'API string compare solo l'id del *report*, ma i rapporti che fai tu riportano
+  `attacker_user_id` nel JSON salvato).
+- `refresh_hours`: dopo quante ore senza update l'app ricarica i dati all'avvio.
+
+## API locali
+
+| Metodo | Percorso | Descrizione |
+|---|---|---|
+| GET | `/api/bootstrap` | stato universo + statistiche rapporti |
+| GET | `/api/galaxy?g=&s=` | celle del sistema (15 posizioni) con rank giocatori |
+| GET | `/api/planet?g=&s=&p=` | dettaglio pianeta + rapporti + rank giocatore |
+| GET | `/api/player?id=` | tutti i pianeti del giocatore + tutti i suoi rapporti |
+| GET | `/api/rankings?type=total\|military\|fleet&status=&start=&end=&q=` | classifiche filtrate |
+| GET | `/rankings` | pagina web classifiche |
+| GET | `/api/reports/<sr_id>` | JSON completo di un rapporto |
+| DELETE | `/api/reports/<sr_id>` | elimina un rapporto (file + indice) |
+| POST | `/api/reports` | importa un rapporto `{"token": "sr-ar-170-..."}` |
+| POST | `/api/refresh` | forza l'aggiornamento dei dati |
+
+`status` accetta: `all`, `active`, `inactive` (i/I), `vacation` (v),
+`vacation_inactive` (vi/vI), `admin` (a).
+
+## Note
+
+- Il tool usa solo API ufficiali/approvate da Gameforge (API pubblica XML e proxy
+  community per i rapporti, che restano sotto il controllo del giocatore che
+  condivide i propri ID).
+- L'app ascolta su `0.0.0.0:8899` senza autenticazione: se il server è raggiungibile
+  da altri, valuta un reverse proxy con auth o un firewall.
+- Lo storico giornaliero viene tenuto per 30 giorni in `data/snapshots/`.