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

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