# OGame Galaxy Viewer

> 📖 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/`.