breakpilot-pwa/CONTENT_SERVICE_SETUP.md

# BreakPilot Content Service - Setup & Deployment Guide

## 🎯 Übersicht

Der BreakPilot Content Service ist eine vollständige Educational Content Management Plattform mit:

- ✅ **Content Service API** (FastAPI) - Educational Content Management
- ✅ **MinIO S3 Storage** - File Storage für Videos, PDFs, Bilder
- ✅ **H5P Service** - Interactive Educational Content (Quizzes, etc.)
- ✅ **Matrix Feed Integration** - Content Publishing zu Matrix Spaces
- ✅ **PostgreSQL** - Content Metadata Storage
- ✅ **Creative Commons Licensing** - CC-BY, CC-BY-SA, etc.
- ✅ **Rating & Download Tracking** - Analytics & Impact Scoring

## 🚀 Quick Start

### 1. Alle Services starten

```bash
# Haupt-Services + Content Services starten
docker-compose \
  -f docker-compose.yml \
  -f docker-compose.content.yml \
  up -d

# Logs verfolgen
docker-compose -f docker-compose.yml -f docker-compose.content.yml logs -f
```

### 2. Verfügbare Services

| Service | URL | Beschreibung |
|---------|-----|--------------|
| Content Service API | http://localhost:8002 | REST API für Content Management |
| MinIO Console | http://localhost:9001 | Storage Dashboard (User: minioadmin, Pass: minioadmin123) |
| H5P Service | http://localhost:8003 | Interactive Content Editor |
| Content DB | localhost:5433 | PostgreSQL Database |

### 3. API Dokumentation

Content Service API Docs:
```
http://localhost:8002/docs
```

## 📦 Installation (Development)

### Content Service (Backend)

```bash
cd backend/content_service

# Virtual Environment erstellen
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Dependencies installieren
pip install -r requirements.txt

# Environment Variables
cp .env.example .env

# Database Migrations
alembic upgrade head

# Service starten
uvicorn main:app --reload --port 8002
```

### H5P Service

```bash
cd h5p-service

# Dependencies installieren
npm install

# Service starten
npm start
```

### Creator Dashboard (Frontend)

```bash
cd frontend/creator-studio

# Dependencies installieren
npm install

# Development Server
npm run dev
```

## 🔧 Konfiguration

### Environment Variables

Erstelle `.env` im Projekt-Root:

```env
# Content Service
CONTENT_DB_URL=postgresql://breakpilot:breakpilot123@localhost:5433/breakpilot_content
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin123
MINIO_BUCKET=breakpilot-content

# Matrix Integration
MATRIX_HOMESERVER=http://localhost:8008
MATRIX_ACCESS_TOKEN=your-matrix-token-here
MATRIX_BOT_USER=@breakpilot-bot:localhost
MATRIX_FEED_ROOM=!breakpilot-feed:localhost

# OAuth2 (consent-service)
CONSENT_SERVICE_URL=http://localhost:8081
JWT_SECRET=your-jwt-secret-here

# H5P Service
H5P_BASE_URL=http://localhost:8003
H5P_STORAGE_PATH=/app/h5p-content
```

## 📝 Content Service API Endpoints

### Content Management

```bash
# Create Content
POST /api/v1/content
{
  "title": "5-Minuten Yoga für Grundschule",
  "description": "Bewegungspause mit einfachen Yoga-Übungen",
  "content_type": "video",
  "category": "movement",
  "license": "CC-BY-SA-4.0",
  "age_min": 6,
  "age_max": 10,
  "tags": ["yoga", "bewegung", "pause"]
}

# Upload File
POST /api/v1/upload
Content-Type: multipart/form-data
file: <video-file>

# Add Files to Content
POST /api/v1/content/{content_id}/files
{
  "file_urls": ["http://minio:9000/breakpilot-content/..."]
}

# Publish Content (→ Matrix Feed)
POST /api/v1/content/{content_id}/publish

# List Content (with filters)
GET /api/v1/content?category=movement&age_min=6&age_max=10

# Get Content Details
GET /api/v1/content/{content_id}

# Rate Content
POST /api/v1/content/{content_id}/rate
{
  "stars": 5,
  "comment": "Sehr hilfreich für meine Klasse!"
}
```

### H5P Interactive Content

```bash
# Get H5P Editor
GET http://localhost:8003/h5p/editor/new

# Save H5P Content
POST http://localhost:8003/h5p/editor
{
  "library": "H5P.InteractiveVideo 1.22",
  "params": { ... }
}

# Play H5P Content
GET http://localhost:8003/h5p/play/{contentId}

# Export as .h5p File
GET http://localhost:8003/h5p/export/{contentId}
```

## 🎨 Creator Workflow

### 1. Content erstellen

```javascript
// Creator Dashboard
const content = await createContent({
  title: "Mathe-Quiz: Einmaleins",
  description: "Interaktives Quiz zum Üben des Einmaleins",
  content_type: "h5p",
  category: "math",
  license: "CC-BY-SA-4.0",
  age_min: 7,
  age_max: 9
});
```

### 2. Files hochladen

```javascript
// Upload Video/PDF/Images
const file = document.querySelector('#fileInput').files[0];
const formData = new FormData();
formData.append('file', file);

const response = await fetch('/api/v1/upload', {
  method: 'POST',
  body: formData
});

const { file_url } = await response.json();
```

### 3. Publish to Matrix Feed

```javascript
// Publish → Matrix Spaces
await publishContent(content.id);
// → Content erscheint in #movement, #math, etc.
```

## 📊 Matrix Feed Integration

### Matrix Spaces Struktur

```
#breakpilot (Root Space)
├── #feed (Chronologischer Content Feed)
├── #bewegung (Kategorie: Movement)
├── #mathe (Kategorie: Math)
├── #steam (Kategorie: STEAM)
└── #sprache (Kategorie: Language)
```

### Content Message Format

Wenn Content published wird, erscheint in Matrix:

```
📹 5-Minuten Yoga für Grundschule

Bewegungspause mit einfachen Yoga-Übungen für den Unterricht

📝 Von: Max Mustermann
🏃 Kategorie: movement
👥 Alter: 6-10 Jahre
⚖️ Lizenz: CC-BY-SA-4.0
🏷️ Tags: yoga, bewegung, pause

[📥 Inhalt ansehen/herunterladen]
```

## 🔐 Creative Commons Lizenzen

Verfügbare Lizenzen:

- `CC-BY-4.0` - Attribution (Namensnennung)
- `CC-BY-SA-4.0` - Attribution + ShareAlike (empfohlen)
- `CC-BY-NC-4.0` - Attribution + NonCommercial
- `CC-BY-NC-SA-4.0` - Attribution + NonCommercial + ShareAlike
- `CC0-1.0` - Public Domain

### Lizenz-Workflow

```python
# Bei Content-Erstellung: Creator wählt Lizenz
content.license = "CC-BY-SA-4.0"

# System validiert:
✅ Nur erlaubte Lizenzen
✅ Lizenz-Badge wird angezeigt
✅ Lizenz-Link zu Creative Commons
```

## 📈 Analytics & Impact Scoring

### Download Tracking

```python
# Automatisch getrackt bei Download
POST /api/v1/content/{content_id}/download

# → Zähler erhöht
# → Download-Event gespeichert
# → Für Impact-Score verwendet
```

### Creator Statistics

```bash
# Get Creator Stats
GET /api/v1/stats/creator/{creator_id}

{
  "total_contents": 12,
  "total_downloads": 347,
  "total_views": 1203,
  "avg_rating": 4.7,
  "impact_score": 892.5,
  "content_breakdown": {
    "movement": 5,
    "math": 4,
    "steam": 3
  }
}
```

## 🧪 Testing

### API Tests

```bash
# Pytest
cd backend/content_service
pytest tests/

# Mit Coverage
pytest --cov=. --cov-report=html
```

### Integration Tests

```bash
# Test Content Upload Flow
curl -X POST http://localhost:8002/api/v1/content \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Content",
    "content_type": "pdf",
    "category": "math",
    "license": "CC-BY-SA-4.0"
  }'
```

## 🐳 Docker Commands

```bash
# Build einzelnen Service
docker-compose -f docker-compose.content.yml build content-service

# Nur Content Services starten
docker-compose -f docker-compose.content.yml up -d

# Logs einzelner Service
docker-compose logs -f content-service

# Service neu starten
docker-compose restart content-service

# Alle stoppen
docker-compose -f docker-compose.yml -f docker-compose.content.yml down

# Mit Volumes löschen (Achtung: Datenverlust!)
docker-compose -f docker-compose.yml -f docker-compose.content.yml down -v
```

## 🗄️ Database Migrations

```bash
cd backend/content_service

# Neue Migration erstellen
alembic revision --autogenerate -m "Add new field"

# Migration anwenden
alembic upgrade head

# Zurückrollen
alembic downgrade -1
```

## 📱 Frontend Development

### Creator Studio

```bash
cd frontend/creator-studio

# Install dependencies
npm install

# Development
npm run dev  # → http://localhost:3000

# Build
npm run build

# Preview Production Build
npm run preview
```

## 🔒 DSGVO Compliance

### Datenminimierung

- ✅ Nur notwendige Metadaten gespeichert
- ✅ Keine Schülerdaten
- ✅ IP-Adressen anonymisiert nach 7 Tagen
- ✅ User kann Content/Account löschen

### Datenexport

```bash
# User Data Export
GET /api/v1/user/export
→ JSON mit allen Daten des Users
```

## 🚨 Troubleshooting

### MinIO Connection Failed

```bash
# Check MinIO status
docker-compose logs minio

# Test connection
curl http://localhost:9000/minio/health/live
```

### Content Service Database Connection

```bash
# Check PostgreSQL
docker-compose logs content-db

# Connect manually
docker exec -it breakpilot-pwa-content-db psql -U breakpilot -d breakpilot_content
```

### H5P Service Not Starting

```bash
# Check logs
docker-compose logs h5p-service

# Rebuild
docker-compose build h5p-service
docker-compose up -d h5p-service
```

## 📚 Weitere Dokumentation

- [Architekturempfehlung](./backend/docs/Architekturempfehlung%20für%20Breakpilot%20–%20Offene,%20modulare%20Bildungsplattform%20im%20DACH-Raum.pdf)
- [Content Service API](./backend/content_service/README.md)
- [H5P Integration](./h5p-service/README.md)
- [Matrix Feed Setup](./docs/matrix-feed-setup.md)

## 🎉 Next Steps

1. ✅ Services starten (siehe Quick Start)
2. ✅ Creator Account erstellen
3. ✅ Ersten Content hochladen
4. ✅ H5P Interactive Content erstellen
5. ✅ Content publishen → Matrix Feed
6. ✅ Teacher Discovery UI testen
7. 🔜 OAuth2 SSO mit consent-service integrieren
8. 🔜 Production Deployment vorbereiten

## 💡 Support

Bei Fragen oder Problemen:
- GitHub Issues: https://github.com/breakpilot/breakpilot-pwa/issues
- Matrix Chat: #breakpilot-dev:matrix.org
- Email: dev@breakpilot.app