# @vben/desktop — 萧康云医 PC 桌面端

Electron 壳工程：打包加载 `apps/web-antd` 的生产构建产物，提供桌面通知、开机自启、系统托盘、未读角标、静默打印、全局快捷键与自动更新能力。

## 常用命令（在仓库根目录执行）

```bash
# 开发：并行启动 web-antd dev server（:5666）与 Electron 壳（壳会自动等待/重试连接 dev server）
pnpm dev:desktop

# 打包：turbo 先构建 web-antd dist，再构建主进程并出安装包（产物在 apps/desktop/release/）
pnpm build:desktop

# 一键同时打 Web + 桌面（根目录 build-antd-desktop.mjs，先 web 再桌面）
pnpm build:antd-desktop
```

- Windows 机器出 NSIS 安装包；mac 包必须在 macOS 机器上执行同一命令（electron-builder 不支持交叉编译 mac 包）。
- 不需要打桌面包的同事 / CI，可设置环境变量 `ELECTRON_SKIP_BINARY_DOWNLOAD=1` 跳过 Electron 二进制下载，不影响 web 开发。

## 环境切换（dev 走本地，打包走生产）

| 模式 | 页面来源 | API 走向 |
|---|---|---|
| `pnpm dev:desktop` | `http://localhost:5666`（web-antd vite dev server） | vite 代理转发到**本地后端**：`/api/*` → `localhost:18001`、`/im-api/*` → `localhost:12080`（见 `apps/web-antd/vite.config.ts`） |
| 打包后的安装包 | `app://local/`（内置 web-antd 生产 dist） | 主进程协议处理器转发到**生产上游**：`/api/admin/*` → `api.xiaokang88.com`、`/im-api/*` → `api.ws.g.xiaokang88.com/api`（见 `src/main/config.ts`，可用环境变量覆盖） |

即：开发调试自动对接本地后端（与网页开发完全一致），只有 `pnpm build:desktop` 出的安装包才请求生产环境，无需手动切换。

## 环境变量

| 变量 | 用途 |
|---|---|
| `XK_DESKTOP_API_UPSTREAM` | 覆盖 `/api/admin` 转发上游（联调测试环境用） |
| `XK_DESKTOP_IM_UPSTREAM` | 覆盖 `/im-api` 转发上游 |
| `XK_DESKTOP_DEV_URL` | 覆盖开发模式加载的 dev server 地址（默认 `http://localhost:5666`） |
| `XK_DESKTOP_OPEN_API_VERSION_URL` | 覆盖桌面版本 OpenAPI 完整 URL（默认 `{API_UPSTREAM}/open-api/desktop/version/latest`） |
| `XK_DESKTOP_VERSION` | 打包时跳过交互，强制写入该 semver（CI 用；也可用 `--version=1.0.1`） |
| `CSC_LINK` / `CSC_KEY_PASSWORD` | 代码签名证书；**未配置时自动跳过签名，出未签名包，构建不报错** |
| `APPLE_ID` / `APPLE_APP_SPECIFIC_PASSWORD` / `APPLE_TEAM_ID` | mac 公证三件套；三者齐全才启用公证 |

未签名 mac 包可内部分发：首次打开需右键「打开」，且 mac 自动更新不可用（应用内会降级为提示前往下载页手动安装）。

## 打包与版本确认

`pnpm -F @vben/desktop run pack`（以及根目录 `build:desktop` / `build:antd-desktop`）会先交互确认版本：

```
上次打包版本号：1.0.0
  1) 使用上次版本号（1.0.0）
  2) 输入新的版本号
```

确认后写入 `apps/desktop/package.json` 的 `version`，再执行 electron-builder。

产物目录 `apps/desktop/release/`：

| 文件 | 用途 |
|---|---|
| `xk-desktop-{version}-win-x64.exe` | 自动更新 / latest.yml 引用（ASCII） |
| `萧康医药 {version}.exe` | 人工或后台上传用友好文件名（由 pack 脚本复制生成） |

## 发布自动更新

`release/` 里的以下产物上传到静态托管地址（`electron-builder.config.cjs` 的 `publish.url`）：

- Windows：`latest.yml` + `xk-desktop-*.exe` + `*.blockmap`（自动更新）；另可将 `萧康医药 {version}.exe` 作对外下载名
- mac：`latest-mac.yml` + `*.dmg` + `*.zip` + `*.blockmap`（zip 是 mac 自动更新必需格式）

前端每次发版后跟着跑一次 `pnpm build:desktop` 并上传产物，再在后台「系统管理 → 桌面端更新」登记并发布。

桌面端行为：启动约 10 秒后检查一次，之后每 **3 小时**轮询；发现新版本后台下载，完成后提示重启安装（后台勾选「强制更新」则下载完直接重启）。检查前会请求 OpenAPI 元数据以覆盖 feed / 强制标记。

Windows 桌面端使用自绘顶栏（与系统窗口按钮同一行）：左上角「萧康云医」菜单含刷新 / 检查更新 / 关于。