qzl
b34697660d
- 新增 AuthSessionInvalidated 事件处理 token 失效场景 - ApiInterceptor 新增 authFailureCallback 单飞机制 - AuthBloc 区分 manual logout 与 auto expiry 语义 - 新增 startup recovery fallback 防止启动卡死 feat: 重构 Calendar DayWeek 视图事件布局引擎 - 新增 DayEventLayoutEngine 解耦事件计算与渲染 - 新增 DayTimelineMetrics 统一时间轴常量 - 新增 DayViewScale 支持捏合缩放 feat: 新增 Settings 页面共享 UI 组件 - 新增 BackTitlePageHeader 统一页面 header - 新增 DetailHeaderActionMenu 统一操作菜单 - 新增 DestructiveActionSheet 统一删除确认 - 新增 AppToggleSwitch 统一开关组件 feat: Chat UI Schema 支持导航操作 - 支持 navigation 类型 action 触发内部路由跳转 - 新增路径验证与参数处理 chore: 更新相关测试覆盖 auth 失效路径
159 lines
5.0 KiB
Markdown
159 lines
5.0 KiB
Markdown
# 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**
|
|
|
|
输出剩余风险、可观测性建议、生产灰度建议。
|