docs: add desktop project plan

docs/desktop-project-plan.md

@@ -0,0 +1,139 @@
+# 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 桌面壳。
+
+范围：
+
+- 在现有前端工程中加入 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 使用被隔离在适配层之后，除非有明确记录的理由。
+
+如果用户请求与本文档冲突，先停止实现并确认范围，不要直接推进。