feat: ATM10-Statistikportal

Statistikportal für den All-the-Mods-10-Server (Minecraft 1.21.1, NeoForge 21.1): - mod/: serverseitige NeoForge-Mod atmstats – Ereignisse, Live-Zähler, Servergesundheit, FTB-Dateien; Outbox auf der Festplatte, signierter gzip-Versand per HTTPS mit Backoff - backend/: Fastify + PostgreSQL – idempotenter Ingest, Projektionen, Parser für SNBT, FTB Quests/Teams, world/stats, world/advancements und latest.log; Ranglisten, Snapshots, Retention, öffentliche API, SSE-Live-Updates, Admin mit argon2/CSRF, SFTP-Worker - web/: Next.js-Dashboard – Übersicht, Ranglisten, Spielerprofile, ATM10, Server, Datenquellen, Verwaltung - shared/: Protokoll v1 und API-Typen; tools/: Simulator, Log-Anonymisierer, RCON-Client - deploy/: Docker Compose hinter Traefik, Backup; docs/: Architektur, Datenquellen, Betrieb Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 09:33:25 +02:00
1 parent 56d2078e6a
commit e66f89f49e
@@ -0,0 +1,71 @@
+# 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.