# Changelog: 主动 JWT 续期 —— 消除文件管理器双刷新

**日期**: 2026-06-02  
**类型**: 修复 (Bug Fix)  
**影响范围**: frontend/src/stores/auth.ts · frontend/src/api/index.ts

---

## 变更摘要

实现客户端 JWT access token 提前续期机制，彻底消除文件管理器"进目录双刷新"问题。

---

## 动机

每次 access token 过期后，`api/index.ts` 的 `fetchAuthed()` 会：
1. 先发出一次业务请求 → 服务端返回 401
2. 触发 `/auth/refresh` 获取新 token
3. 用新 token 重发同一业务请求

导致每次进入目录产生 2 次 `/api/sync/browse` 请求，页面可见"双刷新"（`_browseSeq` 虽可防止旧数据覆盖，但无法消除 2 次请求本身）。

---

## 方案

### `frontend/src/stores/auth.ts`

- 新增 `decodeJwtExp(jwt)` 工具函数：不验签地从 JWT Payload 解码 `exp` 字段（秒）
- 新增 `tokenExp` computed：返回当前 token 的过期 unix 秒，无 token 时为 0
- 新增 `isTokenExpiringSoon(thresholdSec = 300)` 方法：当距过期 < `thresholdSec` 秒时返回 true

### `frontend/src/api/index.ts`

在 `fetchAuthed()` 发出实际请求之前加入一个提前续期分支：

```typescript
if (!_retry && !AUTH_SKIP_REFRESH.has(path) && auth.token && auth.isTokenExpiringSoon(300)) {
  await tryRefreshSession()
}
```

若 token 将在 5 分钟内过期，先刷新再发请求，完全跳过"401 → 重试"路径。
原有的 401 兜底重试逻辑保留不变（处理极端并发或时钟偏差场景）。

---

## 涉及文件

| 文件 | 变更类型 |
|------|---------|
| `frontend/src/stores/auth.ts` | 新增 `decodeJwtExp` / `tokenExp` / `isTokenExpiringSoon` |
| `frontend/src/api/index.ts` | 在 `fetchAuthed` 中新增提前续期分支 |

---

## 是否需要迁移 / 重启

- **前端**: 需重新 `vite build` 后部署到服务器
- **后端**: 无变更，无需重启
- **数据库**: 无变更

---

## 追加修复（2026-06-02 续）

- `FilesPage.vue`：`v-select` 在 `onMounted` 赋值 `selectedServer` 时会触发 `@update:model-value` → `onServerChange` 再次 `browse()`；增加 `_initing` 守卫
- `FilesPage.vue`：`pageReady` 避免首屏短暂显示「请先选择服务器」
- `FilesPage.vue`：同路径并发 `browse()` 合并为单次 in-flight 请求
- 部署须执行 `deploy/prune_frontend_assets.py` 清理服务器上残留的旧 hash chunk（否则浏览器可能仍加载旧 `FilesPage-*.js`）

## 验证方式

1. 登录后等待 access token 接近过期（或手动修改 token exp 为近期时间）
2. 进入文件管理器浏览目录
3. 打开 DevTools Network 过滤 `/sync/browse`
4. 预期：每次进目录只有 **1 条** `/sync/browse` 请求，不再出现 401 后重试的第 2 条
5. 空目录区不应再闪现「请先选择服务器」（已选服务器时）
