---
name: resource-import
description: "Freie Bücher und andere Ressourcen (ePub, PDF) mit vollständigen Metadaten recherchieren und in die Bollwerk-App importieren. Nutze diesen Skill wenn neue Ressourcen gesucht, zusammengestellt oder importiert werden sollen. Trigger-Phrasen: 'Bücher importieren', 'freie Bücher', 'Ressourcen importieren', 'neue Bücher', 'Gutenberg', 'ePub', 'Ressource hinzufügen', 'Import Ressourcen', 'Bibliothek erweitern', '10 Bücher', 'Leseliste'."
---

# Skill: Ressourcen-Import (freie Bücher mit Metadaten)

Recherchiert freie Bücher (Public Domain / Creative Commons) und importiert sie als Ressourcen in die Bollwerk-App. Enthält den gesamten Workflow: Auswahl → Metadaten → Download → Upload.

---

## Kontext

Die Bollwerk-App hat eine **Ressourcen-Bibliothek** mit ePub/PDF-Dateien. Der Server speichert pro Ressource:

| Feld         | Typ         | Beschreibung                                  |
| ------------ | ----------- | --------------------------------------------- |
| guid         | String      | UUID, wird beim Upload generiert              |
| title        | String      | Buchtitel                                     |
| author       | String?     | Autor(en)                                     |
| description  | String      | 2–3 Sätze, deutsch, themenrelevant            |
| tags         | List<String>| Kategorie-Tags (siehe unten)                  |
| fileFormat   | String      | `epub` oder `pdf`                             |
| mimeType     | String      | `application/epub+zip` / `application/pdf`    |
| fileSize     | Long        | Wird beim Upload automatisch gesetzt          |
| releaseDate  | String?     | Erstveröffentlichung (ISO oder Jahreszahl)    |
| language     | String?     | ISO-639-1 Sprachcode (`en`, `de`, etc.)       |
| edition      | String?     | Ausgabe/Übersetzung                           |
| createdAt    | Long        | Epoch-Millisekunden (automatisch)             |
| updatedAt    | Long        | Epoch-Millisekunden (automatisch)             |
| downloadUrl  | String      | Server setzt dies auf `/api/resources/{guid}/download` |

### Bekannte Tags

- `nachschlagewerk` – Sachbuch, Lexikon, Ratgeber
- `handbuch` – Praxisorientiertes How-To
- `novel` – Belletristik, Roman, Novelle
- `abenteuer` – Abenteuer-/Entdeckerthematik
- `quellenbuch` – Inspirationsquelle / Settingbuch

Neue Tags dürfen bei Bedarf ergänzt werden, sollten aber zur bestehenden Systematik passen (Singular, Kleinbuchstaben, deutsch).

---

## Quellen für freie Bücher

| Quelle                     | URL                                 | Formate      | Lizenz       |
| -------------------------- | ----------------------------------- | ------------ | ------------ |
| Project Gutenberg          | https://www.gutenberg.org           | ePub, txt    | Public Domain |
| Standard Ebooks            | https://standardebooks.org          | ePub         | Public Domain |
| Internet Archive (OpenLib) | https://archive.org                 | ePub, PDF    | Gemischt     |
| ManyBooks                  | https://manybooks.net               | ePub, PDF    | Public Domain |

### Gutenberg-Download-URLs (Priorität)

```
1. https://www.gutenberg.org/ebooks/{id}.epub.noimages   (klein, schnell)
2. https://www.gutenberg.org/ebooks/{id}.epub3.images    (mit Bildern)
3. https://www.gutenberg.org/cache/epub/{id}/pg{id}.epub (Fallback)
```

---

## Workflow

### 1. Auswahl (Recherche)

Wenn der User z.B. sagt "importiere 10 gute freie Bücher":

1. **Thema klären** – Was für Bücher? (Klassiker, Survival, Philosophie, Horror, etc.)
2. **Lizenz sicherstellen** – Nur Public Domain oder explizit freie Lizenzen.
3. **Duplikate prüfen** – Über `GET /api/resources` oder lokal prüfen, was bereits vorhanden ist.
4. **Liste zusammenstellen** – Pro Buch:
   - Gutenberg-ID (oder Download-URL)
   - Titel, Autor
   - Deutsche Beschreibung (2–3 Sätze, für den Bollwerk-Kontext relevant)
   - Tags, Sprache, Erscheinungsjahr, Edition/Übersetzung

### 2. Import-Skript generieren/aktualisieren

Das Projekt hat bereits `import-books.py` als Referenzimplementierung. Für neue Imports:

- Entweder das bestehende Skript mit neuer BOOKS-Liste anpassen
- Oder ein neues spezialisiertes Skript erstellen

**Skript-Struktur** (Python, nur stdlib):

```python
BOOKS = [
    {
        "gutenberg_id": 132,
        "title": "The Art of War",
        "author": "Sun Tzu",
        "description": "Deutsche Beschreibung, 2-3 Sätze.",
        "tags": ["nachschlagewerk", "handbuch"],
        "language": "en",
        "release_date": "-500",
        "edition": "Lionel Giles Translation, 1910",
    },
    # ...
]
```

### 3. Ausführung

```powershell
# Voraussetzungen
$env:BOLLWERK_ADMIN_USER = "<admin-username>"
$env:BOLLWERK_ADMIN_PASS = "<admin-password>"

# Import starten
python import-books.py

# Nur Download testen (kein Upload)
python import-books.py --dry-run
```

### 4. Verifizierung

Nach dem Import:

1. Server-Health prüfen: `GET /api/health`
2. Ressourcen-Liste abrufen: `GET /api/resources` (Auth-Token nötig)
3. Stichprobe: Ein Buch per `GET /api/resources/{guid}/download` herunterladen

---

## API-Endpunkte (Admin)

| Methode | Endpunkt                       | Beschreibung                    |
| ------- | ------------------------------ | ------------------------------- |
| POST    | `/api/admin/resources`         | Ressource hochladen (multipart) |
| PUT     | `/api/admin/resources/{guid}`  | Metadaten aktualisieren         |
| DELETE  | `/api/admin/resources/{guid}`  | Ressource löschen               |
| GET     | `/api/admin/resources/tags`    | Alle Tags mit Häufigkeit        |
| POST    | `/api/admin/resources/analyze` | Datei analysieren (ohne Speichern) |

### Multipart-Upload-Format

```
POST /api/admin/resources
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=...

Part 1: name="metadata", Content-Type: application/json
  → ResourceDto als JSON

Part 2: name="file", filename="<guid>.epub"
  → Datei-Bytes (max 25 MB)
```

---

## Qualitätskriterien für Beschreibungen

- **Sprache**: Deutsch
- **Länge**: 2–3 Sätze
- **Inhalt**: Was ist das Buch? Warum ist es relevant/interessant?
- **Keine Spoiler** bei Belletristik
- **Kontext-Bezug**: Wenn möglich, Relevanz für Rollenspiel/Abenteuer/Strategie/Überleben hervorheben (passend zum Bollwerk-Thema)

---

## Checkliste vor Import

- [ ] Alle Bücher sind Public Domain oder frei lizenziert
- [ ] Keine Duplikate mit bestehenden Ressourcen
- [ ] Deutsche Beschreibungen vorhanden
- [ ] Tags passen zur bestehenden Systematik
- [ ] Gutenberg-IDs / Download-URLs verifiziert
- [ ] `--dry-run` erfolgreich (alle Downloads funktionieren)
- [ ] Env-Vars für Admin-Credentials gesetzt

---

## Referenz-Dateien

- `import-books.py` – Bestehende Importimplementierung (10 Klassiker)
- `shared/src/main/kotlin/de/bollwerk/shared/model/ResourceDto.kt` – Datenmodell
- `server/src/main/kotlin/de/bollwerk/server/routes/ResourceRoutes.kt` – API-Endpunkte
- `server/src/main/kotlin/de/bollwerk/server/service/ResourceAnalyzer.kt` – Dateianalyse (epub/pdf/images)