# 船长·HeiXiu

> 桌面效率工作台 — Electron + React 19 + TypeScript + Ant Design + Tailwind CSS

---

## 技术栈

| 层   | 技术                           |
| ---- | ------------------------------ |
| 框架 | Electron 42                    |
| 前端 | React 19 + TypeScript + Vite 8 |
| UI   | Ant Design 6 + Tailwind CSS 4  |
| 主题 | 蓝紫渐变（亮色 / 暗色）        |
| 更新 | 自定义 API + 阿里云 OSS        |
| 打包 | electron-builder + NSIS        |

---

## 快速开始

```bash
# 安装依赖
npm install

# 开发模式（Electron + HMR）
npm run dev

# 打包（Windows 个人版）
npm run build:win
```

---

## 构建命令

### 打包

```bash
npm run build:win                # Windows 个人版
npm run build:win:enterprise     # Windows 企业版
npm run build:mac                # macOS 个人版
npm run build:linux              # Linux 个人版
```

### 构建总管 `build.mjs`

所有打包命令最终调用 `build.mjs`，支持灵活组合操作：

```bash
# 查看帮助
node build.mjs --help

# 仅打包
node build.mjs --win --personal

# 打包 + 上传 OSS + 发布到 API
node build.mjs --win --personal --upload --publish

# 全流程（清理 → 构建 → 签名 → 上传 → 发布）
node build.mjs --win --enterprise --all

# 带签名打包
node build.mjs --win --personal --sign --cert ./cert.pfx --cert-password xxx

# 先清理再构建
node build.mjs --win --personal --clean --build
```

| 操作        | 说明                                                           |
| ----------- | -------------------------------------------------------------- |
| `--build`   | 构建（默认：tsc + vite + electron-builder + update-info.json） |
| `--clean`   | 构建前清理 release/ dist/ dist-electron/                       |
| `--sign`    | 代码签名（需配合 `--cert` 或 `CSC_LINK` 环境变量）             |
| `--upload`  | 上传安装包到 OSS                                               |
| `--publish` | POST 版本信息到后端 API                                        |
| `--all`     | 全流程                                                         |

### 工具命令

```bash
npm run build:clean               # 清理所有构建产物
node scripts/upload-oss.mjs win32 personal 0.1.0     # 手动上传 OSS
node scripts/publish-release.mjs win32 personal 0.1.0 # 手动发布到 API
node scripts/generate-update-info.mjs win32 personal 0.1.0  # 重新生成 info
```

---

## 目录结构

```
ele-heixiu/
├ build.mjs                  # 构建总管
├ CHANGELOG.md               # 更新日志
├ UpdateA.md                 # 发布手册（后端 API / 签名 / 发版流程）
├ package.json               # 项目配置
├ electron-builder.json5     # 打包配置
├ electron/                  # Electron 主进程
│  ├ main.ts                 # 入口
│  ├ preload.ts              # 预加载脚本
│  └ main/
│     ├ updater.ts           # 自动更新模块
│     ├ menu/                # 菜单
│     └ utils/               # 工具函数
├ src/                       # 渲染进程
│  ├ App.tsx                 # 根组件
│  ├ main.tsx                # 渲染入口
│  ├ components/             # 组件
│  │  ├ navbar/              # 自定义导航栏
│  │  └ LegalTextModal.tsx   # 协议弹窗
│  ├ pages/
│  │  └ login/               # 登录 / 注册
│  ├ hooks/                  # Hooks
│  │  ├ use-theme.tsx        # 主题切换
│  │  ├ use-updater.ts       # 更新状态
│  │  └ ...
│  ├ theme/                  # 主题配置
│  │  ├ tokens.ts            # 设计令牌
│  │  ├ globals.css          # Tailwind + CSS 变量
│  │  └ adapters/            # Ant Design 适配
│  ├ services/               # API 服务（axios）
│  ├ utils/                  # 工具函数
│  └ assets/                 # 静态资源
├ shared/                    # 主进程 & 渲染进程共享
│  ├ types/                  # 类型定义
│  ├ constants/              # 常量
│  └ utils/                  # 通用工具
├ scripts/                   # 构建辅助脚本
│  ├ clean.mjs               # 清理产物
│  ├ generate-update-info.mjs # 生成 API 信息 JSON
│  ├ upload-oss.mjs          # OSS 上传
│  └ publish-release.mjs     # 发布到 API
└ release/                   # 构建产物
   └ {version}/
      ├ xxx-Setup.exe
      └ xxx-update-info.json
```

---

## 环境变量

主进程加载顺序：`.env.{mode}` → `.env.local` → OS 环境变量 → 代码默认值。

| 变量                    | 默认值                                                 | 用途            |
| ----------------------- | ------------------------------------------------------ | --------------- |
| `UPDATE_API_URL`        | `https://www.heixiu.com`                               | 版本检查 API    |
| `UPDATE_API_KEY`        | —                                                      | 发布 API 鉴权   |
| `UPDATE_DOWNLOAD_BASE`  | `https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases` | OSS 下载基地址  |
| `OSS_ENDPOINT`          | —                                                      | OSS endpoint    |
| `OSS_BUCKET`            | —                                                      | OSS bucket      |
| `OSS_ACCESS_KEY_ID`     | —                                                      | OSS AccessKey   |
| `OSS_ACCESS_KEY_SECRET` | —                                                      | OSS Secret      |
| `CSC_LINK`              | —                                                      | 签名证书路径    |
| `CSC_KEY_PASSWORD`      | —                                                      | 签名证书密码    |
| `VITE_API_BASE_URL`     | `http://8.160.179.64:8000`（dev）                      | 业务 API 基地址 |

> **`.env.local`**（不进 git）用于个人特殊配置，如打包后覆盖 `UPDATE_API_URL` 指向本地测试服务器。

---

## 相关文档

| 文档 | 面向 | 内容 |
|------|------|------|
| [PROJECT.md](./PROJECT.md) | 开发者 | 技术架构、更新系统、环境变量架构、测试流程 |
| [UpdateA.md](./UpdateA.md) | 前端发版 | 构建命令、发版流程、代码签名 |
| [test-server/README.md](./test-server/README.md) | 后端程序员 | API 规格、数据库表结构、实现清单 |