feat: 优化客户端跨平台配置和运行态管理

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

@@ -34,8 +34,9 @@ SDK 核心程序：
 
 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 版本混用。
+3. `update-client/Docs` 里的 Markdown 文档会随 SDK 一起打包，是默认接入说明来源。
+4. Word 接入说明是可选增强。如果本地有文件名包含 `SDK` 的 `.docx`，打包脚本会额外复制到 SDK 根目录；如果没有，也不会影响 SDK 打包。
+5. 如果业务软件本身已经带 Qt DLL，通常不要把 SDK 的 Qt 运行库打进去，避免 Qt 版本混用。
 
 在 Windows PowerShell 中执行：
 
@@ -43,7 +44,7 @@ SDK 核心程序：
 cd C:\Users\admin\Desktop\update-client
 
 .\scripts\package-sdk.ps1 `
-  -SourceDir .\out\bin `
+  -SourceDir .\out\bin\Release `
   -OutputDir .\dist\UpdateClientSDK `
   -ZipFile .\dist\UpdateClientSDK.zip `
   -SdkVersion 0.1.0
@@ -54,8 +55,11 @@ cd C:\Users\admin\Desktop\update-client
 ```text
 dist/
   UpdateClientSDK/
-    SimCAE自动升级SDK接入说明_v0.1.docx
     sdk_manifest.json
+    Docs/
+      00-先读我-客户端文档入口.txt
+      01-客户端接入打包部署指南.md
+      02-编译环境和第三方依赖说明.md
     bin/
       Launcher.exe
       Updater.exe
@@ -68,6 +72,7 @@ dist/
       install-sdk.ps1
       package-client.ps1
       package-sdk.ps1
+    SimCAE自动升级SDK接入说明_v0.1.docx   # 可选：只有本地存在 Word 说明时才会出现
   UpdateClientSDK.zip
 ```
 
@@ -98,8 +103,11 @@ Linux SDK 包里核心程序名不带 `.exe`：
 ```text
 dist/
   UpdateClientSDK-linux/
-    SimCAE自动升级SDK接入说明_v0.1.docx
     sdk_manifest.json
+    Docs/
+      00-先读我-客户端文档入口.txt
+      01-客户端接入打包部署指南.md
+      02-编译环境和第三方依赖说明.md
     bin/
       Launcher
       Updater
@@ -115,6 +123,7 @@ dist/
     scripts/
       package-sdk.sh
       package-client.sh
+    SimCAE自动升级SDK接入说明_v0.1.docx   # 可选：只有本地存在 Word 说明时才会出现
   UpdateClientSDK-linux.tar.gz
 ```
 
@@ -196,13 +205,14 @@ D:\SimCAE_SDK\scripts\install-sdk.ps1 `
 
 - `app_config.json` 是部署配置源文件，适合交付、复制、人工修改。
 - `api_base_url` 不再属于 `app_config.json` 字段。它只存在于 `config/server_config.json`，并通过 qrc 编进程序。
+- 交付给你的 SDK 运行包不会包含 `server_config.json` 和 `server_config.qrc`。它们是编译材料，不是运行配置；修改 SDK 包里的文件不会改变已经编译好的 `Launcher.exe`。
 - 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、旧设备身份、旧版本策略或旧防回滚状态；如果安装目录不可写，会弹出管理员权限确认框。
+- 如果检测到 `app_config.json` 确实发生变化，SDK 会同时删除当前用户数据目录里的 `client_identity.dat`、`version_policy.dat` 和 `local_state.json`，避免继续使用旧 License、旧设备身份、旧版本策略或旧防回滚状态；这些运行态文件不再默认写入安装目录。
 - 正常启动成功后，不要删除 `client_identity.dat`、`version_policy.dat`、`local_state.json`。它们分别用于本地设备身份、离线策略和防回滚/防时间倒退，删除后会影响离线启动或导致重新授权。
 - 注册表按安装目录隔离；同一台电脑上多个安装目录不会互相覆盖配置。
 - 注册表位置为 `HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config`。
@@ -343,9 +353,9 @@ 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 管理员权限确认框，用户点击“是”后会继续保存。
+如果安装在 `C:\Program Files\...`、`D:\...` 或其他普通用户不一定可写的目录，SDK 的普通配置值会写入当前用户注册表，不需要修改 `app_config.json`。`client_identity.dat`、`local_state.json`、`version_policy.dat`、更新缓存和 Manifest 缓存也会写入当前用户数据目录，不再默认写到安装目录。
 
-注意：这次提权主要覆盖小型配置/状态文件的写入和删除。更新缓存、离线包暂存、升级替换 EXE/DLL 等大文件操作仍建议放在可写目录；如果最终产品必须完整安装到 `C:\Program Files\SimCAE\bin` 并在普通用户下自动升级，后续建议把运行时状态迁移到 `ProgramData` / `AppData`，或让 Updater/Bootstrap 在替换安装目录文件时走管理员权限。
+Windows 用户数据目录类似：`%LOCALAPPDATA%\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\`。因此日常启动、首次授权、保存设备身份、保存策略、防回滚状态和下载缓存不应再触发管理员权限确认框。只有真正要替换安装目录里的 EXE/DLL 等程序文件时，才需要保证安装目录可写，或让安装器/Updater 具备相应权限。
 
 ## 八、维护者：生成某个产品的最终客户端包
 
@@ -357,7 +367,7 @@ SDK 是给接入方开发使用的。最终给用户安装或分发时，可以
 cd C:\Users\admin\Desktop\update-client
 
 .\scripts\package-client.ps1 `
-  -SourceDir .\out\bin `
+  -SourceDir .\out\bin\Release `
   -ConfigFile .\config\app_config.json `
   -OutputDir .\dist\UpdateClient `
   -ZipFile .\dist\UpdateClient.zip
@@ -368,7 +378,9 @@ cd C:\Users\admin\Desktop\update-client
 - 配置文件必填字段是否完整。
 - 主程序、Launcher、Updater、Bootstrap 是否存在。
 - 是否混入 Debug DLL、PDB、ILK。
-- 当前版本是否已有签名 Manifest 缓存。
+- 当前版本是否已有签名 Manifest 缓存。脚本会优先从当前用户数据目录读取：
+  `%LOCALAPPDATA%\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\update\manifest_cache`。
+  同时兼容旧版 Release 目录里的 `update\manifest_cache`。
 - 是否存在重复主程序。
 
 生成结果：
@@ -396,7 +408,10 @@ Linux 打包脚本会检查：
 - `app_config.json` 必填字段是否完整。
 - 主程序、Launcher、Updater、Bootstrap 是否存在。
 - 是否混入 Debug 产物。
-- 当前版本是否已有签名 Manifest 缓存。
+- 当前版本是否已有签名 Manifest 缓存。脚本会优先从当前用户数据目录读取：
+  `$XDG_DATA_HOME/Marsco/UpdateClientSDK/installations/<安装目录SHA256>/update/manifest_cache`，
+  未设置 `XDG_DATA_HOME` 时通常是 `~/.local/share/Marsco/UpdateClientSDK/installations/<安装目录SHA256>/update/manifest_cache`。
+  同时兼容旧版 Release 目录里的 `update/manifest_cache`。
 - 是否存在重复主程序。
 
 Linux 下如果程序安装在 `/opt`、`/usr/local` 等普通用户不可写目录，升级器无法像 Windows UAC 那样自动提权修改安装目录。正式部署前建议二选一：