social-app/docs/plans/2026-03-18-auth-global-rewrite-plan.md

# Auth Global Rewrite Implementation Plan

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

**Goal:** 将 Flutter 客户端 Auth 重构为全局单一状态源，解决 401 后会话不一致、页面卡死和设备行为分裂问题。

**Architecture:** 以 `AuthBloc` 为唯一认证真相源，`ApiInterceptor` 仅负责协议层刷新与失败信号上抛。401 刷新失败后通过统一回调触发 `AuthSessionInvalidated`，由 `AuthBloc` 执行本地会话失效与状态切换，Router 仅根据 Auth 状态跳转。

**Tech Stack:** Flutter, flutter_bloc, dio, flutter_secure_storage, flutter_test, mocktail, bloc_test

---

### Task 1: 定义 Auth 失效语义与事件模型

**Files:**
- Modify: `apps/lib/features/auth/presentation/bloc/auth_event.dart`
- Modify: `apps/lib/features/auth/presentation/bloc/auth_state.dart`
- Test: `apps/test/features/auth/presentation/bloc/auth_bloc_test.dart`

**Step 1: Write the failing test**

新增失败测试：收到 session invalidated 事件后，状态应进入 `AuthUnauthenticated(expired)`。

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

Run: `flutter test test/features/auth/presentation/bloc/auth_bloc_test.dart`
Expected: FAIL（事件/状态原因不存在）

**Step 3: Write minimal implementation**

新增失效来源枚举、失效事件、未登录原因字段。

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

Run: `flutter test test/features/auth/presentation/bloc/auth_bloc_test.dart`
Expected: PASS

### Task 2: 重写 AuthBloc 启动恢复与失效收敛逻辑

**Files:**
- Modify: `apps/lib/features/auth/presentation/bloc/auth_bloc.dart`
- Modify: `apps/lib/features/auth/data/auth_repository.dart`
- Modify: `apps/lib/features/auth/data/auth_repository_impl.dart`
- Test: `apps/test/features/auth/presentation/bloc/auth_bloc_test.dart`
- Test: `apps/test/features/auth/data/auth_repository_test.dart`

**Step 1: Write failing tests**

- 启动读取 refresh token 抛异常 -> `AuthUnauthenticated(startupRecoveryFailed)`
- 自动过期登出只清本地不调后端

**Step 2: Run tests to verify failure**

Run: `flutter test test/features/auth/presentation/bloc/auth_bloc_test.dart test/features/auth/data/auth_repository_test.dart`
Expected: FAIL

**Step 3: Implement minimal code**

- `AuthBloc._onStarted` 增加异常兜底
- `AuthRepository` 新增 `clearSessionLocalOnly()`
- `AuthBloc` 处理 `AuthSessionInvalidated`

**Step 4: Run tests to verify pass**

Run: `flutter test test/features/auth/presentation/bloc/auth_bloc_test.dart test/features/auth/data/auth_repository_test.dart`
Expected: PASS

### Task 3: 改造 ApiInterceptor / ApiClient 全局失效回调链

**Files:**
- Modify: `apps/lib/core/api/api_interceptor.dart`
- Modify: `apps/lib/core/api/api_client.dart`
- Modify: `apps/lib/core/di/injection.dart`
- Test: `apps/test/core/api/api_interceptor_test.dart`

**Step 1: Write failing test**

并发 401 + refresh 失败时，`onAuthFailure` 仅触发一次。

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

Run: `flutter test test/core/api/api_interceptor_test.dart`
Expected: FAIL

**Step 3: Implement minimal code**

- interceptor 新增 auth failure singleflight
- api client 新增 `setAuthFailureCallback`
- DI 中将回调绑定到 `AuthBloc(AuthSessionInvalidated)`

**Step 4: Run test to verify pass**

Run: `flutter test test/core/api/api_interceptor_test.dart`
Expected: PASS

### Task 4: 平台安全存储配置与稳定性增强

**Files:**
- Modify: `apps/lib/core/di/injection.dart`

**Step 1: Add platform options**

为 `FlutterSecureStorage` 显式设置 Android/iOS 选项，减少机型差异。

**Step 2: Run targeted tests/analyze**

Run: `flutter analyze lib/core/di/injection.dart`
Expected: PASS

### Task 5: 路由与使用点适配

**Files:**
- Modify: `apps/lib/core/router/app_router.dart`
- Modify: `apps/lib/features/settings/ui/screens/account_screen.dart`
- Modify: `apps/lib/features/settings/ui/screens/change_password_screen.dart`

**Step 1: Update route/auth checks**

兼容 `AuthUnauthenticated(reason)` 新结构，保持原有登录流 UX。

**Step 2: Run focused tests**

Run: `flutter test test/features/auth`
Expected: PASS

### Task 6: 增加 Auth 全局强约束

**Files:**
- Modify: `apps/AGENTS.md`

**Step 1: Add mandatory auth rules**

新增“Auth 全局模块（MUST）”章节：
- 401 只允许走统一失效回调链
- 禁止 feature 私自清 token/私自跳登录
- Auth 状态只能由全局模块写入

**Step 2: Verify docs consistency**

Run: `git diff -- apps/AGENTS.md`
Expected: 仅新增约束，不改现有视觉/UI强规则

### Task 7: 全量验证

**Files:**
- Modify if needed after fixes

**Step 1: Run test suites**

Run: `flutter test test/core/api/api_interceptor_test.dart test/features/auth`

**Step 2: Run analyze on touched auth scope**

Run: `flutter analyze lib/core/api lib/features/auth lib/core/router/app_router.dart lib/core/di/injection.dart`

**Step 3: Report residual risks**

输出剩余风险、可观测性建议、生产灰度建议。