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

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

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

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

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

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

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