breakpilot-pwa/geo-service/STATUS.md

# GeoEdu Service - Implementierungsstatus

**Stand:** 2026-01-24
**Status:** Infrastruktur komplett, Downloads ausstehend

---

## Übersicht

Der GeoEdu Service ist eine DSGVO-konforme Erdkunde-Lernplattform mit:
- Self-Hosted OpenStreetMap Tile Server für Deutschland
- 3D-Terrain aus Copernicus DEM (Open Data)
- Unity WebGL Integration für immersive Lernwelten
- Learning Nodes System für didaktische Inhalte (via Ollama LLM)

**Port:** 8088

---

## Abgeschlossene Arbeiten

### Backend (geo-service/)

| Datei | Status | Beschreibung |
|-------|--------|--------------|
| `Dockerfile` | ✅ | Python 3.11 + GDAL + Geo-Libraries |
| `requirements.txt` | ✅ | FastAPI, asyncpg, shapely, rasterio, pmtiles |
| `config.py` | ✅ | Pydantic Settings |
| `main.py` | ✅ | FastAPI App mit allen Routers |
| `api/tiles.py` | ✅ | Vector Tile Endpoints |
| `api/terrain.py` | ✅ | DEM/Heightmap Endpoints |
| `api/aoi.py` | ✅ | AOI Packaging Endpoints |
| `api/learning.py` | ✅ | Learning Nodes API |
| `services/tile_server.py` | ✅ | PMTiles Reader |
| `services/dem_service.py` | ✅ | Copernicus DEM Handler |
| `services/aoi_packager.py` | ✅ | Unity Bundle Generator |
| `services/osm_extractor.py` | ✅ | OSM Feature Extraction |
| `services/learning_generator.py` | ✅ | Ollama LLM Integration |
| `models/aoi.py` | ✅ | AOI Pydantic Models |
| `models/learning_node.py` | ✅ | Learning Node Models |
| `models/attribution.py` | ✅ | License Attribution |
| `utils/geo_utils.py` | ✅ | Koordinaten-Transformationen |
| `utils/minio_client.py` | ✅ | S3 Client |
| `utils/license_checker.py` | ✅ | Lizenz-Validierung |
| `scripts/download_osm.sh` | ✅ | Geofabrik Download (NICHT ausgeführt) |
| `scripts/download_dem.sh` | ✅ | Copernicus Download (NICHT ausgeführt) |
| `scripts/import_osm.sh` | ✅ | osm2pgsql Import |
| `scripts/generate_tiles.sh` | ✅ | PMTiles Generation |
| `scripts/init_postgis.sql` | ✅ | PostGIS Schema + Tabellen |
| `tests/test_tiles.py` | ✅ | API Tests |
| `tests/test_aoi.py` | ✅ | AOI + Geo Utils Tests |
| `tests/test_learning.py` | ✅ | Learning Generator Tests |
| `.env.example` | ✅ | Environment Template |

### Frontend (studio-v2/)

| Datei | Status | Beschreibung |
|-------|--------|--------------|
| `package.json` | ✅ | maplibre-gl Dependency hinzugefügt |
| `app/geo-lernwelt/page.tsx` | ✅ | Hauptseite mit Tabs |
| `app/geo-lernwelt/types.ts` | ✅ | TypeScript Interfaces |
| `components/geo-lernwelt/AOISelector.tsx` | ✅ | MapLibre Polygon-Zeichnung |
| `components/geo-lernwelt/UnityViewer.tsx` | ✅ | Unity WebGL Viewer |
| `lib/geo-lernwelt/GeoContext.tsx` | ✅ | React Context |
| `lib/geo-lernwelt/mapStyles.ts` | ✅ | MapLibre Styles |
| `lib/geo-lernwelt/unityBridge.ts` | ✅ | Unity Communication |

### Docker-Konfiguration

| Änderung | Status | Beschreibung |
|----------|--------|--------------|
| `docker-compose.yml` | ✅ | geo-service hinzugefügt |
| PostgreSQL Image | ✅ | Geändert zu `postgis/postgis:16-3.4-alpine` |
| PostGIS Init Script | ✅ | Auto-Setup bei Container-Start |
| Volumes | ✅ | geo_osm_data, geo_dem_data, geo_tile_cache, geo_aoi_bundles |

---

## Ausstehende Arbeiten

### Downloads (NICHT automatisch starten!)

| Download | Größe | Script | Dauer (~100 Mbit/s) |
|----------|-------|--------|---------------------|
| Germany OSM PBF | 4.4 GB | `scripts/download_osm.sh` | ~6 Min |
| Copernicus DEM | ~25 GB | `scripts/download_dem.sh` | ~35 Min |

### Generierung (nach Downloads)

| Prozess | Output | Dauer |
|---------|--------|-------|
| osm2pgsql Import | PostgreSQL DB | ~2-4 Stunden |
| PMTiles (Z0-14) | ~200-300 GB | ~12-24 Stunden |
| DEM Tiles | ~15 GB | ~2-3 Stunden |

**Gesamtspeicherbedarf nach Setup: ~350 GB**

---

## API Endpoints

```
# Tiles
GET  /api/v1/tiles/{z}/{x}/{y}.pbf     → Vector Tile
GET  /api/v1/tiles/style.json          → MapLibre Style
GET  /api/v1/tiles/metadata            → Tile Metadata
GET  /api/v1/tiles/bounds              → Germany Bounds

# Terrain
GET  /api/v1/terrain/{z}/{x}/{y}.png   → Heightmap (Terrain-RGB)
GET  /api/v1/terrain/hillshade/{z}/{x}/{y}.png → Hillshade
GET  /api/v1/terrain/elevation?lat=&lon= → Point Elevation
GET  /api/v1/terrain/metadata          → DEM Metadata

# AOI (Area of Interest)
POST /api/v1/aoi                       → Create AOI
GET  /api/v1/aoi/{id}                  → Get Status
GET  /api/v1/aoi/{id}/manifest.json    → Unity Manifest
POST /api/v1/aoi/validate              → Validate Polygon
GET  /api/v1/aoi/templates/mainau      → Mainau Demo

# Learning Nodes
POST /api/v1/learning/generate         → Generate with LLM
GET  /api/v1/learning/templates        → Available Themes
GET  /api/v1/learning/{aoi_id}/nodes   → Get Nodes
GET  /api/v1/learning/statistics       → Stats
```

---

## Nächste Schritte

1. **Container starten (ohne Downloads):**
   ```bash
   docker compose up -d geo-service
   ```

2. **Health Check testen:**
   ```bash
   curl http://localhost:8088/health
   ```

3. **Frontend testen:**
   ```
   http://localhost:3001/geo-lernwelt
   ```

4. **Downloads starten (wenn bereit):**
   ```bash
   # OSM Download (~6 Min)
   docker exec breakpilot-pwa-geo-service /app/scripts/download_osm.sh

   # DEM Download (~35 Min)
   docker exec breakpilot-pwa-geo-service /app/scripts/download_dem.sh
   ```

5. **Tile-Generierung (nach Downloads):**
   ```bash
   # OSM Import (~2-4h)
   docker exec breakpilot-pwa-geo-service /app/scripts/import_osm.sh

   # PMTiles Generation (~12-24h)
   docker exec breakpilot-pwa-geo-service /app/scripts/generate_tiles.sh
   ```

---

## Lizenz-Compliance

### Zugelassene Quellen
- ✅ OpenStreetMap (ODbL)
- ✅ Copernicus DEM (Copernicus License)
- ✅ OpenAerialMap (CC-BY 4.0)

### VERBOTEN
- ❌ Google Maps/Earth
- ❌ Bing Maps
- ❌ Apple Maps
- ❌ HERE

---

## Wichtige Dateien

| Datei | Pfad |
|-------|------|
| Haupt-Plan | `/Users/benjaminadmin/.claude/plans/stateful-hugging-kahan.md` |
| Backend | `/Users/benjaminadmin/Projekte/breakpilot-pwa/geo-service/` |
| Frontend | `/Users/benjaminadmin/Projekte/breakpilot-pwa/studio-v2/app/geo-lernwelt/` |
| Docker Config | `/Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml` |

---

## Kontakt bei Fragen

Dieser Service wurde gemäß dem Plan in `/Users/benjaminadmin/.claude/plans/stateful-hugging-kahan.md` implementiert.