# 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` 中验证缓存清理和诊断入口。