/// Gemeinsame Schnittstelle für Ländercode-Ermittlungsquellen
/// (`docs/plan.md`, Abschnitt 6 + 8, AP4).
///
/// Implementierungen liefern best-effort einen ISO 3166-1 alpha-2
/// Ländercode oder `null`, wenn sie ihn nicht ermitteln konnten. Sie dürfen
/// dabei **niemals** werfen – Fehler (fehlende Berechtigung, kein Netz,
/// Plugin-Fehler auf Emulatoren o. Ä.) werden intern abgefangen und als
/// `null` codiert. Das erlaubt [LocationService], die Kette gleichförmig zu
/// orchestrieren, ohne pro Quelle try/catch zu benötigen.
abstract class CountryCodeSource {
  Future<String?> resolve();
}

/// Erweiterung von [CountryCodeSource] um eine Schreibmöglichkeit.
///
/// Wird von der Cache-Quelle implementiert: Sie liefert nicht nur den
/// zuletzt bekannten Ländercode zurück ([resolve]), sondern erlaubt auch,
/// einen neu ermittelten Code zu speichern ([save]) – siehe
/// `CachedCountryCodeSource`.
abstract class CountryCodeCache implements CountryCodeSource {
  /// Speichert [isoCode] als zuletzt bekannten Ländercode (best effort).
  Future<void> save(String isoCode);
}

/// Erweiterung von [CountryCodeSource] um die manuelle Länderauswahl
/// (`docs/plan.md`, Abschnitt 8, AP6).
///
/// Im Gegensatz zu [CountryCodeCache] erlaubt [save] hier explizit `null`,
/// damit der Nutzer die manuelle Auswahl wieder löschen und zur
/// automatischen Ermittlungskette (SIM → GPS → Cache) zurückkehren kann.
abstract class ManualCountryCodeStore implements CountryCodeSource {
  /// Setzt die manuelle Länderauswahl. `null` löscht eine zuvor gesetzte
  /// Auswahl wieder (best effort).
  Future<void> save(String? isoCode);
}