181 lines
7 KiB
Markdown
181 lines
7 KiB
Markdown
---
|
||
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)
|