Cheng Zhou
140 lines
5.6 KiB
Markdown
140 lines
5.6 KiB
Markdown
# 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 使用被隔离在适配层之后，除非有明确记录的理由。
|
||
|
||
如果用户请求与本文档冲突，先停止实现并确认范围，不要直接推进。
|