Caching Strategy Patterns

// domain/repository/i_schedule_repository.dart
abstract interface class IScheduleRepository {
  /// Returns Stream using SWR strategy
  Stream<Either<Failure, List<ScheduleDayData>>> getScheduleData({
    required DateTime startDate,
    required DateTime endDate,
    String? classId,
  });
}

mixin ScheduleOpenApiMixin implements IScheduleRepository {
  OpenApiService get openApiService;
  ScheduleItemDao get scheduleItemDao;

  @override
  Stream<Either<Failure, List<ScheduleDayData>>> getScheduleData({
    required DateTime startDate,
    required DateTime endDate,
    String? classId,
  }) =>
      SwrStrategyImpl<List<ScheduleDayData>>(
        cacheRepository: ScheduleDataCacheRepository(
          scheduleItemDao: scheduleItemDao,
        ),
        networkRepository: ScheduleDataNetworkRepository(
          openApiService: openApiService,
        ),
        policy: CachePolicies.standard,
      ).watchStream(
        ScheduleDataCacheQuery(
          startDate: startDate,
          endDate: endDate,
          classId: classId,
        ),
      );
}

// ✅ 권장형 — 세대 토큰 (unibook #13475 · unibook 정본 구현은 `package/core` 의
//    `SwrBlocSignalMixin`. 아래 ③(등록 직전 재확인)의 `isClosed` 와 `close()` 의
//    `super.close()` 선행은 그 정본에는 아직 없는 추가 방어다.)
class ScheduleBloc extends BlocSignal<ScheduleEvent, ScheduleState> {
  ScheduleBloc() : super(initialState: const ScheduleState()) {
    // restartable() 은 의도적으로 없다 — 아래 ⚠️ 참조.
    on<_LoadData>(_onLoadData);
  }

  StreamSubscription<Either<Failure, ScheduleData>>? _dataSub;
  int _dataGeneration = 0; // 겹친 호출 중 마지막만 구독한다 (unibook #13475)

  Future<void> _onLoadData(
    _LoadData event,
    void Function(ScheduleState) emit,
  ) async {
    // ① 호출 시작 시 세대를 확보하고, **같은 동기 구간에서** 슬롯을 비운 뒤 이전
    //    구독을 해제한다. 슬롯 쓰기를 `await` 뒤로 미루면, 늦게 재개한 낡은 호출이
    //    그 사이 등록된 **더 새로운** 구독의 등록을 지워 추적 밖으로 떨어뜨린다.
    final generation = ++_dataGeneration;
    final previous = _dataSub;
    _dataSub = null;
    await previous?.cancel();

    if (isClosed) return;
    // ② 위 await 사이에 같은 핸들러가 다시 들어왔으면 이 호출은 이미 낡았다 —
    //    구독을 열지 않고 물러난다. 열고 나서 등록하면 뒤 호출이 그것을 모른 채
    //    덮어써 아무도 닫지 못하는 좀비 구독이 남는다.
    if (generation != _dataGeneration) return;

    late final StreamSubscription<Either<Failure, ScheduleData>> subscription;
    subscription = const GetScheduleDataUseCase().call(
      GetScheduleDataParams(
        startDate: event.startDate,
        endDate: event.endDate,
      ),
    ).listen(
      (result) {
        if (isClosed) return;
        emit(result.fold(
          (failure) => stateValue.copyWith(status: LoadingStatus.failure),
          (data)    => stateValue.copyWith(status: LoadingStatus.success, data: data),
        ));
      },
      onError: (Object _, StackTrace __) {
        if (isClosed) return;
        emit(stateValue.copyWith(status: LoadingStatus.failure));
      },
      onDone: () {
        // ⑤ 자기 자신일 때만 등록 해제 — 더 새로운 구독의 등록을 지우면 안 된다.
        if (identical(_dataSub, subscription)) _dataSub = null;
      },
      // 에러 emission 후에도 구독을 유지 — 영구 watch(Drift) 반응성 보존.
      cancelOnError: false,
    );

    // ③ 등록 직전 재확인 — `emit` 이나 `listen` 이 **동기적으로** 같은 이벤트의
    //    재발행을, 혹은 리스너를 통해 `close()` 자체를 유발했을 수 있다. 낡았으면
    //    방금 연 구독을 닫는다. (`isClosed` 는 정본 `SwrBlocSignalMixin` 에는 없는
    //    추가 방어다 — 정본은 세대만 본다.)
    if (isClosed || generation != _dataGeneration) {
      await subscription.cancel();
      return;
    }
    // ④ 남아 있는 다른 구독은 먼저 cancel — 살아 있는 구독은 언제나 하나뿐이다.
    final stale = _dataSub;
    if (stale != null && !identical(stale, subscription)) {
      unawaited(stale.cancel()); // unawaited: dart:async
    }
    _dataSub = subscription;
  }

  /// ⑥ 명시적 취소도 **세대를 올린다** — 그러지 않으면 진행 중이던 호출이 취소
  /// 뒤에 구독을 열어 아무도 닫지 못한다.
  Future<void> cancelData() {
    _dataGeneration++;
    final subscription = _dataSub;
    _dataSub = null;
    return subscription?.cancel() ?? Future<void>.value();
  }

  @override
  Future<void> close() async {
    if (isClosed) return;
    // ⚠️ 정리보다 `super.close()` 를 **먼저** 부른다 — `bloc_signals` 1.2.0 의
    //    `CubitSignalMixin.close()`(`cubit_signal_mixin.dart`)는 가드
    //    `if (_isClosed) return;` **다음 줄**에서, 그리고 본문에 `await` 이 하나도
    //    없으므로 **어떤 await 보다 먼저** `_isClosed = true` 를 세운다. 즉
    //    `super.close()` 호출 즉시 `isClosed` 가 참이다. 반대로 취소를 먼저 await
    //    하면 그 구간 내내 `isClosed` 가 거짓이라, 그때 재개한 핸들러가 ②·③을
    //    통과해 새 구독을 열고 아무도 닫지 못한다. 구독은 그 await 앞에서
    //    스냅샷으로 떼어 둔다.
    //    (여기서 세대를 올려도 이 창은 닫히지 않는다 — 창 안에서 **새로 시작하는**
    //    호출은 스스로 최신 세대를 받아 ②·③을 그대로 통과한다. 닫는 것은
    //    `super.close()` 선행 하나뿐이다. SKILL §9-7 과 같은 근거.)
    final subscription = _dataSub;
    _dataSub = null;
    await super.close();
    await subscription?.cancel(); // ⚠️ 자동 정리 없음
  }
}

// ❌ 옛 형태 — 두 호출이 겹치면 구독이 샌다 (unibook #13475)
await _dataSub?.cancel();   // 겹친 두 호출이 각자 이전 구독을 취소하고
                            // (첫 로드면 취소할 것이 없다)
_dataSub = const GetScheduleDataUseCase().call(...).listen(...);
                            // 각자 새 구독을 연 뒤, 나중에 대입하는 쪽이
                            // 앞의 구독을 취소 없이 덮어쓴다 → 좀비 구독

1. add(LoadData(start: mar1))  → 스트림A 구독 (캐시 → 서버 순차 emit)
2. add(LoadData(start: apr1))  → 핸들러가 세대 확인 후 _dataSub 취소로 스트림A 해제
                                  → 스트림B 구독 시작
3. 1·2 가 await 사이에 겹침     → 세대 1 은 구독을 열지 않고 물러남(②)
                                  → 세대 2 만 구독 — 아래 ⚠️ 참조

@override
Future<Either<Failure, ScheduleMemo?>> getMemo({
  required DateTime date,
}) =>
    CacheFirstStrategyImpl<ScheduleMemo?>(
      cacheRepository: ScheduleMemoCacheRepository(
        memoCacheDao: memoCacheDao,
      ),
      networkRepository: ScheduleMemoNetworkRepository(
        openApiService: openApiService,
      ),
      policy: CachePolicies.standard,
    ).execute(
      ScheduleMemoCacheQuery(date: date),
    );

Future<void> _onDetailLoaded(
  _DetailLoaded event,
  void Function(ScheduleState) emit,
) async {
  emit(stateValue.copyWith(detailStatus: LoadingStatus.loading));
  final result = await const GetMemoUseCase().call(
    GetMemoParams(date: event.date),
  );
  if (isClosed) return;  // Required
  result.fold(
    (failure) => emit(stateValue.copyWith(detailStatus: LoadingStatus.failure)),
    (memo)    => emit(stateValue.copyWith(detailStatus: LoadingStatus.success, memo: memo)),
  );
}

@override
Future<Either<Failure, PaymentStatus>> getPaymentStatus({
  required String orderId,
}) =>
    NetworkFirstStrategyImpl<PaymentStatus>(
      cacheRepository: PaymentStatusCacheRepository(
        paymentStatusDao: paymentStatusDao,
      ),
      networkRepository: PaymentStatusNetworkRepository(
        openApiService: openApiService,
      ),
      policy: CachePolicies.realtime,
    ).execute(
      PaymentStatusCacheQuery(orderId: orderId),
    );

@DataClassName('ScheduleItemData')
class ScheduleItems extends Table {
  TextColumn get cacheKey => text()();          // Required
  DateTimeColumn get date => dateTime()();      // Parent field
  TextColumn get id => text()();
  TextColumn get title => text()();
  DateTimeColumn get cachedAt => dateTime()();  // Required
  // No primaryKey (use rowid)
}

// DELETE(cacheKey) + INSERT (upsert prohibited)
Future<void> saveItems(
  List<ScheduleItemsCompanion> companions,
  String cacheKey,
) async {
  await (delete(scheduleItems)
        ..where((t) => t.cacheKey.equals(cacheKey)))
      .go();
  await batch((b) => b.insertAll(scheduleItems, companions));
}

// Cache invalidation (prefix matching)
// ⚠️ Do NOT use like('$prefix%') — `_` in cache keys is a single-char LIKE
// wildcard, so 'my_page__' would also delete 'myxpage__…' keys (#8334).
// Use a string range comparison for exact prefix semantics:
Future<void> deleteByCacheKeyPrefix(String prefix) =>
    (delete(scheduleItems)..where(
          (t) =>
              t.cacheKey.isBiggerOrEqualValue(prefix) &
              t.cacheKey.isSmallerThanValue('$prefix\uffff'),
        ))
        .go();

HTTP Method?
├── GET
│   ├── Response is list  →  SWR
│   └── Response is single
│       ├── Offline first  →  CacheFirst
│       └── Always latest  →  NetworkFirst
└── POST/PUT/DELETE
    → Direct call + deleteByCacheKeyPrefix()