Merge pull request #558 from DevKor-github/feature/issue-531-preparation-prefetch

fix: batch selected-day preparation prefetch

Author: jjoonleo

CONTEXT.md

@@ -53,6 +53,22 @@ _Avoid_: Provider login completed, credential received
 An allowlisted non-content value attached to a Product Usage Event.
 _Avoid_: Event payload, arbitrary metadata, raw detail
 
+**Schedule**:
+A planned commitment with an appointment time and place that OnTime helps the user prepare for.
+_Avoid_: Calendar event, meeting
+
+**Preparation**:
+The set of user-planned steps completed before leaving for a Schedule.
+_Avoid_: Prep routine, checklist
+
+**Preparation Duration**:
+The sum of a Schedule's Preparation step durations, excluding move time and Schedule Spare Time.
+_Avoid_: Total duration, travel time, buffer time
+
+**Schedule Spare Time**:
+A user buffer before a Schedule's appointment time, separate from travel time and Preparation Duration.
+_Avoid_: Preparation time, move time
+
 **Schedule Notification**:
 A user-facing notification that starts preparation for a scheduled commitment at the intended moment.
 _Avoid_: Schedule alarm, alarm, push
@@ -117,6 +133,8 @@ _Avoid_: Notification, native alarm
 - An **Analytics Event Parameter** must not contain user-authored text, direct identifiers, tokens, raw exception strings, request bodies, or response bodies.
 - A **Product Usage Event** uses a stable snake_case name and includes a schema version.
 - A changed **Product Usage Event** meaning requires a new event name or schema version.
+- A **Schedule** has a **Preparation** whose **Preparation Duration** contributes to preparation-start timing.
+- **Preparation Duration**, move time, and **Schedule Spare Time** are distinct schedule timing inputs.
 - User-facing copy should call a scheduled notification a **Schedule Notification**, not an **Alarm**, unless it opens an OnTime screen without the user first tapping a notification.
 - The profile setting for upcoming schedule preparation delivery should be called **Schedule Notification Setting**.
 - On iOS, user-facing copy may say **Alarm** only when OnTime can deliver an **iOS AlarmKit Alarm**.
@@ -180,3 +198,4 @@ _Avoid_: Notification, native alarm
 - "Time Sensitive" was too platform-specific for default user-facing status; resolved: fallback iOS delivery should be called notification.
 - "Status label" was ambiguous across platforms; resolved: Android uses precise notification or notification status, while iOS uses alarm status only for **iOS AlarmKit Alarm**.
 - "No scheduled alarm" was too capability-specific for an empty state; resolved: use **No Scheduled Notification** across platforms.
+- "Total duration" was ambiguous between **Preparation Duration** and the broader preparation-start timing calculation; resolved: **Preparation Duration** is steps only, while move time and **Schedule Spare Time** are separate inputs.

lib/presentation/calendar/bloc/monthly_schedules_bloc.dart

@@ -20,6 +20,8 @@ part 'monthly_schedules_state.dart';
 @Injectable()
 class MonthlySchedulesBloc
     extends Bloc<MonthlySchedulesEvent, MonthlySchedulesState> {
+  static const int _maxPreparationPrefetchConcurrency = 4;
+
   MonthlySchedulesBloc(
     this._loadSchedulesForMonthUseCase,
     this._getSchedulesByDateUseCase,
@@ -219,30 +221,77 @@ class MonthlySchedulesBloc
     }
 
     final fetchedDurations = <String, Duration>{};
-    var hasUpdates = false;
+    await _forEachMissingPreparationId(missingIds, (scheduleId) async {
+      final duration = await _loadPreparationDuration(scheduleId);
+      if (duration != null) {
+        fetchedDurations[scheduleId] = duration;
+      }
+    });
 
-    for (final scheduleId in missingIds) {
-      try {
-        await _loadPreparationByScheduleIdUseCase(scheduleId);
-        if (state.preparationDurationByScheduleId.containsKey(scheduleId)) {
-          // Stream update already has fresher data.
+    if (fetchedDurations.isNotEmpty && !emit.isDone) {
+      final updatedMap = Map<String, Duration>.from(
+        state.preparationDurationByScheduleId,
+      );
+      var hasUpdates = false;
+      for (final entry in fetchedDurations.entries) {
+        if (updatedMap.containsKey(entry.key)) {
           continue;
         }
-        final preparation = await _getPreparationByScheduleIdUseCase(
-          scheduleId,
-        );
-        fetchedDurations[scheduleId] = preparation.totalDuration;
+        updatedMap[entry.key] = entry.value;
         hasUpdates = true;
-      } catch (_) {
-        // Keep fallback UI when loading fails.
+      }
+      if (hasUpdates) {
+        emit(state.copyWith(preparationDurationByScheduleId: () => updatedMap));
       }
     }
+  }
 
-    if (hasUpdates) {
-      final updatedMap = Map<String, Duration>.from(
-        state.preparationDurationByScheduleId,
-      )..addAll(fetchedDurations);
-      emit(state.copyWith(preparationDurationByScheduleId: () => updatedMap));
+  Future<void> _forEachMissingPreparationId(
+    Set<String> scheduleIds,
+    Future<void> Function(String scheduleId) load,
+  ) async {
+    final ids = scheduleIds.toList(growable: false);
+    var nextIndex = 0;
+    final workerCount = ids.length < _maxPreparationPrefetchConcurrency
+        ? ids.length
+        : _maxPreparationPrefetchConcurrency;
+
+    String? takeNextId() {
+      if (nextIndex >= ids.length) {
+        return null;
+      }
+      return ids[nextIndex++];
+    }
+
+    await Future.wait(
+      List<Future<void>>.generate(workerCount, (_) async {
+        while (true) {
+          final scheduleId = takeNextId();
+          if (scheduleId == null) {
+            return;
+          }
+          await load(scheduleId);
+        }
+      }),
+    );
+  }
+
+  Future<Duration?> _loadPreparationDuration(String scheduleId) async {
+    if (state.preparationDurationByScheduleId.containsKey(scheduleId)) {
+      return null;
+    }
+
+    try {
+      await _loadPreparationByScheduleIdUseCase(scheduleId);
+      if (state.preparationDurationByScheduleId.containsKey(scheduleId)) {
+        // Stream update already has fresher data.
+        return null;
+      }
+      final preparation = await _getPreparationByScheduleIdUseCase(scheduleId);
+      return preparation.totalDuration;
+    } catch (_) {
+      // Keep fallback UI when loading fails.
+      return null;
     }
   }
 

test/presentation/calendar/bloc/monthly_schedules_bloc_test.dart

@@ -187,6 +187,67 @@ void main() {
     },
   );
 
+  test(
+    'preparation prefetch starts multiple uncached schedule loads without serial waiting',
+    () async {
+      final loadStarted = <String, Completer<void>>{
+        scheduleA.id: Completer<void>(),
+        scheduleB.id: Completer<void>(),
+      };
+      final loadAllowedToFinish = <String, Completer<void>>{
+        scheduleA.id: Completer<void>(),
+        scheduleB.id: Completer<void>(),
+      };
+      addTearDown(() {
+        for (final completer in loadAllowedToFinish.values) {
+          if (!completer.isCompleted) {
+            completer.complete();
+          }
+        }
+      });
+
+      loadPreparationByScheduleIdUseCase =
+          StubLoadPreparationByScheduleIdUseCase((scheduleId) async {
+            loadStarted[scheduleId]?.complete();
+            await loadAllowedToFinish[scheduleId]?.future;
+          });
+
+      final bloc = buildBloc();
+      addTearDown(bloc.close);
+
+      bloc.add(
+        MonthlySchedulesPreparationsPrefetchRequested(
+          scheduleIds: [scheduleA.id, scheduleB.id],
+        ),
+      );
+
+      await loadStarted[scheduleA.id]!.future.timeout(
+        const Duration(milliseconds: 50),
+      );
+      await loadStarted[scheduleB.id]!.future.timeout(
+        const Duration(milliseconds: 50),
+      );
+
+      loadAllowedToFinish[scheduleA.id]!.complete();
+      loadAllowedToFinish[scheduleB.id]!.complete();
+
+      final prefetchedState = await bloc.stream.firstWhere(
+        (state) =>
+            state.preparationDurationByScheduleId.containsKey(scheduleA.id) &&
+            state.preparationDurationByScheduleId.containsKey(scheduleB.id),
+      );
+
+      expect(
+        prefetchedState.preparationDurationByScheduleId[scheduleA.id],
+        const Duration(minutes: 20),
+      );
+      expect(
+        prefetchedState.preparationDurationByScheduleId[scheduleB.id],
+        const Duration(minutes: 15),
+      );
+    },
+  );
+
   test('cached schedule preparations are not fetched again', () async {
     getSchedulesByDateUseCase = StubGetSchedulesByDateUseCase(
       (_, __) => Stream<List<ScheduleEntity>>.fromIterable([