chore: 更新客户端和服务端子模块交付状态

项目总览.md

@@ -2,6 +2,8 @@
 
 本文档用于总览当前项目的目标、已实现能力、主要目录、交付物和后续注意事项。适合在提交代码、交接项目或给他人快速了解项目时阅读。
 
+如果只想快速判断“现在能交付什么、还要注意什么”，先看根目录的 `项目交付状态一页纸.md`。
+
 ## 一、项目整体是什么
 
 本项目是一套面向 Windows/Linux 客户端软件的自动升级与版本控制系统，并补充实现了 SimCAE 崩溃报告后端接口。
@@ -69,7 +71,7 @@ MainApp.exe / MainApp        当前仓库内的示例业务程序
 - 升级后健康检查 `--health-file`，业务程序启动成功后写入 `ok`。
 - 升级失败回滚。
 - 升级日志和下载日志上报服务端。
-- `update-server/legacy/admin.html` 管理后台布局已优化，升级日志和下载日志默认折叠。
+- Launcher / Updater / Bootstrap 已支持 Windows 和 Linux Qt 跨平台编译。
 
 ## 三、客户端 SDK 交付状态
 
@@ -94,20 +96,27 @@ update-client/Docs/02-编译环境和第三方依赖说明.md
 
 ```text
 UpdateClientSDK/
-  SimCAE自动升级SDK接入说明_v0.1.docx
   sdk_manifest.json
+  Docs/
+    00-先读我-客户端文档入口.txt
+    01-客户端接入打包部署指南.md
+    02-编译环境和第三方依赖说明.md
   bin/
   config/
     app_config.json
     manifest_public_key.pem
+  Common/
+    ConfigHelper.h/.cpp
+    TicketHelper.h/.cpp
   scripts/
+  SimCAE自动升级SDK接入说明_v0.1.docx   可选，本地存在时才会随包复制
 ```
 
-为了降低接入方理解成本，SDK 根目录只保留一个 Word 说明文档作为入口。
+为了降低接入方理解成本，SDK 包内默认带 `Docs/00-先读我-客户端文档入口.txt`。Word 接入说明是可选增强，`.docx` 不进 Git；fresh clone 没有 Word 时也能打包 SDK。
 
 Linux 当前已完成 Qt 跨平台编译、Linux SDK 打包脚本、Linux 最终客户端打包脚本、Linux 配置模板和部署说明。真实 Linux 版 SimCAE 主程序还未由业务开发方交付，因此真实业务联调暂未完成。
 
-Word 文档已经说明：
+客户端接入文档已经说明：
 
 - 拿到 `UpdateClientSDK.zip` 后怎么操作。
 - 如何复制 SDK 运行时到业务软件 Release 目录。
@@ -127,6 +136,7 @@ Word 文档已经说明：
 - 管理后台前端：使用 GitHub 上的 `pure-admin-thin` / `vue-pure-admin` 生态，技术栈是 `Vue3 + Element Plus + TypeScript + Vite`。
 - 存储组件：元数据使用 SQLite，版本文件和崩溃文件使用 MinIO 对象存储。
 - 当前说明：后端已经完成工程化分层，并已加入用户名/密码登录、Argon2 密码哈希、JWT access/refresh token、RBAC 权限检查和管理员用户管理页面。当前实现是轻量用户体系，后续仍可继续接入 FastAPI Users 等更完整的成熟认证组件。
+- 自动化测试：使用 pytest，测试会创建隔离的临时数据库、临时 Manifest 私钥和临时存储目录，覆盖管理员登录/JWT、License/设备登记、更新检查、发布事务和崩溃报告核心流程。
 
 当前后端已经从早期单文件形态拆成分层结构，主要入口和目录：
 
@@ -140,7 +150,6 @@ update-server/db.py
 update-server/tables.sql
 update-server/minio_tool.py
 update-server/admin-ui/            新版管理后台源码
-update-server/legacy/admin.html           旧版管理后台页面，保留兼容
 ```
 
 服务端文档现在统一放在：
@@ -159,6 +168,7 @@ update-server/Docs/03-后端工程化结构说明.md
 - License 管理。
 - 设备首次登记。
 - 版本发布。
+- 版本发布已支持后台任务模式：浏览器上传完成后，服务端继续在后台校验、入库和上传 MinIO，管理页面轮询任务状态。
 - 版本发布支持两种方式：选择软件发布根目录，或上传压缩好的发布包。管理页面已经拆成“软件根目录/压缩发布包”两个发布方式，避免用户误以为只能选择文件夹。
 - 压缩发布包支持 `zip`、`tar.gz`、`tgz`、`tar.bz2`、`tbz2`、`rar`；服务端会先解压，再按 `RELEASE_MAIN_EXECUTABLE` 校验主程序路径。
 - Manifest 生成和私钥签名。
@@ -335,7 +345,7 @@ SimCAE/
 
 ## 十、运行目录权限说明
 
-当前客户端 SDK 把部署配置源放在 `Launcher.exe` 所在目录下的 `config/app_config.json`，启动时同步到当前 Windows 用户注册表；运行时普通配置值优先读写注册表，路径为 `HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config`。服务端 API 地址 `api_base_url` 是例外：它位于源码 `config/server_config.json`，通过 `config/server_config.qrc` 编译进程序，不再写入 `app_config.json` 或注册表。如果检测到 `app_config.json` 变化，SDK 会删除 `config/client_identity.dat` 和 `config/version_policy.dat`，避免旧授权身份或旧策略继续生效；安装目录不可写时会弹出管理员权限确认框。设备身份、状态、策略、更新事务、备份、暂存文件、下载断点和 Manifest 缓存仍位于 `Launcher.exe` 所在目录下，例如 `config/client_identity.dat`、`config/local_state.json`、`config/version_policy.dat`、`update/` 和 `update_temp/`。当 SDK 放在 `SimCAE/bin` 时，这些运行时文件都在 `SimCAE/bin` 下，不会再在 `SimCAE/` 根目录生成顶层 `update/`。
+当前客户端 SDK 把部署配置源放在 `Launcher.exe` 所在目录下的 `config/app_config.json`，启动时同步到当前用户的 QSettings 配置区；Windows 下对应注册表路径 `HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config`，Linux 下由 Qt QSettings 写入当前用户配置目录。服务端 API 地址 `api_base_url` 是例外：它位于源码 `config/server_config.json`，通过 `config/server_config.qrc` 编译进程序，不再写入 `app_config.json` 或注册表。如果检测到 `app_config.json` 变化，SDK 会删除当前用户数据目录里的 `client_identity.dat`、`version_policy.dat` 和 `local_state.json`，避免旧授权身份、旧策略或旧防回滚状态继续生效。设备身份、状态、策略、更新事务、备份、暂存文件、下载断点和 Manifest 缓存默认位于当前用户数据目录，例如 Windows：`%LOCALAPPDATA%\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\`。当 SDK 放在 `SimCAE/bin` 时，不会再在 `SimCAE/` 根目录生成顶层 `update/`。
 
 如果把软件放在 `C:\Program Files\SimCAE\bin` 并用普通用户启动，普通配置值已经不需要写回 `app_config.json`；但设备身份、状态、策略、更新缓存等文件仍可能需要写安装目录。当前代码对小型状态文件写入已有管理员权限确认；正式要完整安装到 `Program Files` 并自动升级大文件时，后续仍建议补 Windows 服务，或将更多运行时状态迁移到 `ProgramData` / `AppData`。
 
@@ -1072,7 +1082,7 @@ SimCAE Crash Report 第一阶段——已实现。
 5. 对 Manifest、策略、设备身份、离线包做 RSA 签名。
 6. 给客户端签发临时下载 URL。
 7. 接收升级结果、下载结果、设备登记和 License 授权。
-8. 提供新版 admin-ui 管理后台，并保留 legacy/admin.html 作为旧版兼容入口。
+8. 提供新版 admin-ui 管理后台；旧版 admin.html 已在开发阶段移除，不再保留兼容入口。
 9. 接收 SimCAE 崩溃报告和符号包。
 
 服务端主要存储有三类：
@@ -1453,7 +1463,7 @@ Docker 运行时，依赖的是镜像里的 Python、镜像里的依赖、容器
 1. 使用 python:3.12-slim 作为基础镜像。
 2. 安装 update-server/requirements.txt 里的 FastAPI、MinIO、cryptography 等依赖。
 3. 拷贝 main.py、db.py、minio_tool.py、tables.sql。
-4. 拷贝 update-server/legacy/admin.html 到容器内 /app/legacy/admin.html。
+4. 拷贝 admin-ui/dist 管理后台静态文件到容器内 /app/admin-ui/dist。
 5. 使用非 root 用户 updateapp 运行。
 6. 暴露 8000 端口。
 7. 提供 healthcheck。
@@ -1591,7 +1601,7 @@ cd update-client
 
 第五步：补接入方文档和 Demo。
 
-1. SDK 根目录只保留一个 Word 接入说明作为入口，打开包后一眼能看到。
+1. SDK 包内提供 Docs/00-先读我-客户端文档入口.txt 作为默认入口；Word 说明仅作为可选增强。
 2. 准备一个最小 MainApp 示例，演示 --ticket-file 和 --health-file。
 3. 准备一份常见错误说明。
 4. 准备一份服务端 Docker 部署说明。