303 lines
17 KiB
Markdown
303 lines
17 KiB
Markdown
# 11. 门店上下文与会话管理
|
||
|
||
## 为什么单独一篇
|
||
|
||
门店上下文是**贯穿整个 App 的隐式依赖**：首页 tile、菜单、购物车、待办、预警、订单、缓存表、H5 页面全部与"当前门店"绑定（PRD REQ-LGN-010：当前门店影响所有业务数据）。它不属于任何一个 `feature_*`，但每个 `feature_*` 都依赖它。
|
||
|
||
更关键的是**切换门店时的级联失效**——这是最容易漏、漏了就会出"看到别的门店数据"这种严重问题的地方。之前 01-10 里只在各自话题下提了一句（03 讲 provider 失效、06 讲缓存清理、10 讲 H5 失效），没有一个地方定义完整顺序。这一篇负责收口。
|
||
|
||
## 会话状态模型
|
||
|
||
```
|
||
AppSession
|
||
├── AuthState 登录态（token 生命周期，归 core_auth）
|
||
├── UserContext 用户上下文（PRD 第 4.1 节）
|
||
└── StoreContext 门店上下文（PRD REQ-LGN-010）
|
||
```
|
||
|
||
```dart
|
||
// packages/core_auth/lib/src/model/app_session.dart
|
||
sealed class AppSession {}
|
||
|
||
/// 冷启动读本地态期间，UI 停在 splash
|
||
class SessionLoading extends AppSession {}
|
||
|
||
class SessionUnauthenticated extends AppSession {
|
||
final LogoutReason? reason; // 主动登出 / token 失效 / 被踢，用于登录页提示文案
|
||
}
|
||
|
||
/// 已登录但还没确定门店（多门店用户需要选，或门店列表拉取失败）
|
||
class SessionAwaitingStore extends AppSession {
|
||
final UserContext user;
|
||
}
|
||
|
||
class SessionActive extends AppSession {
|
||
final UserContext user;
|
||
final StoreContext store;
|
||
}
|
||
```
|
||
|
||
**四个状态，不是布尔值。** 用 `bool isLoggedIn` 表达会立刻遇到两个说不清的场景：冷启动期间算不算已登录（算，会闪一下首页；不算，会闪一下登录页），以及"已登录但没门店"该去哪（PRD REQ-LGN-010 要求登录后必须确定唯一「当前门店」，缺失时需引导重新选择，这是一个独立页面，既不是登录页也不是首页）。sealed class 让 `04-routing.md` 的 redirect 能穷举分支，漏一个编译器就报错。
|
||
|
||
```dart
|
||
final class UserContext {
|
||
final String userId, employeeId, phone, roleCode, channel;
|
||
final Set<String> permissions; // 权限集
|
||
}
|
||
|
||
final class StoreContext {
|
||
final int storeId;
|
||
final String storeCode, storeName;
|
||
final int orgId;
|
||
final String? parentStoreId; // 所属总店，无则为分店/独立店
|
||
final List<MenuItem> menus; // 当前门店可访问菜单，见 04-routing.md 的 menuRouteMap
|
||
}
|
||
```
|
||
|
||
`menus` 放在 `StoreContext` 里而不是 `UserContext` 里——PRD 第 4.2.5 节（导航收敛与角色化配置）明确菜单是**门店维度**的（同一个人在 A 店是店长、在 B 店是店员，菜单不同）。放错地方会导致切店后菜单不刷新。
|
||
|
||
## 唯一真相源
|
||
|
||
```dart
|
||
@riverpod
|
||
class SessionNotifier extends _$SessionNotifier {
|
||
@override
|
||
Future<AppSession> build() async { ... }
|
||
}
|
||
|
||
/// 全 App 读 storeId 的唯一入口
|
||
@riverpod
|
||
int currentStoreId(Ref ref) {
|
||
final session = ref.watch(sessionNotifierProvider).valueOrNull;
|
||
return switch (session) {
|
||
SessionActive(:final store) => store.storeId,
|
||
_ => throw StateError('在没有门店上下文时访问了 currentStoreId'),
|
||
};
|
||
}
|
||
```
|
||
|
||
规则（与 [03-state-management.md](./03-state-management.md) 一致）：
|
||
|
||
- **任何请求里带 storeId 的 provider，必须 `ref.watch(currentStoreIdProvider)` 拿它**，不能 `ref.read`，也不能作为参数从上层传下来。这样切店时依赖图自动失效，不需要维护"哪些 provider 要手动 invalidate"的清单——那份清单一定会漏。
|
||
- `currentStoreId` 在非 `SessionActive` 时**抛异常而不是返回 0 或 null**。能读到这个 provider 说明 UI 已经渲染到了业务页面，此时没有门店上下文是路由守卫的 bug，应该在开发期直接炸出来，而不是发一个 `storeId=0` 的请求让后端返回一堆空数据。
|
||
|
||
## 登录流程
|
||
|
||
PRD REQ-LGN-010：登录后必须确定唯一「当前门店」。
|
||
|
||
```
|
||
输入手机号 + 验证码（或账号密码）
|
||
↓
|
||
POST /api/v1/auth/login → { accessToken, refreshToken, user }
|
||
↓
|
||
写入 secure storage（core_auth 独占，见 06）
|
||
↓
|
||
GET /api/v1/stores/accessible → 门店列表
|
||
↓
|
||
┌────┴────┬──────────────┐
|
||
0 个 1 个 多个
|
||
↓ ↓ ↓
|
||
"无门店权限" 直接选中 上次门店仍在列表 → 选中
|
||
提示 + 登出 否则 → 门店选择页
|
||
↓
|
||
POST /api/v1/stores/{id}/switch → StoreContext（含菜单）
|
||
↓
|
||
SessionActive → 跳首页
|
||
```
|
||
|
||
几个容易做错的点：
|
||
|
||
- **`stores/accessible` 失败不等于登录失败**。token 已经拿到了，此时应该进 `SessionAwaitingStore` 并展示一个可重试的页面，而不是回登录页让用户重新发一遍验证码。
|
||
- **"上次门店"只是一个提示，不是权限依据**。它存在 `shared_preferences`（非敏感，见 [06-local-storage.md](./06-local-storage.md)），冷启动/登录时用来预选，但**必须先确认它在后端返回的可访问列表里**——用户的门店权限可能已经被管理员回收了。
|
||
- **0 个门店时必须登出**，不能停在一个空白首页。PRD 第 4.1.1 节的异常流程把「账号无任何门店归属」列为阻断登录的分支。
|
||
|
||
## 切换门店：级联失效清单
|
||
|
||
这是本篇的核心。PRD REQ-LGN-010：切换门店时级联失效所有门店相关缓存与在途请求。
|
||
|
||
**顺序是有意义的**，不能随便调：
|
||
|
||
```dart
|
||
Future<void> switchStore(int targetStoreId) async {
|
||
// ── 0. 前置：有未完成的写操作就拦住 ──────────────────
|
||
if (ref.read(pendingWriteProvider).isNotEmpty) {
|
||
throw const PreconditionException('有未完成的操作，请稍后再试'); // 本地判定，不编后端错误码，见 12
|
||
}
|
||
|
||
// ── 1. 先让 UI 进入切换中，挡住用户继续操作 ──────────
|
||
state = const AsyncLoading();
|
||
|
||
// ── 2. 服务端切换（失败则整个流程中止，本地状态不动）──
|
||
final newStore = await _repo.switchStore(targetStoreId);
|
||
|
||
// ── 3. 关闭 H5 会话（不清 Cookie，见 10）─────────────
|
||
await ref.read(webViewSessionProvider).invalidateAll(clearCookies: false);
|
||
|
||
// ── 4. 清本地业务缓存（事务内，见 06）────────────────
|
||
await ref.read(appDatabaseProvider).clearBusinessCache();
|
||
|
||
// ── 5. 落新的门店上下文 → 依赖 currentStoreId 的 provider 自动失效 ──
|
||
state = AsyncData(SessionActive(user: _user, store: newStore));
|
||
|
||
// ── 6. 路由清栈回首页（见 04）────────────────────────
|
||
ref.read(goRouterProvider).go('/home');
|
||
|
||
// ── 7. 记住这次选择，供下次冷启动预选 ────────────────
|
||
await ref.read(prefsProvider).setInt('last_store_id', newStore.storeId);
|
||
|
||
// ── 8. 同步观测上下文（见 13）────────────────────────
|
||
ref.read(crashReporterProvider).setTag('storeId', '${newStore.storeId}');
|
||
ref.read(analyticsProvider).registerSuperProperties({'storeId': newStore.storeId});
|
||
// 切店事件本身由后端从 /stores/{id}/switch 的接口日志出，客户端不重复上报，见 13
|
||
}
|
||
```
|
||
|
||
| 步 | 为什么必须在这个位置 |
|
||
|---|---|
|
||
| 2 在 3/4 之前 | 服务端切换失败（网络断、权限被回收）时**本地必须原样不动**。反过来先清缓存再请求，一旦失败用户就停在一个"门店没变但数据全没了"的状态 |
|
||
| 3 在 5 之前 | H5 页面里可能有在途请求。先 `about:blank` 停掉，再换上下文，否则旧门店的 H5 请求会带着新门店的票据回来 |
|
||
| 4 在 5 之前 | 缓存表带 `storeId`（见 06），但**清理和新上下文之间不能有窗口期**：如果先落新上下文，provider 立刻失效并重新请求，可能在清理完成前就把新数据写进去，然后被 `clearBusinessCache()` 一起删掉 |
|
||
| 6 在 5 之后 | 清栈时目标页面（首页）要用新上下文渲染 |
|
||
| 8 在 5 之后 | 观测上下文要和业务上下文保持一致；漏了这一步的表现是**切店后的崩溃和埋点还挂在旧门店名下**，按门店维度分析时数据是错的，而且错得很隐蔽 |
|
||
|
||
**关于步骤 0（未完成写操作）**：切店时用户可能正在提交订单或上传图片。默认策略是**阻止切换并提示**，而不是静默取消——取消一个已经发出去的下单请求，客户端不知道服务端到底成没成。`pendingWriteProvider` 由发起写操作的 feature 自己注册/注销。
|
||
|
||
**关于购物车**：PRD 要求切店后购物车同步切换。购物车走 `clearBusinessCache()` 一起清（它是门店维度的业务数据）。如果后续产品要求"每个门店各自保留购物车"，那就改成按 `storeId` 分区保留而不是清空——表结构已经带 `storeId`，改动只在这一处。
|
||
|
||
## 登出：清理清单
|
||
|
||
PRD REQ-LGN-008（登出）：清理本地会话、门店上下文、缓存的业务数据与 WebView Cookie。
|
||
|
||
```dart
|
||
Future<void> logout({LogoutReason reason = LogoutReason.userInitiated}) async {
|
||
// 1. 通知服务端撤销 refresh token（尽力而为，失败不阻断本地登出）
|
||
if (reason == LogoutReason.userInitiated) {
|
||
await _repo.revokeSession().timeout(const Duration(seconds: 3)).catchError((_) {});
|
||
}
|
||
|
||
// 2. H5 会话 + Cookie/LocalStorage/Cache 全清（见 10）
|
||
await ref.read(webViewSessionProvider).invalidateAll(clearCookies: true);
|
||
|
||
// 3. 本地数据
|
||
await ref.read(appDatabaseProvider).clearAllUserData(); // Drift 业务表
|
||
await ref.read(secureStorageProvider).deleteAll(); // token
|
||
await ref.read(prefsProvider).clearUserScoped(); // 只清用户相关的 key
|
||
|
||
// 4. 状态置为未登录 → 路由守卫自动跳登录页
|
||
state = AsyncData(SessionUnauthenticated(reason: reason));
|
||
|
||
// 5. 断开观测/埋点的用户关联（门店设备是共用的，不断开会让下一个人的数据串到上一个人身上）
|
||
ref.read(analyticsProvider)
|
||
..track(AnalyticsEvent.logout, {'reason': reason.name}) // 报完再 reset，顺序不能反
|
||
..reset();
|
||
ref.read(crashReporterProvider).setUser('');
|
||
|
||
// 6. 兜底：清掉所有 provider 缓存
|
||
ref.invalidate(...); // 或在 ProviderScope 层重建，见下文
|
||
}
|
||
```
|
||
|
||
要点：
|
||
|
||
- **第 1 步失败不能阻断登出**。网络不通时用户点登出必须能退出去，否则用户体验是"这个 App 退不出来"。服务端 token 会自然过期，不撤销的代价可以接受。加 3 秒超时。
|
||
- **`prefs.clearUserScoped()` 而不是 `prefs.clear()`**。`shared_preferences` 里还有"是否同意过协议""夜间模式偏好""是否看过新手引导"这类设备级配置，全清会导致下一个用户看一遍新手引导。约定：用户相关的 key 统一加 `u_` 前缀，`clearUserScoped()` 按前缀删。
|
||
- **必须等第 2/3 步完成再切状态**。fire-and-forget 会出现"新用户已经登录进首页了，上一个用户的缓存清理才刚跑完"，然后把新用户的数据也删了。门店共用设备上这不是理论问题。
|
||
- **`clearCookies: true` 在登出时是硬要求**。不清的话下一个人打开 H5 会直接落进上一个人的 F6 会话——这是本项目最有可能出现的一个真实安全事故。
|
||
|
||
### 登出兜底：为什么还要一步 provider 清理
|
||
|
||
`ref.invalidate` 一个个点名会漏。更稳的做法是让整个业务 provider 树挂在一个 key 上重建：
|
||
|
||
```dart
|
||
// main.dart
|
||
ProviderScope(
|
||
retry: (_, __) => null,
|
||
child: Consumer(builder: (context, ref, _) {
|
||
final sessionKey = ref.watch(sessionKeyProvider); // 每次登录/登出自增
|
||
return KeyedSubtree(key: ValueKey(sessionKey), child: const ContiApp());
|
||
}),
|
||
)
|
||
```
|
||
|
||
**注意这只重建 widget 树，不重建 provider（provider 挂在 `ProviderScope` 上，在 `KeyedSubtree` 外面）。** 真正让业务 provider 全部失效的是"它们都直接或间接 `ref.watch(currentStoreIdProvider)` / `sessionNotifierProvider`"这条规则 —— 状态一变，`autoDispose` 的 provider 自然重算，`keepAlive` 的少数几个（见 03 的三类白名单）**必须在登出时显式 invalidate**，清单就是那三类，是有限且可维护的。
|
||
|
||
## 与 refresh token 轮换的配合
|
||
|
||
后端采用**一次性 refresh token + 重放即全量撤销**（见 [backend/04-security-auth.md](../backend/04-security-auth.md)）。这对客户端有两条硬约束，已经在 [05-networking.md](./05-networking.md) 的 `AuthInterceptor` 里实现，这里说明它和会话状态的关系：
|
||
|
||
1. **刷新必须串行**。并发刷新会把同一个 refresh token 用两次，后端判定为重放，**撤销该用户所有设备的会话**——用户会在自己毫无操作的情况下被全端踢下线。
|
||
2. **刷新失败立即登出，不重试**。失败意味着 refresh token 已失效（过期、被撤销、或已被重放），重试只会再触发一次重放判定。
|
||
|
||
```dart
|
||
// TokenRefresher 刷新失败 → 通知会话层
|
||
void _onRefreshFailed() {
|
||
ref.read(sessionNotifierProvider.notifier).logout(reason: LogoutReason.tokenExpired);
|
||
}
|
||
```
|
||
|
||
`LogoutReason.tokenExpired` 让登录页能显示「登录已过期，请重新登录」而不是一个没有解释的空登录页。用户在别处被踢（`sessionRevoked`）时提示文案也不同。
|
||
|
||
## 冷启动恢复
|
||
|
||
```
|
||
App 启动 → SessionLoading（splash）
|
||
↓
|
||
读 secure storage 的 token
|
||
↓
|
||
没有 → SessionUnauthenticated
|
||
有 → GET /api/v1/auth/me + /stores/accessible
|
||
↓
|
||
┌───┴────────────────┬─────────────────┐
|
||
成功 401 网络失败
|
||
↓ ↓ ↓
|
||
预选 last_store_id → 登出 进首页 + 用本地缓存渲染
|
||
→ SessionActive （见 12 的降级约定）
|
||
```
|
||
|
||
- **secure storage 读失败要当作未登录处理**，不能让异常冒到启动流程里（见 [06-local-storage.md](./06-local-storage.md) 关于 `flutter_secure_storage 11.0.0` 的说明）。启动崩溃是最难排查也最致命的一类问题。
|
||
- **网络失败时不要把用户踢到登录页**。门店里网络不稳是常态，本地有 token 就先按已登录处理，用缓存渲染首页，顶部提示"数据可能不是最新"。真正无效的 token 会在第一个业务请求返回 401 时被发现，那时再登出。
|
||
- splash 有**最长等待时间**（3 秒）。超时就按"网络失败"分支走，不能无限转圈。
|
||
|
||
## 回到前台时的一致性校验
|
||
|
||
App 从后台回来时，服务端的门店权限可能已经变了（管理员回收了权限、门店被停用）。
|
||
|
||
```dart
|
||
// 冷时间超过 5 分钟才校验，避免频繁切前后台打接口
|
||
if (elapsedSinceBackground > const Duration(minutes: 5)) {
|
||
final stores = await _repo.fetchAccessibleStores();
|
||
if (!stores.any((s) => s.storeId == currentStoreId)) {
|
||
// 当前门店已不可访问
|
||
await switchStore(stores.first.storeId); // 或引导重选
|
||
showToast('您对当前门店的权限已变更，已切换到 ${stores.first.storeName}');
|
||
}
|
||
}
|
||
```
|
||
|
||
不做这个校验的后果是：用户带着一个已失效的 storeId 继续操作，每个请求都被后端拒绝，界面上表现为"什么都点不动但也不说为什么"。
|
||
|
||
## 埋点
|
||
|
||
会话相关事件大部分**由后端从自己的接口日志出**（登录、切店都是接口调用），客户端不重复报（见 [13-observability-analytics.md](./13-observability-analytics.md) 的分工原则）。客户端只补后端看不到的两件事：
|
||
|
||
| 事件 | 谁报 | 关键字段 |
|
||
|---|---|---|
|
||
| 登录成功/失败、门店切换 | **后端** | 接口日志即可，客户端不重复上报 |
|
||
| `logout` | **客户端** | `reason`（userInitiated / tokenExpired / sessionRevoked）。**被动登出往往没有对应的接口调用**——token 刷新失败是客户端本地判定的，后端只看到一个失败的刷新请求，看不到"用户因此被踢了出去" |
|
||
| `session_restore_failed` | **客户端** | 失败阶段（读 storage / me / stores）。冷启动恢复失败在读 secure storage 这一步时**完全不产生网络请求**，后端无从知晓 |
|
||
|
||
`logout` 的 `reason` 分布是最有价值的一个指标——如果 `tokenExpired` 占比异常高，说明刷新逻辑有问题（很可能就是并发刷新触发了后端的重放撤销）。这个指标只能由客户端提供。
|
||
|
||
## 待确认项
|
||
|
||
- `/api/v1/stores/accessible` 与 `/api/v1/stores/{id}/switch` 的接口契约，以及切换是否需要服务端记录（影响多端一致性）。
|
||
- 切店时"未完成写操作"的判定粒度：是全局阻止，还是只阻止发起写操作的那个 feature。
|
||
- 购物车是否需要按门店分别保留（当前决策：清空）。
|
||
- 前台一致性校验的触发阈值（当前定 5 分钟）需要跑一个迭代后按实际接口压力调整。
|
||
|
||
## 参考链接
|
||
|
||
- [PRD 第 4.1 节 账号登录（REQ-LGN-008 登出 / REQ-LGN-010 门店上下文）](../prd/Continental-Retail-APP-PRD.md)
|
||
- [backend/04-security-auth.md：refresh token 轮换](../backend/04-security-auth.md)
|
||
- [Riverpod: Combining requests](https://riverpod.dev/docs/essentials/combining_requests)
|