feat: require exact mensa selection

Author: FarisZR

AGENTS.md

@@ -43,6 +43,9 @@ Important runtime behavior:
 - View model: `lib/canteen/ui/viewmodels/canteen_view_model.dart`
 - Page: `lib/canteen/ui/canteen_page.dart`
 - Provider/repository: `lib/canteen/business/canteen_provider.dart`, `lib/canteen/data/canteen_meal_repository.dart`
+- Users must choose an exact mensa during onboarding before finishing; the same selection can be changed later in Settings.
+- Karlsruhe keeps the existing Studierendenwerk Karlsruhe scraper/model path (`Mensa Erzbergerstrasse`); non-Karlsruhe supported locations currently use the OpenMensa path.
+- The active mensa is stored as a single selected-location cache; widgets/background refresh follow that active selection.
 - Scraping/parsing offloads heavy parsing to isolate path in service layer.
 - UI is day-based with visible-content-day bounds (recent fixes prevent invalid swipe pages/overscroll edge issues).
 

docs/canteen-feature.md

@@ -26,9 +26,12 @@ The canteen feature provides a performant, swipeable daily menu for the DHBW Kar
 - Widget: `android/app/src/main/kotlin/com/fariszr/dualmate/widget/canteen` + `android/app/src/main/res/layout/widget_canteen_today.xml`
 
 ## Data Source
-- Provider: Studierendenwerk Karlsruhe
-- URL: `https://www.sw-ka.de/de/hochschulgastronomie/speiseplan/mensa_erzberger/?kw=<week>`
-- Week calculation uses ISO week numbers (see `_isoWeekNumber()` in `CanteenScraper`).
+- On first onboarding completion, users must choose the exact mensa to use.
+- Karlsruhe remains on the legacy Studierendenwerk Karlsruhe scraper path:
+  - URL: `https://www.sw-ka.de/de/hochschulgastronomie/speiseplan/mensa_erzberger/?kw=<week>`
+  - Week calculation uses ISO week numbers (see `_isoWeekNumber()` in `CanteenScraper`).
+- Other currently supported locations use OpenMensa day endpoints through `OpenMensaCanteenSource`.
+- Settings can change the selected mensa later; switching locations clears the active cached meal table and repopulates it for the newly selected location.
 
 ## Parsing Rules
 - Days are read from `#canteen_day_nav_1..5` using their `rel` date attribute.
@@ -65,6 +68,7 @@ To avoid frame drops while loading a new week:
 - The UI shows animated skeleton cards while a week is loading.
 - The day list switches from skeleton to real content using a short fade.
 - Chips are not rendered in the list (notes are shown as a lightweight text row).
+- The selected mensa remains the single active cache source for the page, widget, and background updater.
 
 ### Filters
 The filter dropdown (top-right) uses `CanteenFilter` to filter the list in-memory, without re-querying the network or database.

docs/solutions/ui-bugs/required-exact-mensa-selection-20260601.md

@@ -0,0 +1,41 @@
+---
+module: Canteen UI
+date: 2026-06-01
+problem_type: ui_bug
+component: onboarding_settings
+symptoms:
+  - "Users could finish onboarding without choosing an exact mensa"
+  - "The canteen feature stayed hardcoded to Karlsruhe even when supporting other mensas"
+  - "Canteen setup UI did not match the schedule onboarding/setup design"
+root_cause: canteen_selection_was_not_modeled_as_required_app_configuration_and_the_data_source_was_hardcoded_to_karlsruhe
+resolution_type: code_fix
+severity: medium
+tags: [canteen, mensa, onboarding, settings, karlsruhe, openmensa, flutter]
+---
+
+# Troubleshooting: Required exact mensa selection
+
+## Problem
+The app could not support exact mensa selection end to end. Onboarding had no required mensa step, Settings could not reconfigure the canteen source, and the canteen backend was still hardcoded to Karlsruhe.
+
+## Root Cause
+The canteen stack only had one implicit source: the Karlsruhe scraper path. There was no persisted selected-location concept, so onboarding and Settings could not drive the runtime provider or widget/background cache behavior.
+
+## Solution
+- Added a persisted selected canteen location via `PreferencesProvider` and `CanteenLocationService`.
+- Added a required onboarding mensa step that intentionally matches the schedule setup page structure.
+- Added a Settings dialog to reselect the exact mensa later.
+- Kept Karlsruhe on the existing scraper/model path exactly as before.
+- Added an OpenMensa-backed source for the newly supported non-Karlsruhe locations.
+- Kept the SQLite/widget cache model minimal by treating the selected mensa as the single active canteen cache and clearing cached meals when the selection changes.
+
+## Test Coverage
+- `required canteen step cannot be skipped when invalid`
+- `refreshWeek uses OpenMensa for non-Karlsruhe locations`
+- existing canteen page bounds, visible-days, and startup loading policy suites updated for the new location service path
+
+## Commands run
+```bash
+flutter test test/canteen/business/canteen_provider_refresh_policy_test.dart test/canteen/ui/viewmodels/canteen_visible_days_test.dart test/canteen/ui/viewmodels/canteen_startup_loading_policy_test.dart test/canteen/ui/canteen_page_bounds_test.dart test/ui/onboarding/onboarding_required_canteen_step_test.dart
+flutter analyze lib/canteen lib/ui/onboarding lib/ui/settings lib/common/appstart/service_injector.dart test/canteen test/ui/onboarding/onboarding_required_canteen_step_test.dart
+```

lib/canteen/business/canteen_location_service.dart

@@ -0,0 +1,29 @@
+import 'package:dualmate/canteen/model/canteen_location.dart';
+import 'package:dualmate/common/data/preferences/preferences_provider.dart';
+
+class CanteenLocationService {
+  final PreferencesProvider _preferencesProvider;
+
+  CanteenLocationService(this._preferencesProvider);
+
+  Future<CanteenLocation?> getConfiguredLocation() async {
+    final id = await _preferencesProvider.getSelectedCanteenLocationId();
+    if (id == null || id.isEmpty) {
+      return null;
+    }
+
+    return CanteenLocations.fromId(id);
+  }
+
+  Future<CanteenLocation> getSelectedLocation() async {
+    return await getConfiguredLocation() ?? CanteenLocations.defaultLocation;
+  }
+
+  Future<void> setSelectedLocation(CanteenLocation location) async {
+    await _preferencesProvider.setSelectedCanteenLocationId(location.id);
+  }
+
+  List<CanteenLocation> supportedLocations() {
+    return List<CanteenLocation>.unmodifiable(CanteenLocations.supported);
+  }
+}

lib/canteen/business/canteen_provider.dart

@@ -1,9 +1,12 @@
 import 'dart:async';
 
 import 'package:dualmate/canteen/data/canteen_meal_repository.dart';
+import 'package:dualmate/canteen/model/canteen_location.dart';
 import 'package:dualmate/canteen/model/daily_menu.dart';
 import 'package:dualmate/canteen/model/meal.dart';
+import 'package:dualmate/canteen/business/canteen_location_service.dart';
 import 'package:dualmate/canteen/service/canteen_scraper.dart';
+import 'package:dualmate/canteen/service/open_mensa_canteen_source.dart';
 import 'package:dualmate/common/util/cancellation_token.dart';
 import 'package:dualmate/common/util/date_utils.dart';
 
@@ -15,12 +18,20 @@ typedef CanteenMenuUpdatedCallback = Future<void> Function(
 
 class CanteenProvider {
   final CanteenMealRepository _repository;
+  final CanteenLocationService _locationService;
   final CanteenScraper _scraper;
+  final OpenMensaCanteenSource _openMensaSource;
   final List<CanteenMenuUpdatedCallback> _callbacks = [];
   final Map<DateTime, Future<List<DailyMenu>>> _refreshInFlight = {};
   final Map<DateTime, DateTime> _lastRefreshAtByWeek = {};
+  String? _activeLocationId;
 
-  CanteenProvider(this._repository, this._scraper);
+  CanteenProvider(
+    this._repository,
+    this._locationService,
+    this._scraper,
+    this._openMensaSource,
+  );
 
   void addMenuUpdatedCallback(CanteenMenuUpdatedCallback callback) {
     _callbacks.add(callback);
@@ -31,6 +42,7 @@ class CanteenProvider {
   }
 
   Future<List<DailyMenu>> getCachedWeek(DateTime date) async {
+    await _ensureActiveLocationCache();
     var weekStart = toStartOfDay(toMonday(date));
     var weekEnd = weekStart.add(const Duration(days: 5));
 
@@ -39,6 +51,7 @@ class CanteenProvider {
   }
 
   Future<DateTime?> lastUpdatedForWeek(DateTime date) async {
+    await _ensureActiveLocationCache();
     var weekStart = toStartOfDay(toMonday(date));
     var weekEnd = weekStart.add(const Duration(days: 5));
     return _repository.latestMealDateBetween(weekStart, weekEnd);
@@ -111,9 +124,14 @@ class CanteenProvider {
     CancellationToken? cancellationToken,
     required bool prefetchNextWeek,
   }) async {
+    final location = await _ensureActiveLocationCache();
     var weekEnd = weekStart.add(const Duration(days: 5));
 
-    var menus = await _scraper.loadWeek(weekStart, cancellationToken);
+    var menus = await _loadWeekForLocation(
+      location,
+      weekStart,
+      cancellationToken,
+    );
     var normalizedMenus = _normalizeMenus(weekStart, menus);
 
     await _repository.deleteMealsBetween(weekStart, weekEnd);
@@ -135,11 +153,16 @@ class CanteenProvider {
     DateTime weekStart,
     CancellationToken? cancellationToken,
   ) async {
+    final location = await _ensureActiveLocationCache();
     var nextWeekStart = toStartOfDay(weekStart.add(const Duration(days: 7)));
     var nextWeekEnd = nextWeekStart.add(const Duration(days: 5));
 
     try {
-      var nextMenus = await _scraper.loadWeek(nextWeekStart, cancellationToken);
+      var nextMenus = await _loadWeekForLocation(
+        location,
+        nextWeekStart,
+        cancellationToken,
+      );
       var normalizedNextMenus = _normalizeMenus(nextWeekStart, nextMenus);
 
       await _repository.deleteMealsBetween(nextWeekStart, nextWeekEnd);
@@ -164,6 +187,36 @@ class CanteenProvider {
     }
   }
 
+  Future<CanteenLocation> _ensureActiveLocationCache() async {
+    final selected = await _locationService.getSelectedLocation();
+    if (_activeLocationId == selected.id) {
+      return selected;
+    }
+
+    _activeLocationId = selected.id;
+    _refreshInFlight.clear();
+    _lastRefreshAtByWeek.clear();
+    await _repository.clearMeals();
+    return selected;
+  }
+
+  Future<List<DailyMenu>> _loadWeekForLocation(
+    CanteenLocation location,
+    DateTime weekStart,
+    CancellationToken? cancellationToken,
+  ) {
+    if (location.isKarlsruheLegacy) {
+      return _scraper.loadWeek(weekStart, cancellationToken);
+    }
+
+    final openMensaId = location.openMensaId;
+    if (openMensaId == null) {
+      throw Exception('Missing OpenMensa id for selected canteen');
+    }
+
+    return _openMensaSource.loadWeek(openMensaId, weekStart, cancellationToken);
+  }
+
   List<DailyMenu> _groupMealsByDay(DateTime weekStart, List<Meal> meals) {
     var mealsByDay = <DateTime, List<Meal>>{};
 

lib/canteen/data/canteen_meal_repository.dart

@@ -72,4 +72,8 @@ class CanteenMealRepository {
       ],
     );
   }
+
+  Future<void> clearMeals() async {
+    await _database.deleteWhere(CanteenMealEntity.tableName());
+  }
 }

lib/canteen/model/canteen_location.dart

@@ -0,0 +1,70 @@
+class CanteenLocation {
+  final String id;
+  final String name;
+  final String? subtitle;
+  final CanteenLocationSource source;
+  final int? openMensaId;
+
+  const CanteenLocation({
+    required this.id,
+    required this.name,
+    required this.source,
+    this.subtitle,
+    this.openMensaId,
+  });
+
+  bool get isKarlsruheLegacy => source == CanteenLocationSource.karlsruheLegacy;
+}
+
+enum CanteenLocationSource {
+  karlsruheLegacy,
+  openMensa,
+}
+
+class CanteenLocations {
+  static const String karlsruheId = 'karlsruhe_erzbergerstrasse';
+
+  static const List<CanteenLocation> supported = <CanteenLocation>[
+    CanteenLocation(
+      id: karlsruheId,
+      name: 'DHBW Karlsruhe',
+      subtitle: 'Mensa Erzbergerstrasse',
+      source: CanteenLocationSource.karlsruheLegacy,
+    ),
+    CanteenLocation(
+      id: 'mannheim_dhbw_eppelheim',
+      name: 'DHBW Mannheim',
+      subtitle: 'Mensa DHBW Eppelheim',
+      source: CanteenLocationSource.openMensa,
+      openMensaId: 795,
+    ),
+    CanteenLocation(
+      id: 'horb_dhbw_stuttgart',
+      name: 'DHBW Horb',
+      subtitle: 'Campus Horb',
+      source: CanteenLocationSource.openMensa,
+      openMensaId: 923,
+    ),
+  ];
+
+  static const CanteenLocation defaultLocation = CanteenLocation(
+    id: karlsruheId,
+    name: 'DHBW Karlsruhe',
+    subtitle: 'Mensa Erzbergerstrasse',
+    source: CanteenLocationSource.karlsruheLegacy,
+  );
+
+  static CanteenLocation fromId(String? id) {
+    if (id == null || id.isEmpty) {
+      return defaultLocation;
+    }
+
+    for (final location in supported) {
+      if (location.id == id) {
+        return location;
+      }
+    }
+
+    return defaultLocation;
+  }
+}