docs(打包): 说明客户安装器由服务端生成

.gitignore

@@ -26,10 +26,11 @@ private/
 pdf_requirements.txt
 
 # C/C++ generated artifacts
-*.obj
-*.o
-*.pdb
-*.ilk
+*.obj
+*.o
+*.pdb
+*.qm
+*.ilk
 *.idb
 *.tlog
 *.lastbuildstate

Bootstrap/main.cpp

@@ -45,6 +45,8 @@ static QString joinPath(const QString& root, const QString& relativePath)
 
 static bool removeWithRetry(const QString& path)
 {
+    // Windows 上主程序退出后，DLL/EXE 句柄可能还会短时间被系统占用。
+    // Bootstrap 用短重试等待文件释放，而不是一次失败就判定升级失败。
     for (int i = 0; i < 100; ++i) {
         if (!QFileInfo::exists(path))
             return true;
@@ -164,6 +166,8 @@ int main(int argc, char* argv[])
         rolledBack = rollback(installDir, backupDir, paths);
         success = false;
     } else {
+        // Bootstrap 是替换文件的接力进程：Updater 先退出，Bootstrap 再覆盖安装目录。
+        // 它不会更新自身，避免正在运行的 Bootstrap 被覆盖导致升级中断。
         for (const PlanItem& item : items) {
             const QString& relativePath = item.relativePath;
             if (isBootstrapSelfPath(relativePath)) {

CMakeLists.txt

@@ -89,7 +89,7 @@ endif()
 
 add_compile_definitions(HAVE_OPENSSL=1)
 
-# 统一输出目录。Windows 保持历史 out/bin；Linux 单独输出，避免和 Windows DLL/PDB 混在一起。
+# 统一输出目录。Visual Studio Release 实际输出到 out/bin/Release；Linux 单独输出到 out/linux/bin。
 if(UNIX AND NOT APPLE)
     set(SIMCAE_OUTPUT_ROOT ${CMAKE_SOURCE_DIR}/out/linux)
 else()
@@ -113,21 +113,20 @@ add_subdirectory(MainApp)
 # 默认启动项目
 set_property(DIRECTORY ${CMAKE_SOURCE_DIR} PROPERTY VS_STARTUP_PROJECT Launcher)
 
-# Copy config templates and static resources to output bin folder.
-if(UNIX AND NOT APPLE AND EXISTS "${CMAKE_SOURCE_DIR}/config/app_config.linux.example.json")
-    set(APP_CONFIG_SOURCE_FILE "${CMAKE_SOURCE_DIR}/config/app_config.linux.example.json")
-else()
-    set(APP_CONFIG_SOURCE_FILE "${CMAKE_SOURCE_DIR}/config/app_config.example.json")
-endif()
+# Copy local-only static resources to output bin folder. Final customer
+# app_config.json is generated by the Go server when a release package is
+# uploaded. Developers may create an untracked config/app_config.local.json for
+# local debugging.
 set(CONFIG_SOURCE_DIR "${CMAKE_SOURCE_DIR}/config")
 set(MANIFEST_PUBLIC_KEY_FILE "${CONFIG_SOURCE_DIR}/manifest_public_key.pem")
+set(LOCAL_APP_CONFIG_FILE "${CONFIG_SOURCE_DIR}/app_config.local.json")
 set(INI_TARGET_FOLDER "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}")
 
 # app_config.json 包含运行时版本状态；如果存在旧 client.ini，则交给客户端首次启动迁移
 file(MAKE_DIRECTORY "${INI_TARGET_FOLDER}")
 file(MAKE_DIRECTORY "${INI_TARGET_FOLDER}/config")
-if(NOT EXISTS "${INI_TARGET_FOLDER}/config/app_config.json" AND NOT EXISTS "${INI_TARGET_FOLDER}/client.ini")
-    configure_file("${APP_CONFIG_SOURCE_FILE}" "${INI_TARGET_FOLDER}/config/app_config.json" COPYONLY)
+if(EXISTS "${LOCAL_APP_CONFIG_FILE}" AND NOT EXISTS "${INI_TARGET_FOLDER}/config/app_config.json" AND NOT EXISTS "${INI_TARGET_FOLDER}/client.ini")
+    configure_file("${LOCAL_APP_CONFIG_FILE}" "${INI_TARGET_FOLDER}/config/app_config.json" COPYONLY)
 endif()
 foreach(RUNTIME_RESOURCE local_state.json version_policy.dat)
     if(EXISTS "${CONFIG_SOURCE_DIR}/${RUNTIME_RESOURCE}" AND NOT EXISTS "${INI_TARGET_FOLDER}/config/${RUNTIME_RESOURCE}")
@@ -152,9 +151,6 @@ add_dependencies(MainApp update_client_translations)
 add_dependencies(Bootstrap update_client_translations)
 
 # Install rules for packaging
-if(EXISTS "${APP_CONFIG_SOURCE_FILE}")
-    install(FILES "${APP_CONFIG_SOURCE_FILE}" DESTINATION bin/config RENAME app_config.json)
-endif()
 if(EXISTS "${MANIFEST_PUBLIC_KEY_FILE}")
     install(FILES "${MANIFEST_PUBLIC_KEY_FILE}" DESTINATION bin/config)
     install(FILES "${MANIFEST_PUBLIC_KEY_FILE}" DESTINATION bin)

Common/CMakeLists.txt

@@ -1,23 +1,23 @@
 project(Common LANGUAGES C CXX)
 
 set(SRC
-    HttpHelper.h
-    HttpHelper.cpp
-    FileHelper.h
-    FileHelper.cpp
+    HttpHelper.h
+    HttpHelper.cpp
+    FileHelper.h
+    FileHelper.cpp
     ConfigHelper.h
     ConfigHelper.cpp
     PolicyHelper.h
     PolicyHelper.cpp
     LocalStateHelper.h
     LocalStateHelper.cpp
-    TicketHelper.h
-    TicketHelper.cpp
-    IntegrityHelper.h
-    IntegrityHelper.cpp
-    DeviceIdentityHelper.h
-    DeviceIdentityHelper.cpp
-)
+    TicketHelper.h
+    TicketHelper.cpp
+    UpdatePathPolicy.h
+    UpdatePathPolicy.cpp
+    IntegrityHelper.h
+    IntegrityHelper.cpp
+)
 add_library(Common STATIC ${SRC})
 
 # Common编译自身需要OpenSSL头文件

Common/ConfigHelper.cpp

@@ -13,6 +13,7 @@
 #include <QMessageBox>
 #include <QSaveFile>
 #include <QSettings>
+#include <QStandardPaths>
 #include <QStringList>
 #include <QDebug>
 #include <string>
@@ -34,8 +35,8 @@ const QString kConfigKeyPrefix = QStringLiteral("--config-key-b64=");
 const QString kConfigValuePrefix = QStringLiteral("--config-value-b64=");
 const QString kFilePathPrefix = QStringLiteral("--file-path-b64=");
 const QString kFileDataPrefix = QStringLiteral("--file-data-b64=");
-const QString kRegistryOrganization = QStringLiteral("Marsco");
-const QString kRegistryApplication = QStringLiteral("UpdateClientSDK");
+const QString kRegistryOrganization = QStringLiteral("SimCAE");
+const QString kRegistryApplication = QStringLiteral("HubUpdateClient");
 const QString kRegistryInstallationsGroup = QStringLiteral("installations");
 const QString kRegistryConfigGroup = QStringLiteral("config");
 const QString kRegistryMetaGroup = QStringLiteral("_meta");
@@ -46,6 +47,8 @@ const QString kRegistryImportedAtKey = QStringLiteral("imported_at_utc");
 const QString kEmbeddedServerConfigPath = QStringLiteral(":/simcae/server_config.json");
 const QString kApiBaseUrlKey = QStringLiteral("api_base_url");
 
+// 需要提权写入时，子进程参数统一用 Base64Url 编码。
+// 这样可以避免 Windows 路径、中文、空格或换行在 ShellExecute 参数传递中被截断或误解析。
 QString encodeArgument(const QString& value)
 {
     return QString::fromLatin1(value.toUtf8().toBase64(
@@ -173,7 +176,30 @@ bool writeConfigValueToFile(const QString& configPath, const QString& key,
 
 bool isRegistryManagedConfigKey(const QString& key)
 {
-    return key != kApiBaseUrlKey;
+    // 服务端地址是编译期 qrc 配置，不进入注册表。
+    // 其他运行配置会在 Launcher 首次启动时导入注册表，之后以注册表为准。
+    Q_UNUSED(key);
+    return true;
+}
+
+bool isPathInsideDirectory(const QString& path, const QString& directory)
+{
+    if (path.isEmpty() || directory.isEmpty())
+        return false;
+
+    QString normalizedPath = QDir::cleanPath(QFileInfo(path).absoluteFilePath());
+    QString normalizedDirectory = QDir::cleanPath(QFileInfo(directory).absoluteFilePath());
+#ifdef Q_OS_WIN
+    normalizedPath = normalizedPath.toLower();
+    normalizedDirectory = normalizedDirectory.toLower();
+#endif
+    return normalizedPath == normalizedDirectory
+        || normalizedPath.startsWith(normalizedDirectory + QDir::separator());
+}
+
+bool isUserDataPath(const QString& path)
+{
+    return isPathInsideDirectory(path, ConfigHelper::instance().dataRoot());
 }
 
 QJsonObject registryManagedConfigObject(const QJsonObject& source)
@@ -198,10 +224,12 @@ QString windowsErrorMessage(DWORD errorCode)
 bool runElevatedSelfCommand(const QStringList& arguments, const QString& targetPath,
                             const QString& originalError, QString* errorMessage)
 {
+    // 安装到 C:\Program Files 等目录时，普通用户不能直接修改配置或运行态文件。
+    // 这里不让主进程一直以管理员运行，而是在确实需要写入时临时拉起自身完成单次写入。
     const QMessageBox::StandardButton choice = QMessageBox::question(
         nullptr,
         QCoreApplication::translate("ConfigHelper", "Administrator Permission Required"),
-        QCoreApplication::translate("ConfigHelper", "The current installation directory requires administrator permission to save configuration.\n\nTarget file: %1\nReason: %2\n\nClick OK, then choose Yes in the Windows permission confirmation dialog.")
+        QCoreApplication::translate("ConfigHelper", "The current operation needs administrator permission to modify a protected file.\n\nTarget file: %1\nReason: %2\n\nClick OK, then choose Yes in the Windows permission confirmation dialog.")
             .arg(QDir::toNativeSeparators(targetPath), originalError),
         QMessageBox::Ok | QMessageBox::Cancel,
         QMessageBox::Ok);
@@ -397,6 +425,12 @@ bool ConfigHelper::writeFileWithElevationIfNeeded(const QString& path, const QBy
     }
 
 #ifdef Q_OS_WIN
+    if (isUserDataPath(path))
+    {
+        if (errorMessage)
+            *errorMessage = localError;
+        return false;
+    }
     if (data.size() > 24 * 1024)
     {
         if (errorMessage)
@@ -423,6 +457,12 @@ bool ConfigHelper::removeFileWithElevationIfNeeded(const QString& path, QString*
     }
 
 #ifdef Q_OS_WIN
+    if (isUserDataPath(path))
+    {
+        if (errorMessage)
+            *errorMessage = localError;
+        return false;
+    }
     return removeFileWithElevation(path, localError, errorMessage);
 #else
     if (errorMessage)
@@ -439,7 +479,6 @@ ConfigHelper::ConfigHelper()
         QCryptographicHash::Sha256).toHex());
     migrateLegacyIniIfNeeded();
     syncRegistryFromConfigFileIfChanged();
-    removeRegistryValue(kApiBaseUrlKey);
     qDebug() << "Loading app config path:" << m_configPath;
     qDebug() << "File exists?" << QFile::exists(m_configPath);
     qDebug() << "Registry installation id:" << m_registryInstallId;
@@ -458,15 +497,44 @@ QString ConfigHelper::installRoot() const
     return QDir::cleanPath(QDir(runtimeRoot()).filePath(relativeRoot));
 }
 
-QString ConfigHelper::runtimeRoot() const
-{
-    return QDir::cleanPath(QApplication::applicationDirPath());
-}
-
-QString ConfigHelper::updateRoot() const
-{
-    return QDir(runtimeRoot()).filePath("update");
-}
+QString ConfigHelper::runtimeRoot() const
+{
+    return QDir::cleanPath(QApplication::applicationDirPath());
+}
+
+QString ConfigHelper::dataRoot() const
+{
+    QString base = QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation);
+    if (base.isEmpty())
+        base = QDir::homePath();
+    return QDir::cleanPath(QDir(base).filePath(
+        QStringLiteral("SimCAE/HubUpdateClient/installations/%1").arg(m_registryInstallId)));
+}
+
+QString ConfigHelper::dataConfigDir() const
+{
+    return QDir(dataRoot()).filePath(QStringLiteral("config"));
+}
+
+QString ConfigHelper::clientIdentityPath() const
+{
+    return QDir(dataConfigDir()).filePath(QStringLiteral("client_identity.dat"));
+}
+
+QString ConfigHelper::policyPath() const
+{
+    return QDir(dataConfigDir()).filePath(QStringLiteral("version_policy.dat"));
+}
+
+QString ConfigHelper::localStatePath() const
+{
+    return QDir(dataConfigDir()).filePath(QStringLiteral("local_state.json"));
+}
+
+QString ConfigHelper::updateRoot() const
+{
+    return QDir(dataRoot()).filePath("update");
+}
 
 QString ConfigHelper::runtimeRelativePath() const
 {
@@ -572,16 +640,15 @@ bool ConfigHelper::syncRegistryFromConfigFileIfChanged()
 
     if (configChangedAfterPreviousImport)
     {
-        const QString configDir = QFileInfo(m_configPath).absolutePath();
         const QStringList staleFiles{
-            QDir(configDir).filePath(QStringLiteral("client_identity.dat")),
-            QDir(configDir).filePath(QStringLiteral("version_policy.dat")),
-            QDir(configDir).filePath(QStringLiteral("local_state.json"))
+            clientIdentityPath(),
+            policyPath(),
+            localStatePath()
         };
         for (const QString& staleFile : staleFiles)
         {
             QString removeError;
-            if (!ConfigHelper::removeFileWithElevationIfNeeded(staleFile, &removeError))
+            if (!removeFile(staleFile, &removeError))
             {
                 m_error = QStringLiteral("Cannot remove stale runtime file after config change: %1. %2")
                     .arg(staleFile, removeError);
@@ -608,9 +675,11 @@ bool ConfigHelper::sanitizeConfigFileAfterImport(QSettings& settings)
         QCryptographicHash::hash(normalizedEmptyConfig, QCryptographicHash::Sha256).toHex());
 
     QString writeError;
-    if (!ConfigHelper::writeFileWithElevationIfNeeded(m_configPath, emptyFileBytes, &writeError))
+    if (!writeBytesToFile(m_configPath, emptyFileBytes, &writeError))
     {
-        m_error = QStringLiteral("Cannot clear app_config.json after registry import: %1").arg(writeError);
+        // 清空 app_config.json 只是为了减少明文配置暴露，不是启动必需步骤。
+        // 如果安装目录或文件只读，不再为了清空源配置弹 UAC；运行配置已经写入 HKCU 注册表。
+        m_error = QStringLiteral("Cannot clear app_config.json after registry import without elevation: %1").arg(writeError);
         return false;
     }
 
@@ -719,16 +788,18 @@ QString ConfigHelper::readFileValue(const QString& key) const
 QString ConfigHelper::getValue(const QString& section, const QString& key) const
 {
     Q_UNUSED(section);
-    const QString embeddedValue = readEmbeddedValue(key);
-    if (!embeddedValue.isEmpty())
-        return embeddedValue;
     if (!isRegistryManagedConfigKey(key))
         return QString();
 
     QString value;
     if (readRegistryValue(key, &value))
         return value;
-    return readFileValue(key);
+
+    value = readFileValue(key).trimmed();
+    if (!value.isEmpty())
+        return value;
+
+    return readEmbeddedValue(key);
 }
 
 bool ConfigHelper::setValue(const QString& section, const QString& key, const QString& value)
@@ -755,15 +826,15 @@ bool ConfigHelper::migrateLegacyIniIfNeeded()
         config.insert(key, value);
     };
 
-    copyText("App", "app_id");
-    copyText("App", "app_name", "Marsco Demo App");
+    copyText("App", "app_id");
+    copyText("App", "product_code", ini.value("App/app_id").toString());
+    copyText("App", "app_name", "SimCAE");
     copyText("App", "channel", "stable");
     copyText("App", "current_version", "1.0.0");
-    copyText("App", "client_protocol", "3");
-    copyText("App", "launch_token");
-    copyText("License", "license_key");
-    copyText("Server", "api_base_url");
-    copyText("Server", "client_token");
+    copyText("App", "client_protocol", "3");
+    copyText("Server", "client_token");
+    copyText("App", "launch_token");
+    copyText("Server", "api_base_url");
     copyText("Update", "request_timeout_ms", "5000");
     copyText("Update", "temp_folder", "update_temp");
     copyText("Update", "device_id");
@@ -773,6 +844,9 @@ bool ConfigHelper::migrateLegacyIniIfNeeded()
     copyText("Runtime", "updater_executable", ConfigHelper::executableNameForCurrentPlatform(QString(), "Updater"));
     copyText("Runtime", "bootstrap_executable", ConfigHelper::executableNameForCurrentPlatform(QString(), "Bootstrap"));
     copyText("Runtime", "health_check_timeout_ms", "15000");
+    copyText("Security", "require_manifest_signature", "false");
+    copyText("Security", "verify_installed_on_start", "false");
+    copyText("Platform", "abi");
 #ifdef Q_OS_WIN
     config.insert("platform", "windows");
 #elif defined(Q_OS_LINUX)
@@ -780,7 +854,7 @@ bool ConfigHelper::migrateLegacyIniIfNeeded()
 #else
     config.insert("platform", "unknown");
 #endif
-    config.insert("arch", "x64");
+    config.insert("arch", "x86_64");
 
     QDir().mkpath(QFileInfo(m_configPath).path());
     QSaveFile output(m_configPath);

Common/ConfigHelper.h

@@ -17,9 +17,14 @@ public:
     QString getValue(const QString& section, const QString& key) const;
     bool setValue(const QString& section, const QString& key, const QString& value);
     QString configPath() const;
-    QString installRoot() const;
-    QString runtimeRoot() const;
-    QString updateRoot() const;
+    QString installRoot() const;
+    QString runtimeRoot() const;
+    QString dataRoot() const;
+    QString dataConfigDir() const;
+    QString clientIdentityPath() const;
+    QString policyPath() const;
+    QString localStatePath() const;
+    QString updateRoot() const;
     QString runtimeRelativePath() const;
     QString lastError() const;
 

Common/DeviceIdentityHelper.cpp

@@ -1,48 +0,0 @@
-#include "DeviceIdentityHelper.h"
-#include "ConfigHelper.h"
-#include <QCryptographicHash>
-#include <QDateTime>
-#include <QDir>
-#include <QEventLoop>
-#include <QFile>
-#include <QJsonDocument>
-#include <QJsonObject>
-#include <QNetworkAccessManager>
-#include <QNetworkReply>
-#include <QNetworkRequest>
-#include <QSysInfo>
-#include <QUuid>
-#include <QTimer>
-#ifdef HAVE_OPENSSL
-#include <openssl/evp.h>
-#include <openssl/pem.h>
-#endif
-DeviceIdentityHelper::DeviceIdentityHelper(const QString& dir):m_installDir(dir){}
-QString DeviceIdentityHelper::deviceId() const{return m_deviceId;}
-QString DeviceIdentityHelper::errorString() const{return m_error;}
-bool DeviceIdentityHelper::verifySignature(const QByteArray& payload,const QString& sig64){
-#ifndef HAVE_OPENSSL
- Q_UNUSED(payload);Q_UNUSED(sig64);m_error="OpenSSL unavailable";return false;
-#else
- QFile f(QDir(m_installDir).filePath("config/manifest_public_key.pem")); if(!f.open(QIODevice::ReadOnly)){m_error="device public key missing";return false;}
- QByteArray kd=f.readAll();BIO* b=BIO_new_mem_buf(kd.constData(),kd.size());EVP_PKEY* k=b?PEM_read_bio_PUBKEY(b,nullptr,nullptr,nullptr):nullptr;if(b)BIO_free(b);if(!k){m_error="device public key invalid";return false;}
- EVP_MD_CTX* c=EVP_MD_CTX_new();QByteArray sig=QByteArray::fromBase64(sig64.toUtf8());bool ok=c&&EVP_DigestVerifyInit(c,nullptr,EVP_sha256(),nullptr,k)==1&&EVP_DigestVerifyUpdate(c,payload.constData(),payload.size())==1&&EVP_DigestVerifyFinal(c,reinterpret_cast<const unsigned char*>(sig.constData()),sig.size())==1;if(c)EVP_MD_CTX_free(c);EVP_PKEY_free(k);if(!ok)m_error="device credential RSA signature invalid";return ok;
-#endif
-}
-bool DeviceIdentityHelper::loadAndVerify(const QString& appId,const QString& channel){
- QFile f(QDir(m_installDir).filePath("config/client_identity.dat"));if(!f.open(QIODevice::ReadOnly))return false;QJsonParseError e;auto d=QJsonDocument::fromJson(f.readAll(),&e);if(e.error!=QJsonParseError::NoError||!d.isObject()){m_error="device credential JSON invalid";return false;}auto w=d.object();QByteArray text=w.value("identity_text").toString().toUtf8();if(text.isEmpty()||!verifySignature(text,w.value("signature").toString()))return false;auto identity=QJsonDocument::fromJson(text).object();QDateTime expiry=QDateTime::fromString(identity.value("valid_until").toString(),Qt::ISODate);if(identity.value("app_id").toString()!=appId||identity.value("channel").toString()!=channel||identity.value("license_id").toString().isEmpty()||identity.value("installation_id").toString().isEmpty()||identity.value("device_id").toString().isEmpty()){m_error="device/license credential identity mismatch";return false;}if(!expiry.isValid()||expiry<=QDateTime::currentDateTimeUtc()){m_error="license expired";return false;}m_deviceId=identity.value("device_id").toString();return true;
-}
-bool DeviceIdentityHelper::verifyLocal(const QString& appId,const QString& channel){m_error.clear();return loadAndVerify(appId,channel);}
-bool DeviceIdentityHelper::ensureIssued(const QString& base,const QString& token,const QString& appId,const QString& channel,const QString& licenseKey){
- m_error.clear();if(loadAndVerify(appId,channel)){ConfigHelper::instance().setValue("Update","device_id",m_deviceId);return true;}
- const QString trimmedBase=base.trimmed();
- if(appId.trimmed().isEmpty()){m_error="app_id is empty in config/app_config.json";return false;}
- if(channel.trimmed().isEmpty()){m_error="channel is empty in config/app_config.json";return false;}
- if(trimmedBase.isEmpty()||trimmedBase.contains("YOUR_SERVER_IP",Qt::CaseInsensitive)){m_error="api_base_url is not configured. Set config/server_config.json before building the client, for example http://192.168.229.128:8000";return false;}
- if(token.trimmed().isEmpty()){m_error="client_token is empty in config/app_config.json";return false;}
- if(licenseKey.trimmed().isEmpty()){m_error="license_key is empty. Create a License in the admin page and paste the generated key into config/app_config.json";return false;}
- ConfigHelper& config=ConfigHelper::instance();
- QString installation=config.getValue("Device","installation_id");if(installation.isEmpty()){installation=QUuid::createUuid().toString(QUuid::WithoutBraces);if(!config.setValue("Device","installation_id",installation)){m_error=QString("cannot save installation id to %1: %2").arg(config.configPath(),config.lastError());return false;}}
- QByteArray machine=QSysInfo::machineUniqueId()+installation.toUtf8();QString mh=QString::fromLatin1(QCryptographicHash::hash(machine,QCryptographicHash::Sha256).toHex());QJsonObject body{{"app_id",appId},{"channel",channel},{"license_key",licenseKey},{"installation_id",installation},{"machine_hash",mh}};
- QNetworkAccessManager manager;QNetworkRequest req{QUrl(trimmedBase+"/api/v1/device/issue")};req.setHeader(QNetworkRequest::ContentTypeHeader,"application/json");req.setRawHeader("X-Client-Token",token.toUtf8());QNetworkReply* reply=manager.post(req,QJsonDocument(body).toJson(QJsonDocument::Compact));QEventLoop loop;bool timeoutOk=false;int timeoutMs=ConfigHelper::instance().getValue("Update","request_timeout_ms").toInt(&timeoutOk);if(!timeoutOk||timeoutMs<1000)timeoutMs=5000;QTimer timer;timer.setSingleShot(true);QObject::connect(&timer,&QTimer::timeout,[&](){if(reply&&reply->isRunning())reply->abort();});QObject::connect(reply,&QNetworkReply::finished,&loop,&QEventLoop::quit);timer.start(timeoutMs);loop.exec();timer.stop();int status=reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt();QByteArray raw=reply->readAll();reply->deleteLater();if(status!=200){m_error=QString("device issue failed (HTTP %1): %2").arg(status).arg(QString::fromUtf8(raw));return false;}auto response=QJsonDocument::fromJson(raw).object();QJsonObject wrapper{{"identity_text",response.value("identity_text")},{"signature",response.value("signature")}};QString path=QDir(m_installDir).filePath("config/client_identity.dat");QByteArray bytes=QJsonDocument(wrapper).toJson(QJsonDocument::Compact);QString writeError;if(!ConfigHelper::writeFileWithElevationIfNeeded(path,bytes,&writeError)){m_error=QString("cannot save device credential to %1: %2").arg(path,writeError);return false;}if(!loadAndVerify(appId,channel))return false;if(!config.setValue("Update","device_id",m_deviceId)){m_error=QString("cannot save server device id to %1: %2").arg(config.configPath(),config.lastError());return false;}return true;
-}

Common/DeviceIdentityHelper.h

@@ -1,15 +0,0 @@
-#pragma once
-#include <QString>
-class DeviceIdentityHelper {
-public:
- explicit DeviceIdentityHelper(const QString& installDir);
- bool ensureIssued(const QString& apiBaseUrl, const QString& clientToken, const QString& appId,
-                   const QString& channel, const QString& licenseKey);
- bool verifyLocal(const QString& appId, const QString& channel);
- QString deviceId() const;
- QString errorString() const;
-private:
- bool loadAndVerify(const QString& expectedAppId, const QString& expectedChannel);
- bool verifySignature(const QByteArray& payload, const QString& signatureBase64);
- QString m_installDir, m_deviceId, m_error;
-};

Common/HttpHelper.cpp

@@ -3,65 +3,132 @@
 #include "ConfigHelper.h"
 #include <QFile>
 #include <QDir>
-#include <QApplication>
-#include <QTimer>
-
-void HttpHelper::postRequest(const QString& url, const QJsonObject& jsonBody,
-    std::function<void(int code, const QJsonObject& resp)> callback)
-{
-    QNetworkAccessManager* manager = new QNetworkAccessManager();
-    manager->setProxy(QNetworkProxy::NoProxy);
-
-    QNetworkRequest req(url);
-    req.setHeader(QNetworkRequest::ContentTypeHeader, "application/json");
-    // Add auth token header
-    QString token = ConfigHelper::instance().getValue("Server", "client_token");
-    req.setRawHeader("X-Client-Token", token.toUtf8());
-    QFile identity(QDir(QApplication::applicationDirPath()).filePath("config/client_identity.dat"));
-    if (identity.open(QIODevice::ReadOnly))
-        req.setRawHeader("X-Device-Credential", identity.readAll().toBase64());
-
-    QByteArray data = QJsonDocument(jsonBody).toJson(QJsonDocument::Compact);
-    qDebug() << "=== POST Request ===";
-    qDebug() << "Url:" << url;
-    qDebug() << "Body:" << data;
-
-    QNetworkReply* reply = manager->post(req, data);
-    QEventLoop loop;
-    bool timeoutOk = false;
-    int timeoutMs = ConfigHelper::instance().getValue("Update", "request_timeout_ms").toInt(&timeoutOk);
-    if (!timeoutOk || timeoutMs < 1000) timeoutMs = 5000;
-    QTimer timer;
-    timer.setSingleShot(true);
-    QObject::connect(&timer, &QTimer::timeout, [&]() {
-        if (reply && reply->isRunning()) {
-            qDebug() << "Request timeout, abort:" << url;
-            reply->abort();
-        }
-    });
-
-    QObject::connect(reply, &QNetworkReply::finished, &loop, &QEventLoop::quit);
-    timer.start(timeoutMs);
-    loop.exec();
-    timer.stop();
-
-    int retCode = 0;
-    QJsonObject retObj;
-
-    retCode = reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt();
-    const QByteArray respData = reply->readAll();
-    if (!respData.isEmpty()) {
-        qDebug() << "Server raw response:" << respData;
-        retObj = QJsonDocument::fromJson(respData).object();
-    }
-    if (reply->error() != QNetworkReply::NoError)
-    {
-        qDebug() << "Network error code:" << reply->error();
-        qDebug() << "HTTP status:" << retCode << "detail:" << reply->errorString();
-    }
-
-    callback(retCode, retObj);
-
-    reply->deleteLater();
-    manager->deleteLater();
-}
+#include <QApplication>
+#include <QJsonParseError>
+#include <QTimer>
+#include <QUrl>
+
+namespace {
+
+int requestTimeoutMs()
+{
+    bool timeoutOk = false;
+    int timeoutMs = ConfigHelper::instance().getValue("Update", "request_timeout_ms").toInt(&timeoutOk);
+    if (!timeoutOk || timeoutMs < 1000)
+        timeoutMs = 5000;
+    return timeoutMs;
+}
+
+void applyCommonHeaders(QNetworkRequest& req, const QString& bearerToken)
+{
+    const QString clientToken = ConfigHelper::instance().getValue(QStringLiteral("Server"), QStringLiteral("client_token")).trimmed();
+    if (!clientToken.isEmpty())
+        req.setRawHeader("X-Client-Token", clientToken.toUtf8());
+
+    const QString token = bearerToken.trimmed();
+    if (!token.isEmpty())
+        req.setRawHeader("Authorization", QByteArray("Bearer ") + token.toUtf8());
+}
+
+void readJsonReply(QNetworkReply* reply, int* retCode, QJsonObject* retObj)
+{
+    *retCode = reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt();
+    const QByteArray respData = reply->readAll();
+    if (!respData.isEmpty()) {
+        qDebug() << "Server raw response:" << respData;
+        QJsonParseError parseError;
+        const QJsonDocument document = QJsonDocument::fromJson(respData, &parseError);
+        if (parseError.error == QJsonParseError::NoError && document.isObject())
+            *retObj = document.object();
+    }
+    if (reply->error() != QNetworkReply::NoError)
+    {
+        qDebug() << "Network error code:" << reply->error();
+        qDebug() << "HTTP status:" << *retCode << "detail:" << reply->errorString();
+    }
+}
+
+void waitForReply(const QString& url, QNetworkReply* reply)
+{
+    QEventLoop loop;
+    QTimer timer;
+    timer.setSingleShot(true);
+    QObject::connect(&timer, &QTimer::timeout, [&]() {
+        if (reply && reply->isRunning()) {
+            qDebug() << "Request timeout, abort:" << url;
+            reply->abort();
+        }
+    });
+    QObject::connect(reply, &QNetworkReply::finished, &loop, &QEventLoop::quit);
+    timer.start(requestTimeoutMs());
+    loop.exec();
+    timer.stop();
+}
+
+} // namespace
+
+void HttpHelper::postRequest(const QString& url, const QJsonObject& jsonBody,
+    std::function<void(int code, const QJsonObject& resp)> callback)
+{
+    postRequest(url, jsonBody, QString(), callback);
+}
+
+void HttpHelper::postRequest(const QString& url, const QJsonObject& jsonBody,
+    const QString& bearerToken,
+    std::function<void(int code, const QJsonObject& resp)> callback)
+{
+    QNetworkAccessManager* manager = new QNetworkAccessManager();
+    manager->setProxy(QNetworkProxy::NoProxy);
+
+    QNetworkRequest req{QUrl(url)};
+    req.setHeader(QNetworkRequest::ContentTypeHeader, "application/json");
+    applyCommonHeaders(req, bearerToken);
+
+    QByteArray data = QJsonDocument(jsonBody).toJson(QJsonDocument::Compact);
+    qDebug() << "=== POST Request ===";
+    qDebug() << "Url:" << url;
+    qDebug() << "Body:" << data;
+
+    QNetworkReply* reply = manager->post(req, data);
+    waitForReply(url, reply);
+
+    int retCode = 0;
+    QJsonObject retObj;
+    readJsonReply(reply, &retCode, &retObj);
+
+    callback(retCode, retObj);
+
+    reply->deleteLater();
+    manager->deleteLater();
+}
+
+void HttpHelper::getRequest(const QString& url,
+    std::function<void(int code, const QJsonObject& resp)> callback)
+{
+    getRequest(url, QString(), callback);
+}
+
+void HttpHelper::getRequest(const QString& url, const QString& bearerToken,
+    std::function<void(int code, const QJsonObject& resp)> callback)
+{
+    QNetworkAccessManager* manager = new QNetworkAccessManager();
+    manager->setProxy(QNetworkProxy::NoProxy);
+
+    QNetworkRequest req{QUrl(url)};
+    applyCommonHeaders(req, bearerToken);
+
+    qDebug() << "=== GET Request ===";
+    qDebug() << "Url:" << url;
+
+    QNetworkReply* reply = manager->get(req);
+    waitForReply(url, reply);
+
+    int retCode = 0;
+    QJsonObject retObj;
+    readJsonReply(reply, &retCode, &retObj);
+
+    callback(retCode, retObj);
+
+    reply->deleteLater();
+    manager->deleteLater();
+}

Common/HttpHelper.h

@@ -3,15 +3,23 @@
 #include <QNetworkAccessManager>
 #include <QNetworkRequest>
 #include <QNetworkReply>
-#include <QJsonObject>
-#include <QJsonDocument>
-#include <QEventLoop>
-#include <QDebug>
-
-class HttpHelper
-{
-public:
+#include <QJsonObject>
+#include <QJsonDocument>
+#include <QEventLoop>
+#include <QDebug>
+#include <functional>
+
+class HttpHelper
+{
+public:
     // Create an independent manager for each call instead of keeping it as a member.
-    static void postRequest(const QString& url, const QJsonObject& jsonBody,
-        std::function<void(int code, const QJsonObject& resp)> callback);
+    static void postRequest(const QString& url, const QJsonObject& jsonBody,
+        std::function<void(int code, const QJsonObject& resp)> callback);
+    static void postRequest(const QString& url, const QJsonObject& jsonBody,
+        const QString& bearerToken,
+        std::function<void(int code, const QJsonObject& resp)> callback);
+    static void getRequest(const QString& url,
+        std::function<void(int code, const QJsonObject& resp)> callback);
+    static void getRequest(const QString& url, const QString& bearerToken,
+        std::function<void(int code, const QJsonObject& resp)> callback);
 };

Common/IntegrityHelper.cpp

@@ -1,49 +1,62 @@
-#include "IntegrityHelper.h"
-#include "ConfigHelper.h"
-#include <QCryptographicHash>
-#include <QDir>
-#include <QDirIterator>
-#include <QFile>
+#include "IntegrityHelper.h"
+#include "ConfigHelper.h"
+#include "UpdatePathPolicy.h"
+#include <QCryptographicHash>
+#include <QDir>
+#include <QDirIterator>
+#include <QFile>
 #include <QFileInfo>
-#include <QJsonArray>
-#include <QJsonDocument>
+#include <QJsonArray>
+#include <QCoreApplication>
+#include <QJsonDocument>
 #include <QJsonObject>
 #include <QSet>
-#ifdef HAVE_OPENSSL
-#include <openssl/evp.h>
-#include <openssl/pem.h>
-#endif
-
-IntegrityHelper::IntegrityHelper(const QString& installDir)
+#ifdef HAVE_OPENSSL
+#include <openssl/evp.h>
+#include <openssl/pem.h>
+#endif
+
+namespace {
+
+QString configValue(const QString& key, const QString& fallback = QString())
+{
+    const QString value = ConfigHelper::instance().getValue(QString(), key).trimmed();
+    return value.isEmpty() ? fallback : value;
+}
+
+bool configFlag(const QString& key)
+{
+    const QString value = configValue(key).toLower();
+    return value == QStringLiteral("true")
+        || value == QStringLiteral("1")
+        || value == QStringLiteral("yes")
+        || value == QStringLiteral("on");
+}
+
+bool manifestFileRequired(const QJsonObject& item)
+{
+    if (!item.contains(QStringLiteral("required")))
+        return true;
+    return item.value(QStringLiteral("required")).toBool(true);
+}
+
+} // namespace
+
+IntegrityHelper::IntegrityHelper(const QString& installDir)
     : m_installDir(QDir::cleanPath(installDir)) {}
 
 QString IntegrityHelper::errorString() const { return m_error; }
 
-bool IntegrityHelper::safeRelativePath(const QString& path) const
-{
-    const QString clean = QDir::cleanPath(QDir::fromNativeSeparators(path));
-    return !clean.isEmpty() && !QDir::isAbsolutePath(clean) && clean != ".."
-        && !clean.startsWith("../") && !clean.contains(":");
-}
-
-bool IntegrityHelper::runtimeProtectedPath(const QString& path) const
-{
-    const QString p = QDir::fromNativeSeparators(path).toCaseFolded();
-    QSet<QString> protectedPaths{
-        "bootstrap", "bootstrap.exe", "client.ini", "config/app_config.json", "config/local_state.json",
-        "config/client_identity.dat", "config/version_policy.dat"
-    };
-    const QString runtimePrefix = ConfigHelper::instance().runtimeRelativePath().toCaseFolded();
-    if (!runtimePrefix.isEmpty()) {
-        const QStringList runtimeProtected{
-            "bootstrap", "bootstrap.exe", "client.ini", "config/app_config.json", "config/local_state.json",
-            "config/client_identity.dat", "config/version_policy.dat"
-        };
-        for (const QString& protectedPath : runtimeProtected)
-            protectedPaths.insert(runtimePrefix + "/" + protectedPath);
-    }
-    return protectedPaths.contains(p);
-}
+bool IntegrityHelper::safeRelativePath(const QString& path) const
+{
+    return UpdatePathPolicy::isSafeRelativePath(path);
+}
+
+bool IntegrityHelper::runtimeProtectedPath(const QString& path) const
+{
+    return UpdatePathPolicy::isFullUpdateProtectedPath(
+        path, ConfigHelper::instance().runtimeRelativePath());
+}
 
 QString IntegrityHelper::sha256(const QString& filePath) const
 {
@@ -56,19 +69,32 @@ QString IntegrityHelper::sha256(const QString& filePath) const
 
 bool IntegrityHelper::verifySignature(const QByteArray& payload, const QString& signatureBase64)
 {
-#ifndef HAVE_OPENSSL
-    Q_UNUSED(payload); Q_UNUSED(signatureBase64); m_error = "OpenSSL unavailable"; return false;
-#else
+#ifndef HAVE_OPENSSL
+    Q_UNUSED(payload); Q_UNUSED(signatureBase64);
+    m_error = QCoreApplication::translate("IntegrityHelper",
+        "Cannot verify signed manifest because OpenSSL support is unavailable. Stage: installed version verification.");
+    return false;
+#else
     QString keyPath = QDir(m_installDir).filePath("config/manifest_public_key.pem");
-    if (!QFile::exists(keyPath))
-        keyPath = QFileInfo(ConfigHelper::instance().configPath()).dir().filePath("manifest_public_key.pem");
-    QFile keyFile(keyPath);
-    if (!keyFile.open(QIODevice::ReadOnly)) { m_error = "manifest public key missing"; return false; }
+    if (!QFile::exists(keyPath))
+        keyPath = QFileInfo(ConfigHelper::instance().configPath()).dir().filePath("manifest_public_key.pem");
+    QFile keyFile(keyPath);
+    if (!keyFile.open(QIODevice::ReadOnly)) {
+        m_error = QCoreApplication::translate("IntegrityHelper",
+            "Cannot open manifest public key. Stage: installed version verification. Public key path: %1.")
+            .arg(keyPath);
+        return false;
+    }
     const QByteArray keyData = keyFile.readAll();
     BIO* bio = BIO_new_mem_buf(keyData.constData(), keyData.size());
     EVP_PKEY* key = bio ? PEM_read_bio_PUBKEY(bio, nullptr, nullptr, nullptr) : nullptr;
     if (bio) BIO_free(bio);
-    if (!key) { m_error = "manifest public key invalid"; return false; }
+    if (!key) {
+        m_error = QCoreApplication::translate("IntegrityHelper",
+            "Manifest public key is invalid. Stage: installed version verification. Public key path: %1.")
+            .arg(keyPath);
+        return false;
+    }
     EVP_MD_CTX* ctx = EVP_MD_CTX_new();
     const QByteArray signature = QByteArray::fromBase64(signatureBase64.toUtf8());
     const bool ok = ctx && EVP_DigestVerifyInit(ctx, nullptr, EVP_sha256(), nullptr, key) == 1
@@ -76,65 +102,152 @@ bool IntegrityHelper::verifySignature(const QByteArray& payload, const QString&
         && EVP_DigestVerifyFinal(ctx, reinterpret_cast<const unsigned char*>(signature.constData()), signature.size()) == 1;
     if (ctx) EVP_MD_CTX_free(ctx);
     EVP_PKEY_free(key);
-    if (!ok) m_error = "manifest RSA signature invalid";
-    return ok;
-#endif
-}
+    if (!ok) {
+        m_error = QCoreApplication::translate("IntegrityHelper",
+            "Manifest RSA signature is invalid. Stage: installed version verification. This usually means the cached manifest was changed, the client public key does not match the server private key, or the wrong version cache is being used.");
+    }
+    return ok;
+#endif
+}
 
-bool IntegrityHelper::verifyInstalledVersion(const QString& appId, const QString& channel,
-                                             const QString& version)
-{
-    m_error.clear();
-    QString cachePath = QDir(ConfigHelper::instance().updateRoot()).filePath(
+bool IntegrityHelper::verifyInstalledVersion(const QString& appId, const QString& channel,
+                                             const QString& version)
+{
+    m_error.clear();
+    // Manifest cache 来自服务端发布版本时生成的签名清单。
+    // 客户端先验签 Manifest，再逐个校验文件 SHA256，防止升级文件被篡改或漏替换。
+    QString cachePath = QDir(ConfigHelper::instance().updateRoot()).filePath(
         "manifest_cache/manifest_" + version + ".json");
     const QString legacyCachePath = QDir(m_installDir).filePath(
         "update/manifest_cache/manifest_" + version + ".json");
     if (!QFile::exists(cachePath))
         cachePath = legacyCachePath;
     QFile cache(cachePath);
-    if (!cache.open(QIODevice::ReadOnly)) { m_error = "signed manifest cache missing for " + version; return false; }
+    if (!cache.open(QIODevice::ReadOnly)) {
+        m_error = QCoreApplication::translate("IntegrityHelper",
+            "Local signed manifest cache is missing. Stage: installed version verification. Version: %1. Expected cache file: %2. This cache is created after the same version is published or installed successfully.")
+            .arg(version, cachePath);
+        return false;
+    }
     QJsonParseError wrapperError;
-    const QJsonDocument wrapperDoc = QJsonDocument::fromJson(cache.readAll(), &wrapperError);
-    if (wrapperError.error != QJsonParseError::NoError || !wrapperDoc.isObject()) {
-        m_error = "manifest cache JSON invalid"; return false;
-    }
-    const QJsonObject wrapper = wrapperDoc.object();
-    const QByteArray manifestText = wrapper.value("manifest_text").toString().toUtf8();
-    const QString signature = wrapper.value("manifest").toObject().value("signature").toString();
-    if (manifestText.isEmpty() || signature.isEmpty() || !verifySignature(manifestText, signature)) return false;
+    const QJsonDocument wrapperDoc = QJsonDocument::fromJson(cache.readAll(), &wrapperError);
+    if (wrapperError.error != QJsonParseError::NoError || !wrapperDoc.isObject()) {
+        m_error = QCoreApplication::translate("IntegrityHelper",
+            "Local signed manifest cache is not valid JSON. Stage: installed version verification. Version: %1. File: %2. JSON error: %3.")
+            .arg(version, cachePath, wrapperError.errorString());
+        return false;
+    }
+    const QJsonObject wrapper = wrapperDoc.object();
+    QByteArray manifestText = wrapper.value("manifestText").toString().toUtf8();
+    if (manifestText.isEmpty())
+        manifestText = wrapper.value("manifest_text").toString().toUtf8();
+    const QString manifestSha256 = wrapper.value("manifestSha256").toString(
+        wrapper.value("manifest_sha256").toString());
+    const QString signature = wrapper.value("signature").toString(
+        wrapper.value("manifest").toObject().value("signature").toString());
+    const bool signedManifest = wrapper.value("signed").toBool(!signature.isEmpty());
+    if (manifestText.isEmpty()) {
+        m_error = QCoreApplication::translate("IntegrityHelper",
+            "Local signed manifest cache is incomplete. Stage: installed version verification. Version: %1. File: %2.")
+            .arg(version, cachePath);
+        return false;
+    }
+    if (!manifestSha256.isEmpty()) {
+        const QString actualSha = QString::fromLatin1(
+            QCryptographicHash::hash(manifestText, QCryptographicHash::Sha256).toHex());
+        if (actualSha.compare(manifestSha256, Qt::CaseInsensitive) != 0) {
+            m_error = QCoreApplication::translate("IntegrityHelper",
+                "Local manifest SHA-256 does not match the cached envelope. Stage: installed version verification. Version: %1.\nExpected SHA-256: %2\nActual SHA-256: %3")
+                .arg(version, manifestSha256, actualSha);
+            return false;
+        }
+    }
+    if (signedManifest && !signature.isEmpty()) {
+        if (!verifySignature(manifestText, signature)) return false;
+    } else if (configFlag(QStringLiteral("require_manifest_signature"))) {
+        m_error = QCoreApplication::translate("IntegrityHelper",
+            "Local manifest cache is unsigned, but require_manifest_signature is enabled. Stage: installed version verification. Version: %1.")
+            .arg(version);
+        return false;
+    }
 
     QJsonParseError manifestError;
-    const QJsonDocument manifestDoc = QJsonDocument::fromJson(manifestText, &manifestError);
-    if (manifestError.error != QJsonParseError::NoError || !manifestDoc.isObject()) {
-        m_error = "signed manifest payload invalid"; return false;
-    }
+    const QJsonDocument manifestDoc = QJsonDocument::fromJson(manifestText, &manifestError);
+    if (manifestError.error != QJsonParseError::NoError || !manifestDoc.isObject()) {
+        m_error = QCoreApplication::translate("IntegrityHelper",
+            "Signed manifest payload is not valid JSON. Stage: installed version verification. Version: %1. File: %2. JSON error: %3.")
+            .arg(version, cachePath, manifestError.errorString());
+        return false;
+    }
     const QJsonObject manifest = manifestDoc.object();
-    if (manifest.value("app_id").toString() != appId
-        || manifest.value("channel").toString() != channel
-        || manifest.value("version").toString() != version) {
-        m_error = "manifest identity does not match local application"; return false;
-    }
+    const QString manifestProduct = manifest.value("productCode").toString(
+        manifest.value("app_id").toString());
+    if (manifestProduct != appId
+        || manifest.value("channel").toString() != channel
+        || manifest.value("version").toString() != version) {
+        m_error = QCoreApplication::translate("IntegrityHelper",
+            "Local signed manifest identity does not match this application. Stage: installed version verification. Expected product/channel/version: %1 / %2 / %3. Manifest product/channel/version: %4 / %5 / %6.")
+            .arg(appId, channel, version,
+                 manifestProduct,
+                 manifest.value("channel").toString(),
+                 manifest.value("version").toString());
+        return false;
+    }
 
-    QSet<QString> declaredExecutables;
-    for (const QJsonValue& value : manifest.value("files").toArray()) {
-        const QJsonObject item = value.toObject();
-        const QString path = QDir::fromNativeSeparators(item.value("path").toString());
-        if (!safeRelativePath(path)) { m_error = "unsafe manifest path: " + path; return false; }
-        if (runtimeProtectedPath(path)) continue;
-        const QString fullPath = QDir(m_installDir).filePath(path);
-        if (!QFile::exists(fullPath)) { m_error = "required file missing: " + path; return false; }
-        const QString expected = item.value("sha256").toString();
-        const QString actual = sha256(fullPath);
-        if (actual.isEmpty() || actual.compare(expected, Qt::CaseInsensitive) != 0) {
-            m_error = "file hash mismatch: " + path; return false;
-        }
-        const QString suffix = QFileInfo(path).suffix().toCaseFolded();
-        if (suffix == "exe" || suffix == "dll") declaredExecutables.insert(path.toCaseFolded());
-    }
+    QSet<QString> declaredExecutables;
+    QSet<QString> optionalComponentDirs;
+    for (const QJsonValue& value : manifest.value("files").toArray()) {
+        const QJsonObject item = value.toObject();
+        const QString path = QDir::fromNativeSeparators(item.value("path").toString());
+        if (!safeRelativePath(path)) {
+            m_error = QCoreApplication::translate("IntegrityHelper",
+                "Signed manifest contains an unsafe file path. Stage: installed version verification. Version: %1. Path: %2.")
+                .arg(version, path);
+            return false;
+        }
+        if (UpdatePathPolicy::isExecutableOrLibrary(path))
+            declaredExecutables.insert(path.toCaseFolded());
+        if (!manifestFileRequired(item)) {
+            const QString dir = QDir::fromNativeSeparators(QFileInfo(path).path());
+            if (!dir.isEmpty() && dir != QStringLiteral("."))
+                optionalComponentDirs.insert((dir + QStringLiteral("/")).toCaseFolded());
+            continue;
+        }
+        if (runtimeProtectedPath(path)) continue;
+        const QString fullPath = QDir(m_installDir).filePath(path);
+        if (!QFile::exists(fullPath)) {
+            m_error = QCoreApplication::translate("IntegrityHelper",
+                "A required installed file is missing. Stage: installed version verification. Version: %1. Manifest path: %2. Checked path: %3. The local installation no longer matches the published version.")
+                .arg(version, path, fullPath);
+            return false;
+        }
+        const qint64 expectedSize = item.contains("sizeBytes")
+            ? item.value("sizeBytes").toVariant().toLongLong()
+            : item.value("size").toVariant().toLongLong();
+        if ((item.contains("sizeBytes") || item.contains("size"))
+            && QFileInfo(fullPath).size() != expectedSize) {
+            m_error = QCoreApplication::translate("IntegrityHelper",
+                "Installed file size does not match the local manifest. Stage: installed version verification. Version: %1. Manifest path: %2. Local path: %3.\nExpected size: %4 bytes\nActual size: %5 bytes")
+                .arg(version, path, fullPath,
+                     QString::number(expectedSize), QString::number(QFileInfo(fullPath).size()));
+            return false;
+        }
+        const QString expected = item.value("sha256").toString();
+        const QString actual = sha256(fullPath);
+        if (actual.isEmpty() || actual.compare(expected, Qt::CaseInsensitive) != 0) {
+            m_error = QCoreApplication::translate("IntegrityHelper",
+                "Installed file SHA-256 does not match the local signed manifest. Stage: installed version verification. Version: %1. Manifest path: %2. Local path: %3.\nExpected SHA-256: %4\nActual SHA-256: %5\nThis means the installed file is different from the version that was published or installed. If this is a developer test machine, check whether the local Release directory was recompiled or overwritten after publishing.")
+                .arg(version, path, fullPath, expected,
+                     actual.isEmpty() ? QCoreApplication::translate("IntegrityHelper", "<cannot read file>") : actual);
+            return false;
+        }
+    }
 
-    QDir root(m_installDir);
-    QDirIterator it(m_installDir, QDir::Files, QDirIterator::Subdirectories);
-    while (it.hasNext()) {
+    QDir root(m_installDir);
+    QDirIterator it(m_installDir, QDir::Files, QDirIterator::Subdirectories);
+    // 除了清单中声明的文件，还要拒绝额外出现的 exe/dll。
+    // 这能降低被人偷偷塞插件或可执行文件的风险。
+    while (it.hasNext()) {
         const QString fullPath = it.next();
         const QString relative = QDir::fromNativeSeparators(root.relativeFilePath(fullPath));
         const QString folded = relative.toCaseFolded();
@@ -142,12 +255,23 @@ bool IntegrityHelper::verifyInstalledVersion(const QString& appId, const QString
         const bool runtimeWorkDir = !runtimePrefix.isEmpty()
             && (folded.startsWith(runtimePrefix + "/update/")
                 || folded.startsWith(runtimePrefix + "/update_temp/"));
-        if (folded.startsWith("update/") || folded.startsWith("update_temp/")
-            || runtimeWorkDir || runtimeProtectedPath(relative)) continue;
-        const QString suffix = QFileInfo(relative).suffix().toCaseFolded();
-        if ((suffix == "exe" || suffix == "dll") && !declaredExecutables.contains(folded)) {
-            m_error = "undeclared executable or plugin: " + relative; return false;
-        }
+        if (folded.startsWith("update/") || folded.startsWith("update_temp/")
+            || runtimeWorkDir || runtimeProtectedPath(relative)) continue;
+        bool optionalComponentFile = false;
+        for (const QString& prefix : optionalComponentDirs) {
+            if (folded.startsWith(prefix)) {
+                optionalComponentFile = true;
+                break;
+            }
+        }
+        if (optionalComponentFile)
+            continue;
+        if (UpdatePathPolicy::isExecutableOrLibrary(relative) && !declaredExecutables.contains(folded)) {
+            m_error = QCoreApplication::translate("IntegrityHelper",
+                "An executable or DLL exists locally but is not declared in the signed manifest. Stage: installed version verification. Version: %1. Extra file: %2. Remove unexpected executable/plugin files or publish a new version that declares them.")
+                .arg(version, relative);
+            return false;
+        }
     }
     return true;
 }

Common/LocalStateHelper.cpp

@@ -1,17 +1,25 @@
 #include "LocalStateHelper.h"
 #include "ConfigHelper.h"
+#include <QCoreApplication>
+#include <QDir>
 #include <QFile>
 #include <QJsonDocument>
 
-LocalStateHelper::LocalStateHelper(const QString& baseDir)
-    : m_baseDir(baseDir)
-    , m_filePath(baseDir + "/config/local_state.json")
-{
-}
-
-bool LocalStateHelper::loadState(const QString& relativePath)
-{
-    m_filePath = m_baseDir + "/" + relativePath;
+LocalStateHelper::LocalStateHelper(const QString& baseDir)
+    : m_baseDir(baseDir)
+    , m_filePath(ConfigHelper::instance().localStatePath())
+{
+}
+
+bool LocalStateHelper::loadState(const QString& relativePath)
+{
+    const QString defaultState = QStringLiteral("config/local_state.json");
+    if (relativePath == defaultState)
+        m_filePath = ConfigHelper::instance().localStatePath();
+    else if (QDir::isAbsolutePath(relativePath))
+        m_filePath = relativePath;
+    else
+        m_filePath = m_baseDir + "/" + relativePath;
     QFile file(m_filePath);
     if (!file.exists())
     {
@@ -22,30 +30,39 @@ bool LocalStateHelper::loadState(const QString& relativePath)
             {"last_success_version", QString()}
         };
         m_loaded = true;
-        if (!saveState())
-        {
-            m_error = QString("Cannot write new state file: %1").arg(m_filePath);
-            return false;
-        }
-        return true;
+        if (!saveState())
+        {
+            m_error = QCoreApplication::translate(
+                "LocalStateHelper",
+                "Cannot create local state file: %1. Error: %2.")
+                .arg(m_filePath, m_error);
+            return false;
+        }
+        return true;
     }
 
-    if (!file.open(QIODevice::ReadOnly))
-    {
-        m_error = QString("Cannot open state file: %1").arg(m_filePath);
-        return false;
-    }
+    if (!file.open(QIODevice::ReadOnly))
+    {
+        m_error = QCoreApplication::translate(
+            "LocalStateHelper",
+            "Cannot open local state file: %1. Error: %2.")
+            .arg(m_filePath, file.errorString());
+        return false;
+    }
 
     QByteArray raw = file.readAll();
     file.close();
 
     QJsonParseError parseError;
     QJsonDocument doc = QJsonDocument::fromJson(raw, &parseError);
-    if (parseError.error != QJsonParseError::NoError || !doc.isObject())
-    {
-        m_error = QString("Invalid state JSON: %1").arg(parseError.errorString());
-        return false;
-    }
+    if (parseError.error != QJsonParseError::NoError || !doc.isObject())
+    {
+        m_error = QCoreApplication::translate(
+            "LocalStateHelper",
+            "Local state file is not valid JSON. File: %1. JSON error: %2.")
+            .arg(m_filePath, parseError.errorString());
+        return false;
+    }
 
     m_state = doc.object();
     m_loaded = true;
@@ -56,7 +73,9 @@ bool LocalStateHelper::saveState() const
 {
     if (!m_loaded)
     {
-        m_error = "State is not loaded";
+        m_error = QCoreApplication::translate(
+            "LocalStateHelper",
+            "Local state has not been loaded.");
         return false;
     }
 
@@ -64,7 +83,10 @@ bool LocalStateHelper::saveState() const
     QString writeError;
     if (!ConfigHelper::writeFileWithElevationIfNeeded(m_filePath, doc.toJson(QJsonDocument::Indented), &writeError))
     {
-        m_error = QString("Cannot save state file: %1").arg(writeError);
+        m_error = QCoreApplication::translate(
+            "LocalStateHelper",
+            "Cannot save local state file: %1. Error: %2.")
+            .arg(m_filePath, writeError);
         return false;
     }
     m_error.clear();

Common/PolicyHelper.cpp

@@ -1,7 +1,9 @@
 #include "PolicyHelper.h"
 #include "ConfigHelper.h"
 #include <QApplication>
+#include <QCoreApplication>
 #include <QDateTime>
+#include <QDir>
 #include <QFile>
 #include <QJsonArray>
 #include <QJsonDocument>
@@ -11,19 +13,43 @@
 #include <openssl/pem.h>
 #endif
 
-PolicyHelper::PolicyHelper(const QString& baseDir) : m_baseDir(baseDir) {}
-
-bool PolicyHelper::loadPolicy(const QString& relativePath)
-{
-    QFile file(m_baseDir + "/" + relativePath);
-    if (!file.open(QIODevice::ReadOnly)) { m_error = "Cannot open policy file"; return false; }
-    QJsonParseError error;
-    const QJsonDocument doc = QJsonDocument::fromJson(file.readAll(), &error);
-    if (error.error != QJsonParseError::NoError || !doc.isObject()) {
-        m_error = "Invalid policy JSON: " + error.errorString(); return false;
-    }
-    return loadPolicyObject(doc.object());
-}
+PolicyHelper::PolicyHelper(const QString& baseDir) : m_baseDir(baseDir) {}
+
+static QString resolvePolicyPath(const QString& baseDir, const QString& relativePath, bool forWrite)
+{
+    const QString defaultPolicy = QStringLiteral("config/version_policy.dat");
+    if (relativePath == defaultPolicy) {
+        const QString runtimePolicy = ConfigHelper::instance().policyPath();
+        if (forWrite || QFile::exists(runtimePolicy))
+            return runtimePolicy;
+    }
+    if (QDir::isAbsolutePath(relativePath))
+        return relativePath;
+    return baseDir + "/" + relativePath;
+}
+
+bool PolicyHelper::loadPolicy(const QString& relativePath)
+{
+    const QString path = resolvePolicyPath(m_baseDir, relativePath, false);
+    QFile file(path);
+    if (!file.open(QIODevice::ReadOnly)) {
+        m_error = QCoreApplication::translate(
+            "PolicyHelper",
+            "Cannot open signed version policy file: %1. Error: %2.")
+            .arg(path, file.errorString());
+        return false;
+    }
+    QJsonParseError error;
+    const QJsonDocument doc = QJsonDocument::fromJson(file.readAll(), &error);
+    if (error.error != QJsonParseError::NoError || !doc.isObject()) {
+        m_error = QCoreApplication::translate(
+            "PolicyHelper",
+            "Signed version policy is not valid JSON. File: %1. JSON error: %2.")
+            .arg(path, error.errorString());
+        return false;
+    }
+    return loadPolicyObject(doc.object());
+}
 
 bool PolicyHelper::loadPolicyObject(const QJsonObject& policy, const QString& signedText)
 {
@@ -35,8 +61,12 @@ bool PolicyHelper::savePolicy(const QString& relativePath) const
 {
     const QByteArray bytes = QJsonDocument(m_policy).toJson(QJsonDocument::Indented);
     QString writeError;
-    if (!ConfigHelper::writeFileWithElevationIfNeeded(m_baseDir + "/" + relativePath, bytes, &writeError)) {
-        m_error = "Cannot save policy file: " + writeError;
+    const QString path = resolvePolicyPath(m_baseDir, relativePath, true);
+    if (!ConfigHelper::writeFileWithElevationIfNeeded(path, bytes, &writeError)) {
+        m_error = QCoreApplication::translate(
+            "PolicyHelper",
+            "Cannot save signed version policy file: %1. Error: %2.")
+            .arg(path, writeError);
         return false;
     }
     m_error.clear();
@@ -69,35 +99,73 @@ QByteArray PolicyHelper::canonicalPolicyBytes(const QJsonObject& policy) const
 
 bool PolicyHelper::verifySignature(const QByteArray& payload, const QString& signatureBase64) const
 {
-#ifndef HAVE_OPENSSL
-    Q_UNUSED(payload); Q_UNUSED(signatureBase64); m_error = "OpenSSL unavailable"; return false;
-#else
-    QString keyPath = m_baseDir + "/config/manifest_public_key.pem";
-    QFile keyFile(keyPath);
-    if (!keyFile.open(QIODevice::ReadOnly)) { m_error = "Cannot open policy public key"; return false; }
+#ifndef HAVE_OPENSSL
+    Q_UNUSED(payload);
+    Q_UNUSED(signatureBase64);
+    m_error = QCoreApplication::translate(
+        "PolicyHelper",
+        "OpenSSL is unavailable, so the signed version policy cannot be verified.");
+    return false;
+#else
+    QString keyPath = m_baseDir + "/config/manifest_public_key.pem";
+    QFile keyFile(keyPath);
+    if (!keyFile.open(QIODevice::ReadOnly)) {
+        m_error = QCoreApplication::translate(
+            "PolicyHelper",
+            "Cannot open version policy public key: %1. Error: %2.")
+            .arg(keyPath, keyFile.errorString());
+        return false;
+    }
     const QByteArray keyData = keyFile.readAll();
     BIO* bio = BIO_new_mem_buf(keyData.constData(), keyData.size());
     EVP_PKEY* key = bio ? PEM_read_bio_PUBKEY(bio, nullptr, nullptr, nullptr) : nullptr;
     if (bio) BIO_free(bio);
-    if (!key) { m_error = "Invalid policy public key"; return false; }
+    if (!key) {
+        m_error = QCoreApplication::translate(
+            "PolicyHelper",
+            "Version policy public key is invalid: %1.")
+            .arg(keyPath);
+        return false;
+    }
     EVP_MD_CTX* ctx = EVP_MD_CTX_new();
     const QByteArray signature = QByteArray::fromBase64(signatureBase64.toUtf8());
     bool ok = ctx && EVP_DigestVerifyInit(ctx, nullptr, EVP_sha256(), nullptr, key) == 1
         && EVP_DigestVerifyUpdate(ctx, payload.constData(), payload.size()) == 1
         && EVP_DigestVerifyFinal(ctx, reinterpret_cast<const unsigned char*>(signature.constData()), signature.size()) == 1;
     if (ctx) EVP_MD_CTX_free(ctx); EVP_PKEY_free(key);
-    if (!ok) m_error = "Invalid RSA policy signature";
-    return ok;
-#endif
-}
+    if (!ok) {
+        m_error = QCoreApplication::translate(
+            "PolicyHelper",
+            "Version policy RSA signature is invalid. The policy file may have been changed, or the public key does not match the server private key.");
+    }
+    return ok;
+#endif
+}
 
 bool PolicyHelper::isValid() const
 {
-    if (!m_loaded) return false;
-    const QStringList required{"app_id","channel","current_version","policy_seq","allow_run",
-        "force_update","allow_rollback","offline_allowed","valid_until","signature_alg","key_id","signature"};
-    for (const QString& key : required) if (!m_policy.contains(key)) { m_error = "Missing policy field: " + key; return false; }
-    if (m_policy.value("signature_alg").toString() != "RSA-2048-SHA256") return false;
+    if (!m_loaded) {
+        m_error = QCoreApplication::translate("PolicyHelper", "Version policy has not been loaded.");
+        return false;
+    }
+    const QStringList required{"app_id","channel","current_version","policy_seq","allow_run",
+        "force_update","allow_rollback","offline_allowed","valid_until","signature_alg","key_id","signature"};
+    for (const QString& key : required) {
+        if (!m_policy.contains(key)) {
+            m_error = QCoreApplication::translate(
+                "PolicyHelper",
+                "Version policy is missing required field: %1.")
+                .arg(key);
+            return false;
+        }
+    }
+    if (m_policy.value("signature_alg").toString() != "RSA-2048-SHA256") {
+        m_error = QCoreApplication::translate(
+            "PolicyHelper",
+            "Version policy signature algorithm is unsupported: %1.")
+            .arg(m_policy.value("signature_alg").toString());
+        return false;
+    }
     const QByteArray payload = m_signedText.isEmpty() ? canonicalPolicyBytes(m_policy) : m_signedText.toUtf8();
     return verifySignature(payload, m_policy.value("signature").toString());
 }
@@ -108,10 +176,11 @@ bool PolicyHelper::isVersionAllowed(const QString& version) const {
     return true;
 }
 bool PolicyHelper::allowRun() const { return isValid() && m_policy.value("allow_run").toBool(); }
-bool PolicyHelper::forceUpdate() const { return isValid() && m_policy.value("force_update").toBool(); }
-bool PolicyHelper::allowRollback() const { return isValid() && m_policy.value("allow_rollback").toBool(); }
-bool PolicyHelper::isOfflineAllowed() const { return isValid() && m_policy.value("offline_allowed").toBool(); }
-bool PolicyHelper::isExpired() const {
+bool PolicyHelper::forceUpdate() const { return isValid() && m_policy.value("force_update").toBool(); }
+bool PolicyHelper::allowRollback() const { return isValid() && m_policy.value("allow_rollback").toBool(); }
+bool PolicyHelper::isOfflineAllowed() const { return isValid() && m_policy.value("offline_allowed").toBool(); }
+bool PolicyHelper::gitTagsEnabled() const { return isValid() && m_policy.value("git_tags_enabled").toBool(); }
+bool PolicyHelper::isExpired() const {
     if (!isValid()) return true;
     const QDateTime expiry = QDateTime::fromString(m_policy.value("valid_until").toString(), Qt::ISODate);
     return !expiry.isValid() || QDateTime::currentDateTimeUtc() > expiry;

Common/PolicyHelper.h

@@ -15,9 +15,10 @@ public:
     bool isVersionAllowed(const QString& currentVersion) const;
     bool allowRun() const;
     bool forceUpdate() const;
-    bool allowRollback() const;
-    bool isOfflineAllowed() const;
-    bool isExpired() const;
+    bool allowRollback() const;
+    bool isOfflineAllowed() const;
+    bool gitTagsEnabled() const;
+    bool isExpired() const;
     qint64 policySeq() const;
     QString message() const;
 

Common/TicketHelper.cpp

@@ -5,25 +5,38 @@
 #include <QFile>
 #include <QJsonDocument>
 #include <QJsonObject>
-#include <QMessageAuthenticationCode>
-#include <QSaveFile>
-#include <QStandardPaths>
-#include <QUuid>
+#include <QMessageAuthenticationCode>
+#include <QSaveFile>
+#include <QStandardPaths>
+#include <QStringList>
+#include <QUuid>
 
-static QByteArray ticketMac(const QJsonObject& payload, const QString& secret)
-{
+static QByteArray ticketMac(const QJsonObject& payload, const QString& secret)
+{
     return QMessageAuthenticationCode::hash(
         QJsonDocument(payload).toJson(QJsonDocument::Compact), secret.toUtf8(), QCryptographicHash::Sha256).toHex();
 }
 
-bool TicketHelper::createTicket(const QString& appId, const QString& deviceId,
-                                const QString& version, const QString& secret,
-                                QString* ticketPath, QString* errorMessage)
-{
-    if (appId.isEmpty() || version.isEmpty() || secret.isEmpty()) {
-        if (errorMessage) *errorMessage = "ticket identity or secret is empty";
-        return false;
-    }
+bool TicketHelper::createTicket(const QString& appId, const QString& deviceId,
+                                const QString& version, const QString& secret,
+                                QString* ticketPath, QString* errorMessage)
+{
+    // Launcher 启动业务主程序前生成一次性 ticket。
+    // ticket 只保存在临时目录、有效期 60 秒，并用 launch_token 做 HMAC，防止用户绕过 Launcher 直接启动主程序。
+    if (appId.isEmpty() || deviceId.isEmpty() || version.isEmpty() || secret.isEmpty()) {
+        if (errorMessage) {
+            QStringList missing;
+            if (appId.isEmpty()) missing.append(QStringLiteral("app_id"));
+            if (deviceId.isEmpty()) missing.append(QStringLiteral("device_id"));
+            if (version.isEmpty()) missing.append(QStringLiteral("current_version"));
+            if (secret.isEmpty()) missing.append(QStringLiteral("launch_token"));
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Cannot create launch ticket because required fields are empty: %1. Check app_config.json, registry-imported configuration and device authorization.")
+                .arg(missing.join(QStringLiteral(", ")));
+        }
+        return false;
+    }
     const QDateTime now = QDateTime::currentDateTimeUtc();
     QJsonObject payload{
         {"app_id", appId}, {"device_id", deviceId}, {"version", version},
@@ -34,42 +47,73 @@ bool TicketHelper::createTicket(const QString& appId, const QString& deviceId,
     };
     QJsonObject wrapper{{"payload", payload}, {"signature", QString::fromLatin1(ticketMac(payload, secret))}};
     const QString dirPath = QDir(QStandardPaths::writableLocation(QStandardPaths::TempLocation)).filePath("marsco_tickets");
-    if (!QDir().mkpath(dirPath)) { if (errorMessage) *errorMessage = "cannot create ticket directory"; return false; }
+    if (!QDir().mkpath(dirPath)) {
+        if (errorMessage) {
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Cannot create launch ticket directory: %1.")
+                .arg(dirPath);
+        }
+        return false;
+    }
     const QString path = QDir(dirPath).filePath("ticket_" + QUuid::createUuid().toString(QUuid::WithoutBraces) + ".json");
-    QSaveFile file(path);
-    const QByteArray bytes = QJsonDocument(wrapper).toJson(QJsonDocument::Compact);
-    if (!file.open(QIODevice::WriteOnly) || file.write(bytes) != bytes.size() || !file.commit()) {
-        if (errorMessage) *errorMessage = "cannot save ticket";
-        return false;
-    }
+    QSaveFile file(path);
+    const QByteArray bytes = QJsonDocument(wrapper).toJson(QJsonDocument::Compact);
+    if (!file.open(QIODevice::WriteOnly) || file.write(bytes) != bytes.size() || !file.commit()) {
+        if (errorMessage) {
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Cannot save launch ticket file: %1. Error: %2.")
+                .arg(path, file.errorString());
+        }
+        return false;
+    }
     QFile::setPermissions(path, QFileDevice::ReadOwner | QFileDevice::WriteOwner);
     if (ticketPath) *ticketPath = path;
     return true;
 }
 
-bool TicketHelper::consumeAndVerify(const QString& ticketPath, const QString& expectedAppId,
-                                    const QString& expectedDeviceId, const QString& expectedVersion,
-                                    const QString& secret, QString* errorMessage)
-{
-    const QString consumingPath = ticketPath + ".consuming."
-        + QString::number(QCoreApplication::applicationPid());
-    if (!QFile::rename(ticketPath, consumingPath)) {
-        if (errorMessage) *errorMessage = "ticket missing or already consumed";
-        return false;
-    }
-    QFile file(consumingPath);
-    if (!file.open(QIODevice::ReadOnly)) {
-        QFile::remove(consumingPath);
-        if (errorMessage) *errorMessage = "cannot read claimed ticket";
-        return false;
-    }
+bool TicketHelper::consumeAndVerify(const QString& ticketPath, const QString& expectedAppId,
+                                    const QString& expectedDeviceId, const QString& expectedVersion,
+                                    const QString& secret, QString* errorMessage)
+{
+    // 主程序启动后第一时间把 ticket 改名成 .consuming，再读取并删除。
+    // 这样同一张 ticket 即使校验失败也不能被重复使用，避免重放启动。
+    const QString consumingPath = ticketPath + ".consuming."
+        + QString::number(QCoreApplication::applicationPid());
+    if (!QFile::rename(ticketPath, consumingPath)) {
+        if (errorMessage) {
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Launch ticket is missing or has already been consumed. Ticket file: %1. Please start the application from Launcher.")
+                .arg(ticketPath);
+        }
+        return false;
+    }
+    QFile file(consumingPath);
+    if (!file.open(QIODevice::ReadOnly)) {
+        QFile::remove(consumingPath);
+        if (errorMessage) {
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Cannot read claimed launch ticket: %1. Error: %2.")
+                .arg(consumingPath, file.errorString());
+        }
+        return false;
+    }
     const QByteArray raw = file.readAll(); file.close();
     QFile::remove(consumingPath); // Consume once; it must not be replayed regardless of success or failure.
     QJsonParseError parseError;
-    const QJsonDocument doc = QJsonDocument::fromJson(raw, &parseError);
-    if (parseError.error != QJsonParseError::NoError || !doc.isObject()) {
-        if (errorMessage) *errorMessage = "invalid ticket JSON"; return false;
-    }
+    const QJsonDocument doc = QJsonDocument::fromJson(raw, &parseError);
+    if (parseError.error != QJsonParseError::NoError || !doc.isObject()) {
+        if (errorMessage) {
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Launch ticket is not valid JSON. JSON error: %1.")
+                .arg(parseError.errorString());
+        }
+        return false;
+    }
     const QJsonObject wrapper = doc.object();
     const QJsonObject payload = wrapper.value("payload").toObject();
     const QByteArray actual = wrapper.value("signature").toString().toLatin1();
@@ -80,27 +124,57 @@ bool TicketHelper::consumeAndVerify(const QString& ticketPath, const QString& ex
     const bool timeOk = issued.isValid() && expires.isValid() && issued <= now.addSecs(5)
         && expires >= now && issued.secsTo(expires) <= 65;
     if (actual.isEmpty() || actual != expected) {
-        if (errorMessage) *errorMessage = "ticket signature invalid; check launch_token";
+        if (errorMessage) {
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Launch ticket signature is invalid. The launch_token used by Launcher and the main application is inconsistent, or the ticket content was changed.");
+        }
         return false;
     }
     if (payload.value("app_id").toString() != expectedAppId) {
-        if (errorMessage) *errorMessage = "ticket app_id mismatch";
+        if (errorMessage) {
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Launch ticket app_id does not match. Ticket app_id: %1. Expected app_id: %2.")
+                .arg(payload.value("app_id").toString(), expectedAppId);
+        }
         return false;
     }
     if (payload.value("device_id").toString() != expectedDeviceId) {
-        if (errorMessage) *errorMessage = "ticket device_id mismatch";
+        if (errorMessage) {
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Launch ticket device_id does not match. Ticket device_id: %1. Expected device_id: %2. Reauthorize the device from Launcher if the configuration was regenerated.")
+                .arg(payload.value("device_id").toString(), expectedDeviceId);
+        }
         return false;
     }
     if (payload.value("version").toString() != expectedVersion) {
-        if (errorMessage) *errorMessage = "ticket version mismatch";
+        if (errorMessage) {
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Launch ticket version does not match. Ticket version: %1. Expected version: %2.")
+                .arg(payload.value("version").toString(), expectedVersion);
+        }
         return false;
     }
     if (!timeOk) {
-        if (errorMessage) *errorMessage = "ticket time invalid or expired";
+        if (errorMessage) {
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Launch ticket time is invalid or expired. Issued at: %1. Expires at: %2. Current UTC time: %3.")
+                .arg(payload.value("issued_at").toString(),
+                     payload.value("expires_at").toString(),
+                     now.toString(Qt::ISODate));
+        }
         return false;
     }
     if (payload.value("nonce").toString().isEmpty()) {
-        if (errorMessage) *errorMessage = "ticket nonce missing";
+        if (errorMessage) {
+            *errorMessage = QCoreApplication::translate(
+                "TicketHelper",
+                "Launch ticket nonce is missing. The ticket is incomplete.");
+        }
         return false;
     }
     return true;

Common/UpdatePathPolicy.cpp

@@ -0,0 +1,127 @@
+#include "UpdatePathPolicy.h"
+
+#include <QDir>
+#include <QFileInfo>
+#include <QSet>
+#include <QStringList>
+
+namespace {
+
+bool exactOrRuntimeMatch(const QString& folded, const QString& runtimePrefix,
+                         const QSet<QString>& exactPaths)
+{
+    if (exactPaths.contains(folded))
+        return true;
+    if (runtimePrefix.isEmpty() || !folded.startsWith(runtimePrefix + QStringLiteral("/")))
+        return false;
+    return exactPaths.contains(folded.mid(runtimePrefix.size() + 1));
+}
+
+bool prefixOrRuntimePrefixMatch(const QString& folded, const QString& runtimePrefix,
+                                const QString& prefix)
+{
+    if (folded.startsWith(prefix))
+        return true;
+    if (runtimePrefix.isEmpty())
+        return false;
+    return folded.startsWith(runtimePrefix + QStringLiteral("/") + prefix);
+}
+
+} // namespace
+
+namespace UpdatePathPolicy {
+
+QString normalizeRelativePath(const QString& path)
+{
+    QString normalized = QDir::cleanPath(QDir::fromNativeSeparators(path.trimmed()));
+    if (normalized == QStringLiteral("."))
+        return QString();
+    while (normalized.startsWith(QStringLiteral("./")))
+        normalized = normalized.mid(2);
+    return normalized;
+}
+
+bool isSafeRelativePath(const QString& path)
+{
+    const QString clean = normalizeRelativePath(path);
+    return !clean.isEmpty() && !QDir::isAbsolutePath(clean) && clean != QStringLiteral("..")
+        && !clean.startsWith(QStringLiteral("../")) && !clean.contains(QLatin1Char(':'));
+}
+
+bool isUpdaterRuntimeProtectedPath(const QString& path, const QString& runtimeRelativePath)
+{
+    const QString folded = normalizeRelativePath(path).toCaseFolded();
+    const QString runtimePrefix = normalizeRelativePath(runtimeRelativePath).toCaseFolded();
+    const QSet<QString> exactPaths{
+        QStringLiteral("bootstrap"),
+        QStringLiteral("bootstrap.exe"),
+        QStringLiteral("launcher"),
+        QStringLiteral("launcher.exe"),
+        QStringLiteral("updater"),
+        QStringLiteral("updater.exe"),
+        QStringLiteral("client.ini"),
+        QStringLiteral("config/app_config.json"),
+        QStringLiteral("config/local_state.json"),
+        QStringLiteral("config/client_identity.dat"),
+        QStringLiteral("config/version_policy.dat")
+    };
+    if (exactOrRuntimeMatch(folded, runtimePrefix, exactPaths))
+        return true;
+    return prefixOrRuntimePrefixMatch(folded, runtimePrefix, QStringLiteral("update/"))
+        || prefixOrRuntimePrefixMatch(folded, runtimePrefix, QStringLiteral("update_temp/"));
+}
+
+bool isIFWInstallerManagedPath(const QString& path)
+{
+    const QString folded = normalizeRelativePath(path).toCaseFolded();
+    if (folded.isEmpty())
+        return false;
+
+    const bool rootFile = !folded.contains(QLatin1Char('/'));
+    if (rootFile && (folded == QStringLiteral("maintenancetool")
+            || folded == QStringLiteral("maintenancetool.exe")
+            || folded.startsWith(QStringLiteral("maintenancetool.")))) {
+        return true;
+    }
+
+    const QSet<QString> exactPaths{
+        QStringLiteral("components.xml"),
+        QStringLiteral("components.xml.new"),
+        QStringLiteral("components.xml.old"),
+        QStringLiteral("installation.xml"),
+        QStringLiteral("installation.dat"),
+        QStringLiteral("installer.dat"),
+        QStringLiteral("installer.ini"),
+        QStringLiteral("network.xml"),
+        QStringLiteral("repositories.xml"),
+        QStringLiteral("repositories.cfg"),
+        QStringLiteral("repository.xml")
+    };
+    if (exactPaths.contains(folded))
+        return true;
+
+    const QStringList prefixes{
+        QStringLiteral("installerresources/"),
+        QStringLiteral("installationinformation/"),
+        QStringLiteral("licenses/")
+    };
+    for (const QString& prefix : prefixes) {
+        if (folded.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+
+bool isFullUpdateProtectedPath(const QString& path, const QString& runtimeRelativePath)
+{
+    return isUpdaterRuntimeProtectedPath(path, runtimeRelativePath)
+        || isIFWInstallerManagedPath(path);
+}
+
+bool isExecutableOrLibrary(const QString& path)
+{
+    const QString suffix = QFileInfo(path).suffix().toCaseFolded();
+    return suffix == QStringLiteral("exe") || suffix == QStringLiteral("dll");
+}
+
+} // namespace UpdatePathPolicy

Common/UpdatePathPolicy.h

@@ -0,0 +1,14 @@
+#pragma once
+
+#include <QString>
+
+namespace UpdatePathPolicy {
+
+QString normalizeRelativePath(const QString& path);
+bool isSafeRelativePath(const QString& path);
+bool isUpdaterRuntimeProtectedPath(const QString& path, const QString& runtimeRelativePath);
+bool isIFWInstallerManagedPath(const QString& path);
+bool isFullUpdateProtectedPath(const QString& path, const QString& runtimeRelativePath);
+bool isExecutableOrLibrary(const QString& path);
+
+}

Docs/00-先读我-客户端文档入口.txt

@@ -1,77 +0,0 @@
-客户端文档入口
-==============
-
-你第一次打开 update-client/Docs 时，先看这一份。这里告诉你每份文档是干什么的，以及不同角色应该从哪里开始。
-
-文档阅读顺序
-============
-
-1. 01-客户端接入打包部署指南.md
-   适合 SDK 接入方、测试人员和交付人员。按“生成 SDK -> 放进业务软件 -> 生成配置 -> 联调 -> 打最终包”的顺序写。
-
-2. 02-编译环境和第三方依赖说明.md
-   适合需要编译 Launcher、Updater、Bootstrap 的人。说明 Windows/Linux 下 Qt、OpenSSL、thirdparty/ 和 CMake 怎么准备。
-
-3. ../i18n/ReadMe.txt
-   适合维护界面文案的人。说明新增 tr() 后怎么更新 .ts、生成 .qm，并把翻译文件打进 qrc。
-
-常用任务入口
-============
-
-如果你只是拿到 SDK 接入业务软件：
-
-```text
-读 01-客户端接入打包部署指南.md 的“三、你：把 SDK 放进业务软件目录”和“四、你：生成并填写 app_config.json”。
-```
-
-如果你要重新打 Windows SDK 包：
-
-```powershell
-cd update-client
-.\scripts\package-sdk.ps1 -SourceDir .\out\bin -OutputDir .\dist\UpdateClientSDK -ZipFile .\dist\UpdateClientSDK.zip -SdkVersion 0.1.0
-```
-
-如果你要重新打 Linux SDK 包：
-
-```bash
-cd update-client
-cmake --preset linux-x64-release
-cmake --build --preset linux-x64-release
-bash ./scripts/package-sdk.sh --source-dir ./out/linux/bin --output-dir ./dist/UpdateClientSDK-linux --archive ./dist/UpdateClientSDK-linux.tar.gz --sdk-version 0.1.0
-```
-
-客户端配置速记
-==============
-
-config/app_config.json 是部署配置源文件。Launcher / Updater / MainApp 启动时会把它同步到当前用户的 QSettings 配置区；Windows 下对应注册表，Linux 下对应用户配置文件。后续运行配置优先从 QSettings 读取。
-config/server_config.json 是编译期服务端地址配置源文件。它通过 config/server_config.qrc 编进 Launcher / Updater / MainApp，不写入 app_config.json，也不写入注册表。修改 api_base_url 后必须重新编译客户端程序才会生效。
-如果 config/app_config.json 内容被修改，下一次启动时会按解析后的 JSON 内容 SHA256 判断变化并重新导入注册表。
-非空 app_config.json 成功导入注册表后会自动清空为 {}，文件保留不删除，方便下次直接粘贴管理后台生成的新配置。
-Windows 注册表位置：HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config。
-Linux 配置位置由 Qt QSettings 决定，通常在当前用户 home 目录的 .config/Marsco/UpdateClientSDK.conf 一类路径下。
-如果检测到 app_config.json 发生变化，SDK 会删除 config/client_identity.dat、config/version_policy.dat 和 config/local_state.json，避免继续使用旧授权身份、旧策略或旧防回滚状态；目录不可写时会弹出管理员权限确认框。
-正常启动成功后不要删除这些状态文件，它们用于本地身份、离线策略和安全状态。
-首次运行时如果该文件不存在且发现旧 client.ini，会自动迁移。
-
-接入新软件时通常需要修改：
-
-1. app_id、app_name、channel、current_version。
-2. client_token、license_key、launch_token。
-3. config/server_config.json 里的 api_base_url。
-4. main_executable：团队业务主程序文件名。
-5. launcher_executable、updater_executable、bootstrap_executable。
-6. health_check_timeout_ms：升级后等待业务程序健康确认的毫秒数，最小 1000。
-
-Windows 完整格式参考 update-client/config/app_config.example.json；Linux 完整格式参考 update-client/config/app_config.linux.example.json。
-运行时生成的 client_identity.dat、local_state.json 等文件不得打入通用 SDK 模板。app_config.json 可以作为部署模板，但不要把某台机器运行后产生的临时状态混进去。
-
-Windows 发布打包：
-
-1. 使用 Release 配置编译全部客户端程序。
-2. 先完成当前版本在线校验，确认 out/bin/update/manifest_cache 中存在对应的签名 Manifest。
-3. 准备一份实际 app_config.json，确认其中包含正确的 License Key、当前版本和业务程序名；确认客户端程序已用正确的 config/server_config.json 编译。
-4. 在 PowerShell 执行：
-   powershell -ExecutionPolicy Bypass -File .\scripts\package-client.ps1 -ConfigFile .\config\app_config.json
-5. 输出位于 dist/UpdateClient 和 dist/UpdateClient.zip。
-
-脚本会拒绝 Debug DLL、PDB、嵌套重复主程序和缺少签名 Manifest 的发布源目录。

Docs/01-客户端接入打包部署指南.md

@@ -1,417 +0,0 @@
-# UpdateClientSDK 客户端接入、打包和部署指南
-
-本文按“维护者打包 SDK -> 你接入业务软件 -> 联调测试 -> 生成最终客户端包”的顺序说明。你拿到这份文档后，按章节一步一步做即可。
-
-## 先看这里：你要做哪件事
-
-| 你的目标 | 直接看哪一节 |
-| --- | --- |
-| 重新生成给别人用的 SDK 包 | 二、维护者：生成 SDK 包 |
-| 把 SDK 放到 SimCAE 或其他业务软件目录 | 三、你：把 SDK 放进业务软件目录 |
-| 从后台生成 `app_config.json` 和 qrc 服务端配置 | 四、你：生成并填写客户端配置 |
-| 给业务主程序接入启动保护代码 | 五、你：业务主程序接入要求 |
-| 验证升级、回滚、健康检查 | 六、你：联调测试 |
-| 生成最终交付给用户的客户端包 | 七、维护者：生成最终客户端包 |
-
-## 一、这个 SDK 是什么
-
-UpdateClientSDK 是“独立更新器 SDK / 升级运行时 SDK”。它不是传统的 `include + lib` 形态，而是把自动升级能力做成一组独立程序，让业务软件通过这些程序完成检查更新、下载、安装、回滚和启动保护。
-
-SDK 核心程序：
-
-- `Launcher.exe` / `Launcher`：用户入口。检查版本、验证授权和策略，决定直接启动业务主程序或进入升级流程。
-- `Updater.exe` / `Updater`：下载、校验、备份、安装、健康确认、提交或回滚。
-- `Bootstrap.exe` / `Bootstrap`：处理运行中可能被占用的 EXE/DLL 或 Linux 可执行文件替换。
-- `config/app_config.json`：部署配置源文件。启动时会同步到当前用户的 QSettings 配置区；Windows 下对应注册表，Linux 下对应用户配置文件。
-- `config/server_config.json`：编译期服务端地址配置源文件，通过 `config/server_config.qrc` 编进 Launcher / Updater / MainApp，不写入 `app_config.json` 或注册表。
-- `config/manifest_public_key.pem`：Manifest 签名公钥，用来验证服务端发布包没有被篡改。
-
-## 二、维护者：生成 SDK 包
-
-这一节是 SDK 维护者操作。接入方通常只需要拿到 `UpdateClientSDK.zip`。
-
-打包前确认：
-
-1. 已在 Windows 上用 Release 配置编译完成，输出目录里有 `Launcher.exe`、`Updater.exe`、`Bootstrap.exe`。
-2. `config/manifest_public_key.pem` 和服务端使用的私钥是一对。
-3. SDK Word 接入说明已经放在 `update-client` 根目录或 `update-client/Docs` 目录下，文件名包含 `SDK`，例如 `SimCAE自动升级SDK接入说明_v0.1.docx`。打包脚本会把它复制到 SDK 根目录，方便接入方一打开压缩包就能看到。
-4. 如果业务软件本身已经带 Qt DLL，通常不要把 SDK 的 Qt 运行库打进去，避免 Qt 版本混用。
-
-在 Windows PowerShell 中执行：
-
-```powershell
-cd C:\Users\admin\Desktop\update-client
-
-.\scripts\package-sdk.ps1 `
-  -SourceDir .\out\bin `
-  -OutputDir .\dist\UpdateClientSDK `
-  -ZipFile .\dist\UpdateClientSDK.zip `
-  -SdkVersion 0.1.0
-```
-
-生成结果：
-
-```text
-dist/
-  UpdateClientSDK/
-    SimCAE自动升级SDK接入说明_v0.1.docx
-    sdk_manifest.json
-    bin/
-      Launcher.exe
-      Updater.exe
-      Bootstrap.exe
-      ...
-    config/
-      app_config.json
-      manifest_public_key.pem
-    scripts/
-      install-sdk.ps1
-      package-client.ps1
-      package-sdk.ps1
-  UpdateClientSDK.zip
-```
-
-把 `dist/UpdateClientSDK.zip` 发给接入方即可。
-
-可选参数：
-
-- `-IncludeDemoMainApp`：把仓库里的 Demo 主程序 `MainApp.exe` 也打进 SDK，方便演示。
-- `-IncludeQtRuntime`：把 Qt 运行库也打进 SDK。只有业务软件本身不带 Qt 时才建议使用。
-
-Linux SDK 打包方式：
-
-```bash
-cd /home/laluo/project/update-client
-
-cmake --preset linux-x64-release
-cmake --build --preset linux-x64-release
-
-bash ./scripts/package-sdk.sh \
-  --source-dir ./out/linux/bin \
-  --output-dir ./dist/UpdateClientSDK-linux \
-  --archive ./dist/UpdateClientSDK-linux.tar.gz \
-  --sdk-version 0.1.0
-```
-
-Linux SDK 包里核心程序名不带 `.exe`：
-
-```text
-dist/
-  UpdateClientSDK-linux/
-    SimCAE自动升级SDK接入说明_v0.1.docx
-    sdk_manifest.json
-    bin/
-      Launcher
-      Updater
-      Bootstrap
-    Common/
-      ConfigHelper.h
-      ConfigHelper.cpp
-      TicketHelper.h
-      TicketHelper.cpp
-    config/
-      app_config.json
-      manifest_public_key.pem
-    scripts/
-      package-sdk.sh
-      package-client.sh
-  UpdateClientSDK-linux.tar.gz
-```
-
-## 三、你：把 SDK 放进业务软件目录
-
-假设业务软件目录是：
-
-```text
-D:\SimCAE\
-  bin\
-    SimCAE.exe
-    Qt5Core.dll
-    ...
-  Licenses\
-  installerResources\
-```
-
-推荐把 SDK 放到 `bin` 目录，和 `SimCAE.exe` 同级；后台发布新版本时仍选择整个 `D:\SimCAE\` 作为发布根目录。
-
-先解压 SDK：
-
-```powershell
-Expand-Archive D:\交付\UpdateClientSDK.zip -DestinationPath D:\SimCAE_SDK -Force
-```
-
-再安装到业务软件的 `bin` 目录：
-
-```powershell
-cd D:\SimCAE\bin
-
-D:\SimCAE_SDK\scripts\install-sdk.ps1 `
-  -SdkRoot D:\SimCAE_SDK `
-  -ReleaseDir .
-```
-
-安装后目录应类似：
-
-```text
-D:\SimCAE\
-  bin\
-    Launcher.exe
-    Updater.exe
-    Bootstrap.exe
-    SimCAE.exe
-    config\
-      app_config.json
-      manifest_public_key.pem
-    Qt5Core.dll
-    ...
-  Licenses\
-  installerResources\
-```
-
-如果你需要重新覆盖 `config/app_config.json`，执行安装脚本时加 `-OverwriteConfig`：
-
-```powershell
-D:\SimCAE_SDK\scripts\install-sdk.ps1 `
-  -SdkRoot D:\SimCAE_SDK `
-  -ReleaseDir D:\SimCAE\bin `
-  -OverwriteConfig
-```
-
-注意：SimCAE 自己已经带有 Qt 运行库。SDK 的 Launcher/Updater 应复用 SimCAE 的 `Qt5*.dll`、`platforms/`、`imageformats/` 等目录。不要把另一套 Qt DLL 覆盖到 `SimCAE\bin`，否则可能出现“无法定位程序输入点”一类错误。
-
-## 四、你：生成并填写客户端配置
-
-最推荐的方式是在服务端管理后台生成客户端配置：
-
-1. 浏览器打开服务端管理后台，例如 `http://服务器IP:8000/`。
-2. 登录后台。
-3. 创建或选择应用，例如 `app_id=simcae`。
-4. 创建 License。
-5. 在“客户端配置生成”区域选择应用、渠道、License 和主程序名。
-6. 点击生成配置。
-7. 复制“客户端 app_config.json”，覆盖 `D:\SimCAE\bin\config\app_config.json`。
-8. 复制“qrc 服务端配置 server_config.json”，覆盖 `update-client\config\server_config.json`，然后重新编译 Launcher / Updater / Bootstrap。这个文件会被 `config/server_config.qrc` 编进程序，不会放进用户机器的 `app_config.json` 或注册表。
-
-配置同步规则：
-
-- `app_config.json` 是部署配置源文件，适合交付、复制、人工修改。
-- `api_base_url` 不再属于 `app_config.json` 字段。它只存在于 `config/server_config.json`，并通过 qrc 编进程序。
-- Launcher / Updater / MainApp 启动时会计算 `app_config.json` 解析后的 JSON 内容 SHA256；如果 JSON 内容和上次导入时不同，就把文件里的配置重新写入当前 Windows 用户的注册表。
-- 后续运行时优先从注册表读取配置，不再每次直接读 JSON。
-- 运行过程中产生的动态值，例如首次输入的 `license_key`、服务端返回的 `device_id`、升级后的 `current_version`，会写入注册表。
-- 为减少明文暴露，SDK 成功把非空 `app_config.json` 导入注册表后，会把 `app_config.json` 内容自动清空为 `{}`，但不会删除这个文件。以后你从管理后台复制新的客户端配置时，直接覆盖这个文件即可。
-- SDK 会同步更新注册表里的 `source_sha256`，所以 `{}` 不会在下一次启动时反向覆盖注册表配置。
-- 如果你手动修改了 `app_config.json`，下一次启动会重新导入并覆盖注册表里的同名字段。
-- 如果检测到 `app_config.json` 确实发生变化，SDK 会同时删除 `config/client_identity.dat`、`config/version_policy.dat` 和 `config/local_state.json`，避免继续使用旧 License、旧设备身份、旧版本策略或旧防回滚状态；如果安装目录不可写，会弹出管理员权限确认框。
-- 正常启动成功后，不要删除 `client_identity.dat`、`version_policy.dat`、`local_state.json`。它们分别用于本地设备身份、离线策略和防回滚/防时间倒退，删除后会影响离线启动或导致重新授权。
-- 注册表按安装目录隔离；同一台电脑上多个安装目录不会互相覆盖配置。
-- 注册表位置为 `HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config`。
-
-关键字段说明：
-
-- `app_id`：服务端应用 ID，要和管理后台里的应用一致。
-- `app_name`：应用显示名称。
-- `channel`：发布渠道，例如 `stable`、`beta`、`dev`。
-- `current_version`：客户端当前初始版本，必须和后台已发布的版本一致。
-- `client_protocol`：客户端协议号，当前建议为 `3`。
-- `launch_token`：本机启动票据 HMAC 密钥。服务端生成配置时会填默认值；正式部署建议按项目统一修改。
-- `license_key`：管理后台创建 License 后生成的授权码。为空时首次启动 `Launcher.exe` 会弹窗让用户输入并保存到注册表；如果授权错误或过期，也会提示重新输入。
-- `client_token`：服务端 `.env` 中的 `CLIENT_API_TOKEN`，必须和服务端一致。
-- `device_id`：设备 ID。一般可以留空，首次启动时 SDK 会向服务端登记并写入注册表。
-- `install_root`：被更新的安装根目录相对 `Launcher.exe` 所在目录的位置。SDK 放在 `bin` 时填 `..`。
-- `main_executable`：业务主程序相对 `Launcher.exe` 所在目录的路径。SDK 放在 `bin` 且主程序也在 `bin` 时填 `SimCAE.exe`。
-- `launcher_executable`、`updater_executable`、`bootstrap_executable`：通常不用改。
-- `platform`、`arch`：当前为 `windows`、`x64`。
-
-典型配置：
-
-```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": "MARSCO-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
-  "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"
-}
-```
-
-对应的 `config/server_config.json` 示例：
-
-```json
-{
-  "api_base_url": "http://192.168.229.128:8000"
-}
-```
-
-## 五、你：业务主程序需要配合什么
-
-当前安全模式下，业务主程序需要配合两件事：
-
-1. 接收 `--ticket-file=<path>` 参数，验证并消费一次性启动票据。
-2. 如果收到 `--health-file=<path>` 参数，启动成功后向该路径写入 `ok\n`，让 Updater 确认新版本可用。
-
-接入位置：
-
-```text
-main / WinMain 开头，创建主窗口之前
-```
-
-当前仓库里的 `update-client/MainApp/main.cpp` 是接入示例，已经实现：
-
-- 启动票据校验。
-- 本地 License/设备身份校验。
-- 本地策略校验。
-- Manifest 完整性校验。
-- 健康标记写入。
-
-真正接入业务软件时，把这些启动检查逻辑移植到业务主程序。用户入口应改成 `Launcher.exe`，不要让用户直接双击 `SimCAE.exe`。
-
-重要：业务主程序校验 ticket 时，必须使用 SDK 当前运行配置里的动态值，不要直接从 `app_config.json` 读取 `device_id`。
-
-原因是 `app_config.json` 是部署源文件，网页生成时 `device_id` 通常为空；真正的设备 ID 是 `Launcher.exe` 首次向服务端登记后写入当前用户注册表的。`Launcher.exe` 生成 ticket 时使用的是注册表里的真实 `device_id`。如果业务主程序从 `app_config.json` 读取空的 `device_id` 来校验，就会出现：
-
-```text
-ticket signature, identity, time or nonce invalid
-```
-
-或者细化后的：
-
-```text
-ticket device_id mismatch
-```
-
-业务主程序应像 `MainApp/main.cpp` 示例一样使用：
-
-```cpp
-ConfigHelper& config = ConfigHelper::instance();
-TicketHelper::consumeAndVerify(
-    ticketFilePath,
-    config.getValue("App", "app_id"),
-    config.getValue("Update", "device_id"),
-    config.getValue("App", "current_version"),
-    config.getValue("App", "launch_token"),
-    &ticketError);
-```
-
-也就是说，接入业务主程序时不能只复制一小段 ticket 代码后自己解析 JSON；要么复用 SDK 的 `ConfigHelper` / `TicketHelper`，要么保证业务主程序读取到的 `app_id`、`device_id`、`current_version`、`launch_token` 和 `Launcher.exe` 完全来自同一套运行配置。
-
-## 六、你：准备服务端数据
-
-首次联调前，服务端至少要准备这些内容：
-
-1. 创建应用，例如 `simcae`。
-2. 创建渠道，例如 `stable`。
-3. 创建 License。
-4. 发布一个初始版本，例如 `1.0.0`。
-5. 生成客户端配置，并写入 `bin\config\app_config.json`。客户端下次启动时会自动同步到注册表。
-6. 生成 qrc 服务端配置，并写入源码目录 `config\server_config.json` 后重新编译 SDK 程序。
-
-为什么必须先发布初始版本：Launcher 启动业务主程序前会做 Manifest 完整性校验。这个 Manifest 是服务端发布版本时生成并签名的清单，用来证明当前本地文件属于一个可信版本。如果没有发布过 `current_version` 对应版本，客户端会提示签名 Manifest 缓存缺失。
-
-后台发布版本时，选择整个安装根目录，例如 `D:\SimCAE\`，不要只选择 `D:\SimCAE\bin`。这样服务端会把 `bin/SimCAE.exe`、`Licenses/`、`installerResources/` 等完整结构写进 Manifest。
-
-## 七、你：运行和联调
-
-基础联调步骤：
-
-1. 确认服务端正在运行。
-2. 确认 `bin\config\app_config.json` 中 `client_token`、`license_key`、`current_version` 正确，并确认 `Launcher.exe` 已用正确的 `config/server_config.json` 重新编译。
-3. 双击 `bin\Launcher.exe`。
-4. 首次启动时如果 `license_key` 为空，按弹窗输入后台创建的 License；SDK 会把它保存到注册表。
-5. 成功进入业务主程序后，回到后台查看设备、升级日志、下载日志。
-6. 在后台发布更高版本，例如从 `1.0.0` 发布到 `1.0.1`。
-7. 再次启动 `Launcher.exe`，验证升级、健康确认和回滚逻辑。
-
-联调目录建议：
-
-```text
-D:\SimCAE_Release\
-C:\Users\<你的用户名>\Desktop\SimCAE_Release\
-```
-
-如果安装在 `C:\Program Files\...` 这类默认不可写目录，普通配置值会写入当前用户注册表，不需要修改 `app_config.json`。但 `client_identity.dat`、`local_state.json`、`version_policy.dat` 等本地状态文件仍位于安装目录下；当这些文件需要写入且目录不可写时，SDK 会弹出 Windows 管理员权限确认框，用户点击“是”后会继续保存。
-
-注意：这次提权主要覆盖小型配置/状态文件的写入和删除。更新缓存、离线包暂存、升级替换 EXE/DLL 等大文件操作仍建议放在可写目录；如果最终产品必须完整安装到 `C:\Program Files\SimCAE\bin` 并在普通用户下自动升级，后续建议把运行时状态迁移到 `ProgramData` / `AppData`，或让 Updater/Bootstrap 在替换安装目录文件时走管理员权限。
-
-## 八、维护者：生成某个产品的最终客户端包
-
-SDK 是给接入方开发使用的。最终给用户安装或分发时，可以从已经联调过的 Release 目录生成最终客户端包。
-
-在 Windows PowerShell 中执行：
-
-```powershell
-cd C:\Users\admin\Desktop\update-client
-
-.\scripts\package-client.ps1 `
-  -SourceDir .\out\bin `
-  -ConfigFile .\config\app_config.json `
-  -OutputDir .\dist\UpdateClient `
-  -ZipFile .\dist\UpdateClient.zip
-```
-
-`package-client.ps1` 会检查：
-
-- 配置文件必填字段是否完整。
-- 主程序、Launcher、Updater、Bootstrap 是否存在。
-- 是否混入 Debug DLL、PDB、ILK。
-- 当前版本是否已有签名 Manifest 缓存。
-- 是否存在重复主程序。
-
-生成结果：
-
-```text
-dist/
-  UpdateClient/
-  UpdateClient.zip
-```
-
-Linux 最终客户端包生成方式：
-
-```bash
-cd /home/laluo/project/update-client
-
-bash ./scripts/package-client.sh \
-  --source-dir /path/to/SimCAE \
-  --config-file /path/to/SimCAE/bin/config/app_config.json \
-  --output-dir ./dist/UpdateClient-linux \
-  --archive ./dist/UpdateClient-linux.tar.gz
-```
-
-Linux 打包脚本会检查：
-
-- `app_config.json` 必填字段是否完整。
-- 主程序、Launcher、Updater、Bootstrap 是否存在。
-- 是否混入 Debug 产物。
-- 当前版本是否已有签名 Manifest 缓存。
-- 是否存在重复主程序。
-
-Linux 下如果程序安装在 `/opt`、`/usr/local` 等普通用户不可写目录，升级器无法像 Windows UAC 那样自动提权修改安装目录。正式部署前建议二选一：
-
-1. 把软件安装到当前用户有写权限的目录，例如用户 home 下的应用目录。
-2. 由安装器创建专用目录和权限，让运行用户对软件目录有写入权限。
-
-## 九、常见错误
-
-1. 直接启动业务主程序提示 ticket 错误：应从 `Launcher.exe` 启动。
-2. 首次启动保存配置/状态文件失败：如果目录不可写，SDK 会弹出管理员权限确认框；用户取消或当前账号没有管理员权限时仍会失败。
-3. 首次启动设备登记失败：检查编译进 qrc 的 `config/server_config.json`、`client_token`、`license_key`、服务端 License 状态。
-4. 提示 License 错误或过期：在后台确认 License 是否存在、是否被禁用或删除、是否超过最大设备数。
-5. 策略或 Manifest 验签失败：检查 `config/manifest_public_key.pem` 是否和服务端私钥匹配。
-6. 提示 signed manifest cache missing：先在后台发布一次 `current_version` 对应版本，并让客户端拿到该版本 Manifest。
-7. 升级后回滚：检查业务程序是否在 `health_check_timeout_ms` 内写入健康标记。
-8. 发布失败提示主程序不在根目录：服务端 `.env` 中 `RELEASE_MAIN_EXECUTABLE` 要和平台匹配。Windows 通常是 `bin/SimCAE.exe`；Linux 通常是 `bin/SimCAE`。
-9. 启动时提示 `无法定位程序输入点 ... Qt5*.dll`：通常是 Qt DLL 被不同版本覆盖或混用。恢复业务软件原始 Qt DLL，并重新打包 SDK；SimCAE 场景下不要使用 `-IncludeQtRuntime`。

Docs/02-编译环境和第三方依赖说明.md

@@ -1,175 +0,0 @@
-# 客户端编译环境和第三方依赖说明
-
-`thirdparty/` 是本机依赖目录，已经被 `.gitignore` 忽略，不会提交到 Git。
-
-当前客户端构建依赖：
-
-1. Qt 5.15.2 或兼容的 Qt 5 版本
-2. OpenSSL
-
-Windows 下推荐使用 Qt 5.15.2 msvc2019_64 和 OpenSSL-Win64；Linux 下使用系统安装的 Qt/OpenSSL 开发包。
-
-先看结论：
-
-- Windows：配置 Qt 环境变量，把 OpenSSL 复制到 `thirdparty/OpenSSL-Win64`。
-- Linux：用 apt 安装 Qt/OpenSSL 开发包。
-- `thirdparty/` 只放本机依赖，不提交 Git。
-
-## 1. Qt 配置
-
-### Windows
-
-Qt 路径由本机环境变量提供。你需要在 Windows 环境变量里配置 Qt 路径，让 CMake 的 `find_package(Qt5 ...)` 能找到 Qt。
-
-推荐配置用户环境变量 `CMAKE_PREFIX_PATH`：
-
-```powershell
-[Environment]::SetEnvironmentVariable("CMAKE_PREFIX_PATH", "C:\Qt\5.15.2\msvc2019_64", "User")
-```
-
-设置完成后，重新打开 PowerShell 或 Visual Studio。
-
-如果只想对当前 PowerShell 窗口临时生效：
-
-```powershell
-$env:CMAKE_PREFIX_PATH="C:\Qt\5.15.2\msvc2019_64"
-```
-
-也可以配置更精确的 `Qt5_DIR`：
-
-```powershell
-[Environment]::SetEnvironmentVariable("Qt5_DIR", "C:\Qt\5.15.2\msvc2019_64\lib\cmake\Qt5", "User")
-```
-
-`CMAKE_PREFIX_PATH` 和 `Qt5_DIR` 二选一即可，推荐使用 `CMAKE_PREFIX_PATH`。
-
-一般不需要把 `C:\Qt\5.15.2\msvc2019_64\bin` 加入 `Path`。项目构建后会通过 `windeployqt` 复制运行所需的 Qt DLL。
-
-### Linux
-
-Linux 下需要安装 Qt5 开发包，让 CMake 能找到 `Qt5::Core`、`Qt5::Network`、`Qt5::Gui`、`Qt5::Widgets`。
-
-Ubuntu/Debian 示例：
-
-```bash
-sudo apt update
-sudo apt install -y build-essential cmake qtbase5-dev qttools5-dev-tools libssl-dev
-```
-
-如果 Qt 安装在自定义目录，可以临时设置：
-
-```bash
-export CMAKE_PREFIX_PATH=/path/to/Qt/5.x/gcc_64
-```
-
-## 2. OpenSSL 配置
-
-### Windows
-
-OpenSSL 默认放在：
-
-```text
-thirdparty/OpenSSL-Win64
-```
-
-推荐目录结构：
-
-```text
-thirdparty/
-  OpenSSL-Win64/
-    include/
-      openssl/
-    lib/
-      VC/
-        x64/
-          MD/
-          MDd/
-```
-
-复制命令示例：
-
-```powershell
-cd C:\Users\admin\Desktop\update-client
-mkdir thirdparty
-Copy-Item "C:\Program Files\OpenSSL-Win64" ".\thirdparty\OpenSSL-Win64" -Recurse
-```
-
-如果 OpenSSL 不放在 `thirdparty/`，可以在配置 CMake 时手动指定：
-
-```powershell
-cmake -S . -B out\build\x64-Debug `
-  -G "Visual Studio 17 2022" `
-  -A x64 `
-  -DSIMCAE_OPENSSL_ROOT="C:\Program Files\OpenSSL-Win64"
-```
-
-### Linux
-
-Linux 下 CMake 会通过 `find_package(OpenSSL REQUIRED)` 查找系统 OpenSSL。通常安装 `libssl-dev` 即可，不需要 `thirdparty/OpenSSL-Win64`。
-
-## 3. Windows 重新配置和编译
-
-如果之前配置过 CMake，建议先删除旧缓存：
-
-```powershell
-cd C:\Users\admin\Desktop\update-client
-Remove-Item out\build -Recurse -Force
-```
-
-重新配置：
-
-```powershell
-cmake -S . -B out\build\x64-Debug `
-  -G "Visual Studio 17 2022" `
-  -A x64
-```
-
-编译：
-
-```powershell
-cmake --build out\build\x64-Debug --config Debug
-```
-
-## 4. Linux 重新配置和编译
-
-如果之前配置过 CMake，建议先删除旧缓存：
-
-```bash
-cd ~/project/update-client
-rm -rf out/build/linux-x64-debug out/build/linux-x64-release
-```
-
-Debug 构建：
-
-```bash
-cmake --preset linux-x64-debug
-cmake --build --preset linux-x64-debug
-```
-
-Release 构建：
-
-```bash
-cmake --preset linux-x64-release
-cmake --build --preset linux-x64-release
-```
-
-Linux 构建时会自动使用 `config/app_config.linux.example.json` 作为输出目录里的默认 `config/app_config.json`，可执行程序名不带 `.exe`。
-
-## 5. 提交注意事项
-
-不要提交下面这些内容：
-
-```text
-thirdparty/
-.vs/
-out/
-build/
-dist/
-App/
-*.exe
-*.dll
-*.lib
-*.pdb
-```
-
-这些都属于本机依赖、构建产物或打包产物，不应该进 Git。

Launcher/UpdateLogic.cpp

@@ -1,178 +1,287 @@
-#include "UpdateLogic.h"
-#include "ConfigHelper.h"
-#include <QDebug>
-#include <QJsonArray>
-#include <QApplication>
-#include <QDir>
-#include <QSaveFile>
-#include "PolicyHelper.h"
-#include "LocalStateHelper.h"
-
-UpdateLogic::UpdateLogic(QObject* parent)
-    : QObject(parent)
-{
-    ConfigHelper& cfg = ConfigHelper::instance();
-    m_serverAddr = cfg.getValue("Server", "api_base_url");
-    m_appId = cfg.getValue("App", "app_id");
-    m_curVer = cfg.getValue("App", "current_version");
-    m_channel = cfg.getValue("App", "channel");
-
-    // Debug print config
-    qDebug() << "Read server addr:" << m_serverAddr;
-    qDebug() << "Read app id:" << m_appId;
-}
-
-void UpdateLogic::checkUpdate()
-{
-    if (m_serverAddr.isEmpty() || m_appId.isEmpty() || m_curVer.isEmpty() || m_channel.isEmpty())
-    {
-        qDebug() << "Config incomplete, abort update check";
-        m_needUpdate = false;
-        return;
-    }
-    QString url = m_serverAddr + "/api/v1/update/check";
-    QJsonObject body;
-    body["app_id"] = m_appId;
-    body["current_version"] = m_curVer;
-    body["channel"] = m_channel;
-    const int configuredProtocol = ConfigHelper::instance().getValue("App", "client_protocol").toInt();
-    body["client_protocol"] = qMax(3, configuredProtocol);
-
-    m_http.postRequest(url, body, [this](int code, const QJsonObject& resp)
-        {
-            qDebug() << "Check update HTTP code:" << code;
-            m_lastStatusCode = code;
-            m_checkResp = resp;
-            m_networkOk = (code == 200);
-            if (code == 200)
-            {
-                const QString appDir = QApplication::applicationDirPath();
-                PolicyHelper onlinePolicy(appDir);
-                LocalStateHelper state(appDir);
-                const bool stateLoaded = state.loadState();
-                const bool policyValid = onlinePolicy.loadPolicyObject(
-                    resp.value("policy").toObject(), resp.value("policy_text").toString());
-                if (!policyValid || !stateLoaded
-                    || state.isPolicySeqRolledBack(onlinePolicy.policySeq())
-                    || !onlinePolicy.savePolicy())
-                {
-                    qDebug() << "Online policy rejected:" << onlinePolicy.errorString();
-                    m_networkOk = false;
-                    m_needUpdate = false;
-                    return;
-                }
-                state.updateOnlineVerified(onlinePolicy.policySeq());
-                if (!state.saveState())
-                {
-                    qDebug() << "Cannot persist online policy state";
-                    m_networkOk = false;
-                    m_needUpdate = false;
-                    return;
-                }
-                m_needUpdate = resp["need_update"].toBool();
-                m_latestVer = resp["latest_version"].toString();
-                qDebug() << "Need update:" << m_needUpdate;
-                qDebug() << "Latest version:" << m_latestVer;
-                qDebug() << "Policy seq:" << onlinePolicy.policySeq();
-            }
-            else
-            {
-                m_needUpdate = false;
-                qDebug() << "Check update api failed";
-            }
-        });
-}
-
-void UpdateLogic::getDownloadUrl(const QString& appId, const QString& channel, const QString& ver, int verId)
-{
-    QString url = m_serverAddr + "/api/v1/update/download-url";
-    QJsonObject body;
-    body["app_id"] = appId;
-    body["channel"] = channel;
-    body["version"] = ver;
-    body["version_id"] = verId;
-    QJsonArray files;
-    body["files"] = files;
-
-    m_http.postRequest(url, body, [](int code, const QJsonObject& resp)
-        {
-            qDebug() << "\n========== File Download Url ==========";
-            qDebug() << resp["files"].toArray();
-        });
-}
-
-bool UpdateLogic::cacheManifest(const QString& appId, const QString& channel, const QString& version,
-                                int versionId, const QString& cacheDir)
-{
-    m_error.clear();
-    if (appId.isEmpty() || channel.isEmpty() || version.isEmpty() || versionId <= 0) {
-        m_error = "manifest identity is incomplete";
-        return false;
-    }
-
-    QJsonObject response;
-    int statusCode = 0;
-    QJsonObject body;
-    body["app_id"] = appId;
-    body["channel"] = channel;
-    body["version"] = version;
-    body["version_id"] = versionId;
-    m_http.postRequest(m_serverAddr + "/api/v1/update/manifest", body,
-        [&](int code, const QJsonObject& resp) {
-            statusCode = code;
-            response = resp;
-        });
-
-    if (statusCode != 200) {
-        m_error = QString("manifest request failed (HTTP %1)").arg(statusCode);
-        return false;
-    }
-
-    const QJsonObject manifest = response.value("manifest").toObject();
-    const QString manifestText = response.value("manifest_text").toString();
-    if (manifest.isEmpty() || manifestText.isEmpty()) {
-        m_error = "manifest response is incomplete";
-        return false;
-    }
-    if (manifest.value("app_id").toString() != appId
-        || manifest.value("channel").toString() != channel
-        || manifest.value("version").toString() != version) {
-        m_error = "manifest identity does not match current version";
-        return false;
-    }
-
-    QDir dir(cacheDir);
-    if (!dir.exists() && !dir.mkpath(".")) {
-        m_error = "cannot create manifest cache directory";
-        return false;
-    }
-
-    QJsonObject wrapper;
-    wrapper["manifest"] = manifest;
-    wrapper["manifest_text"] = manifestText;
-    QSaveFile file(dir.filePath("manifest_" + version + ".json"));
-    const QByteArray bytes = QJsonDocument(wrapper).toJson(QJsonDocument::Indented);
-    if (!file.open(QIODevice::WriteOnly) || file.write(bytes) != bytes.size() || !file.commit()) {
-        m_error = "cannot save signed manifest cache";
-        return false;
-    }
-    qDebug() << "Current version manifest cached to" << file.fileName();
-    return true;
-}
-
-void UpdateLogic::reportUpdateResult(const QString& deviceId, const QString& fromVer, const QString& toVer, bool success)
-{
-    QString url = m_serverAddr + "/api/v1/update/report";
-    QJsonObject body;
-    body["app_id"] = m_appId;
-    body["device_id"] = deviceId;
-    body["from_version"] = fromVer;
-    body["to_version"] = toVer;
-    body["result"] = success ? "success" : "fail";
-
-    m_http.postRequest(url, body, [](int code, const QJsonObject& resp)
-        {
-            qDebug() << "\n========== Update Report Result ==========";
-            qDebug() << resp;
-        });
-}
+#include "UpdateLogic.h"
+
+#include "ConfigHelper.h"
+
+#include <QCoreApplication>
+#include <QDebug>
+#include <QDir>
+#include <QJsonArray>
+#include <QJsonDocument>
+#include <QSaveFile>
+#include <QUrl>
+#include <QUrlQuery>
+
+namespace {
+
+QString trimBaseUrl(QString value)
+{
+    value = value.trimmed();
+    while (value.endsWith(QLatin1Char('/')))
+        value.chop(1);
+    return value;
+}
+
+void addQueryValue(QUrlQuery& query, const QString& key, const QString& value)
+{
+    const QString trimmed = value.trimmed();
+    if (!trimmed.isEmpty())
+        query.addQueryItem(key, trimmed);
+}
+
+QString serverMessage(const QJsonObject& response)
+{
+    const QString msg = response.value(QStringLiteral("msg")).toString();
+    if (!msg.isEmpty())
+        return msg;
+
+    const QJsonValue detail = response.value(QStringLiteral("detail"));
+    if (detail.isObject()) {
+        const QJsonObject object = detail.toObject();
+        const QString detailMsg = object.value(QStringLiteral("msg")).toString();
+        if (!detailMsg.isEmpty())
+            return detailMsg;
+        const QString error = object.value(QStringLiteral("error")).toString();
+        if (!error.isEmpty())
+            return error;
+    }
+    return detail.toString();
+}
+
+QJsonObject responseDataObject(const QJsonObject& response)
+{
+    return response.value(QStringLiteral("data")).isObject()
+        ? response.value(QStringLiteral("data")).toObject()
+        : response;
+}
+
+QString configValue(const QString& key, const QString& fallback = QString())
+{
+    const QString value = ConfigHelper::instance().getValue(QString(), key).trimmed();
+    return value.isEmpty() ? fallback : value;
+}
+
+} // namespace
+
+UpdateLogic::UpdateLogic(QObject* parent)
+    : QObject(parent)
+{
+    ConfigHelper& cfg = ConfigHelper::instance();
+    m_serverAddr = trimBaseUrl(cfg.getValue("Server", "api_base_url"));
+    m_appId = cfg.getValue("App", "product_code").trimmed();
+    if (m_appId.isEmpty())
+        m_appId = cfg.getValue("App", "app_id").trimmed();
+    m_curVer = cfg.getValue("App", "current_version").trimmed();
+    m_channel = cfg.getValue("App", "channel").trimmed();
+    if (m_channel.isEmpty())
+        m_channel = QStringLiteral("stable");
+
+    qDebug() << "Read server addr:" << m_serverAddr;
+    qDebug() << "Read product code:" << m_appId;
+}
+
+void UpdateLogic::checkUpdate()
+{
+    m_error.clear();
+    m_needUpdate = false;
+    m_networkOk = false;
+    m_lastStatusCode = 0;
+    m_latestVer.clear();
+    m_checkResp = QJsonObject();
+
+    if (m_serverAddr.isEmpty() || m_appId.isEmpty() || m_curVer.isEmpty())
+    {
+        m_error = QCoreApplication::translate(
+            "UpdateLogic",
+            "Update configuration is incomplete. Server, product_code and current_version are required.");
+        qDebug() << "Config incomplete, abort update check:" << m_error;
+        return;
+    }
+    if (configValue(QStringLiteral("client_token")).isEmpty())
+    {
+        m_lastStatusCode = 401;
+        m_error = QCoreApplication::translate(
+            "UpdateLogic",
+            "Update configuration is incomplete. client_token is required.");
+        m_checkResp.insert(QStringLiteral("msg"), m_error);
+        qDebug() << "Client token missing, abort update check:" << m_error;
+        return;
+    }
+
+    QUrl url(m_serverAddr + QStringLiteral("/api/v1/client/update/authorized-check"));
+    QUrlQuery query;
+    addQueryValue(query, QStringLiteral("productCode"), m_appId);
+    addQueryValue(query, QStringLiteral("currentVersion"), m_curVer);
+    addQueryValue(query, QStringLiteral("clientVersion"), configValue(QStringLiteral("client_protocol"), QStringLiteral("3")));
+    addQueryValue(query, QStringLiteral("channel"), m_channel);
+    addQueryValue(query, QStringLiteral("os"), configValue(QStringLiteral("platform")));
+    addQueryValue(query, QStringLiteral("architecture"), configValue(QStringLiteral("arch")));
+    addQueryValue(query, QStringLiteral("abi"), configValue(QStringLiteral("abi")));
+    url.setQuery(query);
+
+    m_http.getRequest(url.toString(QUrl::FullyEncoded),
+        [this](int code, const QJsonObject& resp)
+        {
+            qDebug() << "Check update HTTP code:" << code;
+            m_lastStatusCode = code;
+            m_checkResp = resp;
+            m_networkOk = (code == 200);
+            if (code != 200)
+            {
+                m_needUpdate = false;
+                m_error = serverMessage(resp);
+                qDebug() << "Check update api failed:" << m_error;
+                return;
+            }
+
+            const QJsonArray releases = resp.value(QStringLiteral("data")).toArray();
+            QJsonObject selected;
+            for (const QJsonValue& value : releases) {
+                const QJsonObject release = value.toObject();
+                const bool hasPackages = !release.value(QStringLiteral("packages")).toArray().isEmpty();
+                const bool hasManifest = release.value(QStringLiteral("manifest")).isObject()
+                    || !release.value(QStringLiteral("manifestUri")).toString().isEmpty();
+                if (hasPackages && hasManifest) {
+                    selected = release;
+                    break;
+                }
+            }
+
+            if (selected.isEmpty()) {
+                m_needUpdate = false;
+                if (!releases.isEmpty())
+                    m_latestVer = releases.first().toObject().value(QStringLiteral("version")).toString();
+                qDebug() << "No entitled downloadable update for current client.";
+                return;
+            }
+
+            m_checkResp = selected;
+            m_checkResp.insert(QStringLiteral("need_update"), true);
+            m_checkResp.insert(QStringLiteral("latest_version"), selected.value(QStringLiteral("version")).toString());
+            m_checkResp.insert(QStringLiteral("release_id"), selected.value(QStringLiteral("id")).toString());
+            m_needUpdate = true;
+            m_latestVer = selected.value(QStringLiteral("version")).toString();
+            qDebug() << "Need update:" << m_needUpdate;
+            qDebug() << "Latest version:" << m_latestVer;
+            qDebug() << "Release id:" << selected.value(QStringLiteral("id")).toString();
+        });
+}
+
+void UpdateLogic::getDownloadUrl(const QString& appId, const QString& channel, const QString& ver, int verId)
+{
+    Q_UNUSED(appId);
+    Q_UNUSED(channel);
+    Q_UNUSED(ver);
+    Q_UNUSED(verId);
+    qDebug() << "SimCAE Hub manifest already contains authorized package download URLs.";
+}
+
+bool UpdateLogic::cacheManifest(const QString& appId, const QString& channel, const QString& version,
+                                int versionId, const QString& cacheDir)
+{
+    Q_UNUSED(versionId);
+    m_error.clear();
+    if (appId.isEmpty() || channel.isEmpty() || version.isEmpty()) {
+        m_error = QCoreApplication::translate(
+            "UpdateLogic",
+            "Current version manifest identity is incomplete. Stage: cache current version manifest. Product: %1, channel: %2, version: %3.")
+            .arg(appId, channel, version);
+        return false;
+    }
+
+    QUrl url(m_serverAddr + QStringLiteral("/api/v1/client/update/manifest"));
+    QUrlQuery query;
+    addQueryValue(query, QStringLiteral("productCode"), appId);
+    addQueryValue(query, QStringLiteral("version"), version);
+    addQueryValue(query, QStringLiteral("clientVersion"), configValue(QStringLiteral("client_protocol"), QStringLiteral("3")));
+    addQueryValue(query, QStringLiteral("channel"), channel);
+    addQueryValue(query, QStringLiteral("os"), configValue(QStringLiteral("platform")));
+    addQueryValue(query, QStringLiteral("architecture"), configValue(QStringLiteral("arch")));
+    addQueryValue(query, QStringLiteral("abi"), configValue(QStringLiteral("abi")));
+    url.setQuery(query);
+
+    QJsonObject response;
+    int statusCode = 0;
+    m_http.getRequest(url.toString(QUrl::FullyEncoded),
+        [&](int code, const QJsonObject& resp) {
+            statusCode = code;
+            response = resp;
+        });
+
+    if (statusCode != 200) {
+        const QString message = serverMessage(response);
+        m_error = QCoreApplication::translate(
+            "UpdateLogic",
+            "Cannot download manifest for the current local version. Stage: cache current version manifest. HTTP status: %1. Product: %2, channel: %3, version: %4.%5")
+            .arg(QString::number(statusCode), appId, channel, version,
+                 message.isEmpty() ? QString() : QCoreApplication::translate("UpdateLogic", "\nServer message: %1").arg(message));
+        return false;
+    }
+
+    QJsonObject wrapper = responseDataObject(response);
+    const QJsonObject manifest = wrapper.value(QStringLiteral("manifest")).toObject();
+    QString manifestText = wrapper.value(QStringLiteral("manifestText")).toString();
+    if (manifestText.isEmpty())
+        manifestText = wrapper.value(QStringLiteral("manifest_text")).toString();
+    if (manifest.isEmpty() || manifestText.isEmpty()) {
+        m_error = QCoreApplication::translate(
+            "UpdateLogic",
+            "The manifest response for the current local version is incomplete. Stage: cache current version manifest. Product: %1, channel: %2, version: %3.")
+            .arg(appId, channel, version);
+        return false;
+    }
+    const QString manifestProduct = manifest.value(QStringLiteral("productCode")).toString(
+        manifest.value(QStringLiteral("app_id")).toString());
+    if (manifestProduct != appId
+        || manifest.value(QStringLiteral("channel")).toString() != channel
+        || manifest.value(QStringLiteral("version")).toString() != version) {
+        m_error = QCoreApplication::translate(
+            "UpdateLogic",
+            "The manifest identity does not match the current local version. Stage: cache current version manifest. Expected product/channel/version: %1 / %2 / %3. Manifest product/channel/version: %4 / %5 / %6.")
+            .arg(appId, channel, version,
+                 manifestProduct,
+                 manifest.value(QStringLiteral("channel")).toString(),
+                 manifest.value(QStringLiteral("version")).toString());
+        return false;
+    }
+
+    QDir dir(cacheDir);
+    if (!dir.exists() && !dir.mkpath(".")) {
+        m_error = QCoreApplication::translate(
+            "UpdateLogic",
+            "Cannot create manifest cache directory. Stage: cache current version manifest. Directory: %1.")
+            .arg(cacheDir);
+        return false;
+    }
+
+    wrapper.insert(QStringLiteral("manifest"), manifest);
+    wrapper.insert(QStringLiteral("manifestText"), manifestText);
+    wrapper.insert(QStringLiteral("manifest_text"), manifestText);
+    QSaveFile file(dir.filePath(QStringLiteral("manifest_") + version + QStringLiteral(".json")));
+    const QByteArray bytes = QJsonDocument(wrapper).toJson(QJsonDocument::Indented);
+    if (!file.open(QIODevice::WriteOnly) || file.write(bytes) != bytes.size() || !file.commit()) {
+        m_error = QCoreApplication::translate(
+            "UpdateLogic",
+            "Cannot save manifest cache. Stage: cache current version manifest. File: %1. Error: %2.")
+            .arg(file.fileName(), file.errorString());
+        return false;
+    }
+    qDebug() << "Current version manifest cached to" << file.fileName();
+    return true;
+}
+
+bool UpdateLogic::refreshGitTagsFile(const QString& outputPath)
+{
+    Q_UNUSED(outputPath);
+    m_error.clear();
+    qDebug() << "Git tag export is not part of the current SimCAE Hub admin pages; skipped.";
+    return true;
+}
+
+void UpdateLogic::reportUpdateResult(const QString& deviceId, const QString& fromVer, const QString& toVer, bool success)
+{
+    Q_UNUSED(deviceId);
+    Q_UNUSED(fromVer);
+    Q_UNUSED(toVer);
+    Q_UNUSED(success);
+    qDebug() << "Update result report is not part of the current SimCAE Hub API; skipped.";
+}

Launcher/UpdateLogic.h

@@ -15,6 +15,7 @@ public:
     void reportUpdateResult(const QString& deviceId, const QString& fromVer, const QString& toVer, bool success);
     bool cacheManifest(const QString& appId, const QString& channel, const QString& version,
                        int versionId, const QString& cacheDir);
+    bool refreshGitTagsFile(const QString& outputPath);
 
     bool getNeedUpdate() const { return m_needUpdate; }
     QString getLatestVersion() const { return m_latestVer; }
@@ -23,8 +24,9 @@ public:
     int lastStatusCode() const { return m_lastStatusCode; }
     QString errorString() const { return m_error; }
 
-    QString getAppId() const { return m_appId; }
-    QString getChannel() const { return m_channel; }
+    QString getAppId() const { return m_appId; }
+    QString getProductCode() const { return m_appId; }
+    QString getChannel() const { return m_channel; }
 
 private:
     HttpHelper m_http;

Launcher/main.cpp

@@ -1,28 +1,75 @@
 #include <QApplication>
 #include <QCoreApplication>
 #include <QDebug>
+#include <QDir>
+#include <QFileInfo>
 #include <QMessageBox>
 #include <QProcess>
 #include <QProgressDialog>
-#include <QInputDialog>
-#include <QLineEdit>
 #include <QTranslator>
+#include <QUuid>
+
 #include "UpdateLogic.h"
-#include "../Common/ConfigHelper.h"
-#include "../Common/PolicyHelper.h"
-#include "../Common/LocalStateHelper.h"
-#include "../Common/TicketHelper.h"
-#include "../Common/DeviceIdentityHelper.h"
-#include <QFile>
-#include <QFileDialog>
-#include <QDir>
-
+#include "../Common/ConfigHelper.h"
+#include "../Common/TicketHelper.h"
+
+namespace {
+
+QString configValue(const QString& key, const QString& fallback = QString())
+{
+    const QString value = ConfigHelper::instance().getValue(QString(), key).trimmed();
+    return value.isEmpty() ? fallback : value;
+}
+
+QString productCode()
+{
+    return configValue(QStringLiteral("product_code"),
+        configValue(QStringLiteral("app_id")));
+}
+
+QString ensureDeviceId()
+{
+    ConfigHelper& config = ConfigHelper::instance();
+    QString deviceId = config.getValue(QStringLiteral("Update"), QStringLiteral("device_id")).trimmed();
+    if (!deviceId.isEmpty())
+        return deviceId;
+
+    deviceId = config.getValue(QStringLiteral("Device"), QStringLiteral("installation_id")).trimmed();
+    if (deviceId.isEmpty())
+        deviceId = QUuid::createUuid().toString(QUuid::WithoutBraces);
+
+    config.setValue(QStringLiteral("Device"), QStringLiteral("installation_id"), deviceId);
+    config.setValue(QStringLiteral("Update"), QStringLiteral("device_id"), deviceId);
+    return deviceId;
+}
+
+QString authFailureMessage(const QJsonObject& response, const QString& fallback)
+{
+    const QString msg = response.value(QStringLiteral("msg")).toString();
+    if (!msg.isEmpty())
+        return msg;
+    const QJsonValue detail = response.value(QStringLiteral("detail"));
+    if (detail.isObject()) {
+        const QJsonObject object = detail.toObject();
+        const QString detailMsg = object.value(QStringLiteral("msg")).toString();
+        if (!detailMsg.isEmpty())
+            return detailMsg;
+        const QString error = object.value(QStringLiteral("error")).toString();
+        if (!error.isEmpty())
+            return error;
+    }
+    const QString detailText = detail.toString();
+    return detailText.isEmpty() ? fallback : detailText;
+}
+
+} // namespace
+
 int main(int argc, char* argv[])
 {
     QApplication app(argc, argv);
-    QApplication::setApplicationName("Marsco Launcher");
+    QApplication::setApplicationName("SimCAE Launcher");
     QTranslator translator;
-    if (translator.load(":/i18n/update-client_zh_CN.qm"))
+    if (translator.load(QStringLiteral(":/i18n/update-client_zh_CN.qm")))
         app.installTranslator(&translator);
 
     const int elevatedWriteExitCode = ConfigHelper::runElevatedWriteCommandIfRequested();
@@ -30,321 +77,160 @@ int main(int argc, char* argv[])
         return elevatedWriteExitCode;
 
     QProgressDialog progress(QCoreApplication::translate("Launcher", "Checking for software updates..."), QString(), 0, 0);
-    progress.setWindowTitle(QCoreApplication::translate("Launcher", "Marsco Launcher"));
-    progress.setCancelButton(nullptr);
-    progress.setWindowModality(Qt::ApplicationModal);
-    progress.setMinimumDuration(0);
-    progress.setAutoClose(false);
-    progress.show();
-    QApplication::processEvents();
-
-    const QString appDir = QApplication::applicationDirPath();
-    ConfigHelper& config = ConfigHelper::instance();
-    const auto isLicenseError = [](const QString& errorText) {
-        const QString text = errorText.toLower();
-        return text.contains("license")
-            || text.contains("authorization")
-            || text.contains("expired")
-            || text.contains("device limit")
-            || text.contains("bound to another license");
-    };
-    const auto clearDeviceCredential = [&]() {
-        ConfigHelper::removeFileWithElevationIfNeeded(QDir(appDir).filePath("config/client_identity.dat"));
-        config.setValue("Update", "device_id", QString());
-    };
-    QString licenseKey = config.getValue("License", "license_key").trimmed();
-    auto promptAndSaveLicense = [&](const QString& reason) -> QString {
-        QString promptReason = reason;
-        while (true) {
-            progress.close();
-            bool accepted = false;
-            const QString appName = config.getValue("App", "app_name").trimmed();
-            const QString prompt = promptReason.trimmed().isEmpty()
-                ? QCoreApplication::translate("Launcher", "Please enter the License for %1:")
-                    .arg(appName.isEmpty() ? QCoreApplication::translate("Launcher", "the application") : appName)
-                : QCoreApplication::translate("Launcher", "%1\n\nPlease enter a new License for %2:")
-                    .arg(promptReason, appName.isEmpty() ? QCoreApplication::translate("Launcher", "the application") : appName);
-            licenseKey = QInputDialog::getText(
-                nullptr,
-                QCoreApplication::translate("Launcher", "Enter License"),
-                prompt,
-                QLineEdit::Normal,
-                QString(),
-                &accepted
-            ).trimmed();
-            if (!accepted) {
-                QMessageBox::information(nullptr,
-                    QCoreApplication::translate("Launcher", "License Required"),
-                    QCoreApplication::translate("Launcher", "A License provided by the administrator is required for the first launch."));
-                return QString();
-            }
-            if (licenseKey.isEmpty()) {
-                QMessageBox::warning(nullptr,
-                    QCoreApplication::translate("Launcher", "License Cannot Be Empty"),
-                    QCoreApplication::translate("Launcher", "Please paste the License created in the admin page."));
-                promptReason.clear();
-                continue;
-            }
-            if (!config.setValue("License", "license_key", licenseKey)) {
-                QMessageBox::critical(nullptr,
-                    QCoreApplication::translate("Launcher", "Failed to Save License"),
-                    QCoreApplication::translate("Launcher", "Cannot write the configuration file:\n%1\n%2").arg(config.configPath(), config.lastError()));
-                return QString();
-            }
-            progress.show();
-            progress.setLabelText(QCoreApplication::translate("Launcher", "Verifying License..."));
-            QApplication::processEvents();
-            return licenseKey;
-        }
-    };
-
-    while (true) {
-        if (licenseKey.isEmpty()) {
-            licenseKey = promptAndSaveLicense(QString());
-            if (licenseKey.isEmpty()) return 0;
-        }
-        DeviceIdentityHelper identity(appDir);
-        if (identity.ensureIssued(config.getValue("Server", "api_base_url"),
-                                  config.getValue("Server", "client_token"),
-                                  config.getValue("App", "app_id"),
-                                  config.getValue("App", "channel"),
-                                  licenseKey)) {
-            break;
-        }
-        const QString error = identity.errorString();
-        if (!isLicenseError(error)) {
-            progress.close();
-            QMessageBox::critical(nullptr,
-                QCoreApplication::translate("Launcher", "Device Authentication Failed"),
-                error);
-            return -1;
-        }
-        clearDeviceCredential();
-        licenseKey = promptAndSaveLicense(QCoreApplication::translate("Launcher", "The current License cannot be used: %1").arg(error));
-        if (licenseKey.isEmpty()) return 0;
-    }
-
-    UpdateLogic logic;
-    logic.checkUpdate();
-
-    const bool needUpdate = logic.getNeedUpdate();
-    const bool networkOk = logic.isNetworkOk();
-    const QString latestVer = logic.getLatestVersion();
+    progress.setWindowTitle(QCoreApplication::translate("Launcher", "SimCAE Launcher"));
+    progress.setCancelButton(nullptr);
+    progress.setWindowModality(Qt::ApplicationModal);
+    progress.setMinimumDuration(0);
+    progress.setAutoClose(false);
+    progress.show();
+    QApplication::processEvents();
+
+    ConfigHelper& config = ConfigHelper::instance();
+    const QString appDir = QApplication::applicationDirPath();
+
+    progress.setLabelText(QCoreApplication::translate("Launcher", "Checking authorized updates..."));
+    QApplication::processEvents();
+    UpdateLogic logic;
+    logic.checkUpdate();
+
+    const bool needUpdate = logic.getNeedUpdate();
+    const bool networkOk = logic.isNetworkOk();
+    const QString latestVer = logic.getLatestVersion();
     const QJsonObject response = logic.getCheckResult();
-    const int targetVersionId = response.value("version_id").toInt();
-    const QString appId = logic.getAppId();
+    const QString releaseId = response.value(QStringLiteral("release_id")).toString(
+        response.value(QStringLiteral("id")).toString());
+    const QString appId = logic.getProductCode();
     const QString channel = logic.getChannel();
-    const QString launchToken = config.getValue("App", "launch_token");
-    const QString currentVersion = config.getValue("App", "current_version");
-
-    if (logic.lastStatusCode() == 401 || logic.lastStatusCode() == 403) {
-        progress.close();
-        const QJsonValue detail = response.value("detail");
-        const QString message = detail.isObject() ? detail.toObject().value("msg").toString() : detail.toString();
-        const QString displayMessage = message.isEmpty()
-            ? QCoreApplication::translate("Launcher", "The device or License authorization is invalid.")
-            : message;
-        if (isLicenseError(displayMessage)) {
-            clearDeviceCredential();
-            const QString newLicense = promptAndSaveLicense(QCoreApplication::translate("Launcher", "The current authorization was rejected by the server: %1").arg(displayMessage));
-            if (!newLicense.isEmpty()) {
-                progress.close();
-                QMessageBox::information(nullptr,
-                    QCoreApplication::translate("Launcher", "License Saved"),
-                    QCoreApplication::translate("Launcher", "Please restart Launcher to complete device authorization and update checking."));
-            }
-            return 0;
-        }
-        QMessageBox::critical(nullptr,
-            QCoreApplication::translate("Launcher", "Authorization Rejected"),
-            displayMessage);
-        return -1;
-    }
-
+    const QString launchToken = config.getValue(QStringLiteral("App"), QStringLiteral("launch_token"));
+    const QString currentVersion = config.getValue(QStringLiteral("App"), QStringLiteral("current_version"));
+    const QString deviceId = ensureDeviceId();
+
     const auto configuredName = [&](const QString& key, const QString& fallback) {
         return ConfigHelper::executableNameForCurrentPlatform(
-            config.getValue("Runtime", key), fallback);
+            config.getValue(QStringLiteral("Runtime"), key), fallback);
     };
-    const QString mainExecutable = configuredName("main_executable", "MainApp");
-    const QString updaterExecutable = configuredName("updater_executable", "Updater");
+    const QString mainExecutable = configuredName(QStringLiteral("main_executable"), QStringLiteral("MainApp"));
+    const QString updaterExecutable = configuredName(QStringLiteral("updater_executable"), QStringLiteral("Updater"));
     const QString mainAppPath = QDir(appDir).filePath(mainExecutable);
     const QString updaterPath = QDir(appDir).filePath(updaterExecutable);
-    const auto importOfflinePackage = [&]() {
-        const QString package = QFileDialog::getOpenFileName(nullptr,
-            QCoreApplication::translate("Launcher", "Select Offline Update Package"),
-            QString(),
-            QCoreApplication::translate("Launcher", "Marsco offline update package (*.upd)"));
-        return package.isEmpty() ? false : QProcess::startDetached(updaterPath, QStringList{QString("--offline-package=%1").arg(package)});
+
+    QString mainStartupError;
+    const auto startMainApp = [&]() {
+        mainStartupError.clear();
+        if (!QFileInfo::exists(mainAppPath)) {
+            mainStartupError = QCoreApplication::translate(
+                "Launcher",
+                "Cannot start the main application because the executable file does not exist.\nExecutable: %1\nCheck main_executable and install_root in the generated client configuration.")
+                .arg(mainAppPath);
+            return false;
+        }
+
+        QString ticketPath;
+        QString ticketError;
+        if (!TicketHelper::createTicket(appId, deviceId, currentVersion,
+                                        launchToken, &ticketPath, &ticketError)) {
+            qDebug() << "Cannot create launch ticket:" << ticketError;
+            mainStartupError = QCoreApplication::translate(
+                "Launcher",
+                "Cannot start the main application because the one-time launch ticket could not be created.\nExecutable: %1\nDetails: %2")
+                .arg(mainAppPath, ticketError);
+            return false;
+        }
+
+        const bool started = QProcess::startDetached(mainAppPath,
+            QStringList{QStringLiteral("--ticket-file=%1").arg(ticketPath)});
+        if (!started) {
+            QFile::remove(ticketPath);
+            mainStartupError = QCoreApplication::translate(
+                "Launcher",
+                "Cannot start the main application process.\nExecutable: %1\nTicket file: %2\nCheck file permissions, dependent DLLs/shared libraries, and whether the executable can run independently.")
+                .arg(mainAppPath, ticketPath);
+        }
+        return started;
     };
-    const QString deviceId = config.getValue("Update", "device_id");
-    if (QCoreApplication::arguments().contains("--import-offline")) {
+
+    if (logic.lastStatusCode() == 401 || logic.lastStatusCode() == 403) {
         progress.close();
-        if (!importOfflinePackage())
-            QMessageBox::information(nullptr,
-                QCoreApplication::translate("Launcher", "Offline Update"),
-                QCoreApplication::translate("Launcher", "No offline update package was selected."));
-        return 0;
+        QMessageBox::critical(nullptr,
+            QCoreApplication::translate("Launcher", "Update Client Rejected"),
+            authFailureMessage(response,
+                QCoreApplication::translate("Launcher", "The update client token is missing or invalid. Please download a valid package from the customer portal.")));
+        return -1;
+    } else if (!networkOk) {
+        progress.close();
+        QMessageBox::warning(nullptr,
+            QCoreApplication::translate("Launcher", "Update Server Unavailable"),
+            QCoreApplication::translate("Launcher", "Cannot connect to the update server. The installed application will be started without downloading an update."));
+        progress.show();
     }
-
-    const auto startMainApp = [&]() {
-        QString ticketPath;
-        QString ticketError;
-        if (!TicketHelper::createTicket(logic.getAppId(), deviceId, currentVersion,
-                                        launchToken, &ticketPath, &ticketError)) {
-            qDebug() << "Cannot create launch ticket:" << ticketError;
-            return false;
-        }
-        const bool started = QProcess::startDetached(mainAppPath,
-            QStringList{QString("--ticket-file=%1").arg(ticketPath)});
-        if (!started) QFile::remove(ticketPath);
-        return started;
-    };
-
-    progress.setLabelText(QCoreApplication::translate("Launcher", "Verifying local runtime policy..."));
-    QApplication::processEvents();
-
-    PolicyHelper policy(appDir);
-    if (!policy.loadPolicy("config/version_policy.dat") || !policy.isValid())
-    {
-        progress.close();
-        QMessageBox::critical(nullptr,
-            QCoreApplication::translate("Launcher", "Cannot Start"),
-            QCoreApplication::translate("Launcher", "The local version policy is invalid: %1").arg(policy.errorString()));
-        return -1;
-    }
-    if (policy.isExpired())
-    {
-        progress.close();
-        QMessageBox::critical(nullptr,
-            QCoreApplication::translate("Launcher", "Cannot Start"),
-            QCoreApplication::translate("Launcher", "The local version policy has expired. Please connect to the network or contact the administrator."));
-        return -1;
-    }
-    if ((!policy.allowRun() || !policy.isVersionAllowed(currentVersion)) && !(networkOk && needUpdate))
-    {
-        progress.close();
-        QMessageBox::critical(nullptr,
-            QCoreApplication::translate("Launcher", "Current Version Cannot Run"),
-            policy.message().isEmpty() ? QCoreApplication::translate("Launcher", "The current version %1 has been disabled by the administrator.").arg(currentVersion)
-                                       : policy.message());
-        return -1;
-    }
-
-    LocalStateHelper state(appDir);
-    if (!state.loadState())
-    {
-        progress.close();
-        QMessageBox::critical(nullptr,
-            QCoreApplication::translate("Launcher", "Cannot Start"),
-            QCoreApplication::translate("Launcher", "Cannot read the local state: %1").arg(state.errorString()));
-        return -1;
-    }
-    if (state.isPolicySeqRolledBack(policy.policySeq()))
-    {
-        progress.close();
-        QMessageBox::critical(nullptr,
-            QCoreApplication::translate("Launcher", "Security Check Failed"),
-            QCoreApplication::translate("Launcher", "A version policy sequence rollback was detected. Startup has been blocked."));
-        return -1;
-    }
-    if (state.isSystemTimeRewound())
-    {
-        progress.close();
-        QMessageBox::critical(nullptr,
-            QCoreApplication::translate("Launcher", "Security Check Failed"),
-            QCoreApplication::translate("Launcher", "A possible system time rollback was detected. Startup has been blocked."));
-        return -1;
-    }
-
+
     if (networkOk && needUpdate)
     {
         progress.close();
-        const bool rollbackOperation = response.value("action").toString() == "rollback_allowed";
-        const QString dialogTitle = rollbackOperation ? QCoreApplication::translate("Launcher", "Version Rollback")
-            : (policy.forceUpdate() ? QCoreApplication::translate("Launcher", "Update Required") : QCoreApplication::translate("Launcher", "New Version Available"));
-        const QString prompt = policy.message().isEmpty()
-            ? (rollbackOperation
-                ? QCoreApplication::translate("Launcher", "The administrator provided version %1 as the rollback target. Downgrade now?").arg(latestVer)
-                : QCoreApplication::translate("Launcher", "Version %1 is available. Update now?").arg(latestVer))
-            : policy.message() + QCoreApplication::translate("Launcher", "\nTarget version: %1").arg(latestVer);
-        bool accepted = true;
-        if (policy.forceUpdate()) {
-            QMessageBox::information(nullptr, dialogTitle, prompt);
-        } else {
-            accepted = QMessageBox::question(nullptr, dialogTitle, prompt,
-                QMessageBox::Yes | QMessageBox::No, QMessageBox::No) == QMessageBox::Yes;
-        }
-        if (!accepted) {
+        const QString prompt = QCoreApplication::translate(
+            "Launcher",
+            "Version %1 is available. Update now?").arg(latestVer);
+        const bool accepted = QMessageBox::question(nullptr,
+            QCoreApplication::translate("Launcher", "New Version Available"),
+            prompt,
+            QMessageBox::Yes | QMessageBox::No,
+            QMessageBox::No) == QMessageBox::Yes;
+        if (!accepted) {
             if (!startMainApp()) {
                 QMessageBox::critical(nullptr,
                     QCoreApplication::translate("Launcher", "Startup Failed"),
-                    QCoreApplication::translate("Launcher", "Cannot start the main application: %1").arg(mainAppPath));
+                    mainStartupError.isEmpty()
+                        ? QCoreApplication::translate("Launcher", "Cannot start the main application: %1").arg(mainAppPath)
+                        : mainStartupError);
                 return -1;
             }
-            return 0;
-        }
-        const QStringList updaterArgs{appId, channel, latestVer, QString::number(targetVersionId)};
+            return 0;
+        }
+
+        const QStringList updaterArgs{
+            appId,
+            channel,
+            latestVer,
+            QStringLiteral("0"),
+            QStringLiteral("--release-id=%1").arg(releaseId)
+        };
+        if (!QFileInfo::exists(updaterPath))
+        {
+            QMessageBox::critical(nullptr,
+                QCoreApplication::translate("Launcher", "Updater Startup Failed"),
+                QCoreApplication::translate(
+                    "Launcher",
+                    "Cannot start the updater because the executable file does not exist.\nExecutable: %1\nCheck updater_executable and install_root in the generated client configuration.")
+                    .arg(updaterPath));
+            return -1;
+        }
         if (!QProcess::startDetached(updaterPath, updaterArgs))
         {
             QMessageBox::critical(nullptr,
                 QCoreApplication::translate("Launcher", "Updater Startup Failed"),
-                QCoreApplication::translate("Launcher", "Cannot start the updater: %1").arg(updaterPath));
-            return -1;
-        }
-        return 0;
-    }
-
-    if (networkOk && !needUpdate && targetVersionId > 0 && latestVer == currentVersion)
-    {
-        progress.setLabelText(QCoreApplication::translate("Launcher", "Caching signed version manifest..."));
-        QApplication::processEvents();
-        const QString manifestCacheDir = QDir(ConfigHelper::instance().updateRoot()).filePath("manifest_cache");
-        if (!logic.cacheManifest(appId, channel, currentVersion, targetVersionId, manifestCacheDir))
-        {
-            progress.close();
-            QMessageBox::critical(nullptr,
-                QCoreApplication::translate("Launcher", "Manifest Cache Failed"),
-                QCoreApplication::translate("Launcher", "Cannot cache the signed manifest for the current version: %1").arg(logic.errorString()));
+                QCoreApplication::translate(
+                    "Launcher",
+                    "Cannot start the updater process.\nExecutable: %1\nArguments: %2\nCheck file permissions, dependent DLLs/shared libraries, and whether the updater can run independently.")
+                    .arg(updaterPath, updaterArgs.join(QStringLiteral(" "))));
             return -1;
         }
-    }
-
-    if (!networkOk) {
-        progress.close();
-        if (QMessageBox::question(nullptr,
-                                  QCoreApplication::translate("Launcher", "Server Unavailable"),
-                                  QCoreApplication::translate("Launcher", "Cannot connect to the update server. Import an offline update package?"),
-                                  QMessageBox::Yes | QMessageBox::No, QMessageBox::No) == QMessageBox::Yes) {
-            if (!importOfflinePackage())
-                QMessageBox::information(nullptr,
-                    QCoreApplication::translate("Launcher", "Offline Update"),
-                    QCoreApplication::translate("Launcher", "No offline update package was selected, or the updater could not be started."));
-            return 0;
-        }
-        progress.show();
-    }
-
-    if (!networkOk && !policy.isOfflineAllowed())
-    {
-        progress.close();
-        QMessageBox::critical(nullptr,
-            QCoreApplication::translate("Launcher", "Network Unavailable"),
-            QCoreApplication::translate("Launcher", "Cannot connect to the update server, and the current policy does not allow offline startup."));
-        return -1;
+        return 0;
     }
 
     progress.setLabelText(networkOk
         ? QCoreApplication::translate("Launcher", "The application is up to date. Starting...")
-        : QCoreApplication::translate("Launcher", "Offline mode is active. Starting..."));
-    QApplication::processEvents();
-    if (!startMainApp())
-    {
-        progress.close();
+        : QCoreApplication::translate("Launcher", "Offline startup. Starting..."));
+    QApplication::processEvents();
+    if (!startMainApp())
+    {
+        progress.close();
         QMessageBox::critical(nullptr,
             QCoreApplication::translate("Launcher", "Startup Failed"),
-            QCoreApplication::translate("Launcher", "Cannot start the main application: %1").arg(mainAppPath));
-        return -1;
-    }
-    progress.close();
-    return 0;
-}
+            mainStartupError.isEmpty()
+                ? QCoreApplication::translate("Launcher", "Cannot start the main application: %1").arg(mainAppPath)
+                : mainStartupError);
+        return -1;
+    }
+    progress.close();
+    return 0;
+}

MainApp/MainWindow.cpp

@@ -1,72 +1,69 @@
-#include "MainWindow.h"
-#include <QApplication>
-#include <QFont>
-#include <QFile>
-#include <QLabel>
-#include <QVBoxLayout>
-#include <QCryptographicHash>
-#include "../Common/PolicyHelper.h"
-#include "../Common/ConfigHelper.h"
-
-static QString readDllVersion(const QString& dllPath)
-{
-    QFile file(dllPath);
-    if (!file.exists())
-        return "missing";
-
-    if (!file.open(QIODevice::ReadOnly))
-        return "unreadable";
-
-    QByteArray data = file.read(1024);
-    file.close();
-    return QString::fromUtf8(QCryptographicHash::hash(data, QCryptographicHash::Sha256).toHex().left(8));
-}
-
-MainWindow::MainWindow(QWidget* parent)
-    : QWidget(parent)
-{
-    this->setWindowTitle("Marsco Demo MainApp");
-    this->resize(600, 400);
-
-    QString appVersion = ConfigHelper::instance().getValue("App", "current_version");
-    if (appVersion.isEmpty())
-        appVersion = "unknown";
-
-    QString dllVersion = readDllVersion(QApplication::applicationDirPath() + "/plugins/demo_plugin.dll");
-
-    PolicyHelper policy(QApplication::applicationDirPath());
-    QString policyResult;
-    if (!policy.loadPolicy("config/version_policy.dat"))
-    {
-        policyResult = "policy missing";
-    }
-    else if (!policy.isValid())
-    {
-        policyResult = "policy invalid";
-    }
-    else if (!policy.isVersionAllowed(appVersion))
-    {
-        policyResult = "version disabled";
-    }
-    else if (policy.isExpired())
-    {
-        policyResult = "policy expired";
-    }
-    else
-    {
-        policyResult = "policy ok";
-    }
-
-    QVBoxLayout* layout = new QVBoxLayout(this);
-    QLabel* label = new QLabel(QString("Software Running Successfully\nVersion: %1\nDLL Version: %2\nPolicy: %3")
-        .arg(appVersion)
-        .arg(dllVersion)
-        .arg(policyResult));
-    QFont font = label->font();
-    font.setPointSize(14);
-    label->setFont(font);
-    label->setAlignment(Qt::AlignCenter);
-
-    layout->addWidget(label);
-    this->setLayout(layout);
-}
+#include "MainWindow.h"
+
+#include <QApplication>
+#include <QCryptographicHash>
+#include <QFile>
+#include <QFont>
+#include <QLabel>
+#include <QVBoxLayout>
+
+#include "../Common/ConfigHelper.h"
+
+namespace {
+
+QString configValue(const QString& key, const QString& fallback = QString())
+{
+    const QString value = ConfigHelper::instance().getValue(QString(), key).trimmed();
+    return value.isEmpty() ? fallback : value;
+}
+
+QString readDllVersion(const QString& dllPath)
+{
+    QFile file(dllPath);
+    if (!file.exists())
+        return QStringLiteral("missing");
+
+    if (!file.open(QIODevice::ReadOnly))
+        return QStringLiteral("unreadable");
+
+    const QByteArray data = file.read(1024);
+    file.close();
+    return QString::fromUtf8(QCryptographicHash::hash(data, QCryptographicHash::Sha256).toHex().left(8));
+}
+
+} // namespace
+
+MainWindow::MainWindow(QWidget* parent)
+    : QWidget(parent)
+{
+    this->setWindowTitle("SimCAE Demo MainApp");
+    this->resize(600, 400);
+
+    const QString appVersion = configValue(QStringLiteral("current_version"), QStringLiteral("unknown"));
+    const QString product = configValue(QStringLiteral("product_code"),
+        configValue(QStringLiteral("app_id"), QStringLiteral("unknown")));
+    const QString channel = configValue(QStringLiteral("channel"), QStringLiteral("stable"));
+    const QString apiBaseUrl = configValue(QStringLiteral("api_base_url"), QStringLiteral("not configured"));
+    const QString tokenState = configValue(QStringLiteral("client_token")).isEmpty()
+        ? QStringLiteral("missing")
+        : QStringLiteral("configured");
+    const QString dllVersion = readDllVersion(QApplication::applicationDirPath() + "/plugins/demo_plugin.dll");
+
+    QVBoxLayout* layout = new QVBoxLayout(this);
+    QLabel* label = new QLabel(QString(
+        "Software Running Successfully\n"
+        "Product: %1\n"
+        "Version: %2\n"
+        "Channel: %3\n"
+        "Server: %4\n"
+        "Update Client Token: %5\n"
+        "DLL Version: %6")
+        .arg(product, appVersion, channel, apiBaseUrl, tokenState, dllVersion));
+    QFont font = label->font();
+    font.setPointSize(13);
+    label->setFont(font);
+    label->setAlignment(Qt::AlignCenter);
+
+    layout->addWidget(label);
+    this->setLayout(layout);
+}

MainApp/main.cpp

@@ -1,133 +1,115 @@
-#include <QApplication>
-#include <QDebug>
-#include <QMessageBox>
-#include <QDir>
-#include <QFileInfo>
-#include <QSaveFile>
-#include <QTranslator>
-#include "MainWindow.h"
-#include "../Common/ConfigHelper.h"
-#include "../Common/PolicyHelper.h"
-#include "../Common/LocalStateHelper.h"
-#include "../Common/TicketHelper.h"
-#include "../Common/IntegrityHelper.h"
-#include "../Common/DeviceIdentityHelper.h"
-
-int main(int argc, char* argv[])
-{
-    QApplication a(argc, argv);
-    QTranslator translator;
-    if (translator.load(":/i18n/update-client_zh_CN.qm"))
-        a.installTranslator(&translator);
-
-    const int elevatedWriteExitCode = ConfigHelper::runElevatedWriteCommandIfRequested();
-    if (elevatedWriteExitCode >= 0)
-        return elevatedWriteExitCode;
-
-    qDebug() << Qt::endl << "entered main app" << Qt::endl;
-
+#include <QApplication>
+#include <QDebug>
+#include <QDir>
+#include <QFileInfo>
+#include <QMessageBox>
+#include <QSaveFile>
+#include <QTranslator>
+
+#include "MainWindow.h"
+#include "../Common/ConfigHelper.h"
+#include "../Common/IntegrityHelper.h"
+#include "../Common/TicketHelper.h"
+
+namespace {
+
+QString configValue(const QString& key, const QString& fallback = QString())
+{
+    const QString value = ConfigHelper::instance().getValue(QString(), key).trimmed();
+    return value.isEmpty() ? fallback : value;
+}
+
+QString productCode()
+{
+    return configValue(QStringLiteral("product_code"),
+        configValue(QStringLiteral("app_id")));
+}
+
+bool configFlag(const QString& key)
+{
+    const QString value = configValue(key).toLower();
+    return value == QStringLiteral("true")
+        || value == QStringLiteral("1")
+        || value == QStringLiteral("yes")
+        || value == QStringLiteral("on");
+}
+
+} // namespace
+
+int main(int argc, char* argv[])
+{
+    QApplication a(argc, argv);
+    QTranslator translator;
+    if (translator.load(QStringLiteral(":/i18n/update-client_zh_CN.qm")))
+        a.installTranslator(&translator);
+
+    const int elevatedWriteExitCode = ConfigHelper::runElevatedWriteCommandIfRequested();
+    if (elevatedWriteExitCode >= 0)
+        return elevatedWriteExitCode;
+
+    qDebug() << Qt::endl << "entered main app" << Qt::endl;
+
     ConfigHelper& config = ConfigHelper::instance();
-    QString launcherExecutable = config.getValue("Runtime", "launcher_executable").trimmed();
-    launcherExecutable = ConfigHelper::executableNameForCurrentPlatform(launcherExecutable, "Launcher");
-    QString ticketFilePath;
-    QString healthFilePath;
-    for (int i = 1; i < argc; ++i)
-    {
-        const QString arg(argv[i]);
-        if (arg.startsWith("--ticket-file="))
-            ticketFilePath = arg.mid(QString("--ticket-file=").size());
-        else if (arg.startsWith("--health-file="))
-            healthFilePath = arg.mid(QString("--health-file=").size());
-    }
-
-    QString ticketError;
-    if (ticketFilePath.isEmpty()
-        || !TicketHelper::consumeAndVerify(ticketFilePath,
-            config.getValue("App", "app_id"), config.getValue("Update", "device_id"),
-            config.getValue("App", "current_version"), config.getValue("App", "launch_token"),
-            &ticketError))
-    {
-        QMessageBox::critical(nullptr, "Startup Restriction",
-            QString("Invalid or missing one-time launch ticket: %1\nPlease use %2.")
-                .arg(ticketError, launcherExecutable));
-        return -1;
-    }
-
-    QString appDir = QApplication::applicationDirPath();
-    const QString installRoot = config.installRoot();
-    DeviceIdentityHelper identity(appDir);
-    if (!identity.verifyLocal(config.getValue("App", "app_id"), config.getValue("App", "channel")))
-    {
-        QMessageBox::critical(nullptr, "License Error", QString("Local license invalid: %1").arg(identity.errorString()));
-        return -1;
-    }
-    PolicyHelper policy(appDir);
-    if (!policy.loadPolicy("config/version_policy.dat") || !policy.isValid())
-    {
-        QMessageBox::critical(nullptr, "Policy Error", QString("Local policy invalid: %1").arg(policy.errorString()));
-        return -1;
-    }
-
-    if (policy.isExpired())
-    {
-        QMessageBox::critical(nullptr, "Policy Error", "Policy expired, cannot start the application.");
-        return -1;
-    }
-
-    LocalStateHelper state(appDir);
-    if (!state.loadState())
-    {
-        QMessageBox::critical(nullptr, "State Error", QString("Cannot load local state: %1").arg(state.errorString()));
-        return -1;
-    }
-
-    if (state.isPolicySeqRolledBack(policy.policySeq()))
-    {
-        QMessageBox::critical(nullptr, "Policy Error", "Detected policy sequence rollback, startup blocked.");
-        return -1;
-    }
-
-    if (state.isSystemTimeRewound())
-    {
-        QMessageBox::critical(nullptr, "Policy Error", "System time appears to be rewound, startup blocked.");
-        return -1;
-    }
-
-    IntegrityHelper integrity(installRoot);
-    if (!integrity.verifyInstalledVersion(
-            config.getValue("App", "app_id"), config.getValue("App", "channel"),
-            config.getValue("App", "current_version")))
-    {
-        QMessageBox::critical(nullptr, "Integrity Check Failed",
-            QString("Application files failed signed Manifest verification:\n%1")
-                .arg(integrity.errorString()));
-        return -1;
-    }
-
-    MainWindow w;
-    w.show();
-
-    state.updateAfterSuccessfulRun(ConfigHelper::instance().getValue("App", "current_version"), policy.policySeq());
-    if (!state.saveState())
-    {
-        QMessageBox::critical(nullptr, "State Error", QString("Cannot save local state: %1").arg(state.errorString()));
-        return -1;
-    }
-
-    if (!healthFilePath.isEmpty())
-    {
-        QDir().mkpath(QFileInfo(healthFilePath).path());
-        QSaveFile healthFile(healthFilePath);
-        const QByteArray healthy("ok\n");
-        if (!healthFile.open(QIODevice::WriteOnly)
-            || healthFile.write(healthy) != healthy.size()
-            || !healthFile.commit())
-        {
-            QMessageBox::critical(nullptr, "Startup Error", "Cannot write update health confirmation file.");
-            return -1;
-        }
-    }
-
-    qDebug() << "Main program MainApp is running normally";
-    return a.exec();
-}
+    QString launcherExecutable = config.getValue(QStringLiteral("Runtime"), QStringLiteral("launcher_executable")).trimmed();
+    launcherExecutable = ConfigHelper::executableNameForCurrentPlatform(launcherExecutable, QStringLiteral("Launcher"));
+
+    QString ticketFilePath;
+    QString healthFilePath;
+    for (int i = 1; i < argc; ++i)
+    {
+        const QString arg(argv[i]);
+        if (arg.startsWith(QStringLiteral("--ticket-file=")))
+            ticketFilePath = arg.mid(QStringLiteral("--ticket-file=").size());
+        else if (arg.startsWith(QStringLiteral("--health-file=")))
+            healthFilePath = arg.mid(QStringLiteral("--health-file=").size());
+    }
+
+    QString ticketError;
+    if (ticketFilePath.isEmpty()
+        || !TicketHelper::consumeAndVerify(ticketFilePath,
+            productCode(), config.getValue(QStringLiteral("Update"), QStringLiteral("device_id")),
+            config.getValue(QStringLiteral("App"), QStringLiteral("current_version")),
+            config.getValue(QStringLiteral("App"), QStringLiteral("launch_token")),
+            &ticketError))
+    {
+        QMessageBox::critical(nullptr, "Startup Restriction",
+            QString("Invalid or missing one-time launch ticket: %1\nPlease use %2.")
+                .arg(ticketError, launcherExecutable));
+        return -1;
+    }
+
+    const QString installRoot = config.installRoot();
+    if (configFlag(QStringLiteral("verify_installed_on_start"))) {
+        IntegrityHelper integrity(installRoot);
+        if (!integrity.verifyInstalledVersion(
+                productCode(),
+                config.getValue(QStringLiteral("App"), QStringLiteral("channel")),
+                config.getValue(QStringLiteral("App"), QStringLiteral("current_version"))))
+        {
+            QMessageBox::critical(nullptr, "Integrity Check Failed",
+                QString("Startup blocked because the installed files failed local Manifest verification.\n\nDetails:\n%1")
+                    .arg(integrity.errorString()));
+            return -1;
+        }
+    }
+
+    if (!healthFilePath.isEmpty())
+    {
+        QDir().mkpath(QFileInfo(healthFilePath).path());
+        QSaveFile healthFile(healthFilePath);
+        const QByteArray healthy("ok\n");
+        if (!healthFile.open(QIODevice::WriteOnly)
+            || healthFile.write(healthy) != healthy.size()
+            || !healthFile.commit())
+        {
+            QMessageBox::critical(nullptr, "Startup Error", "Cannot write update health confirmation file.");
+            return -1;
+        }
+    }
+
+    MainWindow w;
+    w.show();
+
+    qDebug() << "Main program MainApp is running normally";
+    return a.exec();
+}

README.md

@@ -0,0 +1,265 @@
+# SimCAE Hub 更新客户端
+
+`update-client` 是 SimCAE Hub 的 Qt/C++ 整包更新客户端，包含 `Launcher`、`Updater`、`Bootstrap` 和一个示例 `MainApp`。它负责检查整包更新、拉取 Manifest、下载发布包、校验哈希并完成本地安装。
+
+组件级安装、组件级更新和卸载由 Qt IFW 生成的 `maintenancetool.exe` 负责。`update-client` 不替代 MaintenanceTool，也不读取 Qt IFW 的 `Updates.xml`。
+
+## 一、当前接入方式
+
+当前 SIMCAE 的标准接入方式是：
+
+| 阶段 | 发生什么 |
+| --- | --- |
+| SDK 打包 | `update-client` 只打出 `Launcher.exe`、`Updater.exe`、`Bootstrap.exe` 和运行库 |
+| SIMCAE 打包 | SIMCAE 的 `installer` 规则把 SDK 文件放进核心组件 `com.simcae.app` |
+| 本地 IFW package | Hub 更新客户端位于 `package/packages/com.simcae.app/data/view/bin` |
+| 上传到 Hub | 服务端校验 IFW 交付包，并自动注入最终客户配置 |
+| 客户安装 | 客户从门户下载安装器，安装后得到 `maintenancetool.exe` 和 `view/bin/Launcher.exe` |
+| 日常启动 | 客户通过 `Launcher.exe` 或安装器创建的快捷方式启动 SimCAE |
+
+最终客户不需要手动填写 `app_config.json`、服务器地址、token、产品编码、平台架构或版本号。
+
+## 二、程序组成
+
+| 程序 | 作用 |
+| --- | --- |
+| `Launcher` | 客户日常启动入口，读取配置、检查整包更新、启动 `Updater` 或主程序 |
+| `Updater` | 拉取 Manifest、下载发布包、校验文件、准备安装事务 |
+| `Bootstrap` | 替换运行中文件，并把安装结果交回 `Updater` |
+| `MainApp` | 示例主程序，用于验证 launch ticket 和启动前完整性校验 |
+| `Common` | 配置、HTTP、票据、路径、Manifest 和完整性校验等公共代码 |
+
+真实接入 SIMCAE 时，`MainApp` 只是示例程序。正式主程序是 SIMCAE 自己的 `SimCAE.exe`。
+
+## 三、在线更新链路
+
+1. 客户启动 `Launcher.exe`。
+2. 客户端读取服务端注入的初始配置。
+3. 首次启动时，客户端会把 `app_config.json` 中的运行配置导入本机用户配置。
+4. 为减少明文配置暴露，导入成功后客户端可能清空安装目录里的 `app_config.json`。
+5. `Launcher` 确保本机有 `device_id`。
+6. `Launcher` 使用 `X-Client-Token` 调用更新检查接口。
+7. 如果服务端返回可用发布，`Launcher` 启动 `Updater`。
+8. `Updater` 使用 `X-Client-Token` 拉取 Manifest。
+9. `Updater` 校验 Manifest 摘要，并按配置决定是否要求签名。
+10. `Updater` 按 Manifest 下载文件。
+11. 每个文件下载完成后校验大小和 SHA-256。
+12. 安装前校验 staging 目录。
+13. 如需替换运行中文件，`Bootstrap` 接管安装。
+14. 安装完成后保存 Manifest 缓存和本地状态。
+15. 如果主程序开启启动前完整性校验，下次启动时会按本地 Manifest 缓存校验已安装文件。
+
+更新接口使用部署级 `client_token`，不使用客户邮箱密码。客户账号和授权主要控制门户下载、客户权益和席位，不要求最终客户启动软件时再登录。
+
+## 四、当前 SIMCAE 目录规则
+
+客户安装完成后的关键目录是：
+
+| 路径 | 说明 |
+| --- | --- |
+| `maintenancetool.exe` | Qt IFW 生成的组件维护工具，位于安装根目录 |
+| `components.xml` | Qt IFW 记录的已安装组件状态，位于安装根目录 |
+| `network.xml` | Qt IFW 记录的组件仓库地址，位于安装根目录 |
+| `view/bin/Launcher.exe` | Hub 更新客户端启动入口 |
+| `view/bin/Updater.exe` | Hub 整包更新程序 |
+| `view/bin/Bootstrap.exe` | Hub 安装接管程序 |
+| `view/bin/SimCAE.exe` | SIMCAE 业务主程序 |
+| `view/bin/config/app_config.json` | 服务端注入的初始客户配置 |
+
+当前服务端会识别三种运行目录：
+
+| 运行目录 | 服务端写入的 `install_root` | 说明 |
+| --- | --- | --- |
+| 软件根目录 | `.` | `Launcher` 和主程序就在软件根目录 |
+| `bin` | `..` | `Launcher` 在一层 `bin` 目录中 |
+| `view/bin` | `../..` | 当前 SIMCAE 标准结构，`Launcher` 在 `view/bin` 中 |
+
+`install_root` 不是让客户手动填写的字段。上传发布包或 Qt IFW 交付包时，服务端会根据 `Launcher`、`Updater`、`Bootstrap` 的实际位置自动判断。
+
+## 五、服务端注入的配置
+
+正式客户包中的 `app_config.json` 由服务端生成或替换。开发者打 SDK 时不放最终配置，客户也不手动改配置。
+
+服务端生成配置时，信息来源如下：
+
+| 配置内容 | 来源 |
+| --- | --- |
+| `product_code`、`app_id` | 管理后台“产品目录”的产品编码 |
+| `app_name` | 管理后台“产品目录”的产品名称 |
+| `channel` | 管理后台“软件发布”的发布通道 |
+| `current_version` | 管理后台“产品版本”的版本号 |
+| `platform`、`arch`、`abi` | 管理后台“平台管理”和发布包选择的平台 |
+| `api_base_url` | 服务端 `.env` 的 `SIMCAE_CLIENT_API_BASE_URL` |
+| `client_token` | 服务端 `.env` 的 `SIMCAE_CLIENT_TOKEN` |
+| `launch_token` | 服务端 `.env` 的 `SIMCAE_LAUNCH_TOKEN` |
+| `install_root` | 服务端根据运行目录自动判断 |
+| `main_executable` | 服务端在运行目录中识别到的业务主程序，SIMCAE 当前为 `SimCAE.exe` |
+| `launcher_executable` | 按平台生成，Windows 为 `Launcher.exe` |
+| `updater_executable` | 按平台生成，Windows 为 `Updater.exe` |
+| `bootstrap_executable` | 按平台生成，Windows 为 `Bootstrap.exe` |
+| `require_manifest_signature` | 服务端 Manifest 签名配置 |
+| `verify_installed_on_start` | 当前服务端默认写入 `false`，需要强制启动校验时再按发布策略开启 |
+
+如果上传包里已经带了旧的 `app_config.json`、`server_config.json`、`server_config.qrc` 或 `manifest_public_key.pem`，服务端会按当前发布信息重新处理，不让开发机临时配置直接进入最终客户包。
+
+## 六、本地调试配置
+
+正式发布不要手写最终 `app_config.json`。如果开发者只是在本机调试 `Launcher` 或 `Updater`，可以创建未提交的 `config/app_config.local.json`。
+
+CMake 只在本地输出目录还没有 `config/app_config.json` 时，才会把 `app_config.local.json` 复制成调试用配置。这个文件只服务本机调试，不代表服务端最终注入结果。
+
+`config/server_config.json` 和 `config/server_config.qrc` 用于把兜底 API 地址编译进 EXE。正式客户包优先使用服务端注入的 `api_base_url`，一般不需要让客户看到或修改 `server_config.json`。
+
+## 七、启动门禁
+
+如果 SIMCAE 主程序开启 `SimCAE_UseLauncher=ON`，用户直接双击 `SimCAE.exe` 会被拦截，必须通过 `Launcher.exe` 启动。
+
+这套机制依赖 `launch_token`：
+
+| 位置 | 要求 |
+| --- | --- |
+| 服务端 `.env` | 必须配置 `SIMCAE_LAUNCH_TOKEN` |
+| SIMCAE 编译期 | 主程序编译时使用同一个 token |
+| 客户端配置 | 服务端把同一个 token 写入最终客户配置 |
+
+如果三处 token 不一致，就会出现“直接双击被拦住，但从 `Launcher` 启动也失败”的问题。
+
+## 八、Manifest 和哈希校验
+
+整包更新使用 SimCAE Hub Manifest，不使用 Qt IFW 的 `Updates.xml`。
+
+Manifest 负责描述：
+
+| 内容 | 说明 |
+| --- | --- |
+| 发布版本 | 本次更新属于哪个产品、版本线、版本和通道 |
+| 文件清单 | 本次发布包含哪些文件 |
+| 下载地址 | 每个文件从哪个受控接口下载 |
+| 文件大小 | 客户端下载后必须一致 |
+| SHA-256 | 客户端下载后必须一致 |
+| 是否必选 | 必选文件缺失会阻止启动，可选组件文件可由 MaintenanceTool 管理 |
+
+服务端返回 Manifest 前会重新检查发布包文件是否存在、大小是否一致、SHA-256 是否一致。客户端下载完成后也会再次校验大小和 SHA-256。
+
+## 九、和 MaintenanceTool 的边界
+
+| 能力 | 使用程序 | 文件格式 |
+| --- | --- | --- |
+| 整包更新 | `Launcher`、`Updater`、`Bootstrap` | SimCAE Hub 发布包和 Manifest |
+| 组件安装、更新、移除 | `maintenancetool.exe` | Qt IFW repository 和 `Updates.xml` |
+
+两条线可以共存，但不要混淆：
+
+1. `Updater` 不读取 `Updates.xml`。
+2. `MaintenanceTool` 不读取 SimCAE Hub Manifest。
+3. `Updater` 不拉起 `MaintenanceTool`。
+4. `MaintenanceTool` 由客户手动打开，或由 Qt IFW 自己的流程使用。
+5. 核心组件通常包含 `Launcher`、`Updater`、`Bootstrap` 和 `SimCAE.exe`。
+6. 可选组件例如 DAP 插件，可以由 MaintenanceTool 单独安装、更新或移除。
+
+## 十、编译环境
+
+| 依赖 | 要求 |
+| --- | --- |
+| CMake | 建议 3.20 或更高版本 |
+| C++ | C++17 |
+| Qt | Qt 5，至少需要 Core、Network、Gui、Widgets |
+| OpenSSL | 用于 Manifest RSA-SHA256 验签 |
+| 编译器 | Windows 推荐 Visual Studio 2022 x64，Linux 推荐 gcc/g++ |
+
+项目提供的 CMake Preset：
+
+| Preset | 平台 | 用途 |
+| --- | --- | --- |
+| `x64-debug` | Windows | Debug 编译 |
+| `x64-release` | Windows | Release 编译 |
+| `linux-x64-debug` | Linux | Debug 编译 |
+| `linux-x64-release` | Linux | Release 编译 |
+
+## 十一、Windows 编译
+
+建议安装 Visual Studio 2022、Qt 5 x64、CMake 和 OpenSSL x64。
+
+如果 Qt 没有加入环境变量，可以在编译前指定：
+
+```powershell
+$env:CMAKE_PREFIX_PATH = "C:\Qt\5.15.2\msvc2019_64"
+```
+
+当前测试机 OpenSSL 路径是 `C:\Program Files\OpenSSL-Win64`，Release 编译命令：
+
+```powershell
+cmake --preset x64-release -DSIMCAE_OPENSSL_ROOT="C:\Program Files\OpenSSL-Win64"
+cmake --build --preset x64-release
+```
+
+如果 OpenSSL 安装在其他目录，只改 `SIMCAE_OPENSSL_ROOT` 这一项。
+
+Windows Release 产物通常输出到 `out/bin/Release`。
+
+检查核心程序：
+
+```powershell
+Test-Path .\out\bin\Release\Launcher.exe
+Test-Path .\out\bin\Release\Updater.exe
+Test-Path .\out\bin\Release\Bootstrap.exe
+```
+
+预期都返回 `True`。
+
+## 十二、Linux 编译
+
+Ubuntu 示例：
+
+```bash
+sudo apt update
+sudo apt install -y build-essential cmake qtbase5-dev qttools5-dev qttools5-dev-tools libssl-dev
+cmake --preset linux-x64-release
+cmake --build --preset linux-x64-release
+```
+
+Linux 下通常直接使用系统 OpenSSL；如果需要指定自定义 OpenSSL，也可以通过 CMake 变量配置。
+
+## 十三、打包 SDK
+
+SDK 打包流程见当前目录 [updater打包成SDK.md](updater打包成SDK.md)。SIMCAE 拿到 SDK 后的安装器、交付包和上传流程见 [SIMCAE打包上传.md](SIMCAE打包上传.md)。
+
+常用输出：
+
+| 输出 | 说明 |
+| --- | --- |
+| `dist\UpdateClientSDK` | 不带 Qt 运行库的 SDK 展开目录 |
+| `dist\UpdateClientSDK.zip` | 不带 Qt 运行库的 SDK 压缩包 |
+| `dist\UpdateClientSDK-With-QtDll` | 带 Qt 运行库 DLL 的 SDK 展开目录 |
+| `dist\UpdateClientSDK-With-QtDll.zip` | 推荐交给 SIMCAE 开发者的 SDK 压缩包 |
+
+SDK 不包含最终客户配置。`With-QtDll` 表示包里带的是运行所需的 Qt DLL，不是完整 Qt SDK。SDK 的目标是给 SIMCAE 打包流程提供更新客户端程序和运行库。
+
+## 十四、运行数据位置
+
+Windows 运行配置会导入当前用户配置，按安装运行目录计算 installation id。运行数据目录通常位于：
+
+`%LOCALAPPDATA%\SimCAE\HubUpdateClient\installations\<安装目录SHA256>\`
+
+Linux 运行数据目录通常位于：
+
+`$XDG_DATA_HOME/SimCAE/HubUpdateClient/installations/<安装目录SHA256>/`
+
+未设置 `XDG_DATA_HOME` 时通常是：
+
+`~/.local/share/SimCAE/HubUpdateClient/installations/<安装目录SHA256>/`
+
+Manifest 缓存保存在运行数据目录下的 `update/manifest_cache`。
+
+## 十五、常见问题
+
+| 现象 | 排查方向 |
+| --- | --- |
+| 客户启动后提示配置不完整 | 检查交付包是否经过 SimCAE Hub 上传注入，不要直接拿本地未注入包给客户 |
+| 检查更新没有结果 | 检查后台发布是否已发布、发布包是否可用、产品编码、通道和平台是否一致 |
+| 下载返回 401 | 检查客户包里的 `client_token` 是否来自当前服务端 `.env` |
+| Manifest 校验失败 | 检查服务端文件是否被手工改过，大小和 SHA-256 是否与数据库一致 |
+| 强制签名失败 | 检查 `manifest_public_key.pem` 与服务端私钥是否匹配 |
+| 主程序启动失败 | 检查 `main_executable` 和运行目录是否正确 |
+| 从 `Launcher` 启动也被拦截 | 检查服务端、SIMCAE 编译期和客户配置中的 `launch_token` 是否一致 |
+| MaintenanceTool 看不到组件更新 | 检查 IFW repository 地址、`Updates.xml` 和组件版本是否正确 |

SIMCAE打包上传.md

@@ -0,0 +1,621 @@
+# SIMCAE 打包上传
+
+本文站在 SIMCAE 开发者和发布人员的角度，说明拿到 Hub 更新客户端 SDK 后，SIMCAE 怎么打安装器、怎么生成 Qt IFW 交付包、怎么上传到 SimCAE Hub。
+
+服务端部署流程见 simcae-hub 项目根目录《服务端部署.md》。普通发布人员只需要拿到已经打好的更新客户端 SDK；如果需要重新生成 SDK，见源代码仓库 `SIMCAE/update-client/updater打包成SDK.md`。
+
+本文下面的命令默认在 SIMCAE 项目根目录执行。下面用 SIMCAE 当前放在 simcae-hub 项目里的情况举例：
+
+```powershell
+cd .\SIMCAE
+```
+
+进入后再使用相对路径，例如 `.\installer`、`.\update-client`、`.\out\build\...`。这样不要求开发者的 SIMCAE 一定放在某个固定磁盘目录。
+
+## 一、先理解交付物
+
+客户端交付会涉及三类文件：
+
+| 交付物 | 给谁用 | 作用 |
+| --- | --- | --- |
+| Hub 更新客户端 SDK | SIMCAE 开发者 | 提供 `Launcher.exe`、`Updater.exe`、`Bootstrap.exe` 和必要运行库 |
+| Qt IFW 交付包 ZIP | 上传到 SimCAE Hub | 包含 IFW package 和 repository，服务端会校验、注入配置、发布仓库并重新生成客户安装器 |
+| 客户安装器 | 最终客户 | 客户从门户下载后双击安装，安装后得到 `maintenancetool.exe` |
+
+正式主线是：开发者只上传一个 Qt IFW 交付包 ZIP，客户只从门户下载客户安装器。客户不需要手动改服务器地址、token 或 `app_config.json`。
+
+## 二、准备 Hub 更新客户端 SDK
+
+开发者应拿到 `UpdateClientSDK-With-QtDll.zip`。
+
+这个 ZIP 由 `update-client` 仓库的 SDK 打包脚本生成，SDK 维护者按源代码仓库 `SIMCAE/update-client/updater打包成SDK.md` 操作即可。
+
+建议手动解压到 SIMCAE 仓库内的固定相对目录：`.\update-client\dist\UpdateClientSDK-With-QtDll`。
+
+这里的 `With-QtDll` 表示包里带的是运行所需的 Qt DLL，不是完整 Qt SDK。
+
+如果公司内部统一把 SDK 放在别的位置，也可以，只要后面 `$UpdateClientSdk` 指向解压后的 SDK 目录即可。
+
+解压后至少应有：
+
+- `bin\Launcher.exe`
+- `bin\Updater.exe`
+- `bin\Bootstrap.exe`
+
+SDK 包不应该包含最终客户配置，例如 `app_config.json`、`server_config.json`、`server_config.qrc`、`manifest_public_key.pem`。这些最终配置由服务端在上传发布包时生成或注入。
+
+## 三、准备 SIMCAE 已编译产物
+
+默认 SIMCAE 已经在开发机上完成 Release 编译。客户端打包文档不要求每次重新全量编译 SIMCAE，因为 SIMCAE 工程很大，打安装包时通常只需要复用已有 Release 产物。
+
+需要确认：
+
+| 内容 | 说明 |
+| --- | --- |
+| SIMCAE Release 构建目录 | 已经存在 `SimCAE.exe`、库文件、资源文件 |
+| Qt Installer Framework | 已经安装 `binarycreator.exe` 和 `repogen.exe` |
+| DAP 运行时 | 如果启用 DAP 组件，`DAPrailCalxml` 等运行时已放在打包规则要求的位置 |
+| Hub 更新客户端 SDK | 已解压，并能找到 `Launcher.exe`、`Updater.exe`、`Bootstrap.exe` |
+
+如果业务主程序启用了“必须从 Launcher 启动”的门禁，SIMCAE 编译时使用的 launch token 必须和服务端 `.env` 里的 `SIMCAE_LAUNCH_TOKEN` 一致。
+
+## 四、设置本次打包版本
+
+SIMCAE 安装器文件名、IFW 组件 `package.xml` 版本、repository 里的 `Updates.xml` 版本都来自 CMake 变量 `SimCAE_Version`。这个版本默认读取 SIMCAE 仓库最近的纯数字 Git tag，例如 `1.1.3`。
+
+先把几个容易混淆的“版本标签”分清楚：
+
+| 名称 | 写在哪里 | 谁会读取 | 作用 |
+| --- | --- | --- | --- |
+| Git tag | SIMCAE 仓库提交，例如 `git tag 1.1.3` | CMake 版本脚本 | 生成 `SimCAE_Version`，再写入安装器文件名和组件元数据 |
+| 组件版本 | `packages/<组件ID>/meta/package.xml` 的 `<Version>` | `repogen.exe` | 生成 repository 时写入 `Updates.xml` |
+| repository 组件版本 | `Updates.xml` 里的 `<PackageUpdate><Name>...` 和 `<Version>...` | `maintenancetool.exe` | 客户端判断某个组件是否需要更新 |
+| ZIP 文件名 | 例如 `SimCAE-Delivery-1.1.3-windows_x86_64-msvc.zip` | 人和管理后台记录 | 方便识别上传文件，不是 MaintenanceTool 的更新依据 |
+
+所以 `git tag 1.1.3` 打的是 SIMCAE 源码提交标签，不是给 ZIP 文件打标签。它会被 CMake 读取后间接变成组件 `package.xml` 里的版本。真正决定 MaintenanceTool 是否更新的是服务器 repository 的 `Updates.xml`，而 `Updates.xml` 又来自组件自己的 `package.xml`。
+
+正式发布时推荐在 SIMCAE 仓库给本次发布提交打纯数字 tag，再打包：
+
+```powershell
+git tag 1.1.3
+```
+
+如果只是本机演示，不想改 SIMCAE 仓库 tag，可以临时指定本次打包版本。下面命令会创建一个本地临时脚本，让 CMake 本次配置时读到 `1.1.3`：
+
+```powershell
+$Version = "1.1.3"
+$GitVersionShim = "..\.tmp\git-version-$Version.cmd"
+New-Item -ItemType Directory -Force (Split-Path $GitVersionShim) | Out-Null
+
+@"
+@echo off
+if /I "%1"=="describe" (
+  echo $Version
+  exit /b 0
+)
+git %*
+"@ | Set-Content -LiteralPath $GitVersionShim -Encoding ASCII
+```
+
+后续所有命令都复用这个 `$Version`。不要只改 ZIP 文件名，否则会出现文件名是 `1.1.3`，但组件 `package.xml` 和 `Updates.xml` 里版本还是 `0.10.1` 的错包；这种包上传后，MaintenanceTool 仍然会按 `0.10.1` 判断。
+
+## 五、刷新现有 CMake 打包配置
+
+下面命令只刷新已有构建目录的 CMake 配置，用来告诉打包目标 Qt IFW 在哪里，以及 Hub 更新客户端的本地编译产物和 SDK 兜底在哪里，不是全量重新编译 SIMCAE。
+
+先确认当前 PowerShell 已经在 SIMCAE 项目根目录。下面给出一个常见 Qt IFW 安装路径示例；如果你的 Qt IFW 装在别的位置，只改 `$QtIfwRoot` 这一行。
+
+```powershell
+$Build = ".\out\build\SimCAE-release-vs2022-qt515-ifw"
+$QtIfwRoot = "C:\Qt\Tools\QtInstallerFramework\4.11"
+$HubUpdateClientRuntime = ".\update-client\out\bin\Release"
+$UpdateClientSdk = ".\update-client\dist\UpdateClientSDK-With-QtDll"
+```
+
+先检查 SIMCAE 工程里的 Hub 更新客户端本地编译产物：
+
+```powershell
+Test-Path "$QtIfwRoot\bin\binarycreator.exe"
+Test-Path "$QtIfwRoot\bin\repogen.exe"
+Test-Path "$HubUpdateClientRuntime\Launcher.exe"
+Test-Path "$HubUpdateClientRuntime\Updater.exe"
+Test-Path "$HubUpdateClientRuntime\Bootstrap.exe"
+```
+
+如果上面三个 EXE 都存在，打 SIMCAE 安装包时会优先使用它们，不会再从 SDK 目录重复拿一份。
+
+如果本地编译产物不存在，再检查 SDK 兜底目录：
+
+```powershell
+Test-Path "$UpdateClientSdk\bin\Launcher.exe"
+Test-Path "$UpdateClientSdk\bin\Updater.exe"
+Test-Path "$UpdateClientSdk\bin\Bootstrap.exe"
+```
+
+如果本次要让 `SimCAE.exe` 只能从 `Launcher.exe` 启动，先准备 SIMCAE 编译期使用的本地打包配置。这里的 `launch_token` 必须和服务端 `.env` 里的 `SIMCAE_LAUNCH_TOKEN` 完全一致。
+
+```powershell
+$LauncherProductConfig = "..\.tmp\simcae-launcher-product-config.json"
+
+@'
+{
+  "app_id": "simcae",
+  "product_code": "simcae",
+  "app_name": "SimCAE",
+  "launch_token": "SimCAE_Launch_Token_2026_ChangeMe_32Bytes",
+  "license_key": "SIMCAE_LOCAL_PACKAGING_LICENSE_2026"
+}
+'@ | Set-Content -LiteralPath $LauncherProductConfig -Encoding UTF8
+```
+
+刷新配置：
+
+```powershell
+cmake -S . -B $Build `
+  "-DSimCAE_QtIfwRoot=$QtIfwRoot" `
+  "-DSimCAE_PackageHubUpdateClient=ON" `
+  "-DSimCAE_HubUpdateClientRuntimeDir=$HubUpdateClientRuntime" `
+  "-DSimCAE_HubUpdateClientSdkDir=$UpdateClientSdk" `
+  "-DSimCAE_UseLauncher=ON" `
+  "-DSimCAE_LauncherProductConfigFile=$LauncherProductConfig" `
+  "-DGIT_EXECUTABLE=$GitVersionShim"
+```
+
+`SimCAE_PackageHubUpdateClient=ON` 只负责把 `Launcher.exe`、`Updater.exe`、`Bootstrap.exe` 放进 SIMCAE 安装包。正式客户配置文件，例如 `config/app_config.json` 和 `config/manifest_public_key.pem`，仍然由服务端在上传发布包时生成或注入，不从开发机本地目录带进最终客户包。
+
+如果只想把 Hub 更新客户端打进安装包，但暂时不限制用户直接双击 `SimCAE.exe`，则把上面命令中的 `SimCAE_UseLauncher` 改为 `OFF`，并去掉 `SimCAE_LauncherProductConfigFile` 这一项。
+
+## 六、生成客户安装器和 IFW package
+
+执行打包目标：
+
+```powershell
+cmake --build $Build --config Release --target package_installer
+```
+
+这个目标会读取 `SIMCAE\installer` 下的配置和组件规则，整理 IFW package staging，并生成安装器。组件有哪些、每个组件包含哪些文件、组件是否必选、依赖哪些组件，应该由 SIMCAE 开发者在打包配置和 `package.xml.in` 里提前定义好；SimCAE Hub 不会自动猜测业务应该拆成哪些组件。
+
+当前示例里已有两个 IFW 组件：
+
+| 组件目录 | 组件含义 | 元数据来源 |
+| --- | --- | --- |
+| `packages/com.simcae.app` | 核心程序、Launcher、Updater、Bootstrap、核心库和通用资源 | `installer/packages/meta/package.xml.in` |
+| `packages/com.simcae.dap` | DAP 求解器插件及运行资源 | `installer/packages/com.simcae.dap/meta/package.xml.in` |
+
+Qt IFW 的组件 ID 来自 `packages/<组件ID>` 目录名，例如 `com.simcae.dap`。组件显示名称、版本、是否强制安装、依赖关系等来自该组件的 `meta/package.xml`，例如 `<DisplayName>`、`<Version>`、`<ForcedInstallation>`、`<Dependencies>`。
+
+常见输出：
+
+| 输出 | 说明 |
+| --- | --- |
+| `$Build\package` | Qt IFW package staging 目录 |
+| `$Build\SimCAE-<版本>-Windows-installer.exe` | 本地生成的客户安装器 |
+
+确认核心组件里已经带上 Hub 更新客户端：
+
+```powershell
+Test-Path "$Build\package\packages\com.simcae.app\data\view\bin\Launcher.exe"
+Test-Path "$Build\package\packages\com.simcae.app\data\view\bin\Updater.exe"
+Test-Path "$Build\package\packages\com.simcae.app\data\view\bin\Bootstrap.exe"
+Test-Path "$Build\package\packages\com.simcae.app\data\view\bin\SimCAE.exe"
+```
+
+预期都返回 `True`。
+
+再确认 package 里的组件版本就是本次 `$Version`：
+
+```powershell
+$AppPackageXml = "$Build\package\packages\com.simcae.app\meta\package.xml"
+$DapPackageXml = "$Build\package\packages\com.simcae.dap\meta\package.xml"
+$AppVersion = ([xml](Get-Content -LiteralPath $AppPackageXml -Encoding UTF8 -Raw)).Package.Version
+$DapVersion = ([xml](Get-Content -LiteralPath $DapPackageXml -Encoding UTF8 -Raw)).Package.Version
+
+if ($AppVersion -ne $Version -or $DapVersion -ne $Version) {
+  throw "组件版本不一致：app=$AppVersion dap=$DapVersion expected=$Version"
+}
+
+Test-Path "$Build\SimCAE-$Version-Windows-installer.exe"
+```
+
+最后一行预期返回 `True`。如果这里不是 `True`，不要继续生成 repository。
+
+## 七、生成 IFW repository
+
+MaintenanceTool 读取的是 Qt IFW repository，不是客户安装器。
+
+生成前先确认 `$Build\package` 已经存在，并且里面至少有 `config` 和 `packages`：
+
+```powershell
+Test-Path "$Build\package\config\config.xml"
+Test-Path "$Build\package\packages"
+```
+
+预期都返回 `True`。然后生成完整 repository：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File ".\installer\scripts\build-ifw-repository.ps1" `
+  -PackageDir "$Build\package" `
+  -OutputDir "$Build\ifw-repository" `
+  -ZipFile "$Build\SimCAE-IFW-Repository-$Version-windows_x86_64-msvc.zip"
+```
+
+这条命令不是“给压缩包打版本标签”。它只是调用 Qt IFW 的 `repogen.exe`，从 `$Build\package\packages` 读取已经准备好的组件目录和 `meta/package.xml`，生成 `Updates.xml` 和组件 `.7z` 包，最后把 repository 目录压成 ZIP。ZIP 文件名里的 `$Version` 只是为了让发布人员识别文件。
+
+生成后检查：
+
+```powershell
+Test-Path "$Build\ifw-repository\Updates.xml"
+Select-String -LiteralPath "$Build\ifw-repository\Updates.xml" -Pattern "com.simcae.app|com.simcae.dap|<Version>"
+```
+
+生成的 repository 根目录必须包含 `Updates.xml`。这个 ZIP 一般不直接给客户，它是给 SimCAE Hub 后端托管，供 `maintenancetool.exe` 后续检查组件更新。
+
+确认 repository 里的组件版本也是本次 `$Version`：
+
+```powershell
+$UpdatesXml = "$Build\ifw-repository\Updates.xml"
+$UpdatesContent = Get-Content -LiteralPath $UpdatesXml -Encoding UTF8 -Raw
+
+if ($UpdatesContent -notmatch "<Version>$([regex]::Escape($Version))</Version>") {
+  throw "repository Updates.xml 中没有本次版本 $Version"
+}
+```
+
+## 八、组装 Qt IFW 交付包 ZIP
+
+推荐上传给 SimCAE Hub 的是交付包 ZIP，它把 package 和 repository 放在一起。客户安装器由服务端基于注入配置后的 package 重新生成。
+
+目录结构建议：
+
+- `package/config/`
+- `package/packages/com.simcae.app/`
+- `package/packages/com.simcae.dap/`
+- `repository/Updates.xml`
+- `repository/com.simcae.app/`
+- `repository/com.simcae.dap/`
+
+不要依赖交付包里的 `installer/SimCAE-<版本>-Windows-installer.exe` 作为最终客户安装器。本地生成的安装器没有服务端注入的 `app_config.json`，客户直接安装后 `Launcher.exe` 会缺少服务器地址、token 和主程序配置。服务端必须配置 `SIMCAE_IFW_BINARYCREATOR_PATH`，Linux 服务端生成 Windows 安装器时还必须配置 `SIMCAE_IFW_INSTALLERBASE_WINDOWS_PATH` 指向 Windows 版 `installerbase.exe`，上传后由服务端重新生成客户门户可下载的安装器。
+
+示例命令：
+
+```powershell
+$PlatformKey = "windows_x86_64-msvc"
+$Bundle = "$Build\SimCAE-Delivery-$Version-$PlatformKey"
+
+if (-not (Test-Path "$Build\ifw-repository\Updates.xml")) {
+  throw "缺少 repository/Updates.xml，请先生成 IFW repository"
+}
+
+Remove-Item -LiteralPath $Bundle -Recurse -Force -ErrorAction SilentlyContinue
+New-Item -ItemType Directory -Force "$Bundle" | Out-Null
+
+Copy-Item "$Build\package" "$Bundle\package" -Recurse -Force
+Copy-Item "$Build\ifw-repository" "$Bundle\repository" -Recurse -Force
+
+Compress-Archive -Path "$Bundle\*" -DestinationPath "$Build\SimCAE-Delivery-$Version-$PlatformKey.zip" -Force
+```
+
+`release.json` 不需要开发者手写。产品编码、产品名称、版本号、通道、平台、架构和 ABI 来自管理后台表单；运行目录和主程序名由服务端从核心组件中自动识别。
+
+## 九、上传到管理后台
+
+在浏览器打开管理后台，例如 `http://192.168.1.158:1798/login`。
+
+按左侧菜单顺序准备基础数据。第一次发布某个产品时要完整走一遍；后续同产品、同通道、同平台发布新版本时，只需要确认这些数据仍然存在：
+
+1. 产品目录：确认产品编码，例如 `simcae`。
+2. 版本线：确认通道或版本线，例如 `stable`。
+3. 组件管理：确认核心组件和可选组件，例如 `com.simcae.app`、`com.simcae.dap`；如果用于 MaintenanceTool 更新，后台组件编码要和 IFW package 的 `packages/<组件ID>` 目录名一致。
+4. 平台管理：确认 `windows`、`x86_64`、`msvc`。
+5. 产品版本：创建本次版本，例如 `1.1.3`。
+6. 软件发布：创建本次发布，关联产品版本和版本线。
+7. 发布包：新增或编辑发布包。
+
+上传完整 Qt IFW 交付包时，在“发布包”页面直接点击右上角新增发布包，不需要先点击某个软件卡片。这个入口只用于新建整包更新包和 Qt IFW 交付包。
+
+发布包页面选择：
+
+| 字段 | 建议 |
+| --- | --- |
+| 包类型 | Qt IFW 交付包 |
+| 文件 | `SimCAE-Delivery-<版本>-windows_x86_64-msvc.zip` |
+| 平台 | `windows / x86_64 / msvc` |
+| 状态 | 上传校验通过后变为可用 |
+
+操作顺序：
+
+1. 打开“发布包”页面。
+2. 直接点击右上角“新建发布包”。
+3. 包类型选择“Qt IFW 交付包”。此时普通新建入口只应看到“整包更新包”和“Qt IFW 交付包”。
+4. 文件名填写本次交付包文件名，例如 `SimCAE-Delivery-1.1.3-windows_x86_64-msvc.zip`。
+5. 选择产品、版本线、产品版本、发布和平台。
+6. 保存发布包记录。
+7. 点击该记录的“上传”。
+8. 选择本地生成的交付包 ZIP。
+9. 等待上传完成，状态应变为“可用”。
+
+上传成功后，服务端会：
+
+- 校验 ZIP 安全路径和 IFW 结构。
+- 校验 `package/` 和 `repository/Updates.xml`。
+- 读取组件清单和组件版本。
+- 自动注入 `config/app_config.json`。
+- 自动写入必要的公钥配置。
+- 发布 IFW repository。
+- 生成或登记客户门户首次下载的安装器。
+
+上传后建议立刻确认：
+
+```powershell
+$Base = "http://192.168.1.158:18000/api/v1/client/ifw/repositories/simcae/stable/windows_x86_64-msvc"
+(Invoke-WebRequest "$Base/Updates.xml" -UseBasicParsing).Content
+```
+
+预期能看到本次版本号、组件 ID 和组件名称。如果这里还是旧版本，先确认发布包状态是否为“可用”，再确认上传时选择的产品、通道和平台是否一致。
+
+## 十、客户下载和安装
+
+客户登录客户门户后，在下载中心下载客户安装器。客户下载到的是 `.exe` 安装器，不是 IFW repository ZIP，也不是开发者上传的交付包 ZIP。
+
+客户安装后，安装目录中应包含：
+
+- `maintenancetool.exe`
+- `components.xml`
+- `network.xml`
+- `view\bin\SimCAE.exe`
+- `view\bin\Launcher.exe`
+- `view\bin\Updater.exe`
+- `view\bin\Bootstrap.exe`
+- `view\bin\config\app_config.json`
+
+客户日常启动软件应使用 `Launcher.exe` 或安装器创建的快捷方式。组件更新、添加、移除由 `maintenancetool.exe` 负责。
+
+首次安装建议按这个顺序检查：
+
+1. 打开客户门户。
+2. 登录有授权的客户账号。
+3. 进入下载中心。
+4. 找到对应产品和版本。
+5. 点击下载，得到 `SimCAE-<版本>-Windows-installer.exe`。
+6. 双击安装器，按页面提示完成安装。
+7. 安装后进入安装目录，确认 `maintenancetool.exe`、`components.xml` 和 `view\bin\Launcher.exe` 都存在。
+8. 双击 `Launcher.exe`，预期能启动 SimCAE。
+9. 双击 `maintenancetool.exe`，预期能看到“添加或移除组件”“更新组件”“移除所有组件”。
+
+## 十一、组件更新
+
+这里的“组件”指 `maintenancetool.exe` 里能看到的 Qt IFW 组件，例如 `com.simcae.app`、`com.simcae.dap`。组件更新就是“只发布某些组件的新版本，或新增一个组件”，让客户后续通过 MaintenanceTool 更新；它不是客户首次安装用的安装器，也不是 Launcher / Updater 用的整包更新 ZIP。
+
+适合使用组件更新的情况：
+
+| 场景 | 应该怎么做 |
+| --- | --- |
+| 只更新 DAP 插件 | 做一个只包含 `com.simcae.dap` 的组件更新包 |
+| 新增示例、模板、插件等可选功能 | 做一个包含新组件的组件更新包 |
+| 一次更新几个互相依赖的组件 | 做一个多组件更新包，把这些组件一起放进去 |
+| 更新核心程序、Launcher、Updater、Bootstrap 或 `app_config.json` | 更推荐重新发完整 Qt IFW 交付包 |
+| 第一次发布某个产品、通道、平台 | 先发完整 Qt IFW 交付包，后面才能发组件更新 |
+
+组件更新包不是单独飘在系统外面的文件。它上传时必须挂到某个产品、某个产品版本、某次发布、某个平台下面。服务端会把它合并到这个产品对应通道和平台的 current repository 中。
+
+### 11.1 组件版本怎么定
+
+组件版本以组件自己的 `package.xml` 为准。比如 DAP 组件的版本写在这里：
+
+- `$Build\package\packages\com.simcae.dap\meta\package.xml`
+- XML 节点是 `<Version>1.1.4</Version>`
+
+如果说“组件标签”，这里真正参与更新判断的是组件 ID 和组件版本：组件 ID 来自目录名 `packages/com.simcae.dap`，组件版本来自 `meta/package.xml` 里的 `<Version>`。开发者在维护 IFW package 时就应该把组件拆分、显示名、版本、必选状态和依赖关系写清楚。`repogen.exe` 生成 repository 时，会把这些信息写进 `Updates.xml`。MaintenanceTool 也是根据 `Updates.xml` 里的组件版本判断是否可更新。
+
+当前 SIMCAE 全量打包默认会让所有组件跟随同一个 `$Version`，这个 `$Version` 来自 SIMCAE 仓库的纯数字 Git tag，或者前面文档里的 `$GitVersionShim` 临时版本脚本。例如 `$Version = "1.1.3"` 时，`com.simcae.app` 和 `com.simcae.dap` 默认都会变成 `1.1.3`。
+
+如果只更新 DAP，不更新核心组件，规则是：
+
+1. 服务器当前 `com.simcae.app` 是 `1.1.3`，`com.simcae.dap` 是 `1.1.3`。
+2. 本次只把 `com.simcae.dap` 的 `package.xml` 改成 `1.1.4`。
+3. 不改 `com.simcae.app` 的 `package.xml`，它仍然保持 `1.1.3`。
+4. 生成只包含 `com.simcae.dap` 的组件更新包。
+5. 上传后，服务器 current repository 里应变成 `com.simcae.app=1.1.3`、`com.simcae.dap=1.1.4`。
+
+正式流程里，建议 SIMCAE 打包侧给每个组件提供独立版本参数。当前如果只是本地演示，可以在 `$Build\package\packages\<组件ID>\meta\package.xml` 里调整目标组件的 `<Version>`，然后再生成组件更新包。不要改不更新的组件版本，也不要只改 ZIP 文件名。ZIP 名字里写了 `1.1.4`，但 `package.xml` 仍是 `1.1.3` 时，生成出来的 `Updates.xml` 也会是 `1.1.3`。
+
+### 11.2 先确认服务器已有当前仓库
+
+以 `simcae / stable / windows_x86_64-msvc` 为例：
+
+```powershell
+$Base = "http://192.168.1.158:18000/api/v1/client/ifw/repositories/simcae/stable/windows_x86_64-msvc"
+(Invoke-WebRequest "$Base/Updates.xml" -UseBasicParsing).Content
+```
+
+预期能看到当前仓库的组件，例如：
+
+- `<Name>com.simcae.app</Name>`
+- `<Version>1.1.3</Version>`
+- `<Name>com.simcae.dap</Name>`
+- `<Version>1.1.3</Version>`
+
+如果这里访问失败，先不要上传组件更新包，说明服务器还没有这个产品、通道、平台的 current repository。
+
+### 11.3 准备本地组件产物
+
+开发者先按 SIMCAE 自己的规则把组件文件准备到 IFW package staging 里。组件边界应该在开发和打包配置阶段就已经分好；后面的 repository 生成命令只是读取这些组件，不会自动分析文件并替开发者拆组件。当前打包目标会把组件整理到：
+
+- `$Build\package\packages\com.simcae.app`
+- `$Build\package\packages\com.simcae.dap`
+
+如果只更新 DAP 插件，先确认 DAP 组件目录存在：
+
+```powershell
+Test-Path "$Build\package\packages\com.simcae.dap\meta\package.xml"
+Test-Path "$Build\package\packages\com.simcae.dap\data"
+```
+
+预期都返回 `True`。同时要确认 `package.xml` 里的版本已经升高：
+
+```powershell
+Select-String -LiteralPath "$Build\package\packages\com.simcae.dap\meta\package.xml" -Pattern "<Version>"
+```
+
+例如服务器当前 DAP 是 `1.1.3`，本次 DAP 组件更新包应改成 `1.1.4` 或更高。
+
+### 11.4 生成组件更新 ZIP
+
+使用 `-Include` 只把要更新的组件打进 repository。`-Include "com.simcae.dap"` 里的值是组件 ID，也就是 `packages/com.simcae.dap` 这个目录名；它不是 ZIP 标签，也不是版本号。下面以只更新 DAP 为例：
+
+```powershell
+$ComponentVersion = "1.1.4"
+$PlatformKey = "windows_x86_64-msvc"
+$ComponentUpdateRepository = "$Build\ifw-component-update-com.simcae.dap-$ComponentVersion"
+$ComponentUpdateZip = "$Build\SimCAE-IFW-ComponentUpdate-com.simcae.dap-$ComponentVersion-$PlatformKey.zip"
+
+Remove-Item -LiteralPath $ComponentUpdateRepository -Recurse -Force -ErrorAction SilentlyContinue
+
+powershell -NoProfile -ExecutionPolicy Bypass -File ".\installer\scripts\build-ifw-repository.ps1" `
+  -PackageDir "$Build\package" `
+  -OutputDir $ComponentUpdateRepository `
+  -ZipFile $ComponentUpdateZip `
+  -Include "com.simcae.dap"
+```
+
+这条命令不会修改 `com.simcae.dap` 的 `<Version>`。它只是根据 `-Include` 选择已有组件，把该组件当前 `package.xml` 中写好的版本、显示名和依赖交给 `repogen.exe`，再生成本次组件更新 repository ZIP。
+
+如果一次更新多个组件：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File ".\installer\scripts\build-ifw-repository.ps1" `
+  -PackageDir "$Build\package" `
+  -OutputDir "$Build\ifw-component-update-multi-$ComponentVersion" `
+  -ZipFile "$Build\SimCAE-IFW-ComponentUpdate-multi-$ComponentVersion-$PlatformKey.zip" `
+  -Include "com.simcae.app","com.simcae.dap"
+```
+
+生成后检查 ZIP 对应的展开目录：
+
+```powershell
+Test-Path "$ComponentUpdateRepository\Updates.xml"
+Get-ChildItem -LiteralPath $ComponentUpdateRepository
+Select-String -LiteralPath "$ComponentUpdateRepository\Updates.xml" -Pattern "com.simcae.dap|<Version>|<Dependencies>"
+```
+
+单 DAP 更新包的典型结构应类似：
+
+- `Updates.xml`
+- `com.simcae.dap/1.1.4meta.7z`
+- `com.simcae.dap/1.1.4view.7z`
+- `com.simcae.dap/1.1.4view.7z.sha1`
+
+如果 ZIP 解开后外面多套了一层目录，也可以上传；服务端会识别常见外层目录。但推荐让 ZIP 根部直接就是 `Updates.xml` 和组件目录，最不容易出错。
+
+### 11.5 上传组件更新
+
+管理后台操作：
+
+1. 打开“产品版本”，创建本次发布批次版本，例如 `1.1.4`。
+2. 打开“软件发布”，创建本次发布，通道仍选择 `stable`。
+3. 打开“发布包”，先点击要更新的软件卡片，进入该软件的发布包视图。
+4. 点击“新建组件更新包”。进入某个软件后，包类型固定为“组件更新”，产品固定为当前软件。
+5. 发布选择刚创建的 `1.1.4` 发布。
+6. 平台选择和 current repository 完全一致的 `windows / x86_64 / msvc`。
+7. 文件名填写 `SimCAE-IFW-ComponentUpdate-com.simcae.dap-1.1.4-windows_x86_64-msvc.zip`。
+8. 保存后点击“上传”。
+9. 选择上一步生成的 `$ComponentUpdateZip`。
+10. 上传成功后，发布包状态应变为“可用”。
+
+上传成功后，服务端会把更新组件合并进 current repository，未变化组件保持不变。
+
+### 11.6 上传后确认合并结果
+
+重新读取服务器仓库：
+
+```powershell
+$Base = "http://192.168.1.158:18000/api/v1/client/ifw/repositories/simcae/stable/windows_x86_64-msvc"
+(Invoke-WebRequest "$Base/Updates.xml" -UseBasicParsing).Content
+```
+
+预期：
+
+1. 更新过的组件版本变成新版本，例如 `com.simcae.dap` 是 `1.1.4`。
+2. 未更新的组件仍然存在，例如 `com.simcae.app` 还在。
+3. 新增组件能出现在 `Updates.xml` 中。
+4. 旧版本仓库仍保存在服务端 `releases/<版本>` 目录中，current 指向最新合并结果。
+
+### 11.7 常见失败提示
+
+| 提示含义 | 原因 | 处理 |
+| --- | --- | --- |
+| 当前产品、通道和平台下还没有可合并的 IFW 当前仓库 | 还没上传过完整交付包 | 先上传完整 Qt IFW 交付包 |
+| 组件版本不能倒退或重复 | 上传组件版本小于或等于服务器 current 版本 | 升高组件 `package.xml` 里的版本后重新生成 |
+| 组件依赖不存在 | 新组件依赖的组件不在 current 仓库，也不在本次包里 | 先发布依赖组件，或把依赖组件一起打进本次更新包 |
+| 缺少组件目录 | `Updates.xml` 声明了组件，但 ZIP 里没有对应目录 | 重新用 `build-ifw-repository.ps1` 生成 |
+| 包含未在 `Updates.xml` 声明的组件目录 | ZIP 里多了未声明目录 | 删除多余目录后重新压包 |
+| 未包含 `Updates.xml` | 上传的不是 repository ZIP，或服务端没有配置 `SIMCAE_IFW_REPOGEN_PATH` 来从 packages 自动生成 | 上传 repository 形态 ZIP |
+
+更新包失败时，服务端不会破坏原 current repository。
+
+## 十二、换源
+
+服务器地址变化时有两种处理方式：
+
+| 方式 | 适用场景 |
+| --- | --- |
+| 临时换源命令 | 单台客户机器临时切到新仓库 |
+| RepositoryUpdate 批量换源 | 已安装客户软件批量迁移仓库地址 |
+
+换源只影响 `maintenancetool.exe` 访问 IFW repository。Launcher / Updater 的 API 地址来自服务端注入的 `app_config.json`，需要通过新发布包或重新安装包更新。
+
+### 12.1 临时换源
+
+临时换源适合开发、测试、临时排查。它不会永久改安装包里的默认源。
+
+在 SIMCAE 项目根目录执行，假设客户软件安装在 `.tmp\maintenance-installed\SimCAE`：
+
+```powershell
+$Install = ".\.tmp\maintenance-installed\SimCAE"
+$Repo = "http://192.168.1.158:18000/api/v1/client/ifw/repositories/simcae/stable/windows_x86_64-msvc/"
+
+powershell -NoProfile -ExecutionPolicy Bypass -File ".\installer\scripts\switch-maintenance-repository.ps1" `
+  -MaintenanceToolPath "$Install\maintenancetool.exe" `
+  -RepositoryUrl $Repo `
+  -Mode Temp `
+  -Command check-updates `
+  -ClearCache
+```
+
+注意 `$Repo` 必须是仓库根地址，不能写到 `Updates.xml`：
+
+- 正确：`http://192.168.1.158:18000/api/v1/client/ifw/repositories/simcae/stable/windows_x86_64-msvc/`
+- 错误：`http://192.168.1.158:18000/api/v1/client/ifw/repositories/simcae/stable/windows_x86_64-msvc/Updates.xml`
+
+### 12.2 批量换源
+
+批量换源适合服务器域名或 IP 变更。做法是在下一次 repository 的 `Updates.xml` 里加入 `RepositoryUpdate`，让 MaintenanceTool 更新组件时顺便替换本机源地址。
+
+示例：把旧源 `http://192.168.1.158:18000/...` 替换为新源 `https://download.simcae.example.com/...`：
+
+```powershell
+$UpdatesXml = "$Build\ifw-repository\Updates.xml"
+$OldRepo = "http://192.168.1.158:18000/api/v1/client/ifw/repositories/simcae/stable/windows_x86_64-msvc/"
+$NewRepo = "https://download.simcae.example.com/api/v1/client/ifw/repositories/simcae/stable/windows_x86_64-msvc/"
+
+powershell -NoProfile -ExecutionPolicy Bypass -File ".\installer\scripts\write-repository-update.ps1" `
+  -UpdatesXml $UpdatesXml `
+  -Action replace `
+  -OldUrl $OldRepo `
+  -NewUrl $NewRepo `
+  -DisplayName "SimCAE stable component repository" `
+  -ClearExisting
+```
+
+写入后重新压 repository 或重新组装 Qt IFW 交付包，再上传到 SimCAE Hub。客户下一次通过 MaintenanceTool 检查或更新组件后，会把仓库地址换成新地址。
+
+## 十三、常见问题
+
+| 现象 | 原因和处理 |
+| --- | --- |
+| 上传提示缺少 `Updates.xml` | 选择的不是 repository 或交付包结构不对 |
+| MaintenanceTool 看不到更新 | 服务器仓库版本没有高于本机 `components.xml` 里的版本 |
+| 客户下载不到安装器 | 发布包不是 Qt IFW 交付包，或客户安装器生成/登记失败 |
+| Launcher 启动主程序失败 | `SIMCAE_LAUNCH_TOKEN` 和业务主程序编译时 token 不一致 |
+| 直接双击 `SimCAE.exe` 被拦截 | 这是启用 Launcher 启动门禁后的预期行为 |
+| 可选组件删除后 Updater 报缺文件 | Manifest 中可选组件文件没有标为可选，或组件边界划分不对 |

Updater/UpdateTransaction.cpp

@@ -35,9 +35,11 @@ bool UpdateTransaction::copyOverwrite(const QString& source, const QString& dest
     return QFile::copy(source, destination);
 }
 
-bool UpdateTransaction::writeState(const QString& status, const QString& errorCode, const QString& message)
-{
-    m_state["transaction_id"] = m_transactionId;
+bool UpdateTransaction::writeState(const QString& status, const QString& errorCode, const QString& message)
+{
+    // upgrade_state.json 是升级事务的“黑匣子”。
+    // 如果替换文件时断电或崩溃，Bootstrap/Updater 会根据这里的状态继续提交或回滚。
+    m_state["transaction_id"] = m_transactionId;
     m_state["from_version"] = m_fromVersion;
     m_state["to_version"] = m_toVersion;
     m_state["status"] = status;
@@ -146,9 +148,11 @@ bool UpdateTransaction::recordVerifiedFiles(const QStringList& changedPaths,
     return writeState("verified");
 }
 
-bool UpdateTransaction::backupCurrentFiles()
-{
-    if (!writeState("waiting_mainapp_exit")) return false;
+bool UpdateTransaction::backupCurrentFiles()
+{
+    // 替换前先备份所有将被修改或删除的文件。
+    // 后续健康检查失败时，可以用这些备份恢复到升级前版本。
+    if (!writeState("waiting_mainapp_exit")) return false;
     QStringList paths = m_changedPaths;
     paths.append(m_obsoletePaths);
     for (const QString& path : paths) {
@@ -161,9 +165,11 @@ bool UpdateTransaction::backupCurrentFiles()
     return writeState("backed_up");
 }
 
-bool UpdateTransaction::installStagedFiles(QString* failedPath)
-{
-    if (!writeState("replacing")) return false;
+bool UpdateTransaction::installStagedFiles(QString* failedPath)
+{
+    // staging 目录里只放已经下载并校验过 hash 的新文件。
+    // 真正覆盖安装目录时如果任意一个文件失败，就进入 rollback_required。
+    if (!writeState("replacing")) return false;
     for (const QString& path : m_changedPaths) {
         const QString source = QDir(m_stagingDir).filePath(path);
         const QString destination = QDir(m_installDir).filePath(path);
@@ -223,10 +229,11 @@ QString UpdateTransaction::backupDir() const { return m_backupDir; }
 QStringList UpdateTransaction::obsoletePaths() const { return m_obsoletePaths; }
 QString UpdateTransaction::healthFile() const { return QDir(m_updateDir).filePath("health_" + m_transactionId + ".ok"); }
 
-bool UpdateTransaction::recoverInterrupted(const QString& installDir, const QString& updateDir,
-                                           QString* restoredVersion, QString* errorMessage)
-{
-    QString stateFile = QDir(updateDir.isEmpty() ? QDir(installDir).filePath("update") : updateDir)
+bool UpdateTransaction::recoverInterrupted(const QString& installDir, const QString& updateDir,
+                                           QString* restoredVersion, QString* errorMessage)
+{
+    // 启动时恢复未完成事务：如果上次升级停在替换/验证/回滚中间，优先恢复到可启动状态。
+    QString stateFile = QDir(updateDir.isEmpty() ? QDir(installDir).filePath("update") : updateDir)
                             .filePath("upgrade_state.json");
     const QString legacyStateFile = QDir(installDir).filePath("update/upgrade_state.json");
     if (!QFile::exists(stateFile) && QFile::exists(legacyStateFile))

Updater/UpdaterLogic.h

@@ -24,13 +24,15 @@ class UpdaterLogic : public QObject
 public:
     explicit UpdaterLogic(QObject* parent = nullptr);
 
-    void getManifest(const QString& appId, const QString& channel, const QString& targetVer, int versionId);
+    void getManifest(const QString& appId, const QString& channel, const QString& targetVer,
+                     int versionId, const QString& releaseId = QString());
     bool verifyManifestSignature(const QString& publicKeyPath = "config/manifest_public_key.pem") const;
     bool validateLocalFiles(const QString& stagingDir, const QString& installedDir = QString()) const;
     bool saveManifestCache(const QString& cacheDir) const;
     bool loadManifestCache(const QString& cacheDir, const QString& version);
-    bool loadOfflinePackage(const QString& packagePath, const QString& stagingDir = QString());
-    QString offlineError() const { return m_offlineError; }
+    bool loadOfflinePackage(const QString& packagePath, const QString& stagingDir = QString());
+    QString offlineError() const { return m_offlineError; }
+    QString errorString() const { return m_error; }
 
     void getDownloadUrl(const QString& appId, const QString& channel, const QString& targetVer, int versionId);
     void reportResult(const QString& deviceId, const QString& fromVer, const QString& toVer, bool success);
@@ -60,14 +62,20 @@ private:
 
     HttpHelper m_http;
     QString m_serverAddr;
-    QJsonObject m_manifest;
-    QString m_manifestText;
+    QJsonObject m_manifest;
+    QString m_manifestText;
+    QString m_manifestSha256;
+    QString m_manifestSignature;
+    QString m_manifestSignatureAlg;
+    QString m_manifestKeyId;
+    bool m_manifestSigned = false;
     QList<FileDownloadItem> m_fileItems;
-    bool m_downloadAllOk = false;
+    bool m_downloadAllOk = false;
     qint64 m_downloadTotalBytes = 0;
     qint64 m_downloadCompletedBytes = 0;
     qint64 m_sessionDownloadedBytes = 0;
-    QString m_currentDownloadPath;
-    QString m_offlineError;
-    QElapsedTimer m_downloadTimer;
-};
+    QString m_currentDownloadPath;
+    QString m_offlineError;
+    mutable QString m_error;
+    QElapsedTimer m_downloadTimer;
+};

Updater/main.cpp

@@ -1,11 +1,12 @@
-#include <QApplication>
+#include <QApplication>
 #include <QCoreApplication>
 #include <QDebug>
 #include <QDir>
 #include <QDirIterator>
-#include <QElapsedTimer>
-#include <QFile>
-#include <QMessageBox>
+#include <QElapsedTimer>
+#include <QFile>
+#include <QFileInfo>
+#include <QMessageBox>
 #include <QProcess>
 #include <QProgressDialog>
 #include <QSaveFile>
@@ -23,7 +24,7 @@
 int main(int argc, char* argv[])
 {
     QApplication app(argc, argv);
-    QApplication::setApplicationName("Marsco Updater");
+    QApplication::setApplicationName("SimCAE Updater");
     QTranslator translator;
     if (translator.load(":/i18n/update-client_zh_CN.qm"))
         app.installTranslator(&translator);
@@ -34,10 +35,11 @@ int main(int argc, char* argv[])
 
     UpdaterLogic logic;
     QString offlinePackagePath;
-    QString appId;
-    QString channel;
-    QString targetVersion;
-    int targetVersionId = 0;
+    QString appId;
+    QString channel;
+    QString targetVersion;
+    QString releaseId;
+    int targetVersionId = 0;
     if (argc >= 2 && QString(argv[1]).startsWith("--offline-package=")) {
         offlinePackagePath = QString(argv[1]).mid(QString("--offline-package=").size());
         if (!logic.loadOfflinePackage(offlinePackagePath)) {
@@ -61,11 +63,13 @@ int main(int argc, char* argv[])
         appId = argv[1]; channel = argv[2]; targetVersion = argv[3]; targetVersionId = QString(argv[4]).toInt();
     }
     QString bootstrapResult;
-    for (int i = 5; i < argc; ++i) {
-        const QString arg = argv[i];
-        if (arg.startsWith("--bootstrap-resume="))
-            bootstrapResult = arg.mid(QString("--bootstrap-resume=").size());
-    }
+    for (int i = 5; i < argc; ++i) {
+        const QString arg = argv[i];
+        if (arg.startsWith("--bootstrap-resume="))
+            bootstrapResult = arg.mid(QString("--bootstrap-resume=").size());
+        else if (arg.startsWith("--release-id="))
+            releaseId = arg.mid(QString("--release-id=").size());
+    }
     const bool resumingFromBootstrap = !bootstrapResult.isEmpty();
     const QString runtimeDir = QApplication::applicationDirPath();
 
@@ -73,7 +77,13 @@ int main(int argc, char* argv[])
     const QString targetDir = config.installRoot();
     const QString updateDir = config.updateRoot();
     QDir().mkpath(updateDir);
-    if (appId != config.getValue("App", "app_id") || channel != config.getValue("App", "channel")) {
+    QString configuredProductCode = config.getValue("App", "product_code").trimmed();
+    if (configuredProductCode.isEmpty())
+        configuredProductCode = config.getValue("App", "app_id").trimmed();
+    QString configuredChannel = config.getValue("App", "channel").trimmed();
+    if (configuredChannel.isEmpty())
+        configuredChannel = QStringLiteral("stable");
+    if (appId != configuredProductCode || channel != configuredChannel) {
         QMessageBox::critical(nullptr,
             QCoreApplication::translate("Updater", "Offline Package Not Applicable"),
             QCoreApplication::translate("Updater", "The update package application or channel does not match the local configuration."));
@@ -164,14 +174,19 @@ int main(int argc, char* argv[])
         if (offlinePackagePath.isEmpty())
             logic.reportResult(deviceId, fromVersion, targetVersion, success);
     };
-    const auto fail = [&](const QString& title, const QString& message,
-                          const QString& errorCode = QString("update_failed")) {
-        transaction.markFailed(errorCode, message);
-        reportUpdateResult(false);
-        progress.close();
-        QMessageBox::critical(nullptr, title, message);
-        return -1;
-    };
+    const auto fail = [&](const QString& title, const QString& message,
+                          const QString& errorCode = QString("update_failed")) {
+        transaction.markFailed(errorCode, message);
+        reportUpdateResult(false);
+        progress.close();
+        QMessageBox::critical(nullptr, title, message);
+        return -1;
+    };
+    const auto withDetails = [](const QString& message, const QString& details) {
+        return details.trimmed().isEmpty()
+            ? message
+            : message + QCoreApplication::translate("Updater", "\n\nDetails:\n%1").arg(details);
+    };
     const auto configuredName = [&](const QString& key, const QString& fallback) {
         return ConfigHelper::executableNameForCurrentPlatform(
             config.getValue("Runtime", key), fallback);
@@ -182,25 +197,44 @@ int main(int argc, char* argv[])
     bool timeoutOk = false;
     int healthCheckTimeoutMs = config.getValue("Runtime", "health_check_timeout_ms").toInt(&timeoutOk);
     if (!timeoutOk || healthCheckTimeoutMs < 1000) healthCheckTimeoutMs = 15000;
-    const QString mainAppPath = QDir(runtimeDir).filePath(mainExecutable);
-    const QString updaterPath = QDir(runtimeDir).filePath(updaterExecutable);
-    const QString bootstrapPath = QDir(runtimeDir).filePath(bootstrapExecutable);
-    const QString launchToken = config.getValue("App", "launch_token");
-    const auto launchMainApp = [&](const QString& healthFile = QString()) {
-        QString ticketPath;
-        QString ticketError;
-        const QString launchVersion = config.getValue("App", "current_version");
-        if (!TicketHelper::createTicket(appId, deviceId, launchVersion, launchToken,
-                                        &ticketPath, &ticketError)) {
-            qDebug() << "Cannot create launch ticket:" << ticketError;
-            return false;
-        }
-        QStringList args{QString("--ticket-file=%1").arg(ticketPath)};
-        if (!healthFile.isEmpty()) args.append(QString("--health-file=%1").arg(healthFile));
-        const bool started = QProcess::startDetached(mainAppPath, args);
-        if (!started) QFile::remove(ticketPath);
-        return started;
-    };
+    const QString mainAppPath = QDir(runtimeDir).filePath(mainExecutable);
+    const QString updaterPath = QDir(runtimeDir).filePath(updaterExecutable);
+    const QString bootstrapPath = QDir(runtimeDir).filePath(bootstrapExecutable);
+    const QString launchToken = config.getValue("App", "launch_token");
+    QString mainStartupError;
+    const auto launchMainApp = [&](const QString& healthFile = QString()) {
+        mainStartupError.clear();
+        if (!QFileInfo::exists(mainAppPath)) {
+            mainStartupError = QCoreApplication::translate(
+                "Updater",
+                "Cannot start the main application because the executable file does not exist.\nExecutable: %1\nCheck main_executable and install_root in the generated client configuration.")
+                .arg(mainAppPath);
+            return false;
+        }
+        QString ticketPath;
+        QString ticketError;
+        const QString launchVersion = config.getValue("App", "current_version");
+        if (!TicketHelper::createTicket(appId, deviceId, launchVersion, launchToken,
+                                        &ticketPath, &ticketError)) {
+            qDebug() << "Cannot create launch ticket:" << ticketError;
+            mainStartupError = QCoreApplication::translate(
+                "Updater",
+                "Cannot start the main application because the one-time launch ticket could not be created.\nExecutable: %1\nDetails: %2")
+                .arg(mainAppPath, ticketError);
+            return false;
+        }
+        QStringList args{QString("--ticket-file=%1").arg(ticketPath)};
+        if (!healthFile.isEmpty()) args.append(QString("--health-file=%1").arg(healthFile));
+        const bool started = QProcess::startDetached(mainAppPath, args);
+        if (!started) {
+            QFile::remove(ticketPath);
+            mainStartupError = QCoreApplication::translate(
+                "Updater",
+                "Cannot start the main application process.\nExecutable: %1\nTicket file: %2\nHealth file: %3\nCheck file permissions, dependent DLLs/shared libraries, and whether the executable can run independently.")
+                .arg(mainAppPath, ticketPath, healthFile.isEmpty() ? QCoreApplication::translate("Updater", "<not used>") : healthFile);
+        }
+        return started;
+    };
     const auto bootstrapPlanFile = [&]() {
         return QDir(updateDir).filePath("bootstrap_plan_" + transaction.transactionId() + ".txt");
     };
@@ -282,16 +316,19 @@ int main(int argc, char* argv[])
     if (resumingFromBootstrap) {
         if (!logic.loadManifestCache(manifestCacheDir, targetVersion))
             return delegateRollback(QCoreApplication::translate("Updater", "Manifest Cache Failed"),
-                                    QCoreApplication::translate("Updater", "Cannot read the signed manifest cache after Bootstrap installation."));
+                                    withDetails(QCoreApplication::translate("Updater", "Cannot read the signed manifest cache after Bootstrap installation."),
+                                                logic.errorString()));
     } else if (offlinePackagePath.isEmpty()) {
-        logic.getManifest(appId, channel, targetVersion, targetVersionId);
+        logic.getManifest(appId, channel, targetVersion, targetVersionId, releaseId);
     }
     if (!logic.verifyManifestSignature()) {
         if (resumingFromBootstrap)
             return delegateRollback(QCoreApplication::translate("Updater", "Security Verification Failed"),
-                                    QCoreApplication::translate("Updater", "Cannot reverify the manifest signature after Bootstrap installation."));
+                                    withDetails(QCoreApplication::translate("Updater", "Cannot reverify the manifest signature after Bootstrap installation."),
+                                                logic.errorString()));
         return fail(QCoreApplication::translate("Updater", "Security Verification Failed"),
-                    QCoreApplication::translate("Updater", "The version manifest signature is invalid. The update has stopped. Please contact the administrator."),
+                    withDetails(QCoreApplication::translate("Updater", "The version manifest signature is invalid. The update has stopped. Please contact the administrator."),
+                                logic.errorString()),
                     "manifest_signature_invalid");
     }
     QStringList obsoletePaths;
@@ -309,9 +346,11 @@ int main(int argc, char* argv[])
     if (!logic.saveManifestCache(manifestCacheDir)) {
         if (resumingFromBootstrap)
             return delegateRollback(QCoreApplication::translate("Updater", "Manifest Cache Failed"),
-                                    QCoreApplication::translate("Updater", "Cannot save the new version manifest cache."));
+                                    withDetails(QCoreApplication::translate("Updater", "Cannot save the new version manifest cache."),
+                                                logic.errorString()));
         return fail(QCoreApplication::translate("Updater", "Manifest Cache Failed"),
-                    QCoreApplication::translate("Updater", "Cannot save the new version manifest cache. The update has stopped."),
+                    withDetails(QCoreApplication::translate("Updater", "Cannot save the new version manifest cache. The update has stopped."),
+                                logic.errorString()),
                     "manifest_cache_failed");
     }
 
@@ -324,7 +363,8 @@ int main(int argc, char* argv[])
             logic.getDownloadUrl(appId, channel, targetVersion, targetVersionId);
         if (logic.getFileList().isEmpty())
             return fail(QCoreApplication::translate("Updater", "No Files to Update"),
-                        QCoreApplication::translate("Updater", "The server did not return any version files. The update has stopped."),
+                        withDetails(QCoreApplication::translate("Updater", "The server did not return any version files. The update has stopped."),
+                                    logic.errorString()),
                         "empty_file_list");
 
         QStorageInfo storage(updateDir);
@@ -353,7 +393,8 @@ int main(int argc, char* argv[])
             if (!logic.downloadAllFiles(stagingDir, targetDir)) {
                 logic.reportDownloadResult(appId, channel, targetVersion, false);
                 return fail(QCoreApplication::translate("Updater", "Download Failed"),
-                            QCoreApplication::translate("Updater", "Some files failed to download or failed SHA-256 verification. Please check the network and try again."),
+                            withDetails(QCoreApplication::translate("Updater", "Some files failed to download or failed SHA-256 verification. Please check the network, update cache, or server release files and try again."),
+                                        logic.errorString()),
                             "download_failed");
             }
             logic.reportDownloadResult(appId, channel, targetVersion, true);
@@ -362,7 +403,8 @@ int main(int argc, char* argv[])
         setProgress(58, QCoreApplication::translate("Updater", "Verifying complete version files..."));
         if (!logic.validateLocalFiles(stagingDir, targetDir))
             return fail(QCoreApplication::translate("Updater", "File Verification Failed"),
-                        QCoreApplication::translate("Updater", "The staged files do not match the version manifest. The update has stopped."),
+                        withDetails(QCoreApplication::translate("Updater", "The downloaded/staged files do not match the target version manifest. The update has stopped before replacing installed files."),
+                                    logic.errorString()),
                         "staging_verify_failed");
 
         QStringList changedPaths;
@@ -441,7 +483,8 @@ int main(int argc, char* argv[])
     setProgress(82, QCoreApplication::translate("Updater", "Verifying Bootstrap installation result..."));
     if (!transaction.markPostVerify() || !logic.validateLocalFiles(targetDir))
         return delegateRollback(QCoreApplication::translate("Updater", "Installation Verification Failed"),
-                                QCoreApplication::translate("Updater", "New version files failed verification after installation."));
+                                withDetails(QCoreApplication::translate("Updater", "New version files failed verification after installation. The updater will roll back to the previous version."),
+                                            logic.errorString()));
     for (const QString& path : transaction.obsoletePaths()) {
         if (QFile::exists(QDir(targetDir).filePath(path)))
             return delegateRollback(QCoreApplication::translate("Updater", "Obsolete File Cleanup Failed"),
@@ -459,7 +502,9 @@ int main(int argc, char* argv[])
     setProgress(94, QCoreApplication::translate("Updater", "Starting the new version and waiting for health confirmation..."));
     if (!launchMainApp(healthFile))
         return delegateRollback(QCoreApplication::translate("Updater", "Startup Failed"),
-                                QCoreApplication::translate("Updater", "%1 cannot be started.").arg(mainExecutable));
+                                mainStartupError.isEmpty()
+                                    ? QCoreApplication::translate("Updater", "%1 cannot be started.").arg(mainExecutable)
+                                    : mainStartupError);
 
     QElapsedTimer healthTimer;
     healthTimer.start();

config/app_config.example.json

@@ -1,21 +0,0 @@
-{
-  "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": "",
-  "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"
-}

config/app_config.linux.example.json

@@ -1,21 +0,0 @@
-{
-  "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": "",
-  "client_token": "SimCAEClientToken2026",
-  "request_timeout_ms": "5000",
-  "temp_folder": "update_temp",
-  "device_id": "",
-  "install_root": "..",
-  "main_executable": "SimCAE",
-  "launcher_executable": "Launcher",
-  "updater_executable": "Updater",
-  "bootstrap_executable": "Bootstrap",
-  "health_check_timeout_ms": "15000",
-  "platform": "linux",
-  "arch": "x64"
-}

config/server_config.json

@@ -1,3 +1,3 @@
-{
-  "api_base_url": "http://YOUR_SERVER_IP:8000"
+{
+  "api_base_url": "http://192.168.1.158:18000"
 }

scripts/ReadMe.txt

@@ -1,57 +1,32 @@
-客户端脚本说明
-==============
+SimCAE Hub 客户端脚本说明
+==========================
 
-本目录保存 update-client 的辅助脚本。项目根目录只保留源码、CMake 入口、Docs 和配置模板，脚本统一放在这里。
+本目录保存 Qt/C++ 客户端更新链路的辅助脚本。客户端仍然由
+Launcher、Updater、Bootstrap 和业务主程序组成，服务端接口使用当前
+SimCAE Hub 的 Go API。
 
 脚本列表：
 
 1. package-sdk.ps1
-   在 Windows 上生成给其他软件接入用的 UpdateClientSDK 包。
+   在 Windows 上生成给业务软件接入用的客户端更新运行时包。
 
 2. package-client.ps1
-   在 Windows 上生成某个具体产品的最终客户端发布包。
+   Windows 本地调试用的客户包脚本，需要手工提供 app_config.json。
+   新流程建议上传完整软件 ZIP 到 SimCAE Hub，由服务端生成最终配置。
 
 3. install-sdk.ps1
-   将 SDK 运行时复制到业务软件 Release 目录。
+   把客户端更新运行时复制到业务软件 Release 目录。
 
 4. package-sdk.sh
-   在 Linux 上生成给其他软件接入用的 UpdateClientSDK 包，输出 tar.gz。
+   在 Linux 上生成客户端更新运行时包，输出 tar.gz。
 
 5. package-client.sh
-   在 Linux 上生成某个具体产品的最终客户端发布包，输出 tar.gz。
+   Linux 本地调试用的客户包脚本，需要手工提供 app_config.json。
 
-推荐在 update-client 根目录执行：
+SDK 打包命令、两种打包模式、参数含义和输出位置，统一看：
 
-```powershell
-.\scripts\package-sdk.ps1 `
-  -SourceDir .\out\bin `
-  -OutputDir .\dist\UpdateClientSDK `
-  -ZipFile .\dist\UpdateClientSDK.zip `
-  -SdkVersion 0.1.0
-```
+../updater打包成SDK.md
 
-```powershell
-.\scripts\package-client.ps1 `
-  -SourceDir .\out\bin `
-  -ConfigFile .\config\app_config.json `
-  -OutputDir .\dist\UpdateClient `
-  -ZipFile .\dist\UpdateClient.zip
-```
-
-Linux 示例：
-
-```bash
-bash ./scripts/package-sdk.sh \
-  --source-dir ./out/linux/bin \
-  --output-dir ./dist/UpdateClientSDK-linux \
-  --archive ./dist/UpdateClientSDK-linux.tar.gz \
-  --sdk-version 0.1.0
-```
-
-```bash
-bash ./scripts/package-client.sh \
-  --source-dir /path/to/SimCAE \
-  --config-file /path/to/SimCAE/bin/config/app_config.json \
-  --output-dir ./dist/UpdateClient-linux \
-  --archive ./dist/UpdateClient-linux.tar.gz
-```
+生成 SDK 后，SDK 根目录里只带给 SIMCAE 发布人员看的 SIMCAE打包上传.md。
+后续如何把 Launcher、Updater、Bootstrap 和必要运行库放进业务软件、如何
+组装 Qt IFW 交付包并上传，以该文档为准。

scripts/install-sdk.ps1

@@ -1,28 +1,23 @@
 param(
-    [Parameter(Mandatory=$true)]
-    [string]$SdkRoot,
-
-    [string]$ReleaseDir = (Get-Location).Path,
-
-    [switch]$OverwriteConfig,
-
-    [switch]$IncludeQtRuntime
-)
+    [Parameter(Mandatory=$true)]
+    [string]$SdkRoot,
+
+    [string]$ReleaseDir = (Get-Location).Path,
+
+    [switch]$IncludeQtRuntime
+)
 
 $ErrorActionPreference = "Stop"
 
 $sdk = (Resolve-Path $SdkRoot).Path
 $release = (Resolve-Path $ReleaseDir).Path
 
-$binDir = Join-Path $sdk "bin"
-$configDir = Join-Path $sdk "config"
-$appConfig = Join-Path $configDir "app_config.json"
-$publicKey = Join-Path $configDir "manifest_public_key.pem"
-
-foreach ($path in @($binDir, $appConfig, $publicKey)) {
-    if (-not (Test-Path $path)) {
-        throw "SDK file is missing: $path"
-    }
+$binDir = Join-Path $sdk "bin"
+
+foreach ($path in @($binDir)) {
+    if (-not (Test-Path $path)) {
+        throw "SDK file is missing: $path"
+    }
 }
 
 function Test-IsQtRuntimeItem {
@@ -58,17 +53,8 @@ Get-ChildItem $binDir -Force | Where-Object {
     -not (Test-IsQtRuntimeItem $_)
 } | Copy-Item -Destination $release -Recurse -Force
 
-$targetConfigDir = Join-Path $release "config"
-New-Item $targetConfigDir -ItemType Directory -Force | Out-Null
-
-$targetAppConfig = Join-Path $targetConfigDir "app_config.json"
-if ((-not (Test-Path $targetAppConfig)) -or $OverwriteConfig) {
-    Copy-Item $appConfig $targetAppConfig -Force
-} else {
-    Write-Host "Keep existing config/app_config.json. Use -OverwriteConfig to replace it."
-}
-
-Copy-Item $publicKey (Join-Path $targetConfigDir "manifest_public_key.pem") -Force
-
-Write-Host "SDK files installed to: $release"
-Write-Host "Next: edit config/app_config.json, then start Launcher.exe."
+$targetConfigDir = Join-Path $release "config"
+New-Item $targetConfigDir -ItemType Directory -Force | Out-Null
+
+Write-Host "SDK files installed to: $release"
+Write-Host "Next: package the whole application directory and upload it in SimCAE Hub. The server will generate config/app_config.json and config/manifest_public_key.pem when needed."

scripts/package-client.ps1

@@ -3,20 +3,21 @@ param(
     [Parameter(Mandatory = $true)]
     [string]$ConfigFile,
     [string]$OutputDir = "",
-    [string]$ZipFile = ""
+    [string]$ZipFile = "",
+    [switch]$SkipManifestCheck
 )
 
 $ErrorActionPreference = "Stop"
 
 $RepoRoot = Split-Path -Parent $PSScriptRoot
 if ([string]::IsNullOrWhiteSpace($SourceDir)) {
-    $SourceDir = Join-Path $RepoRoot "out/bin"
+    $SourceDir = Join-Path $RepoRoot "out/bin/Release"
 }
 if ([string]::IsNullOrWhiteSpace($OutputDir)) {
-    $OutputDir = Join-Path $RepoRoot "dist/UpdateClient"
+    $OutputDir = Join-Path $RepoRoot "dist/SimCAEUpdateClient"
 }
 if ([string]::IsNullOrWhiteSpace($ZipFile)) {
-    $ZipFile = Join-Path $RepoRoot "dist/UpdateClient.zip"
+    $ZipFile = Join-Path $RepoRoot "dist/SimCAEUpdateClient.zip"
 }
 
 $source = (Resolve-Path $SourceDir).Path
@@ -40,17 +41,35 @@ $configRelativeParent = Split-Path $configRelativePath -Parent
 $runtimeDirRelative = Normalize-RelativePath (Split-Path $configRelativeParent -Parent)
 if ($runtimeDirRelative -eq ".") { $runtimeDirRelative = "" }
 
-function Join-RelativePath([string]$Base, [string]$Child) {
-    $baseNorm = Normalize-RelativePath $Base
-    $childNorm = Normalize-RelativePath $Child
-    if ([string]::IsNullOrWhiteSpace($baseNorm)) { return $childNorm }
-    if ([string]::IsNullOrWhiteSpace($childNorm)) { return $baseNorm }
-    return "$baseNorm/$childNorm"
-}
-
+function Join-RelativePath([string]$Base, [string]$Child) {
+    $baseNorm = Normalize-RelativePath $Base
+    $childNorm = Normalize-RelativePath $Child
+    if ([string]::IsNullOrWhiteSpace($baseNorm)) { return $childNorm }
+    if ([string]::IsNullOrWhiteSpace($childNorm)) { return $baseNorm }
+    return "$baseNorm/$childNorm"
+}
+
+function Get-InstallDirectoryId([string]$RuntimeDir) {
+    $normalized = ([IO.Path]::GetFullPath($RuntimeDir) -replace '\\', '/').TrimEnd('/')
+    $sha = [System.Security.Cryptography.SHA256]::Create()
+    try {
+        $bytes = [System.Text.Encoding]::UTF8.GetBytes($normalized)
+        $hash = $sha.ComputeHash($bytes)
+        return -join ($hash | ForEach-Object { $_.ToString("x2") })
+    } finally {
+        $sha.Dispose()
+    }
+}
+
+function Get-UserDataManifestCandidate([string]$RuntimeDir, [string]$ManifestName) {
+    $localData = [Environment]::GetFolderPath("LocalApplicationData")
+    if ([string]::IsNullOrWhiteSpace($localData)) { return "" }
+    $installId = Get-InstallDirectoryId $RuntimeDir
+    return Join-Path $localData "SimCAE\HubUpdateClient\installations\$installId\update\manifest_cache\$ManifestName"
+}
+
 $requiredFields = @(
-    "app_id", "channel", "current_version",
-    "client_token", "launch_token", "license_key",
+    "product_code", "channel", "current_version", "launch_token",
     "main_executable", "launcher_executable", "updater_executable", "bootstrap_executable"
 )
 foreach ($field in $requiredFields) {
@@ -81,9 +100,9 @@ $debugArtifacts = Get-ChildItem $source -Recurse -File | Where-Object {
     $_.Name -match '^(Qt5.*d|qwindowsd|libEGLd|libGLESv2d|msvcp.*d|vcruntime.*d)\.dll$' -or
     $_.Extension -in @('.pdb', '.ilk')
 }
-if ($debugArtifacts) {
-    throw "Source directory contains Debug artifacts. Clean out/bin and rebuild Release first. Example: $($debugArtifacts[0].FullName)"
-}
+if ($debugArtifacts) {
+    throw "Source directory contains Debug artifacts. Clean the Release output directory and rebuild Release first. Example: $($debugArtifacts[0].FullName)"
+}
 
 $expectedMainPath = Join-RelativePath $runtimeDirRelative $mainExecutable
 $mainLeafName = Split-Path $mainExecutable -Leaf
@@ -95,18 +114,23 @@ if ($duplicateMain) {
     throw "Source directory contains a duplicate main executable outside $expectedMainPath. Use a clean Release root directory: $($duplicateMain.FullName)"
 }
 
-$manifestName = "manifest_$($settings.current_version).json"
-$sourceManifestRelative = Join-RelativePath $runtimeDirRelative "update/manifest_cache/$manifestName"
-$sourceManifest = Join-Path $source ($sourceManifestRelative -replace '/', [IO.Path]::DirectorySeparatorChar)
-if (-not (Test-Path $sourceManifest)) {
-    $legacySourceManifest = Join-Path $source "update/manifest_cache/$manifestName"
-    if (Test-Path $legacySourceManifest) {
-        $sourceManifest = $legacySourceManifest
-    }
-}
-if (-not (Test-Path $sourceManifest)) {
-    throw "Missing signed Manifest cache for current version: $sourceManifest. Complete online update/verification for this version before packaging."
-}
+$manifestName = "manifest_$($settings.current_version).json"
+$runtimeDirAbsolute = if ([string]::IsNullOrWhiteSpace($runtimeDirRelative)) {
+    $source
+} else {
+    Join-Path $source ($runtimeDirRelative -replace '/', [IO.Path]::DirectorySeparatorChar)
+}
+$sourceManifestRelative = Join-RelativePath $runtimeDirRelative "update/manifest_cache/$manifestName"
+$manifestCandidates = @(
+    (Get-UserDataManifestCandidate $runtimeDirAbsolute $manifestName),
+    (Join-Path $source ($sourceManifestRelative -replace '/', [IO.Path]::DirectorySeparatorChar)),
+    (Join-Path $source "update/manifest_cache/$manifestName")
+) | Where-Object { -not [string]::IsNullOrWhiteSpace($_) }
+$sourceManifest = $manifestCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1
+if (-not $SkipManifestCheck -and (-not $sourceManifest -or -not (Test-Path $sourceManifest))) {
+    $searched = ($manifestCandidates | ForEach-Object { "  - $_" }) -join [Environment]::NewLine
+    throw "Missing Manifest cache for current version: $manifestName. Complete online update/verification for this version before packaging, or pass -SkipManifestCheck for a first-time test package. Searched paths:$([Environment]::NewLine)$searched"
+}
 
 if (Test-Path $OutputDir) {
     Remove-Item $OutputDir -Recurse -Force
@@ -131,14 +155,16 @@ $outputConfigDir = Split-Path $outputConfigPath -Parent
 New-Item $outputConfigDir -ItemType Directory -Force | Out-Null
 Copy-Item $config $outputConfigPath -Force
 
-@("client_identity.dat", "local_state.json", "version_policy.dat") | ForEach-Object {
+@("client_identity.dat", "local_state.json", "version_policy.dat") | ForEach-Object {
     $runtimeFile = Join-Path $outputConfigDir $_
     if (Test-Path $runtimeFile) { Remove-Item $runtimeFile -Force }
 }
 
-$manifestDir = Join-Path $OutputDir ((Join-RelativePath $runtimeDirRelative "update/manifest_cache") -replace '/', [IO.Path]::DirectorySeparatorChar)
-New-Item $manifestDir -ItemType Directory -Force | Out-Null
-Copy-Item $sourceManifest (Join-Path $manifestDir $manifestName) -Force
+$manifestDir = Join-Path $OutputDir ((Join-RelativePath $runtimeDirRelative "update/manifest_cache") -replace '/', [IO.Path]::DirectorySeparatorChar)
+if ($sourceManifest -and (Test-Path $sourceManifest)) {
+    New-Item $manifestDir -ItemType Directory -Force | Out-Null
+    Copy-Item $sourceManifest (Join-Path $manifestDir $manifestName) -Force
+}
 
 $zipParent = Split-Path $ZipFile -Parent
 New-Item $zipParent -ItemType Directory -Force | Out-Null

scripts/package-client.sh

@@ -6,8 +6,8 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
 SOURCE_DIR="$REPO_ROOT/out/linux/bin"
 CONFIG_FILE=""
-OUTPUT_DIR="$REPO_ROOT/dist/UpdateClient-linux"
-ARCHIVE_FILE="$REPO_ROOT/dist/UpdateClient-linux.tar.gz"
+OUTPUT_DIR="$REPO_ROOT/dist/SimCAEUpdateClient-linux"
+ARCHIVE_FILE="$REPO_ROOT/dist/SimCAEUpdateClient-linux.tar.gz"
 SKIP_MANIFEST_CHECK=0
 
 usage() {
@@ -17,8 +17,8 @@ Usage: package-client.sh --config-file FILE [options]
 Options:
   --source-dir DIR          Release/install root to package. Default: ./out/linux/bin
   --config-file FILE        app_config.json used by this client package. Required.
-  --output-dir DIR          Output directory. Default: ./dist/UpdateClient-linux
-  --archive FILE            Output tar.gz. Default: ./dist/UpdateClient-linux.tar.gz
+  --output-dir DIR          Output directory. Default: ./dist/SimCAEUpdateClient-linux
+  --archive FILE            Output tar.gz. Default: ./dist/SimCAEUpdateClient-linux.tar.gz
   --skip-manifest-check     Skip current-version manifest cache check.
   -h, --help                Show this help.
 EOF
@@ -72,6 +72,27 @@ print(rel.replace(os.sep, "/").strip("/"))
 PY
 }
 
+install_directory_id() {
+  python3 - "$1" <<'PY'
+import hashlib
+import os
+import sys
+
+value = os.path.realpath(sys.argv[1]).replace(os.sep, "/").rstrip("/")
+print(hashlib.sha256(value.encode("utf-8")).hexdigest())
+PY
+}
+
+user_data_manifest_candidate() {
+  local runtime_dir="$1"
+  local manifest_name="$2"
+  local data_home="${XDG_DATA_HOME:-$HOME/.local/share}"
+  local install_id
+  install_id="$(install_directory_id "$runtime_dir")"
+  printf '%s/SimCAE/HubUpdateClient/installations/%s/update/manifest_cache/%s' \
+    "$data_home" "$install_id" "$manifest_name"
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --source-dir) SOURCE_DIR="$2"; shift 2 ;;
@@ -95,7 +116,7 @@ CONFIG_FILE="$(realpath "$CONFIG_FILE")"
 OUTPUT_DIR="$(realpath -m "$OUTPUT_DIR")"
 ARCHIVE_FILE="$(realpath -m "$ARCHIVE_FILE")"
 
-for field in app_id channel current_version client_token launch_token license_key main_executable launcher_executable updater_executable bootstrap_executable; do
+for field in product_code channel current_version launch_token main_executable launcher_executable updater_executable bootstrap_executable; do
   if [[ -z "$(json_value "$field")" ]]; then
     echo "Config file is missing required field: $field" >&2
     exit 1
@@ -148,12 +169,27 @@ if [[ -n "$DUPLICATE_MAIN" ]]; then
 fi
 
 MANIFEST_NAME="manifest_${CURRENT_VERSION}.json"
-SOURCE_MANIFEST="$SOURCE_DIR/$(join_relative_path "$RUNTIME_DIR_RELATIVE" "update/manifest_cache/$MANIFEST_NAME")"
-if [[ ! -f "$SOURCE_MANIFEST" && -f "$SOURCE_DIR/update/manifest_cache/$MANIFEST_NAME" ]]; then
-  SOURCE_MANIFEST="$SOURCE_DIR/update/manifest_cache/$MANIFEST_NAME"
+if [[ -z "$RUNTIME_DIR_RELATIVE" ]]; then
+  RUNTIME_DIR_ABSOLUTE="$SOURCE_DIR"
+else
+  RUNTIME_DIR_ABSOLUTE="$SOURCE_DIR/$RUNTIME_DIR_RELATIVE"
 fi
+MANIFEST_CANDIDATES=(
+  "$(user_data_manifest_candidate "$RUNTIME_DIR_ABSOLUTE" "$MANIFEST_NAME")"
+  "$SOURCE_DIR/$(join_relative_path "$RUNTIME_DIR_RELATIVE" "update/manifest_cache/$MANIFEST_NAME")"
+  "$SOURCE_DIR/update/manifest_cache/$MANIFEST_NAME"
+)
+SOURCE_MANIFEST=""
+for candidate in "${MANIFEST_CANDIDATES[@]}"; do
+  if [[ -f "$candidate" ]]; then
+    SOURCE_MANIFEST="$candidate"
+    break
+  fi
+done
 if [[ "$SKIP_MANIFEST_CHECK" -eq 0 && ! -f "$SOURCE_MANIFEST" ]]; then
-  echo "Missing signed Manifest cache for current version: $SOURCE_MANIFEST. Complete online update/verification for this version before packaging." >&2
+  echo "Missing Manifest cache for current version: $MANIFEST_NAME." >&2
+  echo "Complete online update/verification for this version before packaging, or pass --skip-manifest-check for a first-time test package. Searched paths:" >&2
+  printf '  - %s\n' "${MANIFEST_CANDIDATES[@]}" >&2
   exit 1
 fi
 

scripts/package-sdk.ps1

@@ -3,7 +3,6 @@ param(
     [string]$OutputDir = "",
     [string]$ZipFile = "",
     [string]$SdkVersion = "0.1.0",
-    [string]$ExampleConfig = "",
     [switch]$IncludeDemoMainApp,
     [switch]$IncludeQtRuntime
 )
@@ -11,42 +10,29 @@ param(
 $ErrorActionPreference = "Stop"
 
 $RepoRoot = Split-Path -Parent $PSScriptRoot
+$DefaultSdkName = if ($IncludeQtRuntime) { "UpdateClientSDK-With-QtDll" } else { "UpdateClientSDK" }
 if ([string]::IsNullOrWhiteSpace($SourceDir)) {
-    $SourceDir = Join-Path $RepoRoot "out/bin"
+    $SourceDir = Join-Path $RepoRoot "out/bin/Release"
 }
 if ([string]::IsNullOrWhiteSpace($OutputDir)) {
-    $OutputDir = Join-Path $RepoRoot "dist/UpdateClientSDK"
+    $OutputDir = Join-Path $RepoRoot "dist/$DefaultSdkName"
 }
 if ([string]::IsNullOrWhiteSpace($ZipFile)) {
-    $ZipFile = Join-Path $RepoRoot "dist/UpdateClientSDK.zip"
-}
-if ([string]::IsNullOrWhiteSpace($ExampleConfig)) {
-    $ExampleConfig = Join-Path $RepoRoot "config/app_config.example.json"
+    $ZipFile = Join-Path $RepoRoot "dist/$DefaultSdkName.zip"
 }
 
 $source = (Resolve-Path $SourceDir).Path
-$exampleConfigPath = (Resolve-Path $ExampleConfig).Path
-
-$requiredFiles = @("Launcher.exe", "Updater.exe", "Bootstrap.exe")
-foreach ($name in $requiredFiles) {
+
+$requiredFiles = @("Launcher.exe", "Updater.exe", "Bootstrap.exe")
+foreach ($name in $requiredFiles) {
     $path = Join-Path $source $name
     if (-not (Test-Path $path)) {
         throw "SDK source directory is missing required file: $path"
-    }
-}
-
-$publicKeyCandidates = @(
-    (Join-Path $source "config/manifest_public_key.pem"),
-    (Join-Path $source "manifest_public_key.pem"),
-    (Join-Path $RepoRoot "config/manifest_public_key.pem")
-)
-$publicKey = $publicKeyCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1
-if (-not $publicKey) {
-    throw "manifest_public_key.pem is missing. Prepare the public key that matches the server signing private key."
-}
-
-$debugArtifacts = Get-ChildItem $source -Recurse -File | Where-Object {
-    $_.Name -match '^(Qt5.*d|qwindowsd|libEGLd|libGLESv2d|msvcp.*d|vcruntime.*d)\.dll$' -or
+    }
+}
+
+$debugArtifacts = Get-ChildItem $source -Recurse -File | Where-Object {
+    $_.Name -match '^(Qt5.*d|qwindowsd|libEGLd|libGLESv2d|msvcp.*d|vcruntime.*d)\.dll$' -or
     $_.Extension -in @('.pdb', '.ilk')
 }
 if ($debugArtifacts) {
@@ -84,9 +70,14 @@ function Test-IsQtRuntimeFile {
     }
 
     return (
-        $Item.Name -match '^Qt5.*\.dll$' -or
-        $Item.Name -in @(
-            "libEGL.dll",
+        $Item.Name -match '^Qt5.*\.dll$' -or
+        $Item.Name -match '^vc_redist.*\.exe$' -or
+        $Item.Name -match '^vcredist.*\.exe$' -or
+        $Item.Name -match '^vcruntime.*\.dll$' -or
+        $Item.Name -match '^msvcp.*\.dll$' -or
+        $Item.Name -match '^concrt.*\.dll$' -or
+        $Item.Name -in @(
+            "libEGL.dll",
             "libGLESv2.dll",
             "opengl32sw.dll",
             "d3dcompiler_47.dll"
@@ -94,21 +85,20 @@ function Test-IsQtRuntimeFile {
     )
 }
 
-Get-ChildItem $source -Force | Where-Object {
-    $_.Name -notin $excludedTopLevel -and -not (Test-IsQtRuntimeFile $_)
-} | Copy-Item -Destination $binDir -Recurse -Force
-
-Copy-Item $exampleConfigPath (Join-Path $configDir "app_config.json") -Force
-Copy-Item $publicKey (Join-Path $configDir "manifest_public_key.pem") -Force
-Copy-Item (Join-Path $RepoRoot "config/server_config.json") (Join-Path $configDir "server_config.json") -Force
-Copy-Item (Join-Path $RepoRoot "config/server_config.qrc") (Join-Path $configDir "server_config.qrc") -Force
+Get-ChildItem $source -Force | Where-Object {
+    $_.Name -notin $excludedTopLevel -and -not (Test-IsQtRuntimeFile $_)
+} | Copy-Item -Destination $binDir -Recurse -Force
 
 $commonSourceDir = Join-Path $RepoRoot "Common"
 $commonSourceFiles = @(
     "ConfigHelper.h",
     "ConfigHelper.cpp",
+    "IntegrityHelper.h",
+    "IntegrityHelper.cpp",
     "TicketHelper.h",
-    "TicketHelper.cpp"
+    "TicketHelper.cpp",
+    "UpdatePathPolicy.h",
+    "UpdatePathPolicy.cpp"
 )
 foreach ($commonFile in $commonSourceFiles) {
     $commonPath = Join-Path $commonSourceDir $commonFile
@@ -118,16 +108,13 @@ foreach ($commonFile in $commonSourceFiles) {
     Copy-Item $commonPath (Join-Path $commonDir $commonFile) -Force
 }
 
-$wordGuideSource = @($RepoRoot, (Join-Path $RepoRoot "Docs")) |
-    Where-Object { Test-Path $_ } |
-    ForEach-Object { Get-ChildItem $_ -File -Filter "*.docx" } |
-    Where-Object { $_.Name -like "*SDK*.docx" -and $_.Name -notlike "~$*" } |
-    Sort-Object Name |
-    Select-Object -First 1
-if (-not $wordGuideSource) {
-    throw "SDK integration Word guide is missing. Expected a *SDK*.docx file in the repository root or Docs directory."
+$sdkGuideName = [string]::Concat("SIMCAE", [char]0x6253, [char]0x5305, [char]0x4e0a, [char]0x4f20, ".md")
+$sdkGuideSource = Join-Path $RepoRoot $sdkGuideName
+if (Test-Path $sdkGuideSource) {
+    Copy-Item $sdkGuideSource (Join-Path $OutputDir $sdkGuideName) -Force
+} else {
+    throw "SIMCAE packaging guide is missing: $sdkGuideSource"
 }
-Copy-Item $wordGuideSource.FullName (Join-Path $OutputDir $wordGuideSource.Name) -Force
 
 Copy-Item (Join-Path $PSScriptRoot "package-client.ps1") (Join-Path $scriptsDir "package-client.ps1") -Force
 Copy-Item (Join-Path $PSScriptRoot "package-sdk.ps1") (Join-Path $scriptsDir "package-sdk.ps1") -Force
@@ -139,6 +126,10 @@ Copy-Item (Join-Path $PSScriptRoot "install-sdk.ps1") (Join-Path $scriptsDir "in
     sdk_type = "external-updater-runtime"
     required_entry = "Launcher.exe"
     contains_demo_main_app = [bool]$IncludeDemoMainApp
+    contains_qt_runtime = [bool]$IncludeQtRuntime
+    contains_final_config = $false
+    docs_entry = $sdkGuideName
+    word_guide_included = $false
     integration_sources = $commonSourceFiles
 } | ConvertTo-Json -Depth 3 | Set-Content (Join-Path $OutputDir "sdk_manifest.json") -Encoding UTF8
 

scripts/package-sdk.sh

@@ -8,8 +8,8 @@ SOURCE_DIR="$REPO_ROOT/out/linux/bin"
 OUTPUT_DIR="$REPO_ROOT/dist/UpdateClientSDK-linux"
 ARCHIVE_FILE="$REPO_ROOT/dist/UpdateClientSDK-linux.tar.gz"
 SDK_VERSION="0.1.0"
-EXAMPLE_CONFIG="$REPO_ROOT/config/app_config.linux.example.json"
 INCLUDE_DEMO_MAIN_APP=0
+INCLUDE_QT_RUNTIME=0
 
 usage() {
   cat <<'EOF'
@@ -20,8 +20,8 @@ Options:
   --output-dir DIR       SDK directory to generate. Default: ./dist/UpdateClientSDK-linux
   --archive FILE         SDK tar.gz path. Default: ./dist/UpdateClientSDK-linux.tar.gz
   --sdk-version VERSION  SDK version. Default: 0.1.0
-  --example-config FILE  app_config template. Default: ./config/app_config.linux.example.json
   --include-demo-mainapp Include MainApp demo executable in SDK bin.
+  --include-qt-runtime   Include Qt runtime files from the Release output directory.
   -h, --help             Show this help.
 EOF
 }
@@ -32,15 +32,14 @@ while [[ $# -gt 0 ]]; do
     --output-dir) OUTPUT_DIR="$2"; shift 2 ;;
     --archive|--tar-file|--zip-file) ARCHIVE_FILE="$2"; shift 2 ;;
     --sdk-version) SDK_VERSION="$2"; shift 2 ;;
-    --example-config) EXAMPLE_CONFIG="$2"; shift 2 ;;
     --include-demo-mainapp) INCLUDE_DEMO_MAIN_APP=1; shift ;;
+    --include-qt-runtime) INCLUDE_QT_RUNTIME=1; shift ;;
     -h|--help) usage; exit 0 ;;
     *) echo "Unknown option: $1" >&2; usage >&2; exit 2 ;;
   esac
 done
 
 SOURCE_DIR="$(realpath "$SOURCE_DIR")"
-EXAMPLE_CONFIG="$(realpath "$EXAMPLE_CONFIG")"
 OUTPUT_DIR="$(realpath -m "$OUTPUT_DIR")"
 ARCHIVE_FILE="$(realpath -m "$ARCHIVE_FILE")"
 
@@ -51,21 +50,6 @@ for name in Launcher Updater Bootstrap; do
   fi
 done
 
-PUBLIC_KEY=""
-for candidate in \
-  "$SOURCE_DIR/config/manifest_public_key.pem" \
-  "$SOURCE_DIR/manifest_public_key.pem" \
-  "$REPO_ROOT/config/manifest_public_key.pem"; do
-  if [[ -f "$candidate" ]]; then
-    PUBLIC_KEY="$candidate"
-    break
-  fi
-done
-if [[ -z "$PUBLIC_KEY" ]]; then
-  echo "manifest_public_key.pem is missing. Prepare the public key that matches the server signing private key." >&2
-  exit 1
-fi
-
 DEBUG_ARTIFACT="$(find "$SOURCE_DIR" -type f \( -name '*.pdb' -o -name '*.ilk' -o -name '*d.dll' \) -print -quit)"
 if [[ -n "$DEBUG_ARTIFACT" ]]; then
   echo "SDK source directory contains Debug artifacts. Use a clean Release output directory." >&2
@@ -76,6 +60,21 @@ fi
 rm -rf "$OUTPUT_DIR"
 mkdir -p "$OUTPUT_DIR/bin" "$OUTPUT_DIR/config" "$OUTPUT_DIR/scripts" "$OUTPUT_DIR/Common"
 
+is_qt_runtime_item() {
+  local base="$1"
+  case "$base" in
+    bearer|iconengines|imageformats|platforms|styles|translations)
+      return 0
+      ;;
+    libQt5*.so*|libEGL.so*|libGLESv2.so*|libqxcb.so*|libxcb*.so*|libstdc++.so*|libgcc_s.so*|libssl.so*|libcrypto.so*|opengl32sw.dll|d3dcompiler_47.dll)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
 shopt -s dotglob nullglob
 for item in "$SOURCE_DIR"/*; do
   base="$(basename "$item")"
@@ -86,18 +85,16 @@ for item in "$SOURCE_DIR"/*; do
       fi
       ;;
     *)
+      if [[ "$INCLUDE_QT_RUNTIME" -eq 0 ]] && is_qt_runtime_item "$base"; then
+        continue
+      fi
       cp -a "$item" "$OUTPUT_DIR/bin/"
       ;;
   esac
 done
 shopt -u dotglob nullglob
 
-cp "$EXAMPLE_CONFIG" "$OUTPUT_DIR/config/app_config.json"
-cp "$PUBLIC_KEY" "$OUTPUT_DIR/config/manifest_public_key.pem"
-cp "$REPO_ROOT/config/server_config.json" "$OUTPUT_DIR/config/server_config.json"
-cp "$REPO_ROOT/config/server_config.qrc" "$OUTPUT_DIR/config/server_config.qrc"
-
-for common_file in ConfigHelper.h ConfigHelper.cpp TicketHelper.h TicketHelper.cpp; do
+for common_file in ConfigHelper.h ConfigHelper.cpp IntegrityHelper.h IntegrityHelper.cpp TicketHelper.h TicketHelper.cpp UpdatePathPolicy.h UpdatePathPolicy.cpp; do
   common_path="$REPO_ROOT/Common/$common_file"
   if [[ ! -f "$common_path" ]]; then
     echo "SDK Common integration source is missing: $common_path" >&2
@@ -106,12 +103,14 @@ for common_file in ConfigHelper.h ConfigHelper.cpp TicketHelper.h TicketHelper.c
   cp "$common_path" "$OUTPUT_DIR/Common/$common_file"
 done
 
-WORD_GUIDE="$(find "$REPO_ROOT" "$REPO_ROOT/Docs" -maxdepth 1 -type f -name '*SDK*.docx' ! -name '~$*' 2>/dev/null | sort | sed -n '1p')"
-if [[ -z "$WORD_GUIDE" ]]; then
-  echo "SDK integration Word guide is missing. Expected a *SDK*.docx file in the repository root or Docs directory." >&2
+SDK_GUIDE_NAME="SIMCAE打包上传.md"
+SDK_GUIDE_SOURCE="$REPO_ROOT/$SDK_GUIDE_NAME"
+if [[ -f "$SDK_GUIDE_SOURCE" ]]; then
+  cp "$SDK_GUIDE_SOURCE" "$OUTPUT_DIR/$SDK_GUIDE_NAME"
+else
+  echo "SIMCAE packaging guide is missing: $SDK_GUIDE_SOURCE" >&2
   exit 1
 fi
-cp "$WORD_GUIDE" "$OUTPUT_DIR/$(basename "$WORD_GUIDE")"
 
 cp "$SCRIPT_DIR/package-sdk.sh" "$OUTPUT_DIR/scripts/package-sdk.sh"
 cp "$SCRIPT_DIR/package-client.sh" "$OUTPUT_DIR/scripts/package-client.sh"
@@ -130,11 +129,19 @@ cat > "$OUTPUT_DIR/sdk_manifest.json" <<EOF
   "platform": "linux",
   "required_entry": "Launcher",
   "contains_demo_main_app": $([[ "$INCLUDE_DEMO_MAIN_APP" -eq 1 ]] && echo true || echo false),
+  "contains_qt_runtime": $([[ "$INCLUDE_QT_RUNTIME" -eq 1 ]] && echo true || echo false),
+  "contains_final_config": false,
+  "docs_entry": "$SDK_GUIDE_NAME",
+  "word_guide_included": false,
   "integration_sources": [
     "ConfigHelper.h",
     "ConfigHelper.cpp",
+    "IntegrityHelper.h",
+    "IntegrityHelper.cpp",
     "TicketHelper.h",
-    "TicketHelper.cpp"
+    "TicketHelper.cpp",
+    "UpdatePathPolicy.h",
+    "UpdatePathPolicy.cpp"
   ]
 }
 EOF

updater打包成SDK.md

@@ -0,0 +1,124 @@
+# Updater 打包成 SDK
+
+本文只说明如何从 `SIMCAE/update-client` 生成给 SIMCAE 打包流程使用的更新客户端 SDK。SIMCAE 如何拿这个 SDK 打客户安装器和交付包，见当前目录《SIMCAE打包上传.md》。
+
+## 一、SDK 包含什么
+
+SDK 用来把 Hub 更新客户端接入 SIMCAE 安装包。
+
+| 内容 | 作用 |
+| --- | --- |
+| `Launcher.exe` | 客户日常启动入口，检查整包更新并启动主程序 |
+| `Updater.exe` | 拉取 Manifest、下载发布包、校验 SHA-256、准备安装 |
+| `Bootstrap.exe` | 替换运行中文件时接管安装 |
+| Qt 运行库 | 可选，给没有单独 Qt 运行环境的接入方使用 |
+| `SIMCAE打包上传.md` | 给 SIMCAE 发布人员看的打包、交付包组装和上传说明 |
+
+SDK 不包含最终客户配置文件，例如 `app_config.json`、`server_config.json`、`server_config.qrc`、`manifest_public_key.pem`。这些文件由服务端在上传客户软件包或 Qt IFW 交付包时生成或注入。
+
+打包后的 SDK 根目录只放 `SIMCAE打包上传.md` 这一份使用说明。本文是维护者打 SDK 的说明，不随 SDK 一起交给接入方。
+
+## 二、编译 Release
+
+先进入 SIMCAE 仓库下的 `update-client` 目录。如果当前已经在 SIMCAE 仓库根目录：
+
+```powershell
+cd .\update-client
+```
+
+然后执行：
+
+```powershell
+cmake --preset x64-release -DSIMCAE_OPENSSL_ROOT="C:\Program Files\OpenSSL-Win64"
+cmake --build --preset x64-release
+```
+
+如果 OpenSSL 安装在其他目录，只改 `SIMCAE_OPENSSL_ROOT` 这一项。
+
+编译完成后，Release 产物通常位于 `out/bin/Release`。
+
+检查核心程序：
+
+```powershell
+Test-Path .\out\bin\Release\Launcher.exe
+Test-Path .\out\bin\Release\Updater.exe
+Test-Path .\out\bin\Release\Bootstrap.exe
+```
+
+预期都返回 `True`。
+
+## 三、打包不带 Qt 运行库的 SDK
+
+适用于接入方已经有 Qt 运行环境，或希望自己控制 Qt DLL 的情况。
+
+```powershell
+.\scripts\package-sdk.ps1 `
+  -SourceDir .\out\bin\Release `
+  -OutputDir .\dist\UpdateClientSDK `
+  -ZipFile .\dist\UpdateClientSDK.zip `
+  -SdkVersion 0.1.0
+```
+
+输出：
+
+| 输出 | 说明 |
+| --- | --- |
+| `dist\UpdateClientSDK` | 不带 Qt 运行库的 SDK 展开目录 |
+| `dist\UpdateClientSDK.zip` | 不带 Qt 运行库的 SDK 压缩包 |
+
+## 四、打包带 Qt 运行库的 SDK
+
+适用于接入方不想单独准备 Qt DLL，或者希望拿到后能直接放进安装包。
+
+```powershell
+.\scripts\package-sdk.ps1 `
+  -SourceDir .\out\bin\Release `
+  -OutputDir .\dist\UpdateClientSDK-With-QtDll `
+  -ZipFile .\dist\UpdateClientSDK-With-QtDll.zip `
+  -SdkVersion 0.1.0 `
+  -IncludeQtRuntime
+```
+
+这里的 `With-QtDll` 表示包里带的是运行所需的 Qt DLL，不是完整 Qt SDK。
+
+输出：
+
+| 输出 | 说明 |
+| --- | --- |
+| `dist\UpdateClientSDK-With-QtDll` | 带 Qt 运行库 DLL 的 SDK 展开目录 |
+| `dist\UpdateClientSDK-With-QtDll.zip` | 推荐交给 SIMCAE 开发者的 SDK 压缩包 |
+
+## 五、打包后检查
+
+```powershell
+Test-Path .\dist\UpdateClientSDK-With-QtDll\bin\Launcher.exe
+Test-Path .\dist\UpdateClientSDK-With-QtDll\bin\Updater.exe
+Test-Path .\dist\UpdateClientSDK-With-QtDll\bin\Bootstrap.exe
+Test-Path .\dist\UpdateClientSDK-With-QtDll\SIMCAE打包上传.md
+Test-Path .\dist\UpdateClientSDK-With-QtDll.zip
+```
+
+预期都返回 `True`。
+
+## 六、不要提交的内容
+
+当前仓库的 `.gitignore` 已忽略这些本地内容：
+
+- `thirdparty/`
+- `out/`
+- `dist/`
+- `*.exe`
+- `*.dll`
+- `*.zip`
+- `config/app_config.json`
+- `config/client_identity.dat`
+- `config/local_state.json`
+- `config/version_policy.dat`
+
+提交前看一下：
+
+```powershell
+git status --short
+```
+
+不要把本地依赖、编译产物、SDK ZIP、客户配置和运行状态提交进仓库。