admin
5ad755116e
1) dsh-server-docs/ 从工作区（原 E:\...\aliyun-dsh-server\dsh-server-docs）**整体并入本仓**，
保留目录名 ⇒ 仓库内 dsh-server-docs/... 的相对引用天然继续有效；旧目录（含其 .git）已归档到
工作区 _中间产物_待清理/，未随本提交带入。
2) .gitattributes：新增 `dsh-server-docs/** -text` —— 原文档库是 `* -text` + autocrlf=false，
必须保持纯 LF，否则会被本仓的 CRLF 规则翻掉。
3) 活引用里的绝对路径已全部改到新位置（docs 的 INDEX / README / scripts / skills + 用户级 skills
+ ~/.workbuddy/settings.json 的 hooks）；历史档案（04-调整方案/、archive/）按「只增不改」未动。
⚠️ hooks 路径改动需「完全重启会话」才生效（配置是会话启动快照）。
4) 交接单/T08：新增 §16「生产整体切换执行记录」（形态 / 落地动作 / **4 个只有真上线才暴露的真 bug** /
验收证据 / 回滚命令 / 残留项）；台账 T08 行 → 已完成并归档；03-路线图 §二 登记 T08 收尾项。
5) 统一称谓：**「本机」只指跑 WorkBuddy 的开发机**，47 / 106 一律写「远程服务器」。
60 lines
3.8 KiB
Markdown
60 lines
3.8 KiB
Markdown
# 62 · 插件目录：缓存状态可见化 + 「重新拉取目录」按钮
|
||
|
||
- 日期：2026-09-12
|
||
- 状态：✅ **已实施并验证**（服务器已生效；代码仓库已提交 `0e141a4`）
|
||
- 触发：用户「**拉取的官方目录可以缓存，不用每次都拉取，增加一个主动刷新开关**」
|
||
- 关联：档案 29（官方目录接入）、31（插件管理页双 Tab）、61（同页列表高度）
|
||
|
||
---
|
||
|
||
## 一、取证结论：**功能早已存在，只是完全看不出来**
|
||
|
||
| 能力 | 改前现状（`src/web/routes/whitelist.ts`）|
|
||
|---|---|
|
||
| **磁盘缓存** | `<dataRoot>/whitelist-cache/index.json` |
|
||
| **TTL** | **6 小时**（`CACHE_TTL`；TTL 内 `getIndex()` 直接返回缓存，**不联网**）|
|
||
| **主动刷新端点** | `POST /api/plugins/whitelist/refresh`（内部 `getIndex(true)` 强制拉取）|
|
||
| **降级** | 拉取失败 → 沿用旧缓存并标 `stale: true` |
|
||
| **返回字段** | `GET /api/plugins/whitelist` **已带 `fetchedAt` + `stale`** |
|
||
|
||
⇒ **"每次都拉取"是错觉**。真实原因是前端有三处**误导**：
|
||
|
||
1. 加载提示写「**拉取官方目录中…（首次约数秒）**」→ 让人以为每次打开都在下载
|
||
2. `wlInfo` **只显示 `stale`、不显示 `fetchedAt`** → 看不出缓存是否生效、也不知道多久没更新
|
||
3. 按钮叫「**刷新清单**」→ 看不出它就是"**绕过缓存从官方站重拉**"
|
||
|
||
## 二、改动（**仅前端 4 处**，`git diff --numstat` = **13 增 4 删**；**后端零改动**）
|
||
|
||
| 位置 | 改动 |
|
||
|---|---|
|
||
| `portal.html` L402 | 按钮「刷新清单」→ **「重新拉取目录」**，并加 `title`：「绕过本地缓存，从官方站重新下载插件目录（约数秒；平时打开本页不会下载，直接读本地缓存）」|
|
||
| L458 | 新增 `relTime(ts)` 工具函数（刚刚 / X 分钟前 / X 小时前 / X 天前）|
|
||
| L458 | 加载提示 → **「加载目录中…（首次会从官方站下载一次，之后读本地缓存）」** |
|
||
| L477 | `wlInfo` 增显 **「目录缓存更新于 X 前（6 小时内直接复用，不联网）」** —— 消费后端**已经返回**的 `fetchedAt` |
|
||
| L509 | 按钮流程提示明确化：「✓ 目录已重新拉取（缓存已更新）」／「重新拉取失败（网络或官方站不可达）」|
|
||
|
||
**设计取向**：不新增后端参数、不改动缓存策略（现状已合理），只把**既有事实暴露给用户**。这是最小改动的正解 —— 用户要的"缓存 + 主动刷新"**本来就工作**，缺的只是可见性。
|
||
|
||
## 三、验证
|
||
|
||
- `git diff --numstat` = **13 增 4 删**（**无整文件 diff**）
|
||
- 部署：`scp` + 服务器 `sed -i 's/\r$//'` 转回 LF（保持与仓库 blob 一致）
|
||
- `curl https://alotbuy.com/portal.html` 命中新文案 ✓（`重新拉取目录` 2 处、`function relTime` 1 处）
|
||
- **`portal.html` 是静态文件 → 改完立即生效，无需重启服务**（不涉及 R8）
|
||
|
||
## 四、回滚
|
||
|
||
```bash
|
||
git -C D:/github/dsh_shenxian checkout HEAD~1 -- web/portal.html # 或 HEAD~2（视改动批）
|
||
scp web/portal.html bt-server:/opt/dshs/web/portal.html
|
||
```
|
||
静态文件，无需重启；浏览器需硬刷新。
|
||
|
||
## 五、附：若还需要「自动更新开关」（**需后端，本次未做**）
|
||
|
||
当前语义 = 「**6 小时内自动复用缓存 + 按钮可随时强制重拉**」。
|
||
|
||
若你要的是一个 **「自动更新：开 / 关」的 toggle** —— 关掉后**连 TTL 到期也不联网**、只能手动点按钮 —— 则需给 `GET /api/plugins/whitelist` 增加一个 `cacheOnly=1` 参数（**只读缓存、不触发拉取**，缓存缺失时返回明确错误而非阻塞拉取），前端开关用 `localStorage` 记忆。
|
||
|
||
**这属于后端改动 → 需 `npm run build` + 重启平台 → 会中断在线用户**（按 R8 须先知会）。**本次未做，等确认。**
|