修复工作人员端令牌失效后的登录恢复

apps/service_app/lib/app/auth_navigation.dart

@@ -0,0 +1,32 @@
+// 功能描述：提供工作人员端鉴权地址构造与站内回跳地址校验。
+// 版本：1.0.0
+
+/// 构造登录地址，并安全携带原目标页和会话失效原因。
+String buildAuthLocation({
+  String? redirectTarget,
+  bool sessionExpired = false,
+}) {
+  final safeTarget = sanitizeRedirectTarget(redirectTarget);
+  final query = <String, String>{
+    'redirect': ?safeTarget,
+    if (sessionExpired) 'reason': 'expired',
+  };
+  return Uri(
+    path: '/login',
+    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') return null;
+  return uri.toString();
+}

apps/service_app/lib/app/dependencies.dart

@@ -1,3 +1,5 @@
+// 功能描述：装配工作人员端依赖，并统一管理登录、退出和失效会话。
+// 版本：1.1.0
 import 'package:flutter/foundation.dart';
 import 'package:uuid/uuid.dart';
 
@@ -8,7 +10,7 @@ import '../data/services/location_service.dart';
 import '../data/services/secure_session_store.dart';
 
 class AppDependencies {
-  AppDependencies._({
+  AppDependencies({
     required this.session,
     required this.repository,
     required this.drafts,
@@ -22,15 +24,19 @@ class AppDependencies {
     final store = SecureSessionStore();
     final session = StaffSession(store);
     await session.restore();
-    final api = ApiClient(() => session.token);
-    return AppDependencies._(
+    final authenticatedApi = ApiClient(
+      () => session.token,
+      onUnauthorized: session.invalidate,
+    );
+    return AppDependencies(
       session: session,
-      repository: ServiceRepository(api, GeolocatorLocationService()),
+      repository: ServiceRepository(authenticatedApi, GeolocatorLocationService()),
       drafts: EncryptedDraftStore(),
     );
   }
 }
 
+/// 管理工作人员令牌、身份、角色、设备标识及会话失效通知。
 class StaffSession extends ChangeNotifier {
   StaffSession(this._store);
 
@@ -39,24 +45,29 @@ class StaffSession extends ChangeNotifier {
   static const _identityKey = 'service_app_identity';
   static const _roleKey = 'service_app_role';
   static const _deviceKey = 'service_app_device';
-  final SecureSessionStore _store;
+  final SessionStore _store;
 
   String _token = '';
   String _identity = '';
   String _roleCode = '';
   String _deviceIdentity = '';
+  bool _expired = false;
+  Future<void> _pendingClear = Future<void>.value();
 
   String get token => _token;
   String get identity => _identity;
   String get roleCode => _roleCode;
   String get deviceIdentity => _deviceIdentity;
   bool get isAuthenticated => _token.isNotEmpty;
+  bool get hasExpired => _expired;
 
+  /// 从安全存储恢复会话上下文；是否有效由后续受保护接口响应确认。
   Future<void> restore() async {
     _token = await _store.read(_tokenKey) ?? '';
     _identity = await _store.read(_identityKey) ?? '';
     _roleCode = await _store.read(_roleKey) ?? '';
     _deviceIdentity = await _store.read(_deviceKey) ?? '';
+    _expired = false;
     if (_deviceIdentity.isEmpty) {
       _deviceIdentity = const Uuid().v7();
       await _store.write(_deviceKey, _deviceIdentity);
@@ -72,15 +83,22 @@ class StaffSession extends ChangeNotifier {
         body: {'phone': phone, 'mode': 'password', 'password': password},
       ),
     );
-    _token = details['access_token'] as String? ?? '';
-    _identity = details['identity'] as String? ?? '';
-    _roleCode = details['role_code'] as String? ?? '';
-    if (_token.isEmpty || _identity.isEmpty || _roleCode.isEmpty) {
+    final token = details['access_token'] as String? ?? '';
+    final identity = details['identity'] as String? ?? '';
+    final roleCode = details['role_code'] as String? ?? '';
+    if (token.isEmpty || identity.isEmpty || roleCode.isEmpty) {
       throw const ApiException(500, '工作人员登录上下文缺失');
     }
-    await _store.write(_tokenKey, _token);
-    await _store.write(_identityKey, _identity);
-    await _store.write(_roleKey, _roleCode);
+
+    // 等待旧会话清理结束，避免迟到的删除任务误删刚写入的新会话。
+    await _pendingClear;
+    await _store.write(_tokenKey, token);
+    await _store.write(_identityKey, identity);
+    await _store.write(_roleKey, roleCode);
+    _token = token;
+    _identity = identity;
+    _roleCode = roleCode;
+    _expired = false;
     notifyListeners();
   }
 
@@ -88,9 +106,33 @@ class StaffSession extends ChangeNotifier {
     _token = '';
     _identity = '';
     _roleCode = '';
-    await _store.delete(_tokenKey);
-    await _store.delete(_identityKey);
-    await _store.delete(_roleKey);
+    _expired = false;
     notifyListeners();
+    _pendingClear = _clearStoredSession();
+    await _pendingClear;
+  }
+
+  /// 仅当服务端拒绝的仍是当前令牌时，使会话失效并通知路由。
+  void invalidate(String rejectedToken) {
+    if (rejectedToken.isEmpty || rejectedToken != _token || _expired) return;
+
+    _token = '';
+    _identity = '';
+    _roleCode = '';
+    _expired = true;
+    notifyListeners();
+    _pendingClear = _clearStoredSession();
+  }
+
+  /// 尽力删除会话字段并保留设备标识；单项失败不得阻塞返回登录页。
+  Future<void> _clearStoredSession() async {
+    for (final key in const [_tokenKey, _identityKey, _roleKey]) {
+      try {
+        await _store.delete(key);
+      } catch (error, stackTrace) {
+        debugPrint('清理工作人员失效会话失败（$key）：$error');
+        debugPrintStack(stackTrace: stackTrace);
+      }
+    }
   }
 }

apps/service_app/lib/app/router.dart

@@ -1,3 +1,5 @@
+// 功能描述：配置工作人员端路由、鉴权守卫及登录后安全回跳。
+// 版本：1.1.0
 import 'package:flutter/material.dart';
 import 'package:go_router/go_router.dart';
 
@@ -7,21 +9,35 @@ import '../ui/features/preflight/preflight_page.dart';
 import '../ui/features/profile/profile_page.dart';
 import '../ui/features/work/work_detail_page.dart';
 import '../ui/features/work/work_list_page.dart';
+import 'auth_navigation.dart';
 import 'dependencies.dart';
 
-GoRouter createRouter(AppDependencies dependencies) => GoRouter(
-  initialLocation: '/preflight',
+GoRouter createRouter(
+  AppDependencies dependencies, {
+  String initialLocation = '/preflight',
+}) => GoRouter(
+  initialLocation: initialLocation,
   refreshListenable: dependencies.session,
   redirect: (context, state) {
     final login = state.matchedLocation == '/login';
-    if (!dependencies.session.isAuthenticated && !login) return '/login';
-    if (dependencies.session.isAuthenticated && login) return '/preflight';
+    if (!dependencies.session.isAuthenticated && !login) {
+      return buildAuthLocation(
+        redirectTarget: state.uri.toString(),
+        sessionExpired: dependencies.session.hasExpired,
+      );
+    }
+    if (dependencies.session.isAuthenticated && login) {
+      return sanitizeRedirectTarget(state.uri.queryParameters['redirect']) ?? '/preflight';
+    }
     return null;
   },
   routes: [
     GoRoute(
       path: '/login',
-      builder: (context, state) => LoginPage(session: dependencies.session),
+      builder: (context, state) => LoginPage(
+        session: dependencies.session,
+        showSessionExpiredMessage: state.uri.queryParameters['reason'] == 'expired',
+      ),
     ),
     GoRoute(
       path: '/preflight',

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

@@ -1,5 +1,5 @@
 // 功能描述：封装工作人员端 HTTP 请求，并将服务端错误转换为安全、可读的中文提示。
-// 版本：1.1.0
+// 版本：1.2.0
 import 'dart:convert';
 
 import 'package:http/http.dart' as http;
@@ -84,20 +84,33 @@ 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})
-    : _client = client ?? http.Client(),
-      baseUrl =
-          baseUrl ??
-          const String.fromEnvironment(
-            'API_BASE_URL',
-            defaultValue: 'http://10.0.2.2:12426',
-          );
+  ApiClient(
+    this._tokenProvider, {
+    http.Client? client,
+    String? baseUrl,
+    this.onUnauthorized,
+  }) : _client = client ?? http.Client(),
+       baseUrl =
+           baseUrl ??
+           const String.fromEnvironment(
+             'API_BASE_URL',
+             defaultValue: 'http://10.0.2.2:12426',
+           );
 
   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);
@@ -116,7 +129,8 @@ class ApiClient {
       'POST',
       Uri.parse('$baseUrl/upload/file'),
     );
-    request.headers['authorization'] = _tokenProvider();
+    final requestToken = _tokenProvider();
+    if (requestToken.isNotEmpty) request.headers['authorization'] = requestToken;
     request.fields['declared_content_type'] = contentType;
     request.files.add(
       http.MultipartFile.fromBytes(
@@ -126,7 +140,11 @@ class ApiClient {
       ),
     );
     final response = await _sendRequest(request);
-    final details = _decode(response);
+    final details = _decode(
+      response,
+      authenticated: true,
+      requestToken: requestToken,
+    );
     return jsonMap(details)['uri'] as String? ?? '';
   }
 
@@ -138,15 +156,21 @@ class ApiClient {
   }) async {
     final request = http.Request(method, Uri.parse('$baseUrl$path'));
     request.headers['accept'] = 'application/json';
-    if (authenticated && _tokenProvider().isNotEmpty) {
-      request.headers['authorization'] = _tokenProvider();
+    var requestToken = '';
+    if (authenticated) {
+      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,
+    );
   }
 
   /// 发送请求并统一处理网络连接异常。
@@ -159,7 +183,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}）');
     }
@@ -174,6 +205,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?),
@@ -181,8 +215,17 @@ class ApiClient {
     }
     return decoded['details'];
   }
+
+  /// 通知会话层并抛出专用异常，避免页面把鉴权失败误报为网络问题。
+  Never _rejectSession(String rejectedToken) {
+    onUnauthorized?.call(rejectedToken);
+    throw const SessionExpiredException();
+  }
 }
 
+/// 判断服务端稳定错误码是否表示登录会话无效。
+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/service_app/lib/data/services/secure_session_store.dart

@@ -1,12 +1,29 @@
+// 功能描述：封装工作人员端会话上下文的安全持久化接口与平台实现。
+// 版本：1.1.0
 import 'package:flutter_secure_storage/flutter_secure_storage.dart';
 
-class SecureSessionStore {
+/// 定义工作人员会话持久化能力，便于会话逻辑隔离具体存储实现。
+abstract interface class SessionStore {
+  Future<String?> read(String key);
+
+  Future<void> write(String key, String value);
+
+  Future<void> delete(String key);
+}
+
+/// 使用平台安全存储保存工作人员会话上下文。
+class SecureSessionStore implements SessionStore {
   SecureSessionStore({FlutterSecureStorage? storage})
     : _storage = storage ?? const FlutterSecureStorage();
 
   final FlutterSecureStorage _storage;
 
+  @override
   Future<String?> read(String key) => _storage.read(key: key);
+
+  @override
   Future<void> write(String key, String value) => _storage.write(key: key, value: value);
+
+  @override
   Future<void> delete(String key) => _storage.delete(key: key);
 }

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

@@ -1,5 +1,5 @@
 // 功能描述：提供工作人员端手机号密码登录界面及本地输入校验。
-// 版本：1.2.0
+// 版本：1.3.0
 import 'package:flutter/material.dart';
 
 import '../../../app/dependencies.dart';
@@ -7,9 +7,14 @@ import '../../../data/services/api_client.dart';
 
 /// 工作人员端手机号密码登录页面。
 class LoginPage extends StatefulWidget {
-  const LoginPage({required this.session, super.key});
+  const LoginPage({
+    required this.session,
+    this.showSessionExpiredMessage = false,
+    super.key,
+  });
 
   final StaffSession session;
+  final bool showSessionExpiredMessage;
 
   @override
   State<LoginPage> createState() => _LoginPageState();
@@ -29,6 +34,14 @@ class _LoginPageState extends State<LoginPage> {
   String? _passwordError;
   bool _obscurePassword = true;
 
+  @override
+  void initState() {
+    super.initState();
+    if (widget.showSessionExpiredMessage) {
+      _error = '登录状态已失效，请重新登录';
+    }
+  }
+
   /// 校验手机号和密码，通过后再提交登录请求。
   Future<void> _login() async {
     final phone = _phone.text.trim();

apps/service_app/lib/ui/features/evidence/evidence_page.dart

@@ -1,3 +1,5 @@
+// 功能描述：管理工作人员现场取证、加密草稿和安全提交。
+// 版本：1.1.0
 import 'package:flutter/material.dart';
 import 'package:image_picker/image_picker.dart';
 import 'package:uuid/uuid.dart';
@@ -5,6 +7,7 @@ import 'package:uuid/uuid.dart';
 import '../../../app/dependencies.dart';
 import '../../../data/offline/encrypted_draft_store.dart';
 import '../../../data/repositories/service_repository.dart';
+import '../../../data/services/api_client.dart';
 import '../../core/widgets.dart';
 
 class EvidencePage extends StatefulWidget {
@@ -138,6 +141,8 @@ class _EvidencePageState extends State<EvidencePage> {
         widget.taskIdentity,
       );
       if (mounted) Navigator.pop(context, true);
+    } on SessionExpiredException {
+      return;
     } catch (error) {
       if (mounted) {
         ScaffoldMessenger.of(

apps/service_app/lib/ui/features/preflight/preflight_page.dart

@@ -1,8 +1,11 @@
+// 功能描述：展示工作人员作业准入检查，并安全处理刷新和会话失效。
+// 版本：1.1.0
 import 'package:flutter/material.dart';
 import 'package:go_router/go_router.dart';
 
 import '../../../app/dependencies.dart';
 import '../../../data/repositories/service_repository.dart';
+import '../../../data/services/api_client.dart';
 import '../../../domain/models/service_models.dart';
 import '../../core/widgets.dart';
 
@@ -26,11 +29,21 @@ class _PreflightPageState extends State<PreflightPage> {
     _future = widget.repository.preflight();
   }
 
+  /// 创建新的加载任务，并在同步状态回调中替换页面 Future。
+  void _reload() {
+    final future = widget.repository.preflight();
+    setState(() {
+      _future = future;
+    });
+  }
+
   Future<void> _attendance(String action) async {
     setState(() => _busy = true);
     try {
       await widget.repository.attendance(action, widget.session.deviceIdentity);
-      setState(() => _future = widget.repository.preflight());
+      if (mounted) _reload();
+    } on SessionExpiredException {
+      return;
     } catch (error) {
       if (mounted) {
         ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(error.toString())));
@@ -48,10 +61,13 @@ class _PreflightPageState extends State<PreflightPage> {
       builder: (context, snapshot) {
         if (!snapshot.hasData) {
           if (snapshot.hasError) {
+            if (snapshot.error is SessionExpiredException) {
+              return const Center(child: CircularProgressIndicator());
+            }
             return MessageState(
               title: '作业检查加载失败',
               description: '请检查网络后重新加载',
-              onRetry: () => setState(() => _future = widget.repository.preflight()),
+              onRetry: _reload,
             );
           }
           return const Center(child: CircularProgressIndicator());

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

@@ -1,9 +1,12 @@
+// 功能描述：展示工作人员资料、钱包和草稿状态，并安全处理刷新与退出。
+// 版本：1.1.0
 import 'package:flutter/material.dart';
 import 'package:go_router/go_router.dart';
 
 import '../../../app/dependencies.dart';
 import '../../../data/offline/encrypted_draft_store.dart';
 import '../../../data/repositories/service_repository.dart';
+import '../../../data/services/api_client.dart';
 import '../../../domain/models/service_models.dart';
 import '../../core/widgets.dart';
 
@@ -38,6 +41,14 @@ class _ProfilePageState extends State<ProfilePage> {
     await widget.drafts.count(widget.session.identity),
   );
 
+  /// 创建新的加载任务，并在同步状态回调中替换页面 Future。
+  void _reload() {
+    final future = _load();
+    setState(() {
+      _future = future;
+    });
+  }
+
   Future<void> _logout(int draftCount) async {
     if (draftCount > 0) {
       final discard = await showDialog<bool>(
@@ -66,10 +77,13 @@ class _ProfilePageState extends State<ProfilePage> {
       builder: (context, snapshot) {
         if (!snapshot.hasData) {
           if (snapshot.hasError) {
+            if (snapshot.error is SessionExpiredException) {
+              return const Center(child: CircularProgressIndicator());
+            }
             return MessageState(
               title: '工作台信息加载失败',
               description: '请检查网络后重新加载',
-              onRetry: () => setState(() => _future = _load()),
+              onRetry: _reload,
             );
           }
           return const Center(child: CircularProgressIndicator());

apps/service_app/lib/ui/features/work/work_detail_page.dart

@@ -1,3 +1,5 @@
+// 功能描述：展示工作人员任务详情，并安全处理业务操作、刷新和会话失效。
+// 版本：1.1.0
 import 'package:flutter/material.dart';
 import 'package:go_router/go_router.dart';
 import 'package:image_picker/image_picker.dart';
@@ -6,6 +8,7 @@ import 'package:uuid/uuid.dart';
 import '../../../app/dependencies.dart';
 import '../../../data/offline/encrypted_draft_store.dart';
 import '../../../data/repositories/service_repository.dart';
+import '../../../data/services/api_client.dart';
 import '../../../domain/models/service_models.dart';
 import '../../core/widgets.dart';
 
@@ -41,6 +44,14 @@ class _WorkDetailPageState extends State<WorkDetailPage> {
       ? widget.repository.deliveryDetail(widget.identity)
       : widget.repository.ticketDetail(widget.identity);
 
+  /// 创建新的加载任务，并在同步状态回调中替换页面 Future。
+  void _reload() {
+    final future = _load();
+    setState(() {
+      _future = future;
+    });
+  }
+
   Future<void> _run(
     Future<void> Function(WorkItem) action,
     WorkItem item,
@@ -48,7 +59,9 @@ class _WorkDetailPageState extends State<WorkDetailPage> {
     setState(() => _busy = true);
     try {
       await action(item);
-      setState(() => _future = _load());
+      if (mounted) _reload();
+    } on SessionExpiredException {
+      return;
     } catch (error) {
       if (mounted) {
         ScaffoldMessenger.of(
@@ -152,7 +165,9 @@ class _WorkDetailPageState extends State<WorkDetailPage> {
         proofFile: temporaryFile,
       );
       await widget.drafts.deleteDraft(widget.session.identity, item.identity);
-      if (mounted) setState(() => _future = _load());
+      if (mounted) _reload();
+    } on SessionExpiredException {
+      return;
     } catch (error) {
       if (mounted) {
         ScaffoldMessenger.of(
@@ -175,10 +190,13 @@ class _WorkDetailPageState extends State<WorkDetailPage> {
       builder: (context, snapshot) {
         if (!snapshot.hasData) {
           if (snapshot.hasError) {
+            if (snapshot.error is SessionExpiredException) {
+              return const Center(child: CircularProgressIndicator());
+            }
             return MessageState(
               title: '任务详情加载失败',
               description: '请检查网络后重新加载',
-              onRetry: () => setState(() => _future = _load()),
+              onRetry: _reload,
             );
           }
           return const Center(child: CircularProgressIndicator());
@@ -292,7 +310,7 @@ class _WorkDetailPageState extends State<WorkDetailPage> {
                           final changed = await context.push<bool>(
                             '/tasks/${item.identity}/evidence',
                           );
-                          if (changed == true) setState(() => _future = _load());
+                          if (changed == true && mounted) _reload();
                         },
                   icon: const Icon(Icons.fact_check_outlined),
                   label: const Text('现场取证与提交'),

apps/service_app/lib/ui/features/work/work_list_view_model.dart

@@ -1,6 +1,9 @@
+// 功能描述：管理工作人员任务列表数据，并将会话失效交给统一路由处理。
+// 版本：1.1.0
 import 'package:flutter/foundation.dart';
 
 import '../../../data/repositories/service_repository.dart';
+import '../../../data/services/api_client.dart';
 import '../../../domain/models/service_models.dart';
 
 class WorkListViewModel extends ChangeNotifier {
@@ -27,7 +30,8 @@ class WorkListViewModel extends ChangeNotifier {
           .where((item) => completed ? item.status == 23 : item.status != 23 && item.status != 22)
           .toList();
     } catch (error) {
-      _error = error;
+      // 会话失效由统一路由接管，不在任务列表重复展示网络错误。
+      if (error is! SessionExpiredException) _error = error;
     } finally {
       _loading = false;
       notifyListeners();

apps/service_app/test/app/auth_navigation_test.dart

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

apps/service_app/test/app/router_test.dart

@@ -0,0 +1,102 @@
+// 功能描述：验证工作人员端鉴权守卫保留目标页，并在重新登录后返回原页面。
+// 版本：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:service_app/app/dependencies.dart';
+import 'package:service_app/app/router.dart';
+import 'package:service_app/data/offline/encrypted_draft_store.dart';
+import 'package:service_app/data/repositories/service_repository.dart';
+import 'package:service_app/data/services/api_client.dart';
+import 'package:service_app/data/services/location_service.dart';
+import 'package:service_app/data/services/secure_session_store.dart';
+
+/// 提供无需平台插件的空会话存储。
+class _EmptySessionStore implements SessionStore {
+  @override
+  Future<void> delete(String key) async {}
+
+  @override
+  Future<String?> read(String key) async => null;
+
+  @override
+  Future<void> write(String key, String value) async {}
+}
+
+/// 提供可切换鉴权状态的测试会话。
+class _RouterTestSession extends StaffSession {
+  _RouterTestSession({required this.authenticated, required this.expired})
+    : super(_EmptySessionStore());
+
+  bool authenticated;
+  bool expired;
+
+  @override
+  bool get isAuthenticated => authenticated;
+
+  @override
+  bool get hasExpired => expired;
+
+  @override
+  String get roleCode => 'delivery';
+
+  /// 模拟工作人员重新登录成功并唤醒路由刷新。
+  void authenticate() {
+    authenticated = true;
+    expired = false;
+    notifyListeners();
+  }
+}
+
+/// 提供不会在路由测试中访问系统定位的占位实现。
+class _UnusedLocationService implements LocationService {
+  @override
+  Future<LocationPoint> current() => throw UnimplementedError();
+}
+
+/// 覆盖过期提示、查询参数保留和登录后回跳。
+void main() {
+  testWidgets('令牌失效后跳转登录并在登录后返回原目标页', (tester) async {
+    final session = _RouterTestSession(authenticated: false, expired: true);
+    final dependencies = AppDependencies(
+      session: session,
+      repository: ServiceRepository(
+        ApiClient(
+          () => '',
+          baseUrl: 'https://api.example.com',
+          client: MockClient(
+            (request) async => http.Response(
+              '{"code":0,"details":{"role_code":"delivery","work_status":"off_duty","can_work":false,"checks":{}}}',
+              200,
+            ),
+          ),
+        ),
+        _UnusedLocationService(),
+      ),
+      drafts: EncryptedDraftStore(),
+    );
+    final router = createRouter(
+      dependencies,
+      initialLocation: '/preflight?source=expired#checks',
+    );
+    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'], '/preflight?source=expired#checks');
+    expect(loginUri.queryParameters['reason'], 'expired');
+    expect(find.text('登录状态已失效，请重新登录'), findsOneWidget);
+
+    session.authenticate();
+    await tester.pumpAndSettle();
+
+    final restoredUri = router.routeInformationProvider.value.uri;
+    expect(restoredUri.path, '/preflight');
+    expect(restoredUri.queryParameters['source'], 'expired');
+    expect(restoredUri.fragment, 'checks');
+  });
+}

apps/service_app/test/app/staff_session_test.dart

@@ -0,0 +1,115 @@
+// 功能描述：验证工作人员会话失效的幂等清理、旧请求隔离和存储异常降级。
+// 版本：1.0.0
+import 'package:flutter_test/flutter_test.dart';
+import 'package:service_app/app/dependencies.dart';
+import 'package:service_app/data/services/secure_session_store.dart';
+
+/// 提供可观测的内存会话存储，避免测试依赖真实平台插件。
+class _MemorySessionStore implements SessionStore {
+  _MemorySessionStore({Map<String, String>? values, this.deleteError}) : values = {...?values};
+
+  final Map<String, String> values;
+  final Object? deleteError;
+  final Map<String, int> deleteCounts = {};
+
+  @override
+  Future<void> delete(String key) async {
+    deleteCounts[key] = (deleteCounts[key] ?? 0) + 1;
+    if (deleteError != null) throw deleteError!;
+    values.remove(key);
+  }
+
+  @override
+  Future<String?> read(String key) async => values[key];
+
+  @override
+  Future<void> write(String key, String value) async {
+    values[key] = value;
+  }
+}
+
+/// 覆盖并发 401、迟到旧请求、设备标识保留和安全存储删除失败。
+void main() {
+  const tokenKey = 'service_app_access_token';
+  const identityKey = 'service_app_identity';
+  const roleKey = 'service_app_role';
+  const deviceKey = 'service_app_device';
+
+  test('同一失效令牌只清理并通知一次且保留设备标识', () async {
+    final store = _MemorySessionStore(
+      values: const {
+        tokenKey: 'JWT expired-token',
+        identityKey: 'staff-1',
+        roleKey: 'delivery',
+        deviceKey: 'device-1',
+      },
+    );
+    final session = StaffSession(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.identity, isEmpty);
+    expect(session.roleCode, isEmpty);
+    expect(session.deviceIdentity, 'device-1');
+    expect(session.hasExpired, isTrue);
+    expect(store.deleteCounts[tokenKey], 1);
+    expect(store.deleteCounts[identityKey], 1);
+    expect(store.deleteCounts[roleKey], 1);
+    expect(store.deleteCounts[deviceKey], isNull);
+    expect(store.values[deviceKey], 'device-1');
+    expect(notificationCount, 1);
+  });
+
+  test('迟到的旧请求不得使当前会话失效', () async {
+    final store = _MemorySessionStore(
+      values: const {
+        tokenKey: 'JWT current-token',
+        identityKey: 'staff-1',
+        roleKey: 'installer',
+        deviceKey: 'device-1',
+      },
+    );
+    final session = StaffSession(store);
+    await session.restore();
+
+    session.invalidate('JWT old-token');
+    await Future<void>.delayed(Duration.zero);
+
+    expect(session.token, 'JWT current-token');
+    expect(session.identity, 'staff-1');
+    expect(session.roleCode, 'installer');
+    expect(session.hasExpired, isFalse);
+    expect(store.deleteCounts, isEmpty);
+  });
+
+  test('持久化删除失败也立即清空内存会话并保留设备标识', () async {
+    final store = _MemorySessionStore(
+      values: const {
+        tokenKey: 'JWT expired-token',
+        identityKey: 'staff-1',
+        roleKey: 'operations',
+        deviceKey: 'device-1',
+      },
+      deleteError: StateError('storage unavailable'),
+    );
+    final session = StaffSession(store);
+    await session.restore();
+
+    session.invalidate('JWT expired-token');
+    await Future<void>.delayed(Duration.zero);
+
+    expect(session.token, isEmpty);
+    expect(session.identity, isEmpty);
+    expect(session.roleCode, isEmpty);
+    expect(session.deviceIdentity, 'device-1');
+    expect(session.hasExpired, isTrue);
+    expect(store.deleteCounts.keys, containsAll([tokenKey, identityKey, roleKey]));
+    expect(store.deleteCounts[deviceKey], isNull);
+  });
+}

apps/service_app/test/data/api_client_test.dart

@@ -0,0 +1,115 @@
+// 功能描述：验证工作人员端统一请求的鉴权失效通知和上传处理。
+// 版本：1.0.0
+import 'dart:typed_data';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:http/http.dart' as http;
+import 'package:http/testing.dart';
+import 'package:image_picker/image_picker.dart';
+import 'package:service_app/data/services/api_client.dart';
+
+/// 覆盖 HTTP 状态、业务码、匿名请求、请求令牌快照和上传场景。
+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('请求发送后令牌变化时仍上报实际被拒绝的旧令牌', () async {
+    var currentToken = 'JWT old-token';
+    final rejectedTokens = <String>[];
+    final client = ApiClient(
+      () => currentToken,
+      baseUrl: 'https://api.example.com',
+      onUnauthorized: rejectedTokens.add,
+      client: MockClient((request) async {
+        currentToken = 'JWT new-token';
+        return http.Response('', 401);
+      }),
+    );
+
+    await expectLater(
+      client.get('/protected'),
+      throwsA(isA<SessionExpiredException>()),
+    );
+    expect(rejectedTokens, ['JWT old-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":1715,"message":"Unauthorized","details":null}',
+          200,
+        ),
+      ),
+    );
+    final file = XFile.fromData(
+      Uint8List.fromList(const [1, 2, 3]),
+      name: 'proof.jpg',
+      mimeType: 'image/jpeg',
+    );
+
+    await expectLater(
+      client.upload(file),
+      throwsA(isA<SessionExpiredException>()),
+    );
+    expect(rejectedTokens, ['JWT expired-token']);
+  });
+}

apps/service_app/test/ui/preflight_page_test.dart

@@ -0,0 +1,77 @@
+// 功能描述：验证作业前检查页面失败重试不会向 setState 返回异步任务。
+// 版本：1.0.0
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:service_app/app/dependencies.dart';
+import 'package:service_app/data/repositories/service_repository.dart';
+import 'package:service_app/data/services/api_client.dart';
+import 'package:service_app/data/services/location_service.dart';
+import 'package:service_app/data/services/secure_session_store.dart';
+import 'package:service_app/domain/models/service_models.dart';
+import 'package:service_app/ui/features/preflight/preflight_page.dart';
+
+/// 提供无需平台插件的空会话存储。
+class _EmptySessionStore implements SessionStore {
+  @override
+  Future<void> delete(String key) async {}
+
+  @override
+  Future<String?> read(String key) async => null;
+
+  @override
+  Future<void> write(String key, String value) async {}
+}
+
+/// 提供不会在重试测试中访问系统定位的占位实现。
+class _UnusedLocationService implements LocationService {
+  @override
+  Future<LocationPoint> current() => throw UnimplementedError();
+}
+
+/// 首次加载失败、第二次成功，用于验证真实重试路径。
+class _FailOnceRepository extends ServiceRepository {
+  _FailOnceRepository()
+    : super(
+        ApiClient(() => '', baseUrl: 'https://api.example.com'),
+        _UnusedLocationService(),
+      );
+
+  int calls = 0;
+
+  @override
+  Future<PreflightResult> preflight() async {
+    calls += 1;
+    if (calls == 1) throw StateError('temporary failure');
+    return const PreflightResult(
+      roleCode: 'delivery',
+      workStatus: 'off_duty',
+      canWork: false,
+      checks: {},
+    );
+  }
+}
+
+/// 点击重新加载后应成功刷新，且测试过程不得出现 Flutter 断言。
+void main() {
+  testWidgets('作业检查失败后可重新加载', (tester) async {
+    final repository = _FailOnceRepository();
+    final session = StaffSession(_EmptySessionStore());
+    await tester.pumpWidget(
+      MaterialApp(
+        home: PreflightPage(session: session, repository: repository),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.text('作业检查加载失败'), findsOneWidget);
+    expect(repository.calls, 1);
+
+    await tester.tap(find.text('重新加载'));
+    await tester.pumpAndSettle();
+
+    expect(find.text('作业检查加载失败'), findsNothing);
+    expect(find.text('仍有前置条件未完成'), findsOneWidget);
+    expect(repository.calls, 2);
+    expect(tester.takeException(), isNull);
+  });
+}

docs/04-服务端App需求.md

@@ -18,6 +18,7 @@
 
 - 登录支持用户名密码、记住登录状态、忘记密码、用户协议和隐私政策确认。注册页可申请配送员、安装维修员或安检员角色，但注册成功仅创建待审核账号；平台审核通过并校验资质后才可接单。
 - 手机号密码登录必须在客户端同时校验手机号格式和密码必填；任一字段无效时不得发送登录请求，应在对应字段显示中文提示并聚焦首个无效字段。登录密码须原样提交，登录按钮和密码框回车提交必须共用同一校验流程。
+- 受保护接口返回 HTTP 401 或稳定鉴权失效业务码时，客户端必须立即清除令牌、工作人员标识和角色并保留设备标识，跳转登录页提示会话失效；重新登录后仅允许安全返回原站内页面。打卡、取证、上传和任务状态等写操作不得自动重放。
 - 服务人员资料包括姓名、手机号、工号、工作单位、身份证明、角色对应从业证号、证书到期日和证件照片。配送员额外维护配送车辆车牌、颜色、车型及车辆照片；安装维修/安检人员维护专业资质、培训和工具能力。证件图片默认最多 6 张，数量和类型可配置。
 - 上班/下班记录当前时间、状态、角色、地点和设备信息。未上班、超出服务区、资质失效或未完成每日培训时不得接新单；已接任务须完成、改派或按规则申请下班。
 - 每日安全知识培训在首次进入工作台时弹出，按角色题库下发单选/多选题，记录题目版本、答案、结果、完成时间和次数。未完成培训时可浏览任务但默认不能开始执行；是否允许补训由平台配置。

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

@@ -94,6 +94,7 @@
 - 平台、气站和配送点三个受控管理后台的列表可以只读展示记录主键 `ID`，用于数据库问题定位；任何写操作、详情定位、关联选择、日志和跨服务传递仍统一使用 `identity`。服务端不得接受客户端指定新记录的 `id` 或 `identity`，创建时必须在逻辑层生成 UUID V7 `identity`。
 
 - 登录令牌短期有效，刷新令牌可撤销；后台高权限账号启用 MFA、IP/设备策略。平台后台管理的平台、气站、配送、员工和业主账号密码按当前实施口径仅要求不少于 6 个字符，不附加复杂度校验。
+- 用户端和工作人员端对受保护请求的 HTTP 401 及稳定鉴权失效业务码采用统一会话失效处理；并发失效只清理一次，迟到旧请求不得清除新会话。重新登录可恢复原站内页面，但任何产生副作用的写请求都不得自动重放。
 - 用户端携带鉴权的请求遇到 HTTP 401 或鉴权业务码 `1301`—`1314`、`1715` 时，应按请求实际携带的令牌触发幂等会话失效；迟到的旧请求不得清除后来建立的新会话。客户端先清空内存状态并跳转登录，再尽力删除安全存储中的旧令牌。
 - 登录前目标页只能保存为站内绝对路径，禁止接受带协议、主机、反斜杠、协议相对形式或登录/注册循环的跳转值。重新登录不得自动重放支付、下单、退款、工单等产生副作用的请求。
 - 权限校验在服务端执行，前端菜单隐藏不构成权限控制。按角色、站点、区域、对象归属联合鉴权。

docs/操作日志_工作人员端令牌失效恢复_20260905.md

@@ -0,0 +1,56 @@
+# 工作人员端令牌失效恢复操作日志
+
+操作时间：2026-09-05 19:44:58
+
+操作类型：修改、扩展
+
+影响模块：工作人员端请求层、会话管理、鉴权路由、登录页、业务页面刷新及本地 Web 运行方式
+
+## 操作前状态
+
+浏览器保留工作人员登录状态，但令牌已被后端拒绝。作业前检查接口实际返回 HTTP 401，客户端却将其显示为“请检查网络”，并因路由继续把本地令牌视为有效而无法返回登录页。点击“重新加载”还会将异步任务从 `setState` 回调返回，在 Flutter 调试模式触发断言；相同写法在作业检查、个人资料和任务详情中共有 7 处。
+
+## 具体操作
+
+1. 请求层保存每个请求实际使用的令牌，统一识别受保护请求的 HTTP 401 与业务码 `1301—1314`、`1715`。
+2. 普通 JSON 请求和文件上传均通知会话层并抛出专用失效异常；匿名登录请求不触发清理。
+3. 会话层仅处理与当前令牌一致的拒绝通知，幂等清除令牌、工作人员标识和角色，并保留设备标识。
+4. 持久化字段逐项尽力删除；新登录写入前等待旧清理任务结束，避免迟到旧请求和删除任务破坏新会话。
+5. 路由将失效前的站内目标页写入登录地址，并通过 `reason=expired` 展示明确提示；重新登录后安全回跳。
+6. 页面层忽略专用会话失效异常，不再重复显示普通网络错误，也不自动重放写操作。
+7. 将全部 7 处异步 `setState` 赋值改为同步状态回调，并新增统一页面刷新方法。
+8. 新增请求层、会话层、路由、安全回跳和作业检查重试测试，同步需求、安全和项目文档。
+9. 构建连接本地后端 `12426` 的 Release Web 产物，将 `5181` 从 Flutter 调试服务切换为隐藏的静态服务。
+
+## 操作后状态
+
+工作人员端遇到失效令牌后会立即停止当前页面错误展示，清理会话并进入登录页，显示“登录状态已失效，请重新登录”。登录地址保留合法原目标页，重新登录后可返回；非法或缺失目标默认进入作业前检查。写操作不会自动重放，设备标识不会因会话失效丢失。所有已知页面刷新入口不再向 `setState` 返回 `Future`。
+
+## 代码变更
+
+- `apps/service_app/lib/data/services/api_client.dart`（+58/-15）：统一鉴权失效识别、令牌快照、专用异常和上传处理。
+- `apps/service_app/lib/app/dependencies.dart`（+57/-15）：会话清理、设备保留、幂等及竞态保护。
+- `apps/service_app/lib/data/services/secure_session_store.dart`（+18/-1）：新增可测试的会话存储接口。
+- `apps/service_app/lib/app/auth_navigation.dart`（新增 32 行）：登录地址构造和站内目标校验。
+- `apps/service_app/lib/app/router.dart`（+21/-5）、登录页（+15/-2）：失效跳转、提示和登录后回跳。
+- 作业检查、个人资料、任务详情、任务列表与取证页面（合计 +65/-8）：鉴权错误抑制与同步刷新。
+- `apps/service_app/test/app/`、`test/data/api_client_test.dart`、`test/ui/preflight_page_test.dart`（新增 448 行）：鉴权、并发、回跳和重试回归测试。
+- `docs/04-服务端App需求.md`、`docs/11-数据接口与安全.md`：同步功能和安全约束。
+- `docs/项目文档_工作人员端令牌失效恢复_v1.0.md`（新增 77 行）：记录结构、行为、维护方法和边界。
+
+## 验证结果
+
+- `flutter analyze --no-pub`：通过，无问题。
+- `flutter test --no-pub`：通过，共 20 项测试。
+- 作业检查组件测试实际执行首次失败和点击重试，确认页面恢复且无 Flutter 断言。
+- `flutter build web --release --no-pub --dart-define=API_BASE_URL=http://127.0.0.1:12426`：通过。
+- 本地 `5181` 已由 Python Release 静态服务监听并返回 HTTP 200；`12426` 后端健康检查返回 HTTP 200。
+- 浏览器端到端验证：原 `/preflight` 页面携带残留失效令牌刷新后，实际跳转至 `/login?redirect=/preflight&reason=expired`，并显示“登录状态已失效，请重新登录”。
+
+## 风险评估
+
+- 会话失效按请求令牌快照与当前令牌比对，避免并发请求或重新登录期间的旧响应清除新会话。
+- 持久化删除失败时，当前运行仍可立即恢复登录；下次全新启动可能再次读取旧值并重新触发清理。
+- 回跳只接受站内绝对路径并排除登录页，降低开放重定向和登录循环风险。
+- 打卡、取证、上传和任务状态操作不自动重放，避免重复副作用。
+- 后端接口、JWT 生命周期、数据库和普通错误文案均未修改。

docs/项目文档_工作人员端令牌失效恢复_v1.0.md

@@ -0,0 +1,77 @@
+# 工作人员端令牌失效恢复项目文档 v1.0
+
+## 1. 项目概述
+
+- 项目名称：工作人员端令牌失效恢复与异步刷新修复。
+- 主要功能：受保护接口拒绝失效令牌后自动清理会话、返回登录页并安全保存原目标页；同时消除页面刷新时向 `setState` 返回异步任务的错误写法。
+- 技术栈：Flutter、Dart、GoRouter、HTTP、Flutter Secure Storage、Flutter Widget Test。
+- 运行环境：项目当前 Flutter SDK、Web Release 静态服务及本地平台 API。
+- 实施范围：仅 `service_app` 请求层、会话层、路由和页面错误处理；后端接口与数据库不变。
+
+## 2. 目录结构说明
+
+```text
+platforms/
+├── apps/service_app/
+│   ├── lib/
+│   │   ├── app/
+│   │   │   ├── auth_navigation.dart              # 登录地址与站内回跳校验
+│   │   │   ├── dependencies.dart                 # 会话失效、清理和并发保护
+│   │   │   └── router.dart                       # 鉴权守卫、过期提示和安全回跳
+│   │   ├── data/services/
+│   │   │   ├── api_client.dart                   # HTTP 与业务码鉴权失效识别
+│   │   │   └── secure_session_store.dart         # 可测试的安全存储接口
+│   │   └── ui/features/                          # 页面错误抑制和同步刷新
+│   └── test/
+│       ├── app/                                  # 会话、回跳和路由测试
+│       ├── data/api_client_test.dart             # 请求层鉴权测试
+│       └── ui/preflight_page_test.dart           # 作业检查重试组件测试
+└── docs/                                         # 需求、安全、项目和操作日志
+```
+
+## 3. 核心文件说明
+
+### 请求与上传
+
+- `ApiClient` 在请求发出前保存实际令牌快照。
+- 受保护请求返回 HTTP 401，或统一响应返回业务码 `1301—1314`、`1715` 时，通知会话层并抛出 `SessionExpiredException`。
+- 匿名登录请求不触发已有会话清理；普通 JSON 请求和文件上传使用同一识别规则。
+
+### 会话与安全存储
+
+- `StaffSession.invalidate` 只接受与当前令牌一致的被拒令牌，并通过失效标记保证幂等。
+- 失效时立即清空内存中的令牌、工作人员标识和角色，保留设备标识并通知路由。
+- 持久化删除逐项尽力执行；单项失败只记录调试信息，不阻塞返回登录页。
+- 新登录写入前等待旧清理任务结束，避免迟到删除覆盖新会话。
+
+### 路由与页面
+
+- 鉴权守卫把原目标页保存为登录页 `redirect` 参数，并通过 `reason=expired` 展示失效原因。
+- 仅允许站内绝对路径回跳；拒绝外部地址、协议相对地址、反斜杠地址和登录页循环。
+- 登录成功后返回原目标页，缺失或非法目标默认进入 `/preflight`。
+- 页面层不重复展示鉴权错误；普通断网和服务端错误仍沿用既有提示。
+- 作业检查、个人资料和任务详情中的 7 处异步刷新均改为同步 `setState` 赋值。
+
+## 4. 变更记录
+
+### v1.0（2026-09-05）
+
+- 新增工作人员端统一会话失效异常与请求令牌回调。
+- 新增会话清理、设备标识保留、并发幂等和迟到旧请求保护。
+- 新增登录失效提示、目标页保存和安全回跳。
+- 修复作业检查、个人资料和任务详情全部已知异步 `setState` 错误。
+- 新增请求层、会话层、路由、安全地址和作业检查重试测试。
+
+## 5. 维护指南
+
+- 新增受保护接口必须复用已装配 `onUnauthorized` 的统一 `ApiClient`。
+- 新增文件上传入口不得绕过统一响应解析和会话失效处理。
+- 页面捕获 `SessionExpiredException` 时只结束当前交互，不显示普通网络错误，也不重放写操作。
+- 替换页面加载任务时，应先创建 `Future`，再用带语句块的同步 `setState` 回调赋值。
+- 修改鉴权流程后至少运行 `flutter analyze --no-pub`、完整测试和 Release Web 构建。
+
+## 6. 已知边界
+
+- 本次不新增刷新令牌接口，也不改变服务端 JWT 生命周期和错误码。
+- 安全存储删除失败时，下次全新启动可能再次读取旧值，但当前运行会立即退出错误状态并可重新登录。
+- 重新登录只恢复页面位置，不恢复或自动执行失效前的打卡、取证、上传及任务操作。