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

docs/desktop-project-plan.md

@@ -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、凭据、文件或通知能力时，确认桌面发布检查脚本和发布清单是否需要同步更新。
 
 如果用户请求与本文档冲突，先停止实现并确认范围，不要直接推进。