功能（桌面端）：增加在线辅助本地缓存

2026-07-08 20:45:08 +08:00
parent b73f23c1eb
commit 76f2d9f22a
20 changed files with 926 additions and 50 deletions
@@ -2,9 +2,9 @@

 状态: `active`
 适用范围: Web 与 macOS Desktop 统一客户端发布
-最后更新: `2026-07-02`
+最后更新: `2026-07-08`

-本清单用于第一、二阶段桌面端能力完成后的准发布稳定化。它不引入离线登录、本地业务数据存储、内嵌后端服务或离线同步。
+本清单用于第一、二阶段桌面端能力完成后的准发布稳定化。当前允许按 `docs/desktop-local-cache-plan.md` 引入在线辅助本地缓存，但不引入离线登录、离线写入、本地业务权威数据、内嵌后端服务或离线同步。

 ## 1. 发布链路门禁

@@ -51,6 +51,9 @@ npm run desktop:build:app
 - [ ] 前端源码不通过 query string 传递 token。
 - [ ] `ctms_token` 只允许由 `secureSessionStorage` 处理。
 - [ ] 登录表单密码不写入 `localStorage` 或 `sessionStorage`；Web 端只使用浏览器凭据管理能力，Desktop 端只使用系统凭据库。
+- [ ] 本地缓存能力只通过 `frontend/src/runtime/desktopDataCache.ts` 或后续同名 runtime 入口暴露，业务模块不直接调用 Tauri 存储 API、SQLite、IndexedDB、Cache Storage 或文件系统。
+- [ ] 本地缓存命名空间包含 server origin、user id 和 cache schema version。
+- [ ] 本地缓存不保存 token、密码、Authorization/Bearer 文本、下载凭据、临时授权 URL 或系统通知正文。
 - [ ] 系统通知只能通过 `frontend/src/runtime/notifications.ts` 发送，标题和正文保持通用。
 - [ ] 通知 capability 只暴露权限查询、权限请求和发送通知，不使用 `notification:default`。
 - [ ] opener capability 只允许打开 `$TEMP/ctms-desktop/**` 下的临时文件，不开放 URL 或 reveal 权限。
@@ -65,6 +68,7 @@ npm run desktop:build:app
 - [ ] 密码不出现在 URL、日志、系统通知正文、诊断信息或明文浏览器存储中。
 - [ ] 桌面端通知正文只显示通用内容，不包含项目、文件或版本详情。
 - [ ] 服务端权限、审计和业务数据持久化仍由 FastAPI 后端裁决。
+- [ ] 本地缓存只作为服务端响应副本，mutation、审批、权限判断和审计判断仍以后端结果为准。
 - [ ] Web 运行时不直接导入 Tauri API。

 ## 3. 端到端回归矩阵
@@ -77,6 +81,9 @@ npm run desktop:build:app
 | 服务器地址未配置 | 不适用 | 必测 | 自动进入服务器设置，不进入业务页 |
 | 服务器地址切换 | 不适用 | 必测 | 清除当前会话和项目上下文，要求重新登录 |
 | 服务端不可达 | 必测 | 必测 | 显示可恢复错误，不进入离线模式 |
+| 本地缓存命中 | 必测 | 必测 | `/me` 校验通过后可先展示缓存再后台刷新 |
+| 本地缓存清理 | 必测 | 必测 | 登出、切换服务器、切换用户、401/403 后旧命名空间不可读取 |
+| mutation 缓存失效 | 必测 | 必测 | 新增、编辑、删除或审批成功后相关列表、详情、统计和图表缓存失效 |
 | 附件上传 | 必测 | 必测 | Web 使用浏览器文件选择，Desktop 使用原生选择 |
 | 附件下载/保存/打开 | 必测 | 必测 | 使用 Authorization header；无 `?token=` |
 | 临时文件清理 | 不适用 | 必测 | 启动时清理 `$TEMP/ctms-desktop/**` |
@@ -96,6 +103,7 @@ npm run desktop:build:app
 - [ ] 服务器设置页显示当前服务器、连接检查状态、HTTP 错误、超时和网络失败原因。
 - [ ] 个人中心显示客户端类型、版本、平台、构建通道、提交、服务器和能力状态。
 - [ ] 个人中心可复制诊断信息，内容不包含 token 或业务敏感数据。
+- [ ] 系统偏好或个人中心提供本地缓存记录数、容量和最近清理时间，且支持手动清理。
 - [ ] 通知开关显示 OS 权限状态。
 - [ ] 手动检查更新能反馈“已是最新版本”、未启用更新或检查失败。
 - [ ] 关键弹窗、表单、按钮在最小窗口尺寸 `1180x760` 下不重叠、不溢出。
@@ -103,10 +111,11 @@ npm run desktop:build:app

 ## 5. 不允许项

- [ ] 不实现离线登录、离线浏览、离线队列或离线同步。
- [ ] 不在桌面端保存 CTMS 业务数据副本。
- [ ] 不内嵌 FastAPI、PostgreSQL、SQLite 或本地业务 API 镜像。
- [ ] 不绕过后端做本地权限裁决或本地审计回放。
+- [ ] 不实现离线登录、离线写入、离线队列或离线同步。
+- [ ] 不在 `/me` 校验通过前展示业务缓存。
+- [ ] 不把本地缓存作为 CTMS 业务权威数据或本地优先数据源。
+- [ ] 不内嵌 FastAPI、PostgreSQL 或本地业务 API 镜像。
+- [ ] 不绕过后端做本地权限裁决、本地审计判定或审计回放。

 ## 6. 2026-07-01 收尾验证记录

@@ -0,0 +1,180 @@
+# CTMS 桌面端本地缓存执行方案
+
+## 目标
+
+桌面端新增本地缓存的目标是降低重复网络请求、改善页面回访和 App 重启后的等待时间。当前项目不涉及受试者隐私问题，后端返回的 CTMS 业务 GET 数据均可进入本地缓存候选范围，但缓存仍只是服务端响应副本，不是业务权威数据。
+
+本方案不改变以下边界：
+
+- 登录、会话恢复和用户身份确认仍必须依赖后端 token 校验和 `/me`。
+- 新增、编辑、删除、审批、导入、导出、通知 ack、权限判断和审计判断仍必须以后端结果为准。
+- 不实现离线登录、离线写入队列、冲突解决、本地优先工作流、本地 API 镜像或内嵌后端服务。
+- token、登录密码、附件下载凭据、临时授权 URL、Authorization/Bearer 文本不得写入本地缓存、URL、日志或系统通知正文。
+
+## 缓存范围
+
+默认可缓存：
+
+- 字典、枚举、菜单、权限摘要、用户可见组织/中心、应用配置、系统元数据。
+- 项目、任务、机构、用户、角色、报表、监控页面等业务 GET 响应。
+- 页面查询结果、分页列表、详情页只读数据和图表数据。
+
+默认不缓存：
+
+- POST、PUT、PATCH、DELETE 等 mutation 请求响应，除非只用于立即失效相关 GET 缓存。
+- 文件下载二进制正文、一次性下载链接、带签名的临时 URL。
+- token、密码、验证码、MFA 信息、Authorization header、Cookie 原文。
+- 系统通知正文和可能包含临时凭据的 release notes 或错误日志。
+
+## 架构约束
+
+- 统一入口命名为 `desktopDataCache`，位于 `frontend/src/runtime/`，并通过 `clientRuntime` 暴露。
+- 业务模块不得直接调用 Tauri 存储 API、文件系统、SQLite、IndexedDB 或 Cache Storage 来实现桌面缓存。
+- Web 与 Desktop 共用业务代码，平台差异只在 runtime 适配层之后收敛。
+- Tauri command 只做窄职责存储读写、清理、容量统计或目录定位，不包含 CTMS 业务规则。
+- 如果引入新的 Tauri command、capability、CSP 或存储插件，必须同步评估 `frontend/scripts/verify-desktop-release.mjs`、`npm run runtime:check` 和桌面发布检查清单。
+
+## 缓存命名和数据模型
+
+缓存命名空间必须包含：
+
+- `serverOrigin`：规范化后的后端服务地址，不包含用户名、密码、token 或 query 凭据。
+- `userId`：后端 `/me` 确认后的用户标识。
+- `schemaVersion`：缓存结构版本，用于升级时整体失效。
+- `requestSignature`：请求方法、路径、排序后的 query、稳定序列化后的 body 摘要和必要的业务上下文。
+
+每条缓存记录至少包含：
+
+- `payload`：后端响应副本。
+- `status`：HTTP 状态码，仅缓存成功的可展示响应。
+- `headers`：只保存白名单响应头，例如 `ETag`、`Last-Modified`、`Cache-Control`、业务版本头。
+- `createdAt`、`updatedAt`、`expiresAt`、`lastAccessedAt`。
+- `sourceEndpoint` 和 `cacheTags`，用于诊断和精准失效。
+
+## 缓存策略
+
+第一优先级是请求减量：
+
+- 同一会话内相同 GET 请求合并为一个 in-flight promise。
+- 页面返回、tab 切换和重复组件挂载时优先命中短时内存缓存。
+- 页面可使用 stale-while-revalidate：先显示本地副本，再后台刷新，刷新失败时保留旧数据并显示可恢复错误。
+
+第二优先级是持久化缓存：
+
+- 仅在后端会话恢复和 `/me` 成功后启用业务缓存读取。
+- 默认缓存 GET 响应；mutation 成功后通过 tags 或 endpoint 规则失效相关 GET 缓存。
+- TTL 先按数据类型配置，缺省值建议 5 分钟；字典和元数据可延长到 24 小时；高频业务列表建议 1 到 5 分钟。
+- 设置总容量上限和 LRU 清理策略，避免缓存无限增长。
+
+第三优先级是 HTTP 条件请求：
+
+- 后端为稳定数据提供 `ETag` 或 `Last-Modified`。
+- 客户端对有验证器的缓存请求带 `If-None-Match` 或 `If-Modified-Since`。
+- 收到 304 时刷新缓存元数据，不重复下载 payload。
+
+## 失效和清理
+
+必须整体清理：
+
+- 用户登出。
+- 切换服务器。
+- 切换用户。
+- 后端返回 401 或 403。
+- `/me` 返回的用户标识、角色、权限版本或租户上下文变化。
+- `schemaVersion` 升级。
+
+必须精准失效：
+
+- mutation 成功后，清理相关详情、列表、统计和图表缓存。
+- 权限、角色、组织、项目状态变化后，清理依赖这些上下文的页面缓存。
+- 后端返回明确业务版本头或失效事件时，按 tags 清理。
+
+应提供用户入口：
+
+- 系统偏好或个人中心诊断信息展示缓存大小、记录数、最近清理时间。
+- 提供“清理本地缓存”按钮。
+- 清理提示只描述缓存状态，不包含具体业务内容。
+
+## 分阶段实施
+
+### 当前落地状态
+
+2026-07-08 已完成阶段 1 的首批实现：
+
+- 新增 `frontend/src/runtime/desktopDataCache.ts`，提供内存级缓存 scope、TTL、tag 失效、清理和统计能力，并通过 `clientRuntime.dataCache` 暴露。
+- `frontend/src/api/axios.ts` 已支持 GET 并发去重、显式 GET 内存缓存、mutation 成功后默认清理缓存、401/403 清理缓存、服务器切换清理缓存。
+- 缓存清理、scope 切换和 tag 失效会递增 generation；GET 响应返回时若 generation 已变化，不再写入缓存，避免旧用户、旧服务器或 mutation 前响应回填到新缓存空间。
+- `/api/v1/auth/login-key` 明确禁用 GET 去重，避免复用登录 challenge。
+- GET 去重和缓存 key 已包含 schema version、server baseURL、请求参数、非敏感请求头、responseType、paramsSerializer 和 withCredentials；包含敏感 header 或 axios auth 的请求不会进入去重或缓存。
+- 登录态已在 `/me` 成功后绑定缓存 scope，登出时清空 scope 和缓存。
+- 首批缓存接入范围包括项目列表/详情、项目配置、权限摘要、系统权限、权限模板、机构、成员、项目概览和仪表盘摘要。
+- `npm run runtime:check` 和 `npm run desktop:release:check` 已增加底层缓存 API 边界检查，业务模块不得直接调用 `indexedDB`、`caches.open`、`CacheStorage` 或 SQLite 入口。
+
+仍未完成：
+
+- 持久化缓存尚未落地，当前缓存只存在于本次前端运行内存中。
+- 后端 `ETag` / `Last-Modified` 和客户端 304 处理尚未落地。
+- 系统偏好或个人中心缓存诊断与手动清理入口尚未落地。
+- mutation 失效当前以默认全量清理为主，后续再按 tags 收敛为精准失效。
+
+### 阶段 0：请求观测和缓存清单
+
+- 梳理 `frontend/src/api/`、Pinia store 和高频页面的 GET 请求。
+- 标记每个接口的缓存 tags、TTL、mutation 失效关系和是否需要后端 ETag。
+- 记录启动、登录后首页、常用列表和详情页的请求数量作为基线。
+
+### 阶段 1：请求去重和内存缓存
+
+- 在 API 客户端层增加 GET 请求 in-flight 去重。
+- 增加短 TTL 内存缓存，先覆盖字典、菜单、权限摘要、组织/中心和常用列表。
+- 增加单元测试覆盖请求合并、TTL 过期、mutation 后失效。
+
+### 阶段 2：runtime 持久化缓存
+
+- 在 `frontend/src/runtime/desktopDataCache.ts` 定义平台无关接口。
+- Web 端提供内存或 IndexedDB 实现；Desktop 端通过 runtime 封装 IndexedDB、Cache Storage 或 Tauri app data 存储。
+- 增加命名空间、容量限制、LRU、schema version、手动清理和诊断 API。
+- 更新 `runtime:check` 和桌面发布检查，禁止业务页面直接使用底层缓存存储。
+
+### 阶段 3：页面接入
+
+- 先接入基础数据和全局布局依赖接口。
+- 再接入项目列表、任务列表、报表图表、详情页只读数据。
+- 为 mutation 建立集中失效规则，避免页面各自手写清理逻辑。
+
+### 阶段 4：后端条件请求
+
+- 为稳定 GET 接口补 `ETag` 或 `Last-Modified`。
+- 前端 API 客户端接入 304 处理。
+- 增加后端和前端测试，确认 304 不改变业务数据语义。
+
+### 阶段 5：诊断、验收和发布门禁
+
+- 在个人中心或系统偏好加入缓存诊断和清理入口。
+- 验证登出、切换服务器、切换用户、401/403、权限变化和版本升级清理行为。
+- 执行相关质量门禁，并把新增缓存边界纳入发布检查清单。
+
+## 验收标准
+
+- App 重启并完成 `/me` 校验后，已访问过的常用页面可以先展示缓存再后台刷新。
+- 同一路由重复进入、组件重复挂载、多个组件请求同一资源时，不产生重复并发请求。
+- 登出、切换服务器、切换用户、401/403 后不能读取旧命名空间缓存。
+- mutation 成功后相关列表、详情、统计和图表缓存被失效或刷新。
+- token、密码、Authorization/Bearer、下载凭据不会出现在缓存文件、IndexedDB、日志、URL 或通知正文中。
+- 业务模块不直接调用 Tauri API、IndexedDB、SQLite、Cache Storage 或文件系统实现缓存。
+
+## 质量门禁
+
+本地缓存相关实现至少执行：
+
+```bash
+cd frontend
+npm run runtime:check
+npm run desktop:release:check
+npm run ui:contract
+npm run type-check
+npm run test:unit
+npm run build
+```
+
+如果新增或修改后端条件请求、缓存头、权限版本或失效事件，还需执行对应后端测试。若新增 Tauri command、capability、CSP 或存储插件，还需执行 `npm run desktop:build:app` 并在真实 macOS `.app` 中验证缓存清理和诊断入口。
@@ -11,10 +11,10 @@
 - 技术路线固定为 Tauri。
 - 第一开发目标是 macOS 桌面端。
 - Windows 仍只作为第二阶段兼容性验证目标，未获明确批准前不发布正式安装包。
- 当前桌面端工作只允许在第一、二阶段边界内做修复、稳定化、体验收口和发布准备，不新增第三阶段能力。
- 不做离线功能。
+- 当前桌面端工作只允许在第一、二阶段边界内做修复、稳定化、体验收口、发布准备，以及本文档明确批准的在线辅助本地缓存；不新增独立第三阶段桌面产品线。
+- 不做离线登录、离线写入、离线同步或本地优先工作流；本地缓存只作为已认证在线客户端的体验加速能力。
 - 不在桌面 App 内嵌本地后端服务。
- 不在桌面 App 内嵌或分发本地数据库来保存 CTMS 业务数据。
+- 允许桌面端保存可清除的服务端响应缓存；缓存不是业务权威数据，不得替代后端持久化、权限裁决或审计判断。
 - 不实现离线同步、冲突解决、本地业务数据队列、本地优先工作流。
 - 不把 CTMS 业务 UI 拆成一套独立的桌面端产品；除非桌面能力确实需要小范围适配层。
 - FastAPI 后端仍是业务权威来源。权限裁决、审计判断、认证、业务数据持久化都保持在服务端。
@@ -38,15 +38,17 @@

 - 修复既有 Tauri、运行时适配层、文件、通知、凭据、更新、菜单/快捷键和打包问题。
 - 稳定 Web 与 Desktop 共用业务代码，确保平台差异继续收敛在 `frontend/src/runtime/` 后面。
+- 按 [`desktop-local-cache-plan.md`](desktop-local-cache-plan.md) 推进在线辅助本地缓存、请求去重、条件请求和缓存失效能力。
 - 完成 macOS 正式发布前的签名、公证、updater 签名、制品发布、CI 门禁和人工回归。
 - 做 Windows 第二阶段兼容性验证，但不发布正式 Windows 安装包。

 仍然不允许：

- 离线登录、离线浏览、离线队列、离线同步或本地优先工作流。
- 本地 PostgreSQL、SQLite、IndexedDB 业务数据缓存或本地 API 镜像。
+- 离线登录、离线写入、离线队列、离线同步或本地优先工作流。
+- 未完成后端会话恢复、token 校验和 `/me` 身份确认前展示业务缓存。
+- 本地 PostgreSQL、本地 API 镜像、内嵌业务后端，或把 SQLite/IndexedDB/Cache Storage/Tauri app data 目录作为业务数据库使用。
 - 内嵌 Python/FastAPI 后端服务。
- 绕过后端做本地权限裁决、本地审计缓存或审计回放。
+- 绕过后端做本地权限裁决、本地审计判定、审计回放或写入补偿。
 - 为桌面端复制或重写一套独立业务 UI。

 ## 架构方向
@@ -66,6 +68,7 @@
 - `updates`：隔离桌面自动更新检查与安装入口。
 - `appMetadata`：在可用时提供桌面 App 版本、平台、构建通道。
 - `desktopMenu` 和 `desktopUiPreferences`：承接桌面菜单命令、收藏模块等桌面体验状态。
+- `desktopDataCache`：承接桌面端在线辅助本地缓存、缓存命名空间、失效、清理和诊断；业务模块不得直接使用 Tauri 存储 API、IndexedDB、SQLite 或文件系统实现桌面缓存。
 - `clientRuntime`：作为业务侧获取平台能力的聚合入口。

 业务模块应调用这些适配层，而不是直接调用 Tauri API。Tauri command 应保持窄职责，不包含 CTMS 业务规则。
@@ -77,6 +80,9 @@
 - 认证与授权决策保留在后端。
 - 审计敏感决策保留在后端。
 - 敏感凭据必须继续使用明确批准的安全存储方案；网页端密码只能交给浏览器凭据管理能力，桌面端密码只能交给系统凭据库。
+- token、登录密码、附件下载凭据和临时授权信息不得进入本地业务缓存、URL、日志或系统通知正文。
+- 本地业务缓存必须按 `server origin + user id + cache schema version` 隔离；登出、切换服务器、切换用户、后端返回 401/403、权限版本变化或缓存结构升级时必须清理或失效。
+- 本地缓存命中只能用于展示后端曾返回的数据副本；新增、编辑、删除、审批、权限判断和审计判断仍必须请求后端并以后端结果为准。
 - 不向前端暴露宽泛文件系统访问权限。
 - Tauri 权限保持最小化，并按功能精确授权。
 - 每个新增 Tauri command 都需要被视为桌面端安全边界的一部分进行审查。
@@ -173,7 +179,24 @@
 - macOS `.app` 在 `1180x760` 下的登录页、服务器设置、个人中心、系统偏好和更新弹窗实际布局。
 - 系统通知权限拒绝后的开关状态、权限提示和错误提示是否与 OS 状态一致。

-如果后续任务试图新增离线登录、本地业务数据存储、内嵌后端、本地业务队列、离线同步或绕过后端权限审计，应先修改并评审本计划书，不能直接实现。
+## 2026-07-08 本地缓存边界调整与执行方案
+
+经当前项目边界复核，桌面端允许新增在线辅助本地缓存，用于减少重复请求、缩短页面回访和 App 重启后的数据展示等待时间。该能力不改变 CTMS 的业务权威边界：FastAPI 后端仍是认证、授权、审计和业务持久化的唯一权威来源。
+
+执行方案以 [`desktop-local-cache-plan.md`](desktop-local-cache-plan.md) 为准，实施顺序为：
+
+1. 建立请求观测和缓存清单，确认高频 GET 接口、页面冷启动接口、基础数据接口和 mutation 后需要失效的资源。
+2. 先实现请求去重、短时内存缓存和页面级 stale-while-revalidate，减少同一会话内重复拉取。
+3. 在 `frontend/src/runtime/` 增加 `desktopDataCache` 适配层，统一提供缓存读写、命名空间、TTL、容量上限、失效、清理和诊断能力。
+4. 增加持久化缓存，默认只缓存后端 GET 响应和明确标记可缓存的数据；缓存 key 必须包含 server origin、user id、请求签名和 cache schema version。
+5. 推进后端 HTTP 条件请求支持，优先为字典、菜单、权限摘要、组织/中心、项目摘要等稳定数据提供 `ETag` 或 `Last-Modified`，客户端使用 `If-None-Match` 或 `If-Modified-Since` 降低 304 场景的数据传输。
+6. 建立统一失效机制：登出、切换服务器、切换用户、401/403、权限版本变化、mutation 成功、应用版本或 cache schema 变化时清理或精准失效。
+7. 在系统偏好或诊断信息中提供缓存状态和手动清理入口，清理文案不得包含业务详情。
+8. 补充单元测试、运行时边界检查和桌面发布检查，确保 token、密码、下载凭据不会写入缓存，业务模块不会绕过 `frontend/src/runtime/` 使用 Tauri 或底层存储 API。
+
+仍禁止把缓存扩展为离线产品能力：不得实现离线登录、离线写入队列、冲突解决、本地审批、本地权限裁决、本地审计回放或本地 API 镜像。服务端不可达时，桌面端不得把缓存解释为已完成身份认证；是否展示已过期缓存必须以后续明确的产品验收口径为准，默认只在在线身份校验通过后使用缓存。
+
+如果后续任务试图新增离线登录、离线写入、本地业务队列、离线同步、内嵌后端、本地 API 镜像或绕过后端权限审计，应先修改并评审本计划书，不能直接实现。

 ## 当前质量门禁

@@ -199,10 +222,10 @@ npm run desktop:build:app

 - 先阅读本文档。
 - 确认任务属于第一阶段或第二阶段。
- 确认任务不会引入离线能力。
+- 确认任务不会引入未批准的离线能力；本地缓存任务必须符合 2026-07-08 缓存边界和 `desktop-local-cache-plan.md`。
 - 确认实现不会破坏 Web 运行时。
 - 确认 Tauri API 使用被隔离在适配层之后，除非有明确记录的理由。
 - 确认不会重复初始化 Tauri 或绕过既有 `frontend/src/runtime/` 运行时边界。
- 涉及 Tauri 权限、CSP、updater、凭据、文件或通知能力时，确认桌面发布检查脚本和发布清单是否需要同步更新。
+- 涉及本地缓存、Tauri 权限、CSP、updater、凭据、文件或通知能力时，确认桌面发布检查脚本和发布清单是否需要同步更新。

 如果用户请求与本文档冲突，先停止实现并确认范围，不要直接推进。