Add delta-reconnect optimization, pupil label printing, and test suite

Delta-reconnect: server tracks per-HubObjectType change timestamps in
memory (HubUpdatesTracker), exposes via getLastChangeTimes RPC endpoint,
and instruments all 50 broadcast sites with touch() calls. Client
compares server change times against disconnect timestamp and emits
HubSelectiveReconnect instead of full HubReconnected. All 10 managers
handle selective reconnect with fallback to full refetch on failure.

Pupil labels: add PupilLabelPdfService generating AVERY 5759 format
labels with QR code, school grade, learning group, and school name.
Integrated into School Lists page.

Tests: 136 tests covering HubUpdatesTracker, delta comparison logic,
DateTimeExtensions (client + server), SchooldayEventFilterPredicates,
PupilIdentityHelper CSV parsing, PupilIdentityExtension serialization/
equality, PupilProxyHelper predicates, and AES-CBC encrypt/decrypt
round-trips.

Author: dabblingwithcode

docs/model_relations/school_data_hub_server.svg

@@ -0,0 +1,82 @@
+/* AUTOMATICALLY GENERATED CODE DO NOT MODIFY */
+/*   To generate run: "serverpod generate"    */
+
+// ignore_for_file: implementation_imports
+// ignore_for_file: library_private_types_in_public_api
+// ignore_for_file: non_constant_identifier_names
+// ignore_for_file: public_member_api_docs
+// ignore_for_file: type_literal_in_constant_pattern
+// ignore_for_file: use_super_parameters
+
+// ignore_for_file: no_leading_underscores_for_library_prefixes
+import 'package:serverpod_client/serverpod_client.dart' as _i1;
+import '../../../_features/hub/models/hub_object_type.dart' as _i2;
+
+abstract class HubTypeLastUpdate implements _i1.SerializableModel {
+  HubTypeLastUpdate._({
+    required this.objectType,
+    required this.changedAt,
+  });
+
+  factory HubTypeLastUpdate({
+    required _i2.HubObjectType objectType,
+    required DateTime changedAt,
+  }) = _HubTypeLastUpdateImpl;
+
+  factory HubTypeLastUpdate.fromJson(Map<String, dynamic> jsonSerialization) {
+    return HubTypeLastUpdate(
+      objectType:
+          _i2.HubObjectType.fromJson((jsonSerialization['objectType'] as int)),
+      changedAt:
+          _i1.DateTimeJsonExtension.fromJson(jsonSerialization['changedAt']),
+    );
+  }
+
+  _i2.HubObjectType objectType;
+
+  DateTime changedAt;
+
+  /// Returns a shallow copy of this [HubTypeLastUpdate]
+  /// with some or all fields replaced by the given arguments.
+  @_i1.useResult
+  HubTypeLastUpdate copyWith({
+    _i2.HubObjectType? objectType,
+    DateTime? changedAt,
+  });
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'objectType': objectType.toJson(),
+      'changedAt': changedAt.toJson(),
+    };
+  }
+
+  @override
+  String toString() {
+    return _i1.SerializationManager.encode(this);
+  }
+}
+
+class _HubTypeLastUpdateImpl extends HubTypeLastUpdate {
+  _HubTypeLastUpdateImpl({
+    required _i2.HubObjectType objectType,
+    required DateTime changedAt,
+  }) : super._(
+          objectType: objectType,
+          changedAt: changedAt,
+        );
+
+  /// Returns a shallow copy of this [HubTypeLastUpdate]
+  /// with some or all fields replaced by the given arguments.
+  @_i1.useResult
+  @override
+  HubTypeLastUpdate copyWith({
+    _i2.HubObjectType? objectType,
+    DateTime? changedAt,
+  }) {
+    return HubTypeLastUpdate(
+      objectType: objectType ?? this.objectType,
+      changedAt: changedAt ?? this.changedAt,
+    );
+  }
+}

school_data_hub_client/lib/src/protocol/_features/hub/models/hub_type_last_update.dart

@@ -1,6 +1,6 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_it/flutter_it.dart';
-import 'package:school_data_hub_flutter/common/services/hub_stream_service.dart';
+import 'package:school_data_hub_flutter/core/client/hub_stream_service.dart';
 import 'package:school_data_hub_flutter/common/services/notification_service.dart';
 import 'package:school_data_hub_flutter/common/theme/app_colors.dart';
 import 'package:school_data_hub_flutter/common/theme/styles.dart';

school_data_hub_client/lib/src/protocol/client.dart

@@ -28,6 +28,28 @@ sealed class HubLocalEvent {}
 /// Emitted after a successful reconnect; subscribers should refetch their data.
 final class HubReconnected extends HubLocalEvent {}
 
+/// Emitted when only specific object types changed during disconnect.
+final class HubSelectiveReconnect extends HubLocalEvent {
+  final Set<HubObjectType> changedTypes;
+  HubSelectiveReconnect(this.changedTypes);
+}
+
+/// Given a list of per-type last-change timestamps from the server and
+/// the moment this client disconnected, returns the set of [HubObjectType]s
+/// that were modified while the client was offline.
+///
+/// Extracted as a top-level function so it can be unit-tested without
+/// standing up [HubStreamService].
+Set<HubObjectType> computeChangedTypes(
+  List<HubTypeLastUpdate> changeTimes,
+  DateTime disconnectedAt,
+) {
+  return changeTimes
+      .where((ct) => ct.changedAt.isAfter(disconnectedAt))
+      .map((ct) => ct.objectType)
+      .toSet();
+}
+
 /// Backoff cap in milliseconds.
 const _maxReconnectDelayMs = 30000;
 const _initialReconnectDelayMs = 1000;
@@ -48,6 +70,7 @@ class HubStreamService with WidgetsBindingObserver {
   final _random = Random();
   VoidCallback? _connectivityListener;
   String? _currentDeviceId;
+  DateTime? _disconnectedAt;
 
   final _events = StreamController<Object>.broadcast();
 
@@ -133,12 +156,26 @@ class HubStreamService with WidgetsBindingObserver {
   }
 
   void _cleanupSubscription() {
+    if (_state.value == HubConnectionState.connected) {
+      _disconnectedAt = DateTime.now().toUtc();
+    }
     _hasReceivedFirstEvent = false;
     final sub = _subscription;
     _subscription = null;
     sub?.cancel();
   }
 
+  Future<Set<HubObjectType>?> _getChangedTypesSinceDisconnect() async {
+    if (_disconnectedAt == null) return null;
+    try {
+      final changeTimes = await di<Client>().hub.getLastChangeTimes();
+      return computeChangedTypes(changeTimes, _disconnectedAt!);
+    } catch (e) {
+      _log.warning('[HUB] Could not fetch change times: $e');
+      return null;
+    }
+  }
+
   void _scheduleReconnect({
     required bool isReconnect,
     required int delayMs,
@@ -181,15 +218,25 @@ class HubStreamService with WidgetsBindingObserver {
     if (isReconnect) {
       _reconnectTimer = Timer(
         const Duration(milliseconds: _dnsGraceDelayMs),
-        () {
+        () async {
           _reconnectTimer = null;
           if (!_appInForeground || _disposed) {
             _connecting = false;
             return;
           }
-          if (!_disposed) {
+
+          final changedTypes = await _getChangedTypesSinceDisconnect();
+          if (changedTypes == null) {
             _events.add(HubReconnected());
+          } else if (changedTypes.isNotEmpty) {
+            _log.info(
+              '[HUB] Selective reconnect: ${changedTypes.length} types changed',
+            );
+            _events.add(HubSelectiveReconnect(changedTypes));
+          } else {
+            _log.info('[HUB] No events missed — skipping refetch');
           }
+
           _doSubscribe();
         },
       );

school_data_hub_client/lib/src/protocol/protocol.dart

@@ -3,7 +3,7 @@ import 'package:logging/logging.dart';
 import 'package:school_data_hub_client/school_data_hub_client.dart';
 import 'package:school_data_hub_flutter/app_utils/secure_storage.dart';
 import 'package:school_data_hub_flutter/common/domain/filters/filters_state_manager.dart';
-import 'package:school_data_hub_flutter/common/services/hub_stream_service.dart';
+import 'package:school_data_hub_flutter/core/client/hub_stream_service.dart';
 import 'package:school_data_hub_flutter/core/env/env_manager.dart';
 import 'package:school_data_hub_flutter/core/init/init_manager.dart';
 import 'package:school_data_hub_flutter/core/session/hub_session_manager.dart';

school_data_hub_flutter/assets/school_data_hub_server.svg

@@ -5,7 +5,7 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter_it/flutter_it.dart';
 import 'package:logging/logging.dart';
 import 'package:school_data_hub_client/school_data_hub_client.dart';
-import 'package:school_data_hub_flutter/common/services/hub_stream_service.dart';
+import 'package:school_data_hub_flutter/core/client/hub_stream_service.dart';
 import 'package:school_data_hub_flutter/common/services/notification_service.dart';
 import 'package:school_data_hub_flutter/core/models/datetime_extensions.dart';
 import 'package:school_data_hub_flutter/core/session/hub_session_manager.dart';
@@ -62,6 +62,10 @@ class AttendanceManager with ChangeNotifier {
       deleteFromStream(event.id);
     } else if (event is HubReconnected) {
       fetchAllPupilMissedSchooldayes();
+    } else if (event is HubSelectiveReconnect) {
+      if (event.changedTypes.contains(HubObjectType.missedSchoolday)) {
+        fetchAllPupilMissedSchooldayes();
+      }
     }
   }