# UpdateClientSDK 接入说明

这个 SDK 是“独立更新器 SDK / 升级运行时 SDK”。它不是传统的 `include + lib` 形态，而是把自动升级能力作为一组独立程序交给业务软件使用。

SDK 核心程序：

- `Launcher.exe`：用户入口。检查版本、验证策略，决定启动业务主程序或启动 Updater。
- `Updater.exe`：下载、校验、备份、安装、健康确认、提交或回滚。
- `Bootstrap.exe`：替换运行中可能被占用的 EXE/DLL。
- `config/app_config.json`：接入方配置。
- `config/manifest_public_key.pem`：验证服务端签名用的公钥。

## 接入方需要做什么

假设接入的软件叫 `YourApp.exe`。

1. 在服务端管理后台创建应用，例如 `app_id=your_app_id`。
2. 创建或确认渠道，例如 `stable`。
3. 创建 License，把生成的 `license_key` 填到客户端配置。
4. 把业务程序和依赖 DLL 放到同一个发布目录。
5. 把 SDK 的 `Launcher.exe`、`Updater.exe`、`Bootstrap.exe` 和运行时 DLL 放到该目录。
6. 把 `config/app_config.example.json` 复制成 `config/app_config.json` 并修改字段。
7. 用户入口改成 `Launcher.exe`，不要直接双击业务主程序。
8. 在管理后台发布新版本时，选择包含业务主程序和 SDK 运行时的干净 Release 根目录。

## app_config.json 关键字段

```json
{
  "app_id": "simcae",
  "app_name": "SimCAE",
  "channel": "stable",
  "current_version": "1.0.0",
  "client_protocol": "3",
  "launch_token": "SimCAE_Launch_Token_2026_ChangeMe_32Bytes",
  "license_key": "",
  "api_base_url": "http://YOUR_SERVER_IP:8000",
  "client_token": "SimCAEClientToken2026",
  "request_timeout_ms": "5000",
  "temp_folder": "update_temp",
  "device_id": "",
  "main_executable": "SimCAE.exe",
  "launcher_executable": "Launcher.exe",
  "updater_executable": "Updater.exe",
  "bootstrap_executable": "Bootstrap.exe",
  "health_check_timeout_ms": "15000",
  "platform": "windows",
  "arch": "x64"
}
```

字段说明：

- `app_id`：服务端应用 ID，默认填 `simcae`；如果后台创建了别的 App ID，这里同步修改。
- `channel`：发布渠道，例如 `stable`、`beta`、`dev`。
- `current_version`：当前客户端初始版本。
- `client_protocol`：客户端协议号，当前建议为 `3`。
- `api_base_url`：服务端 API 地址，例如 `http://192.168.229.128:8000`；服务器 IP 无法提前知道，所以这里需要按现场地址修改。
- `client_token`：服务端 `.env` 中的 `CLIENT_API_TOKEN`，默认交付包已填 `SimCAEClientToken2026`。
- `license_key`：管理后台创建 License 后返回的密钥；模板里先留空，创建授权后再填。
- `launch_token`：本机启动票据 HMAC 密钥，模板已给默认值，可试跑；正式交付建议改成你自己的 32 字符以上随机字符串。
- `main_executable`：业务主程序文件名，默认填 `SimCAE.exe`；如果你的主程序不是这个名字，这里同步修改。
- `health_check_timeout_ms`：升级后等待业务程序写健康标记的时间。

## 业务主程序需要配合什么

当前安全模式下，业务主程序需要配合两件事：

1. 接收 `--ticket-file=<path>` 参数，验证并消费一次性启动票据。
2. 如果收到 `--health-file=<path>` 参数，启动成功后向该路径写入 `ok\n`，让 Updater 确认新版本可用。

当前仓库里的 `client/MainApp/main.cpp` 是接入示例，已经实现了：

- 启动票据校验。
- 本地 License/设备身份校验。
- 本地策略校验。
- Manifest 完整性校验。
- 健康标记写入。

如果第三方业务程序暂时不想改代码，可以先使用当前 `MainApp.exe` 作为 Demo 验证 SDK 包；真正接入时建议把这些启动检查逻辑移植到业务主程序。

## 如何生成 SDK 包

在 Windows PowerShell 中执行：

```powershell
cd client
.\package-sdk.ps1 `
  -SourceDir .\out\bin `
  -OutputDir .\dist\UpdateClientSDK `
  -ZipFile .\dist\UpdateClientSDK.zip `
  -SdkVersion 0.1.0
```

生成结果：

```text
dist/UpdateClientSDK/
  README.md
  bin/
  config/
  scripts/
  samples/
```

把 `UpdateClientSDK.zip` 发给接入方即可。

## 如何生成某个产品的最终客户端包

SDK 是给开发者接入用的，最终给用户安装/分发时，可以使用：

```powershell
cd client
.\package-client.ps1 `
  -SourceDir .\out\bin `
  -ConfigFile .\config\app_config.json `
  -OutputDir .\dist\UpdateClient `
  -ZipFile .\dist\UpdateClient.zip
```

`package-client.ps1` 会检查配置和必需文件，并生成具体产品的客户端包。

## 常见错误

1. 直接启动业务主程序提示 ticket 错误：应从 `Launcher.exe` 启动。
2. 首次启动设备登记失败：检查 `api_base_url`、`client_token`、`license_key`、服务端 License 状态。
3. 策略或 Manifest 验签失败：检查 `config/manifest_public_key.pem` 是否和服务端私钥匹配。
4. 升级后回滚：检查业务程序是否在 `health_check_timeout_ms` 内写入健康标记。
5. 发布失败提示主程序不在根目录：选择发布目录时要选择业务主程序所在目录，而不是上层或下层目录。