# ATM10 Stats

Statistikportal für einen All-the-Mods-10-Server (Minecraft 1.21.1, NeoForge 21.1) bei Mine-Hoster:
Serverstatus mit Live-Ticker, 14 Ranglisten, Spielerprofile mit Verläufen und Aktivitäts-Heatmap,
ATM10-Auswertungen (Aktivität je Mod und Bereich, FTB-Quests) und Serverleistung (TPS, Tickdauer, Speicher).

```
Mine-Hoster (ATM10)                          eigener Server (DMZ, Docker Compose hinter Traefik)
┌───────────────────────┐   HTTPS (signiert)   ┌─────────────────────────────────────────────┐
│ atmstats-Mod          │ ───────────────────▶ │ api     Fastify: Ingest, REST, SSE, Admin   │
│ (nur serverseitig)    │                      │ worker  SFTP-Abgleich, Snapshots, Retention │
└───────────────────────┘                      │ web     Next.js-Dashboard                   │
   ▲ world/stats, ftbquests, logs              │ db      PostgreSQL 16 + tägliches Backup    │
   └──────────── SFTP (Fallback) ◀─────────────┴─────────────────────────────────────────────┘
```

## Inhalt des Repositorys

| Ordner | Inhalt |
|---|---|
| `mod/` | NeoForge-Mod `atmstats` (Java 21): erfasst Ereignisse, puffert sie auf der Festplatte, sendet signiert per HTTPS |
| `backend/` | API und Worker (TypeScript, Fastify, PostgreSQL) |
| `web/` | Dashboard (Next.js, TypeScript, Tailwind, Recharts) |
| `shared/` | Protokoll-Schemas (Zod) und API-Typen, von Backend, Web und Simulator genutzt; Beispiel-Ereignisse in `shared/fixtures/protocol` |
| `deploy/` | Docker Compose (Traefik-Labels), `.env.example`, Backup-Skript |
| `tools/` | Simulator für Testdaten, Log-Anonymisierer, RCON-Client für lokale Tests |
| `docs/` | Architektur, Datenquellen und Einschränkungen, Betrieb |

## Dokumentation

- **[docs/OPERATIONS.md](docs/OPERATIONS.md)**: Installation auf dem DMZ-Server, Traefik/OPNsense, Mod bei Mine-Hoster einspielen, Backups, Fehlerbilder
- **[docs/DATA-SOURCES.md](docs/DATA-SOURCES.md)**: welche Statistik woher kommt, wie aktuell sie ist und was nicht erfasst wird
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Komponenten, Protokoll, Zuverlässigkeit, Datenmodell
- [mod/README.md](mod/README.md): Mod bauen und konfigurieren
- Design und Plan: `docs/superpowers/specs/`, `docs/superpowers/plans/`

## Lokale Entwicklung

Voraussetzungen: Node 22, Docker, für die Mod JDK 21.

```bash
npm install
docker compose -f deploy/docker-compose.test.yml up -d          # Postgres auf localhost:54329

# Backend (eigene Datenbank für die Entwicklung anlegen)
docker exec deploy-db-test-1 createdb -U postgres atm_dev
export DATABASE_URL=postgres://postgres:postgres@localhost:54329/atm_dev
export INGEST_HMAC_SECRET=$(openssl rand -hex 32) NODE_ENV=development
npm run cli -w backend -- token:create                           # Token für Mod oder Simulator
npm run dev -w backend                                           # API auf :3001
npm run dev:worker -w backend                                    # optional: Snapshots, SFTP

# Frontend
npm run dev -w web                                               # http://localhost:3000

# Testdaten
npm run sim -w tools/simulator -- --token <token> --secret $INGEST_HMAC_SECRET --players 6 --minutes 300 --realtime
```

## Tests

```bash
npm test -w shared                       # Protokoll-Schemas
npm test -w backend                      # API, Pipeline, Parser, Worker (braucht die Test-Datenbank)
npm test -w web                          # Komponenten und Formatierung
./mod/gradlew -p mod test                # Mod-Kern: Journal, Versand, Signatur, Serialisierung
cd web && npx playwright test            # E2E gegen einen laufenden Stack (E2E_BASE_URL)
```

Die Mod-Tests prüfen die Java-Serialisierung gegen dieselben Beispiel-Ereignisse, die das Backend validiert,
und die HMAC-Signatur gegen denselben Testvektor. So bleiben Mod und Backend kompatibel.