工作人员端令牌失效恢复操作日志

操作时间：2026-09-05 19:44:58

操作类型：修改、扩展

影响模块：工作人员端请求层、会话管理、鉴权路由、登录页、业务页面刷新及本地 Web 运行方式

操作前状态

浏览器保留工作人员登录状态，但令牌已被后端拒绝。作业前检查接口实际返回 HTTP 401，客户端却将其显示为“请检查网络”，并因路由继续把本地令牌视为有效而无法返回登录页。点击“重新加载”还会将异步任务从 setState 回调返回，在 Flutter 调试模式触发断言；相同写法在作业检查、个人资料和任务详情中共有 7 处。

具体操作

请求层保存每个请求实际使用的令牌，统一识别受保护请求的 HTTP 401 与业务码 1301—1314、1715。
普通 JSON 请求和文件上传均通知会话层并抛出专用失效异常；匿名登录请求不触发清理。
会话层仅处理与当前令牌一致的拒绝通知，幂等清除令牌、工作人员标识和角色，并保留设备标识。
持久化字段逐项尽力删除；新登录写入前等待旧清理任务结束，避免迟到旧请求和删除任务破坏新会话。
路由将失效前的站内目标页写入登录地址，并通过 reason=expired 展示明确提示；重新登录后安全回跳。
页面层忽略专用会话失效异常，不再重复显示普通网络错误，也不自动重放写操作。
将全部 7 处异步 setState 赋值改为同步状态回调，并新增统一页面刷新方法。
新增请求层、会话层、路由、安全回跳和作业检查重试测试，同步需求、安全和项目文档。
构建连接本地后端 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 生命周期、数据库和普通错误文案均未修改。

4.6 KiB Raw Blame History Unescape Escape