Client Cache Conventions

Client cache architecture rules for this project. Refer to the /client-cache skill for detailed implementation guide.

3 Cache Strategies#

Automatic Strategy Selection Rules#

GET 목록  → SWR          → Stream < Either < Failure, List < T > > > 
 GET 단일  → CacheFirst or NetworkFirst  → Future < Either < Failure, T > > 
 POST/PUT/DELETE → 직접 호출 (캐시 없음) + 관련 캐시 무효화

BlocSignal Transformer Rules#

Transformers are built into bloc_signals — do not import bloc_concurrency.

⚠️ bloc_signals' restartable() discards state emissions from superseded executions — unlike package:bloc, it does not cancel the handler's stream subscription. Subscription cleanup is your responsibility (see below). concurrent() does not exist; omitting the transformer is the default.

// ✅ CORRECT: Apply restartable to SWR events
on<ItemsLoad>(_onLoad, transformer: restartable());

// ✅ CORRECT: Apply droppable to write events
on<ItemCreate>(_onCreate, transformer: droppable());

SWR Stream Subscription Rules#

⚠️ emit.forEach does not exist in bloc_signals — it was a package:bloc Emitter API. The previous rule ("manual StreamSubscription management prohibited") is inverted: an explicitly owned subscription is now the required pattern, because nothing cleans it up automatically.

When integrating with an SWR UseCase (call() returns Stream), hold the subscription on the container and cancel it in close(). An onError handler is still required.

// ✅ CORRECT: container-owned subscription + onError + close() cleanup
StreamSubscription<Either<Failure, List<Item>>>? _subscription;

Future<void> _onLoad(ItemsLoad event, void Function(ItemsState) emit) async {
  await _subscription?.cancel(); // re-subscribe cleanly

  _subscription = const GetItemsUseCase().call(GetItemsParams(...)).listen(
    (result) {
      if (isClosed) return; // close() does not cancel in-flight work
      emit(result.fold(
        (failure) => stateValue.copyWith(
          status: LoadingStatus.error,
          failure: failure,
        ),
        (items) => stateValue.copyWith(
          status: LoadingStatus.loaded,
          items: items,
        ),
      ));
    },
    onError: (Object _, StackTrace __) {
      if (isClosed) return;
      emit(stateValue.copyWith(status: LoadingStatus.error));
    },
  );
}

@override
Future<void> close() async {
  if (isClosed) return;
  await _subscription?.cancel(); // ⚠️ required — no automatic cleanup
  await super.close();
}

// ❌ WRONG: emit.forEach — does not exist in bloc_signals
// ❌ WRONG: relying on restartable() to cancel the subscription (it only drops emissions)
// ❌ WRONG: omitting the close() override → leaked subscription

// ❌ WRONG: .last loses SWR benefits (ignores cache)
final result = await useCase.call(params).last;

// ❌ WRONG: .first ignores server refresh (receives cache only)
final result = await useCase.call(params).first;

Anti-pattern details: See swr-pattern.md §8

cacheKey Format#

' {domain}__{usecase}__key:value '

• Separator: double underscore (__)
• Pagination parameters (page, size, limit, offset) not included
• Filter parameters are nullable, included only when != null
• Sort/order parameters must be included — omitting them returns the previous sort's cache on sort change (#6877/#6924)
• User/permission scope segment (e.g. pub:{publisherId}) when the response varies by requester — a shared key leaks another scope's data (#7893)
• Date: Use CacheQuery.fmtDate() (yyyy-MM-dd)

Example:

'schedule__get_schedule_data__start:2026-03-01__end:2026-03-31__class:5566'
'homework__get_homework_list__classId:42'

TTL (Cache Expiration Time)#

Drift Table Rules#

Requirements#

• Row tables only (JSON blob prohibited)
• Do not set primaryKey (use rowid)
• cacheKey + cachedAt columns required
• Column names must match domain entity field names
• For nested structures, include parent entity fields as columns in each row

// ✅ CORRECT: 행 테이블, primaryKey 없음
class HomeworkItems extends Table {
  TextColumn get cacheKey => text()();
  TextColumn get homeworkId => text()();
  TextColumn get title => text()();
  DateTimeColumn get cachedAt => dateTime()();
  // No primaryKey (use rowid)
}

// ❌ WRONG: JSON blob
class HomeworkDetailItems extends Table {
  TextColumn get cacheKey => text()();
  TextColumn get json => text()();  // JSON 금지
  @override
  Set<Column> get primaryKey => {cacheKey};  // primaryKey 설정 금지
}

upsert prohibited -> DELETE + INSERT#

// ✅ CORRECT: DELETE then INSERT
Future<void> saveItems(List<XxxCompanion> companions, String cacheKey) async {
  await (delete(table)..where((t) => t.cacheKey.equals(cacheKey))).go();
  await batch((b) => b.insertAll(table, companions));
}

// ❌ WRONG: upsert prohibited
await into(table).insertOnConflictUpdate(companion);

DB Migration: deleteTable + createTable#

onUpgrade: (Migrator migrator, int from, int to) async {
  for (final table in allTables) {
    await migrator.deleteTable(table.actualTableName);
    await migrator.createTable(table);
  }
},

DAO Rules#

• Handle Drift CRUD only (no domain entity dependency)
• Accept only Companion for INSERT
• Entity <-> Companion conversion is CacheRepository's responsibility

CacheRepository Conversion Methods#

// ✅ CORRECT
static XxxEntity _toEntity(XxxItemData data) { ... }
static XxxCompanion _toCompanion(XxxEntity entity, String cacheKey) { ... }

// ❌ WRONG
static XxxEntity _dataToXxx(XxxItemData data) { ... }

UseCase Rules#

• All UseCases use Params class (when parameters exist)
• SWR UseCase: Does not implement UseCase interface, _repository getter, returns Stream
• Future UseCase: implements UseCase, repo getter, try-catch + Log.e
• Unified OpenApiService (OpenApiClient prohibited)

Cache Invalidation After Write#

Delete related caches by prefix after POST/PUT/DELETE completion.

await dao.deleteByCacheKeyPrefix('schedule__get_memo');
await dao.deleteByCacheKeyPrefix('schedule__get_memos');

Structured alternative (kobic, Epic #6021): prefer repository-level MutationRepositoryMixin.executeMutation(invalidatedPrefixes:) so invalidation cannot be forgotten per-mutation, and invalidation failures never mask an already-successful server mutation — see swr-pattern skill §15.

LIKE wildcard caveat (#8334): implement deleteByCacheKeyPrefix with a string range comparison (>= prefix AND < prefix + '\uffff'), not like('$prefix%') — _ in cache keys is a single-char LIKE wildcard, so my_page__ would also delete myxpage__… keys.

Related Documents#

• Client Cache Skill - Detailed implementation guide
• Caching Patterns Detail
• BLoC Patterns