Merge pull request #57 from FarisZR/fix/dualis-session-refresh

fix: keep Dualis logged in and add manual refresh

Author: FarisZR

AGENTS.md

@@ -50,6 +50,11 @@ Important runtime behavior:
 
 - Navigation entry and page under `lib/dualis/ui`
 - Service stack includes cache decorator + scraper/authentication in `lib/dualis/service`
+- Stored Dualis credentials should restore the session automatically when the
+  Dualis section is shown again; long-idle returns should trigger a refresh
+  instead of dropping the user back to the login form.
+- Logged-in Dualis pages support manual pull-to-refresh, which should force a
+  cache-busting reload of overview and semester data.
 
 ### Schedule (`lib/schedule`)
 

docs/solutions/ui-bugs/dualis-session-persistence-and-refresh-20260519.md

@@ -0,0 +1,52 @@
+---
+module: Dualis UI
+date: 2026-05-19
+problem_type: ui_bug
+component: frontend_flutter
+symptoms:
+  - "Dualis asks the user to log in again after reopening the app"
+  - "There is no manual pull-to-refresh path on the Dualis pages"
+  - "Returning to Dualis after a long time does not automatically refresh stale data"
+root_cause: dualis_view_model_only_supported_explicit_login_and_never_revalidated_on_page_visibility
+resolution_type: code_fix
+severity: medium
+tags: [dualis, login, session, refresh, cache, flutter, android]
+---
+
+# Troubleshooting: Dualis session persistence and refresh
+
+## Problem
+Dualis only stayed usable for the current in-memory session. After reopening the app, the page returned to the login form even when credentials were already stored. The logged-in views also lacked a manual refresh affordance.
+
+## Root Cause
+The Dualis view model supported explicit login only. It never attempted to restore a stored session when the page became visible again, and it had no persisted freshness timestamp to decide when stale data should be reloaded automatically.
+
+## Solution
+- Updated `StudyGradesViewModel` to:
+  - start in an initializing state so Dualis does not render the logged-out UI before the first saved-credential check completes
+  - restore the Dualis session from saved credentials when the Dualis section becomes visible
+  - refresh stale Dualis data automatically when reopening the section after a long gap
+  - expose `refreshData(force: true)` so the UI can trigger a full cache-busting reload
+  - track the last successful Dualis refresh in preferences
+- Updated `DualisPage` to:
+  - observe section visibility inside the main `IndexedStack`
+  - trigger the stale-session refresh flow on first show and on app resume while Dualis is active
+  - show a loading state while the session is being restored
+- Added pull-to-refresh to:
+  - `StudyOverviewPage`
+  - `ExamResultsPage`
+- Extended the Dualis service contract with `clearCache()` so forced refreshes bypass cached grade/module data.
+
+## Test Coverage
+- `login falls back to LoginFailed on unexpected service errors`
+- `loadAllModules keeps loading=true for the newest in-flight request`
+- `restores the Dualis session from saved credentials on page open`
+- `does not show login page before restoring saved session`
+- `refreshData(force: true) clears cached Dualis data before reloading`
+- existing Dualis loading animation widget tests
+
+## Commands run
+```bash
+flutter test test/dualis/ui/viewmodels/study_grades_view_model_test.dart test/dualis/ui/study_overview_loading_animation_test.dart test/dualis/ui/dualis_page_session_restore_test.dart
+flutter analyze lib/dualis lib/common/data/preferences/preferences_provider.dart test/dualis/ui/viewmodels/study_grades_view_model_test.dart test/dualis/ui/study_overview_loading_animation_test.dart
+```

lib/common/data/preferences/preferences_provider.dart

@@ -18,6 +18,7 @@ class PreferencesProvider {
   static const String DualisStoreCredentials = "StoreDualisCredentials";
   static const String DualisUsername = "DualisUsername";
   static const String DualisPassword = "DualisPassword";
+  static const String DualisLastRefreshAt = "DualisLastRefreshAt";
   static const String LastViewedSemester = "LastViewedSemester";
   static const String LastViewedDateEntryDatabase =
       "LastViewedDateEntryDatabase";
@@ -165,6 +166,21 @@ class PreferencesProvider {
     await _preferencesAccess.set<bool>(DualisStoreCredentials, value);
   }
 
+  Future<DateTime?> getDualisLastRefreshAt() async {
+    final storedMs = await _preferencesAccess.get<int>(DualisLastRefreshAt);
+    if (storedMs == null || storedMs <= 0) {
+      return null;
+    }
+    return DateTime.fromMillisecondsSinceEpoch(storedMs);
+  }
+
+  Future<void> setDualisLastRefreshAt(DateTime value) async {
+    await _preferencesAccess.set<int>(
+      DualisLastRefreshAt,
+      value.millisecondsSinceEpoch,
+    );
+  }
+
   Future<String> getLastViewedSemester() async {
     return await _preferencesAccess.get<String>(LastViewedSemester) ?? "";
   }

lib/dualis/service/cache_dualis_service_decorator.dart

@@ -23,7 +23,11 @@ class CacheDualisServiceDecorator extends DualisService {
     String password, [
     CancellationToken? cancellationToken,
   ]) {
-    return _service.login(username, password, cancellationToken ?? CancellationToken());
+    return _service.login(
+      username,
+      password,
+      cancellationToken ?? CancellationToken(),
+    );
   }
 
   @override
@@ -34,7 +38,9 @@ class CacheDualisServiceDecorator extends DualisService {
       return _allModulesCached!;
     }
 
-    var allModules = await _service.queryAllModules(cancellationToken ?? CancellationToken());
+    var allModules = await _service.queryAllModules(
+      cancellationToken ?? CancellationToken(),
+    );
 
     _allModulesCached = allModules;
 
@@ -49,7 +55,10 @@ class CacheDualisServiceDecorator extends DualisService {
     if (_semestersCached.containsKey(name)) {
       return Future.value(_semestersCached[name]);
     }
-    var semester = await _service.querySemester(name, cancellationToken ?? CancellationToken());
+    var semester = await _service.querySemester(
+      name,
+      cancellationToken ?? CancellationToken(),
+    );
 
     _semestersCached[name] = semester;
 
@@ -64,7 +73,9 @@ class CacheDualisServiceDecorator extends DualisService {
       return _allSemesterNamesCached!;
     }
 
-    var allSemesterNames = await _service.querySemesterNames(cancellationToken ?? CancellationToken());
+    var allSemesterNames = await _service.querySemesterNames(
+      cancellationToken ?? CancellationToken(),
+    );
 
     _allSemesterNamesCached = allSemesterNames;
 
@@ -79,7 +90,9 @@ class CacheDualisServiceDecorator extends DualisService {
       return _studyGradesCached!;
     }
 
-    var studyGrades = await _service.queryStudyGrades(cancellationToken ?? CancellationToken());
+    var studyGrades = await _service.queryStudyGrades(
+      cancellationToken ?? CancellationToken(),
+    );
 
     _studyGradesCached = studyGrades;
 
@@ -91,12 +104,14 @@ class CacheDualisServiceDecorator extends DualisService {
     _allSemesterNamesCached = null;
     _semestersCached = {};
     _studyGradesCached = null;
+    _service.clearCache();
   }
 
   @override
   Future<void> logout([
     CancellationToken? cancellationToken,
   ]) async {
-    await _service.logout(cancellationToken ?? CancellationToken());    clearCache();
+    await _service.logout(cancellationToken ?? CancellationToken());
+    clearCache();
   }
 }

lib/dualis/service/dualis_service.dart

@@ -32,6 +32,8 @@ abstract class DualisService {
   Future<void> logout([
     CancellationToken? cancellationToken,
   ]);
+
+  void clearCache();
 }
 
 enum LoginResult {
@@ -155,4 +157,7 @@ class DualisServiceImpl extends DualisService {
   ]) async {
     await _dualisScraper.logout(cancellationToken ?? CancellationToken());
   }
+
+  @override
+  void clearCache() {}
 }

lib/dualis/ui/dualis_navigation_entry.dart

@@ -11,6 +11,8 @@ import 'package:kiwi/kiwi.dart';
 import 'package:property_change_notifier/property_change_notifier.dart';
 
 class DualisNavigationEntry extends NavigationEntry<StudyGradesViewModel> {
+  static const int sectionIndex = 2;
+
   @override
   Widget icon(BuildContext context) {
     return Icon(Icons.data_usage);
@@ -31,7 +33,7 @@ class DualisNavigationEntry extends NavigationEntry<StudyGradesViewModel> {
 
   @override
   Widget build(BuildContext context) {
-    return DualisPage();
+    return const DualisPage(sectionIndex: sectionIndex);
   }
 
   @override

lib/dualis/ui/dualis_page.dart

@@ -8,7 +8,67 @@ import 'package:flutter/material.dart';
 import 'package:property_change_notifier/property_change_notifier.dart';
 import 'package:provider/provider.dart';
 
-class DualisPage extends StatelessWidget {
+class DualisPage extends StatefulWidget {
+  final int sectionIndex;
+
+  const DualisPage({super.key, required this.sectionIndex});
+
+  @override
+  State<DualisPage> createState() => _DualisPageState();
+}
+
+class _DualisPageState extends State<DualisPage> with WidgetsBindingObserver {
+  ValueNotifier<int>? _currentEntryIndex;
+
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addObserver(this);
+  }
+
+  @override
+  void didChangeDependencies() {
+    super.didChangeDependencies();
+    final notifier = Provider.of<ValueNotifier<int>>(context, listen: false);
+    if (!identical(_currentEntryIndex, notifier)) {
+      _currentEntryIndex?.removeListener(_handleSectionChanged);
+      _currentEntryIndex = notifier;
+      _currentEntryIndex?.addListener(_handleSectionChanged);
+    }
+
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!mounted) {
+        return;
+      }
+      _handleSectionChanged();
+    });
+  }
+
+  @override
+  void dispose() {
+    WidgetsBinding.instance.removeObserver(this);
+    _currentEntryIndex?.removeListener(_handleSectionChanged);
+    super.dispose();
+  }
+
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    if (state != AppLifecycleState.resumed) {
+      return;
+    }
+
+    _handleSectionChanged();
+  }
+
+  void _handleSectionChanged() {
+    if (!mounted || _currentEntryIndex?.value != widget.sectionIndex) {
+      return;
+    }
+
+    final viewModel = Provider.of<StudyGradesViewModel>(context, listen: false);
+    viewModel.onPageVisible();
+  }
+
   @override
   Widget build(BuildContext context) {
     StudyGradesViewModel viewModel =
@@ -24,26 +84,31 @@ class DualisPage extends StatelessWidget {
           Set<String>? properties,
         ) {
           final current = model ?? viewModel;
-          final child = current.loginState == LoginState.LoggedIn
-              ? PagerWidget(
-                  key: const ValueKey<String>('dualis_logged_in_pager'),
-                  pagesId: "dualis_pager",
-                  pages: <PageDefinition>[
-                    PageDefinition(
-                      text: L.of(context).pageDualisOverview,
-                      icon: const Icon(Icons.dashboard),
-                      builder: (BuildContext context) => StudyOverviewPage(),
-                    ),
-                    PageDefinition(
-                      text: L.of(context).pageDualisExams,
-                      icon: const Icon(Icons.book),
-                      builder: (BuildContext context) => ExamResultsPage(),
-                    ),
-                  ],
-                )
-              : const DualisLoginPage(
-                  key: ValueKey<String>('dualis_login_page'),
-                );
+          final child = switch (current.loginState) {
+            LoginState.LoggedIn => PagerWidget(
+                key: const ValueKey<String>('dualis_logged_in_pager'),
+                pagesId: "dualis_pager",
+                pages: <PageDefinition>[
+                  PageDefinition(
+                    text: L.of(context).pageDualisOverview,
+                    icon: const Icon(Icons.dashboard),
+                    builder: (BuildContext context) => StudyOverviewPage(),
+                  ),
+                  PageDefinition(
+                    text: L.of(context).pageDualisExams,
+                    icon: const Icon(Icons.book),
+                    builder: (BuildContext context) => ExamResultsPage(),
+                  ),
+                ],
+              ),
+            LoginState.Initializing || LoginState.RestoringSession =>
+              const _DualisSessionLoadingPage(
+                key: ValueKey<String>('dualis_restoring_page'),
+              ),
+            _ => const DualisLoginPage(
+                key: ValueKey<String>('dualis_login_page'),
+              ),
+          };
 
           return AnimatedSwitcher(
             duration: const Duration(milliseconds: 200),
@@ -54,3 +119,14 @@ class DualisPage extends StatelessWidget {
     );
   }
 }
+
+class _DualisSessionLoadingPage extends StatelessWidget {
+  const _DualisSessionLoadingPage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return const Center(
+      child: CircularProgressIndicator(),
+    );
+  }
+}