# 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`](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 强耦合。 - 桌面端运行时边界已文档化。 ## 第二阶段：桌面端能力增强 第二阶段在不改变在线优先产品边界的前提下，增加原生桌面能力。 详细方案见 [`desktop-phase-2-design.md`](desktop-phase-2-design.md)。 范围： - 在附件等场景中引入原生文件选择、下载、打开能力。 - 基于服务端在线数据提供系统通知能力。 - 使用 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/<任务名称>`，必须从最新 `dev` 创建 `codex/ctms-desktop` 仅是第一阶段 Tauri 基线临时集成分支。基线合入 `dev` 后，第二阶段工作不得继续把它作为长期桌面主线。 ## 每次开发前必须执行的检查 开始任何桌面端相关任务前： - 先阅读本文档。 - 确认任务属于第一阶段或第二阶段。 - 确认任务不会引入离线能力。 - 确认实现不会破坏 Web 运行时。 - 确认 Tauri API 使用被隔离在适配层之后，除非有明确记录的理由。 如果用户请求与本文档冲突，先停止实现并确认范围，不要直接推进。