diff --git a/apps/service_app/lib/app/auth_navigation.dart b/apps/service_app/lib/app/auth_navigation.dart new file mode 100644 index 0000000..f80e9b7 --- /dev/null +++ b/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 = { + '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(); +} diff --git a/apps/service_app/lib/app/dependencies.dart b/apps/service_app/lib/app/dependencies.dart index d679d57..e0add44 100644 --- a/apps/service_app/lib/app/dependencies.dart +++ b/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 _pendingClear = Future.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 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 _clearStoredSession() async { + for (final key in const [_tokenKey, _identityKey, _roleKey]) { + try { + await _store.delete(key); + } catch (error, stackTrace) { + debugPrint('清理工作人员失效会话失败($key):$error'); + debugPrintStack(stackTrace: stackTrace); + } + } } } diff --git a/apps/service_app/lib/app/router.dart b/apps/service_app/lib/app/router.dart index 62c2e01..e1ff6d9 100644 --- a/apps/service_app/lib/app/router.dart +++ b/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', diff --git a/apps/service_app/lib/data/services/api_client.dart b/apps/service_app/lib/data/services/api_client.dart index c99dd48..59d689b 100644 --- a/apps/service_app/lib/data/services/api_client.dart +++ b/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 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 jsonMap(Object? value) { if (value is Map) return value; if (value is Map) return value.map((key, item) => MapEntry(key.toString(), item)); diff --git a/apps/service_app/lib/data/services/secure_session_store.dart b/apps/service_app/lib/data/services/secure_session_store.dart index ce2dff1..862012e 100644 --- a/apps/service_app/lib/data/services/secure_session_store.dart +++ b/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 read(String key); + + Future write(String key, String value); + + Future delete(String key); +} + +/// 使用平台安全存储保存工作人员会话上下文。 +class SecureSessionStore implements SessionStore { SecureSessionStore({FlutterSecureStorage? storage}) : _storage = storage ?? const FlutterSecureStorage(); final FlutterSecureStorage _storage; + @override Future read(String key) => _storage.read(key: key); + + @override Future write(String key, String value) => _storage.write(key: key, value: value); + + @override Future delete(String key) => _storage.delete(key: key); } diff --git a/apps/service_app/lib/ui/features/auth/login_page.dart b/apps/service_app/lib/ui/features/auth/login_page.dart index 9cb80a9..236fa63 100644 --- a/apps/service_app/lib/ui/features/auth/login_page.dart +++ b/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 createState() => _LoginPageState(); @@ -29,6 +34,14 @@ class _LoginPageState extends State { String? _passwordError; bool _obscurePassword = true; + @override + void initState() { + super.initState(); + if (widget.showSessionExpiredMessage) { + _error = '登录状态已失效,请重新登录'; + } + } + /// 校验手机号和密码,通过后再提交登录请求。 Future _login() async { final phone = _phone.text.trim(); diff --git a/apps/service_app/lib/ui/features/evidence/evidence_page.dart b/apps/service_app/lib/ui/features/evidence/evidence_page.dart index 1ffa07f..3b4a50e 100644 --- a/apps/service_app/lib/ui/features/evidence/evidence_page.dart +++ b/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 { widget.taskIdentity, ); if (mounted) Navigator.pop(context, true); + } on SessionExpiredException { + return; } catch (error) { if (mounted) { ScaffoldMessenger.of( diff --git a/apps/service_app/lib/ui/features/preflight/preflight_page.dart b/apps/service_app/lib/ui/features/preflight/preflight_page.dart index 8fff512..5599e9d 100644 --- a/apps/service_app/lib/ui/features/preflight/preflight_page.dart +++ b/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 { _future = widget.repository.preflight(); } + /// 创建新的加载任务,并在同步状态回调中替换页面 Future。 + void _reload() { + final future = widget.repository.preflight(); + setState(() { + _future = future; + }); + } + Future _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 { 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()); diff --git a/apps/service_app/lib/ui/features/profile/profile_page.dart b/apps/service_app/lib/ui/features/profile/profile_page.dart index e979a2c..205ee39 100644 --- a/apps/service_app/lib/ui/features/profile/profile_page.dart +++ b/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 { await widget.drafts.count(widget.session.identity), ); + /// 创建新的加载任务,并在同步状态回调中替换页面 Future。 + void _reload() { + final future = _load(); + setState(() { + _future = future; + }); + } + Future _logout(int draftCount) async { if (draftCount > 0) { final discard = await showDialog( @@ -66,10 +77,13 @@ class _ProfilePageState extends State { 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()); diff --git a/apps/service_app/lib/ui/features/work/work_detail_page.dart b/apps/service_app/lib/ui/features/work/work_detail_page.dart index 04cc9f1..bc87283 100644 --- a/apps/service_app/lib/ui/features/work/work_detail_page.dart +++ b/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 { ? widget.repository.deliveryDetail(widget.identity) : widget.repository.ticketDetail(widget.identity); + /// 创建新的加载任务,并在同步状态回调中替换页面 Future。 + void _reload() { + final future = _load(); + setState(() { + _future = future; + }); + } + Future _run( Future Function(WorkItem) action, WorkItem item, @@ -48,7 +59,9 @@ class _WorkDetailPageState extends State { 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 { 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 { 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 { final changed = await context.push( '/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('现场取证与提交'), diff --git a/apps/service_app/lib/ui/features/work/work_list_view_model.dart b/apps/service_app/lib/ui/features/work/work_list_view_model.dart index a7017ed..5b86496 100644 --- a/apps/service_app/lib/ui/features/work/work_list_view_model.dart +++ b/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(); diff --git a/apps/service_app/test/app/auth_navigation_test.dart b/apps/service_app/test/app/auth_navigation_test.dart new file mode 100644 index 0000000..df51b30 --- /dev/null +++ b/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); + }); +} diff --git a/apps/service_app/test/app/router_test.dart b/apps/service_app/test/app/router_test.dart new file mode 100644 index 0000000..509c08c --- /dev/null +++ b/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 delete(String key) async {} + + @override + Future read(String key) async => null; + + @override + Future 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 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'); + }); +} diff --git a/apps/service_app/test/app/staff_session_test.dart b/apps/service_app/test/app/staff_session_test.dart new file mode 100644 index 0000000..a09203e --- /dev/null +++ b/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? values, this.deleteError}) : values = {...?values}; + + final Map values; + final Object? deleteError; + final Map deleteCounts = {}; + + @override + Future delete(String key) async { + deleteCounts[key] = (deleteCounts[key] ?? 0) + 1; + if (deleteError != null) throw deleteError!; + values.remove(key); + } + + @override + Future read(String key) async => values[key]; + + @override + Future 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.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.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.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); + }); +} diff --git a/apps/service_app/test/data/api_client_test.dart b/apps/service_app/test/data/api_client_test.dart new file mode 100644 index 0000000..40c209f --- /dev/null +++ b/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 = []; + 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()), + ); + expect(rejectedTokens, ['JWT expired-token']); + }); + + test('受保护接口返回鉴权业务码时通知会话', () async { + final rejectedTokens = []; + 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()), + ); + expect(rejectedTokens, ['JWT expired-token']); + }); + + test('未鉴权接口返回 401 时不得清理已有会话', () async { + final rejectedTokens = []; + 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() + .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 = []; + 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()), + ); + expect(rejectedTokens, ['JWT old-token']); + }); + + test('文件上传返回鉴权业务码时同样触发统一会话失效', () async { + final rejectedTokens = []; + 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()), + ); + expect(rejectedTokens, ['JWT expired-token']); + }); +} diff --git a/apps/service_app/test/ui/preflight_page_test.dart b/apps/service_app/test/ui/preflight_page_test.dart new file mode 100644 index 0000000..2d892b8 --- /dev/null +++ b/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 delete(String key) async {} + + @override + Future read(String key) async => null; + + @override + Future write(String key, String value) async {} +} + +/// 提供不会在重试测试中访问系统定位的占位实现。 +class _UnusedLocationService implements LocationService { + @override + Future current() => throw UnimplementedError(); +} + +/// 首次加载失败、第二次成功,用于验证真实重试路径。 +class _FailOnceRepository extends ServiceRepository { + _FailOnceRepository() + : super( + ApiClient(() => '', baseUrl: 'https://api.example.com'), + _UnusedLocationService(), + ); + + int calls = 0; + + @override + Future 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); + }); +} diff --git a/docs/04-服务端App需求.md b/docs/04-服务端App需求.md index 5dcbd9d..d0ddcc8 100644 --- a/docs/04-服务端App需求.md +++ b/docs/04-服务端App需求.md @@ -18,6 +18,7 @@ - 登录支持用户名密码、记住登录状态、忘记密码、用户协议和隐私政策确认。注册页可申请配送员、安装维修员或安检员角色,但注册成功仅创建待审核账号;平台审核通过并校验资质后才可接单。 - 手机号密码登录必须在客户端同时校验手机号格式和密码必填;任一字段无效时不得发送登录请求,应在对应字段显示中文提示并聚焦首个无效字段。登录密码须原样提交,登录按钮和密码框回车提交必须共用同一校验流程。 +- 受保护接口返回 HTTP 401 或稳定鉴权失效业务码时,客户端必须立即清除令牌、工作人员标识和角色并保留设备标识,跳转登录页提示会话失效;重新登录后仅允许安全返回原站内页面。打卡、取证、上传和任务状态等写操作不得自动重放。 - 服务人员资料包括姓名、手机号、工号、工作单位、身份证明、角色对应从业证号、证书到期日和证件照片。配送员额外维护配送车辆车牌、颜色、车型及车辆照片;安装维修/安检人员维护专业资质、培训和工具能力。证件图片默认最多 6 张,数量和类型可配置。 - 上班/下班记录当前时间、状态、角色、地点和设备信息。未上班、超出服务区、资质失效或未完成每日培训时不得接新单;已接任务须完成、改派或按规则申请下班。 - 每日安全知识培训在首次进入工作台时弹出,按角色题库下发单选/多选题,记录题目版本、答案、结果、完成时间和次数。未完成培训时可浏览任务但默认不能开始执行;是否允许补训由平台配置。 diff --git a/docs/11-数据接口与安全.md b/docs/11-数据接口与安全.md index 0f1af07..488a5fa 100644 --- a/docs/11-数据接口与安全.md +++ b/docs/11-数据接口与安全.md @@ -94,6 +94,7 @@ - 平台、气站和配送点三个受控管理后台的列表可以只读展示记录主键 `ID`,用于数据库问题定位;任何写操作、详情定位、关联选择、日志和跨服务传递仍统一使用 `identity`。服务端不得接受客户端指定新记录的 `id` 或 `identity`,创建时必须在逻辑层生成 UUID V7 `identity`。 - 登录令牌短期有效,刷新令牌可撤销;后台高权限账号启用 MFA、IP/设备策略。平台后台管理的平台、气站、配送、员工和业主账号密码按当前实施口径仅要求不少于 6 个字符,不附加复杂度校验。 +- 用户端和工作人员端对受保护请求的 HTTP 401 及稳定鉴权失效业务码采用统一会话失效处理;并发失效只清理一次,迟到旧请求不得清除新会话。重新登录可恢复原站内页面,但任何产生副作用的写请求都不得自动重放。 - 用户端携带鉴权的请求遇到 HTTP 401 或鉴权业务码 `1301`—`1314`、`1715` 时,应按请求实际携带的令牌触发幂等会话失效;迟到的旧请求不得清除后来建立的新会话。客户端先清空内存状态并跳转登录,再尽力删除安全存储中的旧令牌。 - 登录前目标页只能保存为站内绝对路径,禁止接受带协议、主机、反斜杠、协议相对形式或登录/注册循环的跳转值。重新登录不得自动重放支付、下单、退款、工单等产生副作用的请求。 - 权限校验在服务端执行,前端菜单隐藏不构成权限控制。按角色、站点、区域、对象归属联合鉴权。 diff --git a/docs/操作日志_工作人员端令牌失效恢复_20260905.md b/docs/操作日志_工作人员端令牌失效恢复_20260905.md new file mode 100644 index 0000000..38aeca0 --- /dev/null +++ b/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 生命周期、数据库和普通错误文案均未修改。 diff --git a/docs/项目文档_工作人员端令牌失效恢复_v1.0.md b/docs/项目文档_工作人员端令牌失效恢复_v1.0.md new file mode 100644 index 0000000..194f166 --- /dev/null +++ b/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 生命周期和错误码。 +- 安全存储删除失败时,下次全新启动可能再次读取旧值,但当前运行会立即退出错误状态并可重新登录。 +- 重新登录只恢复页面位置,不恢复或自动执行失效前的打卡、取证、上传及任务操作。