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

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 生命周期和错误码。
+- 安全存储删除失败时，下次全新启动可能再次读取旧值，但当前运行会立即退出错误状态并可重新登录。
+- 重新登录只恢复页面位置，不恢复或自动执行失效前的打卡、取证、上传及任务操作。