ctms/docs/desktop-project-plan.md

CTMS 桌面端项目计划书

目的

本文档是 CTMS 桌面端工作的长期方向约束。每次开始任何桌面端相关任务前，都必须先阅读本文档，包括 Tauri 初始化、macOS 打包、Windows 适配、桌面端存储、文件集成、系统通知、安全边界和发布流程。

桌面端必须服务于现有 CTMS Web 应用和后端架构。目标是为当前 CTMS 服务提供原生桌面入口，而不是创建一个独立的离线产品。

不可突破的边界

• 技术路线固定为 Tauri。
• 第一开发目标是 macOS 桌面端。
• Windows 需要作为长期适配约束保留，但不是第一阶段交付目标。
• 当前只做第一阶段和第二阶段。
• 不做离线功能。
• 不在桌面 App 内嵌本地后端服务。
• 不在桌面 App 内嵌或分发本地数据库来保存 CTMS 业务数据。
• 不实现离线同步、冲突解决、本地业务数据队列、本地优先工作流。
• 不把 CTMS 业务 UI 拆成一套独立的桌面端产品；除非桌面能力确实需要小范围适配层。
• FastAPI 后端仍是业务权威来源。权限裁决、审计判断、认证、业务数据持久化都保持在服务端。

当前技术基线

桌面端工作基于当前 CTMS Web 技术栈：

• 前端：Vue 3、Vite、TypeScript、Element Plus、Pinia、Vue Router、Axios、ECharts。
• 后端：FastAPI、Uvicorn、SQLAlchemy、Alembic。
• 数据库：PostgreSQL。
• 当前部署：Docker Compose、nginx 托管前端静态资源、nginx 反代 /api。

桌面端应复用现有前端代码和 API 契约。任何共享适配层都应保持小而明确，并可测试。

第一阶段：macOS 在线桌面客户端

第一阶段交付一个面向现有 CTMS 服务的 macOS 桌面壳。

详细方案见 desktop-phase-1-design.md。

范围：

• 在现有前端工程中加入 Tauri 项目结构。
• 将当前 Vue/Vite 应用运行在 Tauri 桌面窗口中。
• 连接已有 CTMS 后端，支持 HTTP/HTTPS。
• 为桌面端提供可配置的服务端地址处理。
• 保持当前登录、角色权限、项目上下文和审计行为。
• 所有业务数据读写仍发生在服务端。
• 产出 macOS 开发构建，并明确后续签名、公证、正式发布路径。

不做：

• 离线登录。
• 离线浏览项目。
• 本地 PostgreSQL、SQLite、IndexedDB 业务数据持久化或本地 API 镜像。
• 桌面端重写 CTMS 页面。
• Windows 安装包交付。
• 自动更新实现，除非被明确提升到第二阶段任务。

退出标准：

• macOS App 可以启动 CTMS UI。
• macOS App 可以连接指定 CTMS 后端。
• 登录和常规在线流程与 Web 端行为一致。
• Web 构建仍可用，不被 Tauri API 强耦合。
• 桌面端运行时边界已文档化。

第二阶段：桌面端能力增强

第二阶段在不改变在线优先产品边界的前提下，增加原生桌面能力。

范围：

• 在附件等场景中引入原生文件选择、下载、打开能力。
• 基于服务端在线数据提供系统通知能力。
• 使用 Tauri 兼容方式实现安全的桌面端 token/session 存储。
• 单实例启动行为。
• 在支持、审计或排障需要时暴露桌面 App 版本、平台、客户端类型等元数据。
• 为签名后的桌面版本设计并实现自动更新。
• 为 Windows 适配做准备，包括路径处理、安装器假设、CI 打包设计。

不做：

• 离线队列。
• 业务数据后台同步。
• 用于离线使用的本地业务数据缓存。
• 绕过后端的本地权限裁决。
• 本地审计日志缓存后再回放。

退出标准：

• 桌面专属能力隔离在适配层之后。
• Web 运行时不依赖桌面 API，仍可正常工作。
• 桌面端 session 存储和文件操作有清晰安全边界。
• macOS 打包路径可重复执行。
• Windows 打包要求在实现前已经文档化。

架构方向

使用运行时适配层，不在业务页面里散落平台判断。

建议的适配层边界：

• platform：识别 Web、macOS 桌面端、Windows 桌面端。
• apiBaseUrl：分别解析 Web 和桌面端的服务端 API 地址。
• storage：隔离浏览器存储与桌面安全存储。
• files：隔离浏览器上传下载与原生文件能力。
• notifications：隔离 Web 通知与桌面系统通知。
• appMetadata：在可用时提供桌面 App 版本、平台、构建通道。

业务模块应调用这些适配层，而不是直接调用 Tauri API。Tauri command 应保持窄职责，不包含 CTMS 业务规则。

安全与合规方向

• 将桌面端视为受监管业务系统的在线客户端。
• 非本地服务连接优先使用 HTTPS。
• 认证与授权决策保留在后端。
• 审计敏感决策保留在后端。
• 第二阶段开始处理敏感凭据时，必须使用明确批准的安全存储方案。
• 不向前端暴露宽泛文件系统访问权限。
• Tauri 权限保持最小化，并按功能精确授权。
• 每个新增 Tauri command 都需要被视为桌面端安全边界的一部分进行审查。

分支与工作区

桌面端工作在以下位置开发：

• Worktree：/Users/zcc/MyCTMS/ctms-dev/worktrees/ctms-desktop
• 分支：codex/ctms-desktop

除非发布计划另有说明，桌面端分支应持续与 dev 对齐。

每次开发前必须执行的检查

开始任何桌面端相关任务前：

• 先阅读本文档。
• 确认任务属于第一阶段或第二阶段。
• 确认任务不会引入离线能力。
• 确认实现不会破坏 Web 运行时。
• 确认 Tauri API 使用被隔离在适配层之后，除非有明确记录的理由。

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