Yang-RuiQi/ele-HeiXiu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 构建系统重构 + VCHSM 架构迁移 + 右键菜单修复 + 尺寸参数统一

Browse Source 
## 构建、打包与分发系统重构 (build/)

- 构建系统收敛至 build/ 目录：build.mjs + electron-builder.js + 6 个脚本

- electron-builder 配置从 package.json 提取为 build/electron-builder.js

- 新增 --edition (personal/enterprise) 和 --channel (stable/beta/alpha) 参数

- OSS 路径按渠道隔离

- 新增 pre-build-check.mjs：Git/CHANGELOG/版本/环境变量校验

- 新增 bump-version.mjs：版本号管理 + CHANGELOG 自动生成

- updater.ts 发送 channel/edition/deviceFingerprint

- 新增 src/shared/utils/rollout.ts 灰度测试工具

- 新增 10 条 NPM 脚本

## VCHSM 五层架构迁移

- 7 个业务模块 + ~500 处导入路径同步

## 修复

- MediaCardContextMenu 改用共享 ContextMenu 组件

- ComboBox 尺寸参数显示统一 (size-format.ts)

## 文档

- UpdateA.md / build/README.md / README.md / .env.example 更新

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
YoungestSongMo
2026-06-29 18:41:07 +08:00
parent e0d91335c7
commit 337d6c1205
187 changed files with 5252 additions and 1702 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
UpdateA.md
View File

@@ -38,63 +38,107 @@
## 二、项目脚本速查
### 总入口：`build.mjs`
### 总入口：`build/build.mjs`
```bash
node build.mjs --help # 查看完整帮助
npm run build:win # 打包 Windows 个人版（快捷命令）
node build/build.mjs --help # 查看完整帮助
npm run build:win # 打包 Windows 个人版 Stable（快捷命令）
```
### npm 命令速查
```bash
# 构建（仅打包，不上传/发布）
npm run build:win # Windows 个人版
npm run build:win:enterprise # Windows 企业版
npm run build:mac # macOS 个人版
npm run build:linux # Linux 个人版
npm run build:win # Windows 个人版 Stable
npm run build:win:enterprise # Windows 企业版 Stable
npm run build:win:beta # Windows 个人版 Beta 渠道
npm run build:win:alpha # Windows 个人版 Alpha 渠道
npm run build:mac # macOS 个人版
npm run build:mac:enterprise # macOS 企业版
npm run build:linux # Linux 个人版
npm run build:linux:enterprise # Linux 企业版
# 版本管理
npm run version:patch # 0.0.28 → 0.0.29
npm run version:minor # 0.0.28 → 0.1.0
npm run version:pre-beta # 0.0.29 → 0.0.30-beta.1
npm run version:pre-alpha # 0.0.29 → 0.0.30-alpha.1
# 工具
npm run build:clean # 清理 release/ + dist/ + dist-electron/
node build.mjs --win --personal --help # 查看完整 CLI 指南
npm run build:clean # 清理 release/ + dist/ + dist-electron/
# 独立脚本（需传参数）
node scripts/generate-update-info.mjs <平台> <版本类型> [版本号] [--url <url>]
node scripts/upload-oss.mjs <平台> <版本类型> [版本号]
node scripts/publish-release.mjs <平台> <版本类型> [版本号] [--url <url>]
node build/scripts/generate-update-info.mjs <平台> <版本> [渠道] [版本类型] [ossPrefix]
node build/scripts/upload-oss.mjs <平台> <版本> [渠道] [ossPrefix]
node build/scripts/publish-release.mjs <平台> <版本> [渠道] [版本类型] [ossPrefix]
```
### `build.mjs` 操作组合
### `build/build.mjs` 操作组合
| 操作 | 说明 |
|-------------|------------------------------------------------------|
| `--build` | 构建（tsc + vite + electron-builder + update-info.json） |
| `--clean` | 清理旧产物 |
| `--sign` | 代码签名（配合 `--cert` 或环境变量） |
| `--upload` | 上传 OSS |
| `--publish` | POST 版本信息到后端 API |
| `--all` | 全流程 = clean + build + sign + upload + publish |
| 操作 | 说明 |
|-------------|------------------------------------------------------------|
| `--build` | 构建（校验 → tsc → vite → electron-builder → update-info.json） |
| `--clean` | 清理旧产物 |
| `--sign` | 代码签名（配合 `--cert` 或环境变量） |
| `--upload` | 上传 OSS |
| `--publish` | POST 版本信息到后端 API |
| `--all` | 全流程 = clean + build + sign + upload + publish |
| `--edition` | 版本类型：personal（默认）或 enterprise |
| `--channel` | 发布渠道：stable（默认）、beta 或 alpha |
---
## 三、发版工作流
## 三、渠道与灰度测试
### 渠道体系
| 渠道 | OSS 路径 | 生命周期 | 适用场景 |
|------|----------|----------|----------|
| `stable` | `releases/{version}/` | 永久 | 正式发布 |
| `beta` | `releases/beta/{version}/` | 可设 OSS 30 天自动过期 | 灰度测试 |
| `alpha` | `releases/{version}/alpha/` | 手动管理 | 内部开发测试 |
### 灰度发布工作流
```bash
# 1. 创建 beta 预发布版本号
npm run version:pre-beta # 0.0.29 → 0.0.30-beta.1
# 2. 写 CHANGELOG.md 更新日志
# 3. 构建并发布到 beta 渠道
node build/build.mjs --win --channel beta --upload --publish
# 4. 后端 API 设置 rolloutPercent: 10 → 30 → 100 逐步放量
# 客户端通过 deviceFingerprint 哈希分组（同一用户始终在同一组）
```
### 灰度原理
1. 客户端 `HeiXiuProvider` 请求 `/api/v1/update/check` 时携带 `channel`、`edition`、`deviceFingerprint`
2. 服务端根据 `rolloutPercent` + `deviceFingerprint` 哈希判断是否返回新版本
3. `src/shared/utils/rollout.ts` 提供 `isInRolloutGroup()` / `getRolloutGroup()` 工具函数
---
## 四、发版工作流
### 路径 A：快速打包（日常开发 / 内部测试）
```bash
# 1. 修改版本号
# package.json → "version": "0.1.0"
# 1. 升级版本号
npm run version:patch # package.json + CHANGELOG.md 自动更新
# 2. 写更新日志
# CHANGELOG.md → 顶部新增 ## 0.1.0（2026-xx-xx）...
# CHANGELOG.md → 编辑自动生成的 ## 0.1.0（日期）条目
# 3. 打包
npm run build:win && npm run build:win:enterprise
npm run build:win
# 4. 产物在 release/0.1.0/ 下：
# - xxx-Setup.exe（安装包）
# - xxx-Setup.exe.blockmap（块映射，增量更新用）
# - xxx-update-info.json（所有 API 字段，downloadUrl 为预判 URL）
# - xxx-update-info.json（channel、SHA512、blockmap 等全字段）
# 5. 手动上传 exe + .blockmap 到 OSS releases/0.1.0/
# 6. 将 update-info.json 内容录入数据库 releases 表
@@ -107,10 +151,10 @@ npm run build:win && npm run build:win:enterprise
npm run build:win
# 上传到 OSS（自动打印实际 URL）
node scripts/upload-oss.mjs win32 personal 0.1.0
node build/scripts/upload-oss.mjs win32 0.1.0
# 用实际 URL 重新生成 update-info.json
node scripts/generate-update-info.mjs win32 personal 0.1.0 \
node build/scripts/generate-update-info.mjs win32 0.1.0 stable personal \
--url "https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases/0.1.0/xxx.exe"
# 将 update-info.json 录入数据库
@@ -125,12 +169,12 @@ OSS_BUCKET=heixiu \
OSS_ACCESS_KEY_ID=xxx \
OSS_ACCESS_KEY_SECRET=xxx \
UPDATE_API_KEY=xxx \
node build.mjs --win --personal --upload --publish
node build/build.mjs --win --upload --publish
```
---
## 四、代码签名
## 五、代码签名
### 证书获取
@@ -145,7 +189,7 @@ node build.mjs --win --personal --upload --publish
```bash
# 方式 1：build.mjs 参数
node build.mjs --win --personal --sign --cert ./cert.pfx --cert-password xxx
node build/build.mjs --win --sign --cert ./cert.pfx --cert-password xxx
# 方式 2：环境变量（CI/CD 友好）
CSC_LINK=/path/to/cert.pfx CSC_KEY_PASSWORD=xxx npm run build:win
@@ -155,14 +199,27 @@ CSC_LINK=/path/to/cert.pfx CSC_KEY_PASSWORD=xxx npm run build:win
---
## 五、API 接口
## 六、API 接口
客户端调用的两个端点，完整规格见 [test-server/README.md](test-server/README.md)（可直接发给后端程序员）。
客户端调用的两个端点，完整规格见 [test-server/README.md](test-server/README.md)。
| 端点 | 用途 |
|----------------------------|-------------------------------------|
| `GET /api/v1/update/check` | 客户端版本检查，返回最新版本信息（含 blockmap 用于增量更新） |
| `POST /api/v1/releases` | 前端构建脚本发布新版本，需 Bearer Token 鉴权 |
### GET /api/v1/update/check
客户端版本检查，请求参数：
| 参数 | 类型 | 说明 |
|------|------|------|
| `platform` | string | `win32` / `darwin` / `linux` |
| `version` | string | 当前客户端版本号 |
| `channel` | string | 客户端渠道：`stable` / `beta` / `alpha` |
| `edition` | string | 版本类型：`personal` / `enterprise` |
| `deviceFingerprint` | string | 设备指纹（SHA-256 前 16 位，灰度分组用） |
响应字段含 `channel`、`rolloutPercent` 等灰度相关字段。
### POST /api/v1/releases
前端构建脚本发布新版本，需 `Authorization: Bearer <UPDATE_API_KEY>` 鉴权。请求体包含 `channel`、`edition` 等字段。
---
@@ -239,22 +296,28 @@ cd test-server && python server.py --release-dir ../release --port 8000
```
ele-heixiu/
├ build.mjs ← 构建总管（npm run build 入口）
├ CHANGELOG.md ← 更新日志（打包时自动提取）
├ UpdateA.md ← 本文档
├ package.json ← 仅保留简短的 npm 快捷命令
├ scripts/
│ ├ clean.mjs ← 清理产物
│ ├ generate-update-info.mjs ← 生成 API 信息 JSON（含 blockmap 信息）
│ ├ upload-oss.mjs ← 上传 OSS（安装包 + blockmap）
│ └ publish-release.mjs ← 发布到 API（axios）
├ release/ ← 构建产物目录（按版本分）
│ └ 0.1.0/
├ build/ ← 构建系统（2026-06-29 重构）
│ ├ build.mjs ← 构建总管（npm run build 入口）
│ ├ electron-builder.js ← electron-builder 配置（从 package.json 提取）
│ ├ README.md ← 构建系统文档
│ └ scripts/
│ ├ clean.mjs ← 清理产物
│ ├ pre-build-check.mjs ← 构建前校验（Git/CHANGELOG/版本一致性）
│ ├ generate-update-info.mjs← 生成 update-info.json（SHA512 + blockmap + channel）
│ ├ upload-oss.mjs ← 上传 OSS（安装包 + blockmap）
│ ├ publish-release.mjs ← 发布到 API（axios）
│ └ bump-version.mjs ← 版本号管理（major/minor/patch/pre）
├ CHANGELOG.md ← 更新日志（打包时自动提取）
├ UpdateA.md ← 本文档
├ package.json ← 不含 "build" 字段（已提取到 build/electron-builder.js）
├ release/ ← 构建产物目录
│ ├ .build-meta.json ← 最近一次构建元数据
│ └ 0.1.0/ ← Stable 版本
│ ├ xxx-Setup.exe
│ ├ xxx-Setup.exe.blockmap ← 差分更新块映射文件
│ ├ xxx-Setup.exe.blockmap ← 差分更新块映射文件
│ └ xxx-update-info.json
├ dist/ ← Vite 前端产物（构建输入）
└ dist-electron/ ← Electron 主进程产物（构建输入）
├ dist/ ← Vite 前端产物
└ dist-electron/ ← Electron 主进程产物
```
---