修复用户端令牌失效后的登录恢复

apps/user_app/lib/app/auth_navigation.dart

@@ -0,0 +1,33 @@
+// 功能描述：提供鉴权页面地址构造与站内回跳地址校验。
+// 版本：1.0.0
+
+/// 构造登录或注册地址，并安全携带原目标页和会话失效原因。
+String buildAuthLocation(
+  String authPath, {
+  String? redirectTarget,
+  bool sessionExpired = false,
+}) {
+  final safeTarget = sanitizeRedirectTarget(redirectTarget);
+  final query = <String, String>{
+    'redirect': ?safeTarget,
+    if (sessionExpired) 'reason': 'expired',
+  };
+  return Uri(
+    path: authPath,
+    queryParameters: query.isEmpty ? null : query,
+  ).toString();
+}
+
+/// 只接受站内绝对路径，阻止外部地址和鉴权页之间形成重定向循环。
+String? sanitizeRedirectTarget(String? value) {
+  final candidate = value?.trim() ?? '';
+  if (candidate.isEmpty) return null;
+
+  final uri = Uri.tryParse(candidate);
+  if (uri == null || uri.hasScheme || uri.hasAuthority || !uri.path.startsWith('/')) {
+    return null;
+  }
+  if (uri.path.startsWith('//') || uri.path.contains(r'\')) return null;
+  if (uri.path == '/login' || uri.path == '/register') return null;
+  return uri.toString();
+}

apps/user_app/lib/app/dependencies.dart

@@ -1,3 +1,6 @@
+// 功能描述：装配用户端依赖，并统一管理登录、退出和失效会话。
+// 版本：1.1.0
+
 import 'package:flutter/foundation.dart';
 
 import '../data/repositories/client_repository.dart';
@@ -5,7 +8,7 @@ import '../data/services/api_client.dart';
 import '../data/services/secure_session_store.dart';
 
 class AppDependencies {
-  AppDependencies._({
+  AppDependencies({
     required this.session,
     required this.repository,
   });
@@ -17,23 +20,32 @@ class AppDependencies {
     final store = SecureSessionStore();
     final session = UserSession(store);
     await session.restore();
-    final api = ApiClient(() => session.token);
-    return AppDependencies._(session: session, repository: ClientRepository(api));
+    final api = ApiClient(
+      () => session.token,
+      onUnauthorized: session.invalidate,
+    );
+    return AppDependencies(session: session, repository: ClientRepository(api));
   }
 }
 
+/// 管理内存令牌、持久化令牌以及会话失效通知。
 class UserSession extends ChangeNotifier {
   UserSession(this._store);
 
   static const _root = '/heqi/client/v1/user';
-  final SecureSessionStore _store;
+  final SessionStore _store;
   String _token = '';
+  bool _expired = false;
+  Future<void> _pendingClear = Future<void>.value();
 
   String get token => _token;
   bool get isAuthenticated => _token.isNotEmpty;
+  bool get hasExpired => _expired;
 
+  /// 从安全存储恢复令牌；是否有效由后续受保护接口响应确认。
   Future<void> restore() async {
     _token = await _store.readToken() ?? '';
+    _expired = false;
   }
 
   Future<void> login({
@@ -57,9 +69,14 @@ class UserSession extends ChangeNotifier {
         },
       ),
     );
-    _token = details['access_token'] as String? ?? '';
-    if (_token.isEmpty) throw const ApiException(500, '登录令牌缺失');
-    await _store.writeToken(_token);
+    final token = details['access_token'] as String? ?? '';
+    if (token.isEmpty) throw const ApiException(500, '登录令牌缺失');
+
+    // 等待旧令牌清理结束，避免迟到的删除任务误删刚写入的新令牌。
+    await _pendingClear;
+    await _store.writeToken(token);
+    _token = token;
+    _expired = false;
     notifyListeners();
   }
 
@@ -77,7 +94,29 @@ class UserSession extends ChangeNotifier {
 
   Future<void> logout() async {
     _token = '';
-    await _store.clear();
+    _expired = false;
     notifyListeners();
+    _pendingClear = _clearStoredToken();
+    await _pendingClear;
+  }
+
+  /// 仅当服务端拒绝的仍是当前令牌时，使会话失效并通知路由。
+  void invalidate(String rejectedToken) {
+    if (rejectedToken.isEmpty || rejectedToken != _token || _expired) return;
+
+    _token = '';
+    _expired = true;
+    notifyListeners();
+    _pendingClear = _clearStoredToken();
+  }
+
+  /// 尽力删除持久化令牌；失败不得阻塞用户返回登录页。
+  Future<void> _clearStoredToken() async {
+    try {
+      await _store.clear();
+    } catch (error, stackTrace) {
+      debugPrint('清理失效登录令牌失败：$error');
+      debugPrintStack(stackTrace: stackTrace);
+    }
   }
 }

apps/user_app/lib/app/router.dart

@@ -1,3 +1,5 @@
+// 功能描述：配置用户端路由、鉴权守卫及登录后安全回跳。
+// 版本：1.1.0
 import 'package:flutter/material.dart';
 import 'package:go_router/go_router.dart';
 
@@ -9,25 +11,45 @@ import '../ui/features/profile/profile_page.dart';
 import '../ui/features/shared/record_list_page.dart';
 import '../ui/features/shared/record_list_view_model.dart';
 import '../ui/features/shop/shop_page.dart';
+import 'auth_navigation.dart';
 import 'dependencies.dart';
 
-GoRouter createRouter(AppDependencies dependencies) => GoRouter(
-  initialLocation: '/home',
+GoRouter createRouter(
+  AppDependencies dependencies, {
+  String initialLocation = '/home',
+}) => GoRouter(
+  initialLocation: initialLocation,
   refreshListenable: dependencies.session,
   redirect: (context, state) {
     final authRoute = state.matchedLocation == '/login' || state.matchedLocation == '/register';
-    if (!dependencies.session.isAuthenticated && !authRoute) return '/login';
-    if (dependencies.session.isAuthenticated && state.matchedLocation == '/login') return '/home';
+    if (!dependencies.session.isAuthenticated && !authRoute) {
+      return buildAuthLocation(
+        '/login',
+        redirectTarget: state.uri.toString(),
+        sessionExpired: dependencies.session.hasExpired,
+      );
+    }
+    if (dependencies.session.isAuthenticated && state.matchedLocation == '/login') {
+      return sanitizeRedirectTarget(state.uri.queryParameters['redirect']) ?? '/home';
+    }
     return null;
   },
   routes: [
     GoRoute(
       path: '/login',
-      builder: (context, state) => LoginPage(session: dependencies.session),
+      builder: (context, state) => LoginPage(
+        session: dependencies.session,
+        redirectTarget: sanitizeRedirectTarget(state.uri.queryParameters['redirect']),
+        showSessionExpiredMessage: state.uri.queryParameters['reason'] == 'expired',
+      ),
     ),
     GoRoute(
       path: '/register',
-      builder: (context, state) => RegisterPage(session: dependencies.session),
+      builder: (context, state) => RegisterPage(
+        session: dependencies.session,
+        redirectTarget: sanitizeRedirectTarget(state.uri.queryParameters['redirect']),
+        showSessionExpiredMessage: state.uri.queryParameters['reason'] == 'expired',
+      ),
     ),
     GoRoute(
       path: '/records/contracts',

apps/user_app/lib/data/services/api_client.dart

@@ -1,5 +1,5 @@
 // 功能描述：封装用户端 HTTP 请求，并将服务端错误转换为安全、可读的中文提示。
-// 版本：1.1.0
+// 版本：1.2.0
 import 'dart:convert';
 import 'dart:typed_data';
 
@@ -84,12 +84,21 @@ class ApiException implements Exception {
   String toString() => message;
 }
 
+/// 表示鉴权会话已经失效；页面层应等待路由跳转，不再展示普通网络错误。
+class SessionExpiredException extends ApiException {
+  const SessionExpiredException() : super(401, '登录状态已失效，请重新登录');
+}
+
+/// 接收被服务端拒绝的请求令牌，用于安全地失效对应会话。
+typedef UnauthorizedCallback = void Function(String rejectedToken);
+
 /// 负责用户端统一 HTTP 请求、鉴权头和响应解析。
 class ApiClient {
   ApiClient(
     this._tokenProvider, {
     http.Client? client,
     String? baseUrl,
+    this.onUnauthorized,
   }) : _client = client ?? http.Client(),
        baseUrl =
            baseUrl ??
@@ -101,6 +110,7 @@ class ApiClient {
   final String baseUrl;
   final String Function() _tokenProvider;
   final http.Client _client;
+  final UnauthorizedCallback? onUnauthorized;
 
   Future<Object?> get(String path, {bool authenticated = true}) =>
       _send('GET', path, authenticated: authenticated);
@@ -112,6 +122,13 @@ class ApiClient {
     final token = _tokenProvider();
     if (token.isNotEmpty) request.headers['authorization'] = token;
     final response = await _sendRequest(request);
+    if (response.statusCode == 401 && token.isNotEmpty) {
+      _rejectSession(token);
+    }
+    final responseCode = _jsonResponseCode(response);
+    if (token.isNotEmpty && responseCode != null && _isAuthenticationFailure(responseCode)) {
+      _rejectSession(token);
+    }
     if (response.statusCode == 404) return null;
     if (response.statusCode < 200 || response.statusCode >= 300) {
       throw ApiException(response.statusCode, '头像加载失败');
@@ -138,16 +155,21 @@ class ApiClient {
   }) async {
     final request = http.Request(method, Uri.parse('$baseUrl$path'));
     request.headers['accept'] = 'application/json';
+    var requestToken = '';
     if (authenticated) {
-      final token = _tokenProvider();
-      if (token.isNotEmpty) request.headers['authorization'] = token;
+      requestToken = _tokenProvider();
+      if (requestToken.isNotEmpty) request.headers['authorization'] = requestToken;
     }
     if (body != null) {
       request.headers['content-type'] = 'application/json; charset=UTF-8';
       request.body = jsonEncode(body);
     }
     final response = await _sendRequest(request);
-    return _decode(response);
+    return _decode(
+      response,
+      authenticated: authenticated,
+      requestToken: requestToken,
+    );
   }
 
   /// 发送请求并统一处理网络连接异常。
@@ -160,7 +182,14 @@ class ApiClient {
   }
 
   /// 解析统一响应结构，并按错误码生成中文提示。
-  Object? _decode(http.Response response) {
+  Object? _decode(
+    http.Response response, {
+    required bool authenticated,
+    required String requestToken,
+  }) {
+    if (authenticated && response.statusCode == 401 && requestToken.isNotEmpty) {
+      _rejectSession(requestToken);
+    }
     if (response.statusCode < 200 || response.statusCode >= 300) {
       throw ApiException(response.statusCode, '网络请求失败（${response.statusCode}）');
     }
@@ -175,6 +204,9 @@ class ApiClient {
     }
     final code = (decoded['code'] as num?)?.toInt() ?? 500;
     if (code != 0) {
+      if (authenticated && requestToken.isNotEmpty && _isAuthenticationFailure(code)) {
+        _rejectSession(requestToken);
+      }
       throw ApiException(
         code,
         localizeApiErrorMessage(code, decoded['message'] as String?),
@@ -182,8 +214,37 @@ class ApiClient {
     }
     return decoded['details'];
   }
+
+  /// 通知会话层并抛出专用异常，避免页面把鉴权失败误报为网络问题。
+  Never _rejectSession(String rejectedToken) {
+    onUnauthorized?.call(rejectedToken);
+    throw const SessionExpiredException();
+  }
+
+  /// 尝试从二进制接口返回的 JSON 错误体中提取业务码。
+  int? _jsonResponseCode(http.Response response) {
+    final contentType = response.headers['content-type'] ?? '';
+    int? firstContentByte;
+    for (final byte in response.bodyBytes) {
+      if (byte == 0x20 || byte == 0x09 || byte == 0x0a || byte == 0x0d) continue;
+      firstContentByte = byte;
+      break;
+    }
+    if (!contentType.contains('json') && firstContentByte != 0x7b) {
+      return null;
+    }
+    try {
+      final decoded = jsonDecode(response.body);
+      return decoded is Map ? (decoded['code'] as num?)?.toInt() : null;
+    } on FormatException {
+      return null;
+    }
+  }
 }
 
+/// 判断服务端稳定错误码是否表示登录会话无效。
+bool _isAuthenticationFailure(int code) => (code >= 1301 && code <= 1314) || code == 1715;
+
 Map<String, Object?> jsonMap(Object? value) {
   if (value is Map<String, Object?>) return value;
   if (value is Map) return value.map((key, item) => MapEntry(key.toString(), item));

apps/user_app/lib/data/services/secure_session_store.dart

@@ -1,15 +1,30 @@
+// 功能描述：封装用户端登录令牌的安全持久化接口与平台实现。
+// 版本：1.1.0
 import 'package:flutter_secure_storage/flutter_secure_storage.dart';
 
-class SecureSessionStore {
+/// 定义登录令牌持久化能力，便于会话逻辑隔离具体存储实现。
+abstract interface class SessionStore {
+  Future<String?> readToken();
+
+  Future<void> writeToken(String token);
+
+  Future<void> clear();
+}
+
+/// 使用平台安全存储保存用户端登录令牌。
+class SecureSessionStore implements SessionStore {
   SecureSessionStore({FlutterSecureStorage? storage})
     : _storage = storage ?? const FlutterSecureStorage();
 
   static const _tokenKey = 'user_app_access_token';
   final FlutterSecureStorage _storage;
 
+  @override
   Future<String?> readToken() => _storage.read(key: _tokenKey);
 
+  @override
   Future<void> writeToken(String token) => _storage.write(key: _tokenKey, value: token);
 
+  @override
   Future<void> clear() => _storage.delete(key: _tokenKey);
 }

apps/user_app/lib/ui/features/auth/login_page.dart

@@ -3,14 +3,22 @@
 import 'package:flutter/material.dart';
 import 'package:go_router/go_router.dart';
 
+import '../../../app/auth_navigation.dart';
 import '../../../app/dependencies.dart';
 import '../../../data/services/api_client.dart';
 
 /// 用户端手机号密码登录页面。
 class LoginPage extends StatefulWidget {
-  const LoginPage({required this.session, super.key});
+  const LoginPage({
+    required this.session,
+    this.redirectTarget,
+    this.showSessionExpiredMessage = false,
+    super.key,
+  });
 
   final UserSession session;
+  final String? redirectTarget;
+  final bool showSessionExpiredMessage;
 
   @override
   State<LoginPage> createState() => _LoginPageState();
@@ -27,6 +35,14 @@ class _LoginPageState extends State<LoginPage> {
   String? _phoneError;
   bool _obscurePassword = true;
 
+  @override
+  void initState() {
+    super.initState();
+    if (widget.showSessionExpiredMessage) {
+      _error = '登录状态已失效，请重新登录';
+    }
+  }
+
   @override
   void dispose() {
     _phone.dispose();
@@ -174,7 +190,13 @@ class _LoginPageState extends State<LoginPage> {
                       : const Text('安全登录'),
                 ),
                 TextButton(
-                  onPressed: () => context.push('/register'),
+                  onPressed: () => context.push(
+                    buildAuthLocation(
+                      '/register',
+                      redirectTarget: widget.redirectTarget,
+                      sessionExpired: widget.showSessionExpiredMessage,
+                    ),
+                  ),
                   child: const Text('首次使用？注册账号'),
                 ),
                 const SizedBox(height: 8),

apps/user_app/lib/ui/features/auth/register_page.dart

@@ -1,12 +1,24 @@
+// 功能描述：提供用户注册流程，并在注册后保留原登录目标页。
+// 版本：1.1.0
 import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
 
+import '../../../app/auth_navigation.dart';
 import '../../../app/dependencies.dart';
 import '../../../data/services/api_client.dart';
 
+/// 用户端账号注册页面。
 class RegisterPage extends StatefulWidget {
-  const RegisterPage({required this.session, super.key});
+  const RegisterPage({
+    required this.session,
+    this.redirectTarget,
+    this.showSessionExpiredMessage = false,
+    super.key,
+  });
 
   final UserSession session;
+  final String? redirectTarget;
+  final bool showSessionExpiredMessage;
 
   @override
   State<RegisterPage> createState() => _RegisterPageState();
@@ -51,7 +63,19 @@ class _RegisterPageState extends State<RegisterPage> {
           'request_identity': _requestIdentity,
         },
       );
-      if (mounted) Navigator.of(context).pop();
+      if (mounted) {
+        if (Navigator.of(context).canPop()) {
+          Navigator.of(context).pop();
+        } else {
+          context.go(
+            buildAuthLocation(
+              '/login',
+              redirectTarget: widget.redirectTarget,
+              sessionExpired: widget.showSessionExpiredMessage,
+            ),
+          );
+        }
+      }
     } catch (error) {
       if (mounted) setState(() => _message = error.toString());
     } finally {

apps/user_app/lib/ui/features/home/home_page.dart

@@ -3,6 +3,7 @@
 import 'package:flutter/material.dart';
 
 import '../../../data/repositories/client_repository.dart';
+import '../../../data/services/api_client.dart';
 import '../../../domain/models/client_models.dart';
 import '../../core/widgets.dart';
 import 'service_relation_card.dart';
@@ -47,6 +48,9 @@ class _HomePageState extends State<HomePage> {
             return const Center(child: CircularProgressIndicator());
           }
           if (snapshot.hasError) {
+            if (snapshot.error is SessionExpiredException) {
+              return const SizedBox.shrink();
+            }
             return EmptyState(
               title: '首页加载失败',
               description: snapshot.error.toString(),

apps/user_app/lib/ui/features/orders/orders_page.dart

@@ -1,8 +1,11 @@
+// 功能描述：展示用户订单、退款和工单，并处理显式确认后的业务操作。
+// 版本：1.1.0
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:uuid/uuid.dart';
 
 import '../../../data/repositories/client_repository.dart';
+import '../../../data/services/api_client.dart';
 import '../../../data/services/payment_launcher.dart';
 import '../../../domain/models/client_models.dart';
 import '../shared/record_list_page.dart';
@@ -93,6 +96,7 @@ class OrdersPage extends StatelessWidget {
         );
       }
     } catch (error) {
+      if (error is SessionExpiredException) return;
       if (context.mounted) {
         ScaffoldMessenger.of(context).showSnackBar(
           SnackBar(content: Text(error.toString())),

apps/user_app/lib/ui/features/profile/profile_page.dart

@@ -8,6 +8,7 @@ import 'package:uuid/uuid.dart';
 
 import '../../../app/dependencies.dart';
 import '../../../data/repositories/client_repository.dart';
+import '../../../data/services/api_client.dart';
 import '../../../domain/models/client_models.dart';
 import '../../core/widgets.dart';
 import 'profile_avatar.dart';
@@ -65,7 +66,11 @@ class _ProfilePageState extends State<ProfilePage> {
     );
     controller.dispose();
     if (address == null || address.isEmpty) return;
-    await widget.repository.addAddress(address, isDefault: true);
+    try {
+      await widget.repository.addAddress(address, isDefault: true);
+    } on SessionExpiredException {
+      return;
+    }
     if (mounted) ScaffoldMessenger.of(context).showSnackBar(const SnackBar(content: Text('地址已保存')));
   }
 
@@ -91,11 +96,15 @@ class _ProfilePageState extends State<ProfilePage> {
     );
     controller.dispose();
     if (description == null || description.isEmpty) return;
-    await widget.repository.createTicket(
-      requestNo: const Uuid().v7(),
-      category: 'repair',
-      description: description,
-    );
+    try {
+      await widget.repository.createTicket(
+        requestNo: const Uuid().v7(),
+        category: 'repair',
+        description: description,
+      );
+    } on SessionExpiredException {
+      return;
+    }
     if (mounted) ScaffoldMessenger.of(context).showSnackBar(const SnackBar(content: Text('工单已提交')));
   }
 
@@ -107,6 +116,9 @@ class _ProfilePageState extends State<ProfilePage> {
       builder: (context, snapshot) {
         if (!snapshot.hasData) {
           if (snapshot.hasError) {
+            if (snapshot.error is SessionExpiredException) {
+              return const SizedBox.shrink();
+            }
             return EmptyState(
               title: '个人信息加载失败',
               description: '请检查网络后重新进入本页',

apps/user_app/lib/ui/features/shared/record_list_view_model.dart

@@ -1,5 +1,8 @@
+// 功能描述：管理通用记录列表的加载、数据和非鉴权错误状态。
+// 版本：1.1.0
 import 'package:flutter/foundation.dart';
 
+import '../../../data/services/api_client.dart';
 import '../../../domain/models/client_models.dart';
 
 typedef RecordLoader = Future<List<ClientRecord>> Function();
@@ -23,7 +26,8 @@ class RecordListViewModel extends ChangeNotifier {
     try {
       _records = await _loader();
     } catch (error) {
-      _error = error;
+      // 会话失效由统一路由接管，不在列表中重复展示网络错误。
+      if (error is! SessionExpiredException) _error = error;
     } finally {
       _loading = false;
       notifyListeners();

apps/user_app/lib/ui/features/shop/shop_page.dart

@@ -1,7 +1,10 @@
+// 功能描述：展示商城商品并处理用户确认后的下单流程。
+// 版本：1.1.0
 import 'package:flutter/material.dart';
 import 'package:uuid/uuid.dart';
 
 import '../../../data/repositories/client_repository.dart';
+import '../../../data/services/api_client.dart';
 import '../../../domain/models/client_models.dart';
 import '../../core/widgets.dart';
 
@@ -80,6 +83,7 @@ class _ShopPageState extends State<ShopPage> {
         ScaffoldMessenger.of(context).showSnackBar(const SnackBar(content: Text('订单已创建，请前往订单页支付')));
       }
     } catch (error) {
+      if (error is SessionExpiredException) return;
       if (mounted) {
         ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(error.toString())));
       }
@@ -96,6 +100,9 @@ class _ShopPageState extends State<ShopPage> {
           return const Center(child: CircularProgressIndicator());
         }
         if (snapshot.hasError) {
+          if (snapshot.error is SessionExpiredException) {
+            return const SizedBox.shrink();
+          }
           return EmptyState(title: '商品加载失败', description: snapshot.error.toString());
         }
         final products = snapshot.data ?? const [];

apps/user_app/test/app/auth_navigation_test.dart

@@ -0,0 +1,40 @@
+// 功能描述：验证登录目标页构造、站内地址校验及开放重定向防护。
+// 版本：1.0.0
+import 'package:flutter_test/flutter_test.dart';
+import 'package:user_app/app/auth_navigation.dart';
+
+/// 覆盖合法深链接、鉴权页循环和外部地址攻击场景。
+void main() {
+  test('保留站内目标页的路径、查询参数和片段', () {
+    const target = '/orders?status=pending#payment';
+
+    expect(sanitizeRedirectTarget(target), target);
+    final loginUri = Uri.parse(
+      buildAuthLocation(
+        '/login',
+        redirectTarget: target,
+        sessionExpired: true,
+      ),
+    );
+    expect(loginUri.path, '/login');
+    expect(loginUri.queryParameters['redirect'], target);
+    expect(loginUri.queryParameters['reason'], 'expired');
+  });
+
+  test('拒绝外部地址、协议相对地址和鉴权页循环', () {
+    expect(sanitizeRedirectTarget('https://example.com/orders'), isNull);
+    expect(sanitizeRedirectTarget('//example.com/orders'), isNull);
+    expect(sanitizeRedirectTarget(r'/\example.com/orders'), isNull);
+    expect(sanitizeRedirectTarget('/login'), isNull);
+    expect(sanitizeRedirectTarget('/register?redirect=/orders'), isNull);
+  });
+
+  test('非法目标页不写入登录地址', () {
+    final loginUri = Uri.parse(
+      buildAuthLocation('/login', redirectTarget: 'https://example.com'),
+    );
+
+    expect(loginUri.path, '/login');
+    expect(loginUri.queryParameters, isEmpty);
+  });
+}

apps/user_app/test/app/router_test.dart

@@ -0,0 +1,87 @@
+// 功能描述：验证鉴权守卫保留目标页，并在重新登录后替换返回原页面。
+// 版本：1.0.0
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:http/http.dart' as http;
+import 'package:http/testing.dart';
+import 'package:user_app/app/dependencies.dart';
+import 'package:user_app/app/router.dart';
+import 'package:user_app/data/repositories/client_repository.dart';
+import 'package:user_app/data/services/api_client.dart';
+import 'package:user_app/data/services/secure_session_store.dart';
+
+/// 提供无需平台插件的空会话存储。
+class _EmptySessionStore implements SessionStore {
+  @override
+  Future<void> clear() async {}
+
+  @override
+  Future<String?> readToken() async => null;
+
+  @override
+  Future<void> writeToken(String token) async {}
+}
+
+/// 提供可切换鉴权状态的测试会话。
+class _RouterTestSession extends UserSession {
+  _RouterTestSession({required this.authenticated, required this.expired})
+    : super(_EmptySessionStore());
+
+  bool authenticated;
+  bool expired;
+
+  @override
+  bool get isAuthenticated => authenticated;
+
+  @override
+  bool get hasExpired => expired;
+
+  /// 模拟用户重新登录成功并唤醒路由刷新。
+  void authenticate() {
+    authenticated = true;
+    expired = false;
+    notifyListeners();
+  }
+}
+
+/// 覆盖过期提示、查询参数保留和登录后回跳。
+void main() {
+  testWidgets('令牌失效后跳转登录并在登录后返回原目标页', (tester) async {
+    final session = _RouterTestSession(authenticated: false, expired: true);
+    final dependencies = AppDependencies(
+      session: session,
+      repository: ClientRepository(
+        ApiClient(
+          () => '',
+          baseUrl: 'https://api.example.com',
+          client: MockClient(
+            (request) async => http.Response('{"code":0,"details":[]}', 200),
+          ),
+        ),
+      ),
+    );
+    final router = createRouter(
+      dependencies,
+      initialLocation: '/orders?status=pending',
+    );
+    addTearDown(router.dispose);
+
+    await tester.pumpWidget(MaterialApp.router(routerConfig: router));
+    await tester.pumpAndSettle();
+
+    final loginUri = router.routeInformationProvider.value.uri;
+    expect(loginUri.path, '/login');
+    expect(loginUri.queryParameters['redirect'], '/orders?status=pending');
+    expect(loginUri.queryParameters['reason'], 'expired');
+    expect(find.text('登录状态已失效，请重新登录'), findsOneWidget);
+
+    session.authenticate();
+    await tester.pumpAndSettle();
+
+    expect(router.routeInformationProvider.value.uri.path, '/orders');
+    expect(
+      router.routeInformationProvider.value.uri.queryParameters['status'],
+      'pending',
+    );
+  });
+}

apps/user_app/test/app/user_session_test.dart

@@ -0,0 +1,78 @@
+// 功能描述：验证会话失效的幂等清理、旧请求隔离和存储异常降级。
+// 版本：1.0.0
+import 'package:flutter_test/flutter_test.dart';
+import 'package:user_app/app/dependencies.dart';
+import 'package:user_app/data/services/secure_session_store.dart';
+
+/// 提供可观测的内存令牌存储，避免测试依赖真实平台插件。
+class _MemorySessionStore implements SessionStore {
+  _MemorySessionStore({this.token, this.clearError});
+
+  String? token;
+  final Object? clearError;
+  int clearCount = 0;
+
+  @override
+  Future<void> clear() async {
+    clearCount++;
+    if (clearError != null) throw clearError!;
+    token = null;
+  }
+
+  @override
+  Future<String?> readToken() async => token;
+
+  @override
+  Future<void> writeToken(String token) async {
+    this.token = token;
+  }
+}
+
+/// 覆盖并发 401、迟到的旧请求和安全存储删除失败场景。
+void main() {
+  test('同一失效令牌只清理并通知一次', () async {
+    final store = _MemorySessionStore(token: 'JWT expired-token');
+    final session = UserSession(store);
+    await session.restore();
+    var notificationCount = 0;
+    session.addListener(() => notificationCount++);
+
+    session.invalidate('JWT expired-token');
+    session.invalidate('JWT expired-token');
+    await Future<void>.delayed(Duration.zero);
+
+    expect(session.token, isEmpty);
+    expect(session.hasExpired, isTrue);
+    expect(store.clearCount, 1);
+    expect(notificationCount, 1);
+  });
+
+  test('迟到的旧请求不得使当前令牌失效', () async {
+    final store = _MemorySessionStore(token: 'JWT current-token');
+    final session = UserSession(store);
+    await session.restore();
+
+    session.invalidate('JWT old-token');
+    await Future<void>.delayed(Duration.zero);
+
+    expect(session.token, 'JWT current-token');
+    expect(session.hasExpired, isFalse);
+    expect(store.clearCount, 0);
+  });
+
+  test('持久化删除失败也立即清空内存登录态', () async {
+    final store = _MemorySessionStore(
+      token: 'JWT expired-token',
+      clearError: StateError('storage unavailable'),
+    );
+    final session = UserSession(store);
+    await session.restore();
+
+    session.invalidate('JWT expired-token');
+    await Future<void>.delayed(Duration.zero);
+
+    expect(session.token, isEmpty);
+    expect(session.hasExpired, isTrue);
+    expect(store.clearCount, 1);
+  });
+}

apps/user_app/test/data/api_client_test.dart

@@ -1,5 +1,5 @@
-// 功能描述：验证受保护头像二进制接口的鉴权读取和异常处理。
-// 版本：1.1.0
+// 功能描述：验证统一请求鉴权、会话失效通知和二进制资源处理。
+// 版本：1.2.0
 import 'dart:typed_data';
 
 import 'package:flutter_test/flutter_test.dart';
@@ -51,4 +51,99 @@ void main() {
       ),
     );
   });
+
+  test('受保护接口返回 HTTP 401 时通知会话并抛出专用异常', () async {
+    final rejectedTokens = <String>[];
+    final client = ApiClient(
+      () => 'JWT expired-token',
+      baseUrl: 'https://api.example.com',
+      onUnauthorized: rejectedTokens.add,
+      client: MockClient((request) async => http.Response('', 401)),
+    );
+
+    await expectLater(
+      client.get('/protected'),
+      throwsA(isA<SessionExpiredException>()),
+    );
+    expect(rejectedTokens, ['JWT expired-token']);
+  });
+
+  test('受保护接口返回鉴权业务码时通知会话', () async {
+    final rejectedTokens = <String>[];
+    final client = ApiClient(
+      () => 'JWT expired-token',
+      baseUrl: 'https://api.example.com',
+      onUnauthorized: rejectedTokens.add,
+      client: MockClient(
+        (request) async => http.Response(
+          '{"code":1308,"message":"Token Expired","details":null}',
+          200,
+        ),
+      ),
+    );
+
+    await expectLater(
+      client.get('/protected'),
+      throwsA(isA<SessionExpiredException>()),
+    );
+    expect(rejectedTokens, ['JWT expired-token']);
+  });
+
+  test('未鉴权接口返回 401 时不得清理已有会话', () async {
+    final rejectedTokens = <String>[];
+    final client = ApiClient(
+      () => 'JWT current-token',
+      baseUrl: 'https://api.example.com',
+      onUnauthorized: rejectedTokens.add,
+      client: MockClient((request) async => http.Response('', 401)),
+    );
+
+    await expectLater(
+      client.post('/login', authenticated: false),
+      throwsA(
+        isA<ApiException>()
+            .having((error) => error.code, 'code', 401)
+            .having((error) => error is SessionExpiredException, 'session expired', isFalse),
+      ),
+    );
+    expect(rejectedTokens, isEmpty);
+  });
+
+  test('头像接口返回 401 时同样触发统一会话失效', () async {
+    final rejectedTokens = <String>[];
+    final client = ApiClient(
+      () => 'JWT expired-token',
+      baseUrl: 'https://api.example.com',
+      onUnauthorized: rejectedTokens.add,
+      client: MockClient((request) async => http.Response('', 401)),
+    );
+
+    await expectLater(
+      client.getBytes('/avatar'),
+      throwsA(isA<SessionExpiredException>()),
+    );
+    expect(rejectedTokens, ['JWT expired-token']);
+  });
+
+  test('头像接口在 HTTP 200 错误体中返回鉴权码时触发会话失效', () async {
+    final rejectedTokens = <String>[];
+    final client = ApiClient(
+      () => 'JWT expired-token',
+      baseUrl: 'https://api.example.com',
+      onUnauthorized: rejectedTokens.add,
+      client: MockClient(
+        (request) async => http.Response(
+          '{"code":1715,"message":"Unauthorized","details":null}',
+          200,
+          headers: {'content-type': 'application/json'},
+        ),
+      ),
+    );
+
+    await expectLater(
+      client.getBytes('/avatar'),
+      throwsA(isA<SessionExpiredException>()),
+    );
+    expect(rejectedTokens, ['JWT expired-token']);
+  });
 }

docs/03-用户端App需求.md

@@ -163,6 +163,8 @@ apps/user_app/lib/
 - 写请求生成并持久化幂等键；重试复用原键。余额支付、充值、提现、订单提交、报修和设备命令均不得因页面重建或网络重连重复创建事实。
 - ViewModel 根据稳定错误码映射可操作文案与恢复入口；不得解析后端错误文案驱动流程。401/403、状态冲突、限流、外部依赖不可用和未知错误分别处理。
 - 所有面向用户的接口错误必须显示中文；已知错误按稳定错误码映射，未知英文技术信息统一收敛为安全的中文失败提示。登录页在请求前校验纯 11 位中国大陆手机号，并在输入框下显示格式错误原因。
+- 携带用户令牌的请求收到 HTTP 401，或统一响应返回鉴权业务码 `1301`—`1314`、`1715` 时，客户端必须立即清空当前内存会话并尽力删除持久化令牌，由根路由统一跳转登录页；并发鉴权失败只执行一次失效流程，不得在业务页面重复显示为网络异常。登录、注册和验证码等未鉴权请求失败不得清理当前会话。
+- 会话失效或未登录访问受保护页面时，登录地址应通过受校验的站内 `redirect` 参数保留完整目标路径和查询参数。重新登录成功后使用替换导航返回目标页，非法、外部或鉴权页目标统一回退首页；登录前失败的订单、支付、退款和工单等写操作不得自动重放。
 - 金额以最小货币单位整数进入领域层，只在格式化组件中转换为展示文本；时间统一解析为 UTC 并按用户时区展示，同时保留数据更新时间。
 
 ### 7.5 本地数据、安全与平台能力

docs/11-数据接口与安全.md

@@ -94,6 +94,8 @@
 - 平台、气站和配送点三个受控管理后台的列表可以只读展示记录主键 `ID`，用于数据库问题定位；任何写操作、详情定位、关联选择、日志和跨服务传递仍统一使用 `identity`。服务端不得接受客户端指定新记录的 `id` 或 `identity`，创建时必须在逻辑层生成 UUID V7 `identity`。
 
 - 登录令牌短期有效，刷新令牌可撤销；后台高权限账号启用 MFA、IP/设备策略。平台后台管理的平台、气站、配送、员工和业主账号密码按当前实施口径仅要求不少于 6 个字符，不附加复杂度校验。
+- 用户端携带鉴权的请求遇到 HTTP 401 或鉴权业务码 `1301`—`1314`、`1715` 时，应按请求实际携带的令牌触发幂等会话失效；迟到的旧请求不得清除后来建立的新会话。客户端先清空内存状态并跳转登录，再尽力删除安全存储中的旧令牌。
+- 登录前目标页只能保存为站内绝对路径，禁止接受带协议、主机、反斜杠、协议相对形式或登录/注册循环的跳转值。重新登录不得自动重放支付、下单、退款、工单等产生副作用的请求。
 - 权限校验在服务端执行，前端菜单隐藏不构成权限控制。按角色、站点、区域、对象归属联合鉴权。
 - 手机号、地址、身份证明、收款账户、定位、视频为敏感数据：传输 TLS、存储加密/字段加密、访问留痕、最小化留存。默认响应继续脱敏；仅已通过平台总后台 JWT 和对应菜单权限校验的管理员，可在用户、工作人员和平台账户的列表与详情中查看姓名、显示名称和主手机号明文。用户地址资源另设最小范围例外：仅 `/user_address` 的受控列表与详情接口可向具备对应菜单权限的平台管理员返回完整地址及经纬度，用于地址维护和编辑回填。配送订单联系人另设业务后台例外：平台订单详情可返回联系人姓名和联系电话明文；配送点后台的启用管理员可在严格限定当前配送点订单范围后，于列表和详情查看联系人快照明文。平台订单列表、气站端、用户端和工作人员端继续脱敏。上述例外不放宽身份证明、头像、资质编号或收款账户的脱敏规则。
 - 所有支付回调验证签名与金额、订单、商户号一致性；合同文件使用可信第三方原文与哈希存证。渠道回调入口为 `/heqi/payment-return/v1/{alipay|wechat}/notify`，不使用用户 JWT；必须完成渠道证书验签、商户/appid、平台支付单号、金额、币种和状态校验后才可在数据库事务中推进业务。重复通知必须幂等，原始敏感报文只保存摘要。

docs/操作日志_用户端令牌失效恢复_20260904.md

@@ -0,0 +1,52 @@
+# 用户端令牌失效恢复操作日志
+
+操作时间：2026-09-04
+
+操作类型：修改、扩展
+
+影响模块：用户端 Flutter App 请求层、会话管理、鉴权路由及错误展示
+
+## 操作前状态
+
+浏览器残留的用户令牌失效后，首页、订单和个人中心的受保护接口返回 401，但请求层将其转换为普通网络错误。内存和浏览器安全存储中的令牌仍被视为有效，路由因此把 `/login` 再次重定向到 `/home`，用户无法自行恢复登录。
+
+## 具体操作
+
+1. 在统一请求层识别受保护请求的 HTTP 401，以及业务码 `1301`—`1314`、`1715`，抛出专用会话失效异常。
+2. 请求层把实际被拒绝的令牌交给会话层；会话层仅在该令牌仍为当前令牌时执行失效，防止迟到旧请求清除新会话。
+3. 会话失效立即清空内存令牌并通知根路由，持久化令牌采用幂等、尽力而为的异步清理；新登录写入前等待旧清理结束。
+4. 鉴权守卫通过 `/login?redirect=...&reason=expired` 保存原目标页，并严格限制为站内绝对路径。
+5. 登录成功后使用替换导航返回原目标页；目标缺失或非法时回到首页。
+6. 注册流程继续携带原目标页；写操作鉴权失败后只返回原页面，不自动重放。
+7. 首页、商城、订单、个人中心和通用记录列表忽略专用会话失效异常，避免重复显示网络错误。
+
+## 操作后状态
+
+失效令牌首次被服务端拒绝后，用户会自动进入登录页并看到“登录状态已失效，请重新登录”。重新登录后返回登录前目标页；多个并发 401 只清理和通知一次。普通断网、超时、服务端错误及未鉴权登录接口失败仍按原逻辑展示，不会误清理会话。
+
+## 代码变更
+
+- `apps/user_app/lib/data/services/api_client.dart`（+66/-5）：统一鉴权失败识别、旧令牌回调和专用异常。
+- `apps/user_app/lib/app/dependencies.dart`（+47/-8）：幂等会话失效、存储清理及新旧令牌竞态保护。
+- `apps/user_app/lib/app/auth_navigation.dart`（新增 33 行）：新增站内目标页校验和鉴权地址构造。
+- `apps/user_app/lib/app/router.dart`（+28/-6）：保存目标页、失效原因及登录后安全回跳。
+- `apps/user_app/lib/ui/features/auth/login_page.dart`（+24/-2）：显示会话失效提示并把目标页传入注册流程。
+- `apps/user_app/lib/ui/features/auth/register_page.dart`（+26/-2）：注册完成后保留原登录目标页。
+- 首页、个人中心、商城、订单和通用记录列表（合计 +38/-7）：抑制重复鉴权错误。
+- `apps/user_app/test/app/`（新增 205 行）、`apps/user_app/test/data/api_client_test.dart`（+97/-2）：新增会话、路由、安全跳转和请求层回归测试。
+- `docs/03-用户端App需求.md`、`docs/11-数据接口与安全.md`（各新增 2 行）：同步功能与安全约束。
+
+## 验证结果
+
+- `flutter analyze --no-pub`：通过，无问题。
+- `flutter test --no-pub`：通过，共 27 项测试。
+- `flutter build web --release --no-pub --dart-define=API_BASE_URL=http://rest.heqiapp.com`：通过。
+- 本地用户端已使用 `API_BASE_URL=http://127.0.0.1:12426` 重新生成 Release Web 构建，并由隐藏运行的 Python 静态服务在 `5180` 提供访问；已停止 Flutter 调试服务，不再依赖 DDC 调试模块和随机 WebSocket。`localhost`、`127.0.0.1` 均返回 HTTP 200，裸根地址可自动跳转并实际渲染带失效提示的登录页。
+- 已覆盖 HTTP 401、HTTP 200 鉴权业务码、二进制头像接口、未鉴权接口不清理会话、并发失效、迟到旧请求、存储删除失败、开放重定向防护和登录后回跳。
+
+## 风险评估
+
+- 会话失效依据请求实际携带的令牌比对当前令牌，降低并发和重新登录过程中的竞态风险。
+- 持久化删除失败时可能在应用下次完全启动后再次恢复旧令牌，但当前运行会立即退出错误状态；后续受保护请求仍会重新触发清理，不会永久困住用户。
+- `redirect` 只允许站内绝对路径并排除鉴权页，避免开放重定向和登录循环。
+- 任何产生副作用的业务请求均不自动重放，避免重复支付、下单、退款或工单。