dmc/CLAUDE.md

# Drone Mission Control (DMC)

Mobile App zur Missionsplanung und Flugsteuerung für einen Fixed-Wing-Drohnen-Aufbau
(Heewing T1 Ranger, iNAV-Firmware). Wegpunkt-Missionen, Live-Fly-Modus, Point-and-Fly
(PnF)-Einzelziel-Anflug.

**Vollständige Architektur- und Design-Entscheidungen:** [DMC_Architektur_und_Design.md](DMC_Architektur_und_Design.md)
— vor jeder größeren Änderung lesen, insbesondere Abschnitt 4 (Entscheidungen inkl.
Begründung), Abschnitt 5 (verworfene Alternativen) und Abschnitt 6 (offene Fragen).

## Sprachregelung

Konversation und Dokumentation auf Deutsch, Code und UI-Texte auf Englisch.

## Projektstruktur

- `Drone Mission Control.html` — lauffähiger Vanilla-JS/Leaflet-Demonstrator, dient als
  Referenz für UI-Verhalten und bereits gelöste Probleme (Wind-Interpolation,
  Terrain-Sampling, Fillet-Geometrie, swipe-adjustierbare Wegpunkt-Chips, ...). Bei
  Unklarheiten über gewünschtes Verhalten zuerst hier nachsehen, bevor neu entschieden
  wird.
- `design/` — Logo-Assets (SVG-Varianten) und Icon-Sketches. Aktuell verwendetes
  App-Icon: `design/Y2_pink_dark.svg`.
- `app/` — Flutter-Zielarchitektur (Einzelpaket, kein Melos-Monorepo). Siehe unten.
- `test/` — Altlast/Sandbox, nicht Teil der aktiven Entwicklung.

## Flutter-App (`app/`)

Fünf-Schichten-Architektur (Doku Abschnitt 2):

```
lib/
  ui/            Screens (plan, fly, settings, library) + geteilte Widgets
  app_mode/      App-Mode State Machine (Plan → Connect → Upload → Fly)
  domain/        Mission-Domain-Layer (Strategy Pattern: TrackMission, ...)
                 + protokollneutrale FlatWaypointList
  services/      MissionSyncService, TelemetryService, Drift-Datenbank
  transport/     FlightControllerLink-Abstraktion (msp/, mavlink/, mock/)
```

**MVP-Scope (Doku 4.1):** nur Android, nur iNAV via MSP, nur WiFi/TCP. MAVLink,
USB-Seriell und iOS sind bewusst zurückgestellt.

**Kernprinzip:** Die Domain-Schicht kennt nur `FlatWaypointList`, protokollneutral.
Divergenz zu MSP/MAVLink findet ausschließlich im Encoder statt. `FlightControllerLink`
ist die zentrale Abstraktion; `MockFlightControllerLink` erlaubt UI-Arbeit ohne
Hardware. `MspFlightControllerLink` ist aktuell nur ein Gerüst (`UnimplementedError`)
— die eigentliche MSP-Protokoll-Implementierung (Framing, `MSP_SET_WP`,
`MSP_NAV_STATUS`) ist noch offen.

**Ready-to-Fly-Gate (Doku 2.2/4.5):** Upload + verifiziert + disarmed. Wird in
`AppModeCubit.toFly()` technisch erzwungen (wirft `StateError`), nicht nur als
UI-Konvention behandelt.

**Persistenz:** Drift (SQLite), nicht Hive — siehe Begründung 4.15. Schema in
`lib/services/database/app_database.dart`. Nach Schema-Änderungen:
```
dart run build_runner build
```
(im `app/`-Verzeichnis; `--delete-conflicting-outputs` wird von der installierten
build_runner-Version ignoriert und ist nicht nötig).

**Entschiedene Pakete** (siehe Doku Abschnitt 8): `flutter_map` (nicht `google_maps_flutter`),
`drift`, `flutter_bloc` + `flutter_riverpod` (kombiniert: Bloc für die App-Mode State
Machine, Riverpod für reaktive Einzelwerte wie Telemetrie), `go_router`.

**`flutter_map_tile_caching` (FMTC, Doku 4.18) ist aktuell NICHT in der pubspec** —
FMTC 10.1.1 pinnt `objectbox_flutter_libs: ^4.1.0` fest, und diese Version hat einen
AAR-Metadata-Konflikt mit neueren AndroidX-Transitiv-Dependencies (`androidx.fragment`,
`androidx.window`, `androidx.activity` verlangen compileSdk ≥34, `objectbox_flutter_libs`
selbst ist gegen android-31 kompiliert) → Build schlägt fehl
(`checkReleaseAarMetadata`). Da FMTC im Code noch nirgends verwendet wird, wurde es
vorerst entfernt statt mit ungetesteten `dependency_overrides` zu forcieren. Vor
erneutem Hinzufügen: prüfen, ob FMTC eine neuere Version mit `objectbox_flutter_libs ^5.x`
freigegeben hat.

**Noch nicht umgesetzt / bewusst zurückgestellt:**
- Eigener MSP-Encoder/Decoder in Dart (4.19) — kein fertiges Paket verfügbar.
- Telemetrie-Verarbeitung in eigenem Isolate (4.21) — erst sinnvoll mit echtem
  Protokoll-Adapter zu verifizieren.
- `SurveyAreaMission`/`SearchAreaMission` (Strategy-Pattern vorgesehen, Details offen).
- Foreground Service (Android) für Hintergrund-Telemetrie (4.20).
- Offline-Kartenkachel-Caching (FMTC, siehe oben) — Paket-Versionskonflikt zu lösen.
- `flutter_launcher_icons` ist konfiguriert für Android; iOS ist aus MVP-Gründen
  deaktiviert (`ios: false` in der `flutter_launcher_icons`-Sektion der `pubspec.yaml`).
- `web/`-Plattform ist nur für schnelle lokale UI-Vorschau hinzugefügt (kein Android-
  Emulator/Gerät nötig), nicht Teil des Release-Scopes.

## Bekannte Windows-Stolpersteine beim Android-Build

- **Projekt liegt auf D:, Gradle-/Kotlin-Nutzerverzeichnis auf C:** → Kotlins
  inkrementeller Compiler crasht beim Schließen der Caches
  (`Could not close incremental caches ... this and base files have different roots`).
  Fix bereits gesetzt: `kotlin.incremental=false` in `android/gradle.properties`.
- **`flutter run -d <emulator-id> --release`** ist der zuverlässigste Weg, einen
  Android-Emulator/Gerät aus diesem (nicht-interaktiven) Environment heraus zu
  bespielen — Debug-Modus mit Hot-Reload funktioniert nur in einer echten
  interaktiven Session (VS Code, Terminal).
- **`adb shell`/`adb pull` mit absoluten Unix-Pfaden (`/sdcard/...`) in Git Bash**:
  MSYS wandelt den führenden Slash-Pfad fälschlich in einen Windows-Pfad um. Fix:
  Pfad mit doppeltem Slash schreiben (`//sdcard/datei.png`).

## Verifikation nach Änderungen

Im `app/`-Verzeichnis:
```
flutter analyze
flutter test
```

Für einen echten Lauf auf Android (z. B. Emulator `Pixel_10a`, angelegt mit dem
`pixel_10`-Geräteprofil als Näherung, da kein exaktes "Pixel 10a"-Profil im SDK
existiert):
```
flutter emulators --launch Pixel_10a
flutter run -d emulator-5554 --release
```