update-client/SDK_README.md

# 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. 把业务软件完整安装目录作为发布根目录，例如 `SimCAE\`，其中主程序位于 `bin\SimCAE.exe`。
5. 把 SDK 的 `Launcher.exe`、`Updater.exe`、`Bootstrap.exe` 放到 `SimCAE\bin\` 目录，和 `SimCAE.exe` 同级。不要覆盖 SimCAE 自带的 `Qt5*.dll` 和 Qt 插件目录。
6. 把 `config/app_config.example.json` 复制成 `SimCAE\bin\config\app_config.json` 并修改字段。
7. 用户入口改成 `Launcher.exe`，不要直接双击业务主程序。
8. 在管理后台发布新版本时，选择包含业务主程序和 SDK 运行时的干净 Release 根目录。

## 安装目录写权限要求

当前 SDK 会在 `Launcher.exe` 所在目录下写入运行时状态文件。SDK 放在 `SimCAE\bin` 时，这些文件实际位于 `SimCAE\bin` 下，例如：

```text
config/app_config.json
config/client_identity.dat
config/local_state.json
config/version_policy.dat
update/
update_temp/
```

所以联调和普通运行时，`Launcher.exe` 所在目录必须允许当前 Windows 用户写入。不要直接把联调目录放在 `C:\Program Files\...` 后用普通用户启动；该目录默认禁止普通程序写文件，会导致首次启动报错，例如 `cannot save installation id`。

推荐联调目录：

```text
D:\SimCAE_Release\
C:\Users\<你的用户名>\Desktop\SimCAE_Release\
```

如果最终产品必须安装到 `C:\Program Files\SimCAE\bin`，需要额外设计管理员提权、Windows 服务，或把运行时状态迁移到 `ProgramData` / `AppData`。当前交付版本默认按“安装目录可写”的模式工作。

## SimCAE 目录结构建议

SimCAE 当前安装目录是根目录下有 `bin/`、`Licenses/`、`installerResources/` 等子目录。SDK 推荐放在 `bin/` 目录，和 `SimCAE.exe` 同级；后台发布时仍选择整个安装根目录：

```text
SimCAE/
  bin/
    Launcher.exe
    Updater.exe
    Bootstrap.exe
    SimCAE.exe
    config/
      app_config.json
      manifest_public_key.pem
    update/
      manifest_cache/
    Qt5Core.dll
    ...
  Licenses/
  installerResources/
  maintenancetool.exe
```

这种模式下，后台“发布新版本”时选择整个 `SimCAE/` 目录，服务端会检查 `bin/SimCAE.exe` 是否存在，并把整个安装结构写入 Manifest。客户端配置里 `install_root` 填 `..`，表示被更新的安装根目录是 `bin` 的上一级；升级事务、下载缓存和 Manifest 缓存仍放在 `SimCAE\bin\update`。

注意：SimCAE 自己已经带有 Qt 运行库。SDK 的 Launcher/Updater 应使用和 SimCAE 兼容的 Qt 编译，并复用 SimCAE 的 `Qt5*.dll`、`platforms/`、`imageformats/` 等目录。不要把另一套 Qt DLL 覆盖到 `SimCAE\bin`，否则会出现“无法定位程序输入点”一类错误。

## 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": "",
  "install_root": "..",
  "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 字符以上随机字符串。
- `install_root`：安装根目录相对 `Launcher.exe` 所在目录的位置。SDK 放在 `bin` 时填 `..`。
- `main_executable`：业务主程序相对 `Launcher.exe` 所在目录的路径，SimCAE 默认填 `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
```

默认生成的 SDK 不包含 Qt 运行库，避免覆盖业务软件自带的 Qt。只有在接入的软件本身不带 Qt，且你确认要让 SDK 自带一套 Qt 运行库时，才额外添加 `-IncludeQtRuntime`。

生成结果：

```text
dist/UpdateClientSDK/
  SimCAE自动升级SDK接入说明_v0.1.docx
  sdk_manifest.json
  bin/
  config/
    app_config.json
    manifest_public_key.pem
  scripts/
```

把 `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. 首次启动提示 `cannot save installation id`：当前目录不可写，常见于 `C:\Program Files\...`；请换到可写目录联调，或用管理员权限/提权方案。
3. 首次启动设备登记失败：检查 `api_base_url`、`client_token`、`license_key`、服务端 License 状态。
4. 策略或 Manifest 验签失败：检查 `config/manifest_public_key.pem` 是否和服务端私钥匹配。
5. 升级后回滚：检查业务程序是否在 `health_check_timeout_ms` 内写入健康标记。
6. 发布失败提示主程序不在根目录：选择发布目录时要选择业务主程序所在目录，而不是上层或下层目录。
7. 启动时提示 `无法定位程序输入点 ... Qt5*.dll`：通常是 Qt DLL 被不同版本覆盖或混用。恢复业务软件原始 Qt DLL，并重新打包 SDK；SimCAE 场景下不要使用 `-IncludeQtRuntime`。