> ⚠️ **Hinweis:** Dieses Projekt wurde größtenteils KI-generiert (mit GitHub Copilot). Nicht der gesamte Code wurde bisher manuell reviewed – Vorsicht bei produktivem Einsatz, Beiträge und Reviews sind willkommen.

# tiptoi-sync

Android-App zum Suchen, Herunterladen und Synchronisieren von tiptoi-Büchern auf den tiptoi-Stift. Läuft direkt auf dem Smartphone (Capacitor-App) – kein Server, kein selbst-gehostetes Backend nötig.

![App](https://img.shields.io/badge/SolidJS-Capacitor-blue)
![Platform](https://img.shields.io/badge/Android-native-green)

---

## Features

- **Barcode-Scanner** – Buch per Kamera-Scan (QR/EAN) suchen
- **Freitextsuche** – nach Titel oder Artikelnummer suchen
- **Download** – GME-Datei + Cover automatisch von Ravensburger herunterladen
- **Bibliothek** – alle heruntergeladenen Bücher in der Übersicht
- **Stift-Sync** – tiptoi-Stift verbinden (Storage Access Framework), Bücher direkt aus der App auf den Stift kopieren
- **Stift-Status** – zeigt welche Bücher bereits auf dem Stift sind und welche fehlen

---

## Architektur

Die App läuft komplett nativ auf dem Android-Gerät – Suche, Download und Stift-Zugriff passieren alle direkt im Client, ohne Server-Komponente:

```
┌───────────────────────────────────────────────┐
│  Android-App (Capacitor + SolidJS)             │
│                                                 │
│  src/api.ts          → Ravensburger-Suche +    │
│                        Download-Orchestrierung │
│                                                 │
│  Native Plugin (Kotlin, TiptoiPlugin.kt):      │
│   - Download von GME-Datei + Cover             │
│   - Stift-Zugriff via SAF (Storage Access       │
│     Framework, Verzeichnis-Picker)             │
│   - Auflisten/Kopieren/Löschen von .gme auf     │
│     dem Stift                                  │
└───────────────────────────────────────────────┘
```

Details zu Modulaufteilung und Konventionen: siehe [`.github/copilot-instructions.md`](.github/copilot-instructions.md).

---

## Voraussetzungen

- [Bun](https://bun.sh) ≥ 1.0
- Android SDK + Gradle (für lokale Android-Builds) **oder** Docker/Podman (für den containerisierten APK-Build, siehe unten)
- Android-Gerät oder -Emulator zum Testen

---

## Entwicklung (lokal)

```bash
git clone <repo>
cd tiptoi-sync
bun install

# Vite Dev Server starten (Web-Ansicht im Browser)
bun run dev
```

- Web-Ansicht: `http://localhost:5173` (Vite Dev Server mit HMR)

Für Live-Reload direkt auf dem Android-Gerät/-Emulator gegen den Vite Dev-Server:

```bash
bun run cap:sync
DEV_URL=http://<host-ip>:5173 bun run cap:android
```

`capacitor.config.ts` liest `DEV_URL` und lädt die Webview dann direkt vom Dev-Server statt vom gebauten `dist/`-Ordner. Alternativ lässt sich das auch zur Laufzeit über das Dev-Menü in der App umschalten (5x auf den Titel in der Kopfzeile tippen).

---

## Android-APK bauen

### Über Docker/Podman (empfohlen, kein lokales Android SDK nötig)

```bash
./build-apk.sh
```

Baut die APK reproduzierbar in einem Container (Bun + Android SDK + Gradle, siehe `Dockerfile.android`) und legt sie unter `apk-output/tiptoi-sync.apk` ab.

### Lokal mit installiertem Android SDK

```bash
bun run build           # Web-Assets bauen
bun run cap:sync        # Assets ins Android-Projekt synchronisieren
cd android
./gradlew assembleDebug
```

---

## CI

Ein Workflow unter [`.github/workflows/ci.yml`](.github/workflows/ci.yml) führt bei jedem Push/PR auf `main` einen Type-Check aus und baut anschließend die APK, die als Artifact bereitgestellt wird. Kompatibel sowohl mit GitHub Actions als auch mit Gitea Actions.

---

## Projektstruktur

```
tiptoi-sync/
├── src/
│   ├── api.ts                # Ravensburger-Suche, Download-/Sync-Orchestrierung
│   ├── native/               # TS-Interfaces für native Capacitor-Plugins
│   ├── pages/
│   │   ├── ScanPage.tsx       # Barcode-Scanner + Suche
│   │   └── DownloadsPage.tsx  # Bibliothek + Stift-Sync
│   └── components/
├── android/                  # Capacitor Android-Projekt (im Repo eingecheckt)
│   └── app/src/main/java/com/tiptoisync/app/
│       ├── TiptoiPlugin.kt    # Stift-Zugriff (SAF), Download, Bibliothek
│       └── DevPlugin.kt       # Live-Reload gegen Vite Dev-Server
├── Dockerfile.android        # Container-Build für die APK
├── build-apk.sh              # Wrapper um Dockerfile.android (Podman/Docker)
└── .github/
    ├── workflows/ci.yml          # Type-Check + APK-Build
    └── copilot-instructions.md   # Architektur- und Konventions-Details
```

---

## Hinweise

- **Kein direkter USB-Massenspeicher-Zugriff nötig** – der Stift wird über das Android Storage Access Framework (SAF) via Verzeichnis-Picker eingebunden, kein Root/Server erforderlich.
- Die App ist bewusst **Android-only**: ein Web-/iOS-Backend existiert nicht (mehr).