social-app/docs/plans/2026-03-27-data-repositories-cache-strategy.md

# Data Repositories Cache Strategy Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Establish a shared cache abstraction and shared data-repository entrypoints so cross-feature data access no longer depends on direct feature-to-feature data imports.

**Architecture:** Keep cache infrastructure centralized in `apps/lib/data/cache/`, and expose cross-feature data through `apps/lib/data/repositories/` facades registered in DI as singletons. Feature screens consume repositories, while cache policy/key/invalidation remain in repository layer.

**Tech Stack:** Flutter, Dart, GetIt, flutter_test

---

### Task 1: Finalize Shared Cache Foundation

**Files:**
- Modify: `apps/lib/data/cache/cached_repository.dart`
- Modify: `apps/lib/features/settings/data/services/user_profile_cache_repository.dart`
- Test: `apps/test/features/settings/data/services/user_profile_cache_repository_test.dart`

**Step 1: Write the failing test**

Add an invalidate-vs-inflight regression case in `user_profile_cache_repository_test.dart` asserting stale in-flight refresh cannot restore `cachedUser` after invalidate.

**Step 2: Run test to verify it fails**

Run: `flutter test test/features/settings/data/services/user_profile_cache_repository_test.dart`

Expected: FAIL before generation-guard fix.

**Step 3: Write minimal implementation**

Add generation/version guard in `UserProfileCacheRepository` so `invalidate()` increments generation and stale async loader results are ignored for in-memory snapshot updates.

**Step 4: Run test to verify it passes**

Run: `flutter test test/features/settings/data/services/user_profile_cache_repository_test.dart`

Expected: PASS.

**Step 5: Commit**

```bash
git add apps/lib/data/cache/cached_repository.dart apps/lib/features/settings/data/services/user_profile_cache_repository.dart apps/test/features/settings/data/services/user_profile_cache_repository_test.dart
git commit -m "refactor: harden user profile cache invalidation race handling"
```

### Task 2: Introduce Shared Data Repositories Module

**Files:**
- Create: `apps/lib/data/repositories/inbox_repository.dart`
- Create: `apps/lib/data/repositories/calendar_event_repository.dart`
- Create: `apps/lib/data/repositories/user_repository.dart`
- Modify: `apps/lib/app/di/injection.dart`

**Step 1: Write the failing test**

Add a DI registration smoke test (or lightweight compile-level usage test) that resolves the new repositories from GetIt.

**Step 2: Run test to verify it fails**

Run: `flutter test <new-test-file>`

Expected: FAIL because repositories are not yet defined/registered.

**Step 3: Write minimal implementation**

Implement repository facades that wrap existing APIs (`InboxApi`, `CalendarApi`, `UsersApi`) and register them as singletons in DI.

**Step 4: Run test to verify it passes**

Run: `flutter test <new-test-file>`

Expected: PASS.

**Step 5: Commit**

```bash
git add apps/lib/data/repositories apps/lib/app/di/injection.dart
git commit -m "refactor: add shared data repositories module"
```

### Task 3: Migrate Cross-Feature Screens to Shared Repositories

**Files:**
- Modify: `apps/lib/features/messages/presentation/screens/message_invite_detail_screen.dart`
- Modify: `apps/lib/features/messages/presentation/screens/message_invite_list_screen.dart`
- Modify: `apps/lib/features/todo/presentation/screens/todo_edit_screen.dart`

**Step 1: Write the failing test**

Add targeted tests for message detail/list data loading and todo edit schedule loading using repository dependencies.

**Step 2: Run test to verify it fails**

Run: `flutter test <affected-test-files>`

Expected: FAIL before dependency switch.

**Step 3: Write minimal implementation**

Replace direct API injections with shared repository injections from `apps/lib/data/repositories/*`.

**Step 4: Run test to verify it passes**

Run: `flutter test <affected-test-files>`

Expected: PASS.

**Step 5: Commit**

```bash
git add apps/lib/features/messages/presentation/screens/message_invite_detail_screen.dart apps/lib/features/messages/presentation/screens/message_invite_list_screen.dart apps/lib/features/todo/presentation/screens/todo_edit_screen.dart
git commit -m "refactor: switch cross-feature screens to shared repositories"
```

### Task 4: Verification and Cleanup

**Files:**
- Modify: `apps/AGENTS.md`
- Modify: `docs/bugs/2026-03-27-repository缓存抽象.md`
- Modify: `docs/bugs/服务层与Repository层职责混乱.md`

**Step 1: Run full targeted verification**

Run: `flutter analyze lib/data/cache lib/data/repositories lib/app/di/injection.dart lib/features/messages/presentation/screens/message_invite_detail_screen.dart lib/features/messages/presentation/screens/message_invite_list_screen.dart lib/features/todo/presentation/screens/todo_edit_screen.dart`

Expected: No issues.

**Step 2: Run regression tests**

Run: `flutter test test/data/cache/cached_repository_test.dart test/features/settings/data/services/user_profile_cache_repository_test.dart test/app/router/app_router_redirect_test.dart`

Expected: PASS.

**Step 3: Update docs status**

Mark relevant bug docs as in-progress/resolved and document new layering rules.

**Step 4: Commit**

```bash
git add apps/AGENTS.md docs/bugs/2026-03-27-repository缓存抽象.md docs/bugs/服务层与Repository层职责混乱.md
git commit -m "docs: document shared repository and cache strategy"
```