arnef
8ef7b9ce8c
The project is no longer a monorepo/workspace - there is only a single
app package. Remove the redundant client/ nesting: all source, the
Capacitor Android project, config files and package.json/tsconfig now
live directly at the repo root.
- Merge client/package.json into root package.json (drop the
workspaces field and the now-unnecessary bun --cwd client wrappers).
- Merge client/bun.lock (the actual dependency lockfile) into the
root, replacing the stale workspace-only root lockfile.
- Move src/, public/, android/, index.html, vite.config.ts,
capacitor.config.ts, tsconfig.{app,node}.json to the repo root.
- Update Dockerfile.android to build from the repo root instead of
cd'ing into client/.
- Update .github/workflows/ci.yml type-check step to run bun run build
directly instead of bun --cwd client run build.
- Update README.md and .github/copilot-instructions.md to drop
references to the client/ subdirectory.
- Drop the stale server/downloads/ entry from .gitignore (leftover
from an old server-based architecture that no longer exists).
134 lines
5.1 KiB
Markdown
134 lines
5.1 KiB
Markdown
> ⚠️ **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.
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## 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).
|