25-02-2025

DEV-NOTES.md

@@ -0,0 +1,119 @@
+# Dev Notes – Stand 25.02.2026
+
+## node_modules-Konflikt: Mac ↔ Docker ↔ Cursor (gelöst)
+
+### Ausgangslage
+
+Die Quasar App läuft in drei Kontexten parallel:
+
+| Kontext | Pfad | Plattform |
+|---|---|---|
+| **`quasar.app` Docker-Service** | Docker Volume (isoliert) | Linux ARM64 |
+| **Cursor IDE Terminal** | `/workspace/frontend/node_modules` | Linux ARM64 |
+| **Mac Terminal** | `~/Sites/thats-me.local/frontend/node_modules` | macOS ARM64 |
+
+Der `frontend/`-Ordner ist überall **derselbe** (gemountetes Host-Filesystem). Rollup und andere native Pakete benötigen plattformspezifische Binaries – ein `npm install` auf einer Seite überschrieb bisher die Binaries der anderen.
+
+---
+
+### Fix 1 – Docker Volume für `quasar.app` (docker-compose.yml)
+
+Der `quasar.app`-Service nutzt ein eigenes benanntes Docker-Volume für `node_modules`. Dadurch bleibt sein Linux-`node_modules` vollständig vom Host isoliert:
+
+```yaml
+# quasar.app Service:
+volumes:
+    - './frontend:/app'
+    - 'quasar-node-modules:/app/node_modules'   # überschattet Host-Ordner
+
+# volumes-Block:
+volumes:
+    quasar-node-modules:
+        driver: local
+```
+
+Der `quasar.app`-Container führt beim Start automatisch `npm install && npm run dev` aus (in sein isoliertes Volume). Er ist damit **völlig unabhängig** vom Host-`node_modules`.
+
+---
+
+### Fix 2 – Rollup-Binaries als `optionalDependencies` (package.json)
+
+Das Cursor-Terminal und der Mac teilen denselben `node_modules`-Ordner. Um den gegenseitigen Konflikt abzumildern, wurden alle relevanten Rollup-Plattform-Binaries explizit als `optionalDependencies` eingetragen:
+
+```json
+"optionalDependencies": {
+    "@rollup/rollup-darwin-arm64": "^4.0.0",
+    "@rollup/rollup-linux-arm64-gnu": "^4.0.0",
+    "@rollup/rollup-linux-x64-gnu": "^4.0.0"
+}
+```
+
+npm installiert davon nur die zur aktuellen Plattform passenden, schlägt aber nie fehl wenn eine fehlt.
+
+---
+
+### Fix 3 – `npm run dev` repariert sich selbst (package.json)
+
+Das `dev`-Script führt vor dem Start automatisch `npm install` aus:
+
+```json
+"dev": "npm install && quasar dev"
+```
+
+Damit werden nach einem Mac-`npm install` die Linux-Binaries im Cursor-Terminal beim nächsten `npm run dev` automatisch nachgezogen.
+
+---
+
+### Wichtig: Cursor Terminal ≠ `quasar.app`-Container
+
+Das Cursor IDE Terminal hat **keinen** Zugriff auf das isolierte Docker-Volume des `quasar.app`-Services. Für den Web-Dev-Server gilt:
+
+- **Empfohlen:** `docker-compose up -d quasar.app` → App läuft unter `app.thats-me.test` (isoliertes Volume, kein Konflikt)
+- **Alternativ:** `npm run dev` direkt im Cursor-Terminal (teilt node_modules mit dem Mac, aber Fix 3 gleicht das aus)
+
+---
+
+### Workflow: iOS-Build auf dem Mac
+
+Nach einem `npm install` im Linux-Kontext (Cursor oder Docker) müssen auf dem Mac die node_modules neu installiert werden:
+
+```bash
+cd ~/Sites/thats-me.local/frontend
+rm -rf node_modules && npm install
+npx quasar build -m capacitor -T ios --ide
+```
+
+---
+
+## Allgemeiner Projekt-Stand
+
+- **Backend:** Laravel 12, API-Routes unter `api.thats-me.test`, OAuth2 via Passport
+- **Frontend:** Quasar v2 SPA, offline-first mit Dexie.js (IndexedDB)
+- **Mobile:** Capacitor für iOS/Android (in `frontend/src-capacitor/`)
+- **Neue Komponenten:**
+  - `AppSettingsModal.vue`, `ModalCard.vue`, `UserMenu.vue`, `ZoomControl.vue`
+  - `frontend/src/composables/`, `frontend/src/db/`, `frontend/src/services/`
+  - Backend API-Controller + Requests + Resources in `backend/app/Http/`
+  - Event-Model + Migrations + Factory
+
+---
+
+## Wichtige Domains (lokale Entwicklung)
+
+| Domain | Zweck |
+|---|---|
+| `app.thats-me.test` | Quasar Frontend (Quasar Dev-Server) |
+| `api.thats-me.test` | Laravel REST API |
+| `portal.thats-me.test` | Admin Panel |
+| `thats-me.test` | Landingpage |
+| `assets.thats-me.test` | Vite HMR (Laravel Backend Assets) |
+
+## Services & Ports
+
+| Service | Port | Purpose |
+|---|---|---|
+| `quasar.app` | 9000 | Quasar Frontend Dev-Server |
+| `mysql` | 33070 | MySQL Datenbank |
+| `mailpit` | 8028 | E-Mail Testing Dashboard |
+| `redis` | 6383 | Cache & Queue |
+| `laravel.test` | 5180 | Vite Dev-Server (HMR) |