lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
0b05e08705805f40adb4b33a958936ac6d3d41e2
nex/openspec/specs/desktop-app/spec.md
lanyuanxiaoyao 0b05e08705 feat: 新增桌面应用支持 
- 新增 desktop 应用入口，将后端与前端打包为单一可执行文件
- 集成系统托盘功能（getlantern/systray）
- 支持单实例锁和端口冲突检测
- 启动时自动打开浏览器显示管理界面
- 新增 embedfs 模块嵌入静态资源
- 新增跨平台构建脚本（macOS/Windows/Linux）
- 新增 macOS .app 打包脚本
- 统一 Makefile，移除 backend/Makefile
- 更新 README 添加桌面应用使用说明
2026-04-22 19:27:27 +08:00

3.9 KiB
Raw Blame History

桌面应用

Purpose

TBD - 提供跨平台桌面应用支持，将后端服务与前端静态资源打包为单一可执行文件

Requirements

Requirement: 桌面应用启动

系统 SHALL 支持作为桌面应用启动，将后端服务与前端静态资源打包为单一可执行文件。

Scenario: 双击启动

  • WHEN 用户双击桌面应用可执行文件
  • THEN 系统启动后端服务
  • AND 系统托盘图标出现
  • AND 浏览器自动打开 http://localhost:9826 显示管理界面

Scenario: 单实例检查

  • WHEN 用户尝试启动第二个实例
  • THEN 系统检测到已有实例运行
  • AND 显示错误提示"已有 Nex 实例运行"
  • AND 新实例退出

Requirement: 系统托盘

系统 SHALL 提供跨平台系统托盘功能，支持托盘图标和菜单。

Scenario: 托盘图标显示

  • WHEN 桌面应用启动成功
  • THEN 系统托盘区域显示应用图标
  • AND 托盘图标 tooltip 显示"AI Gateway"

Scenario: 托盘菜单显示

  • WHEN 用户点击托盘图标（左键或右键）
  • THEN 显示托盘菜单
  • AND 菜单包含"打开管理界面"选项
  • AND 菜单包含"状态: 运行中"选项（禁用状态）
  • AND 菜单包含"端口: 9826"选项（禁用状态）
  • AND 菜单包含"关于"选项
  • AND 菜单包含"退出"选项

Scenario: 打开管理界面

  • WHEN 用户点击托盘菜单"打开管理界面"
  • THEN 系统在浏览器中打开 http://localhost:9826

Scenario: 浏览器打开失败

  • WHEN 系统无法打开浏览器（浏览器未安装等）
  • THEN 托盘菜单仍可正常使用
  • AND 用户可手动访问 http://localhost:9826

Scenario: 退出应用

  • WHEN 用户点击托盘菜单"退出"
  • THEN 系统优雅关闭后端服务
  • AND 托盘图标消失
  • AND 应用进程退出

Requirement: 静态文件服务

系统 SHALL 通过 Gin 同时服务 API 和前端静态资源。

Scenario: API 请求路由

  • WHEN 请求路径以 /api/ 或 /v1/ 开头
  • THEN 请求由现有业务 handler 处理

Scenario: 静态资源路由

  • WHEN 请求路径为 /assets/*
  • THEN 返回嵌入的前端静态资源文件

Scenario: SPA 路由回退

  • WHEN 请求路径不匹配任何 API 或静态资源路由
  • THEN 返回 index.html（支持前端 SPA 路由）

Requirement: 端口冲突检测

系统 SHALL 在启动前检测端口是否可用。

Scenario: 端口可用

  • WHEN 端口 9826 未被占用
  • THEN 服务正常启动

Scenario: 端口被占用

  • WHEN 端口 9826 已被其他程序占用
  • THEN 显示错误提示"端口 9826 已被占用"
  • AND 应用退出

Requirement: 跨平台构建

系统 SHALL 支持跨平台构建和打包。

Scenario: macOS 构建

  • WHEN 执行 macOS 构建命令
  • THEN 生成 nex-darwin-arm64 和 nex-darwin-amd64 可执行文件
  • AND 可打包为 .app bundle

Scenario: Windows 构建

  • WHEN 执行 Windows 构建命令
  • THEN 生成 nex-windows-amd64.exe 可执行文件
  • AND 运行时不显示控制台窗口

Scenario: Linux 构建

  • WHEN 执行 Linux 构建命令
  • THEN 生成 nex-linux-amd64 可执行文件

Requirement: macOS .app 打包

系统 SHALL 支持打包为 macOS .app bundle。

Scenario: .app 结构

  • WHEN 执行打包脚本
  • THEN 生成 Nex.app 目录结构
  • AND 包含 Contents/Info.plist 元数据
  • AND 包含 Contents/MacOS/nex 可执行文件
  • AND 包含 Contents/Resources/AppIcon.icns 图标
  • AND Info.plist 中 LSUIElement 为 true（不显示 Dock 图标）

Requirement: 关于对话框

系统 SHALL 提供关于对话框显示应用信息。

Scenario: 显示关于

  • WHEN 用户点击托盘菜单"关于"
  • THEN 显示对话框包含应用名称、项目链接
View Git Blame Copy Permalink