# 船长·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 个人版 Stable
npm run build:win:enterprise     # Windows 企业版
npm run build:win:beta           # Windows Beta 渠道（灰度测试）
npm run build:win:alpha          # Windows Alpha 渠道（内部测试）
npm run build:mac                # macOS 个人版
npm run build:linux              # Linux 个人版
```

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

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

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

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

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

# Beta 渠道全流程（清理 → 构建 → 签名 → 上传 → 发布）
node build/build.mjs --win --channel beta --all

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

| 操作          | 说明                                                         |
|-------------|------------------------------------------------------------|
| `--build`   | 构建（校验 → tsc → vite → electron-builder → update-info.json） |
| `--clean`   | 构建前清理 release/ dist/ dist-electron/                       |
| `--sign`    | 代码签名（需配合 `--cert` 或 `CSC_LINK` 环境变量）                      |
| `--upload`  | 上传安装包到 OSS                                                 |
| `--publish` | POST 版本信息到后端 API                                           |
| `--all`     | 全流程                                                        |
| `--edition` | 版本类型：personal（默认）/ enterprise                             |
| `--channel` | 发布渠道：stable（默认）/ beta / alpha                             |

### 版本管理

```bash
npm run version:patch            # 0.0.28 → 0.0.29
npm run version:pre-beta         # 0.0.29 → 0.0.30-beta.1
```

### 工具命令

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

---

## 目录结构

```
ele-heixiu/
├── build/                             # 构建、打包与分发系统
│   ├── build.mjs                      # 构建总管
│   ├── electron-builder.js            # electron-builder 配置
│   └── scripts/                       # 构建辅助脚本（6 个）
├── CHANGELOG.md                     # 更新日志
├── UpdateA.md                       # 发布手册
├── package.json                     # 项目配置
│
├── electron/                        # Electron 主进程
│   ├── main.ts                      # 入口：窗口创建 / IPC 注册
│   ├── preload.ts                   # 预加载脚本
│   └── main/
│       ├── logger.ts                # 日志核心
│       ├── updater.ts               # 自动更新
│       ├── net-request.ts           # HTTP 请求封装
│       ├── menu/                    # 系统菜单
│       ├── ipc/                     # IPC handler（log/safe-storage/storage/canvas）
│       └── utils/                   # 平台判断 / 图标
│
├── src/                             # 渲染进程（React 19 + Vite）
│   ├── app/                         # 应用壳
│   │   ├── App.tsx                  # 根组件
│   │   ├── main.tsx                 # 渲染入口
│   │   ├── providers/               # 全局 Provider（App/Theme/Settings）
│   │   └── layout/                  # Layout.tsx + PageDispatcher.tsx
│   ├── modules/                     # 7 个业务模块（VCHSM 五层架构）
│   │   ├── navbar/                  # 导航栏 UI 壳
│   │   ├── announcement/            # 公告（Badge + 轮询缓存）
│   │   ├── auth/                    # 认证（登录/注册/密码/Token）
│   │   ├── home/                    # 主工作区（左/中/右 三栏）
│   │   ├── account/                 # 账户与支付（6 子功能）
│   │   ├── canvas/                  # 无限画布 + 项目管理
│   │   └── settings/                # 应用设置
│   └── shared/                      # 跨模块共享
│       ├── components/              # 通用 UI
│       ├── hooks/                   # 全局 Hooks
│       ├── services/                # HTTP 客户端
│       ├── utils/                   # 工具函数（bus/env/...）
│       ├── infrastructure/          # 本地加密数据库
│       └── theme/                   # 主题系统
│
├── shared/                          # 主进程 & 渲染进程共享（@shared 别名）
│   ├── constants/                   # IPC 通道 / 应用常量
│   ├── types/                       # Platform / Theme / Logging
│   └── utils/                       # 脱敏 / 工具函数
│
├── release/                         # 构建产物
└── build/                           # 构建系统（见上）
```

> 详见 [PROJECT.md](./PROJECT.md) — 完整架构文档、VCHSM 五层说明及各模块文件清单。

---

## 环境变量

主进程加载顺序：`.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 规格、数据库表结构、实现清单    |