更新
This commit is contained in:
Your Name
@@ -0,0 +1,158 @@
|
||||
# Windows x64 客户端更新 `can_install=False` 诊断
|
||||
|
||||
## 结论
|
||||
|
||||
“已识别最新版本，但按钮显示「暂不可安装」并提示后台尚未配置安装包”并不等价于只有一种后台配置错误。当前链路把多种拒绝原因压缩为同一个 `UpdateOffer.can_install=False`，而对话框的兜底文案统一归因为“后台未配置”。
|
||||
|
||||
对标准 Windows x64 客户端，最值得按以下顺序检查：
|
||||
|
||||
1. **服务端没有在 `packages.windows_x64` 取到同时非空的 `url` 和 `sha256`。** 最新版本是全局字段，安装包是按平台另行选择，因此完全可能 `has_update=True` 但 `can_install=False`。
|
||||
2. **Windows Inno Setup 包使用了 HTTP（非 localhost）地址，或本机关闭了 HTTPS 证书校验。** 前者会被解析器拒绝；后者会在 UI session 中把一个原本可安装的 offer 二次降级为不可安装。
|
||||
3. **服务端返回了非 64 位十六进制 SHA-256。** 当前 PHP evaluate 只检查 SHA 是否非空，Python 客户端则做严格格式校验，两端判定可能不一致。
|
||||
4. **`package` 结构或 `package.type` 不符合客户端契约。** 客户端只接受对象形式的 `package`，类型只接受 `archive` / `inno_setup`；不过当前第一方 PHP 后端会把未知类型归一为 `archive`，当前管理端也只提供这两个选项，所以这通常只发生在旧服务、手工响应或绕过当前保存链路的配置中。
|
||||
|
||||
如果更新对话框确实已经出现，则单纯的版本、`enabled`、响应平台/架构不匹配通常可以排除：`AppUpdateSession._on_offer()` 在 `offer.has_update=False` 时直接返回，不会展示更新对话框（`app/src/doctor_workstation/ui/dialogs/app_update.py:360-368`）。
|
||||
|
||||
## 端到端链路与证据
|
||||
|
||||
### 1. 客户端发送的身份
|
||||
|
||||
- Windows 被映射为 `windows`（`app/src/doctor_workstation/services/app_update.py:78-83`）。
|
||||
- `AMD64`、`x86_64`、`x64` 都被映射为 `x64`（`app/src/doctor_workstation/services/app_update.py:86-92`）。
|
||||
- 检查请求固定发往 `setting.desktop_workstation/check`，携带 `current_version`、`platform`、`arch`（`app/src/doctor_workstation/services/app_update.py:218-243`）。
|
||||
- `ApiClient` 会解开 `{code, data}` 信封，`code == 1` 时把 `data` 直接交给更新解析器（`app/src/doctor_workstation/services/api_client.py:515-542`）。
|
||||
|
||||
因此标准 64 位 Windows 的请求应为：
|
||||
|
||||
```text
|
||||
GET /adminapi/setting.desktop_workstation/check
|
||||
?current_version=<当前版本>&platform=windows&arch=x64
|
||||
```
|
||||
|
||||
### 2. 服务端先决定是否有对应平台安装包
|
||||
|
||||
- 服务端只声明三个包槽位：`windows_x64`、`macos_arm64`、`macos_x64`（`server/app/adminapi/logic/setting/DesktopWorkstationLogic.php:28-32`）。
|
||||
- `windows`/`win32`/`win64` 会归一为 `windows`，`x64`/`amd64`/`x86_64` 会归一为 `x64`，然后拼成 `windows_x64`（同文件 `:125-153`）。
|
||||
- evaluate 从 `config.packages[windows_x64]` 取包；服务端 `canInstall` 只要求 `url !== '' && sha256 !== ''`（同文件 `:75-86`）。
|
||||
- `hasUpdate` 独立由启用状态和版本比较决定（`:86-88`），响应中只有 `canInstall` 为真才返回 `package`，最终 `can_install = hasUpdate && canInstall`（`:90-103`）。
|
||||
|
||||
这直接解释了核心现象：`latest_version` 配置正确会让客户端看到新版本，但 `packages.windows_x64.url` 或 `packages.windows_x64.sha256` 任一为空，响应仍会是 `has_update: true`、`package: null`、`can_install: false`。
|
||||
|
||||
管理端保存的真实字段是嵌套结构 `packages.windows_x64.{url,sha256,size,filename,type}`（`admin/src/api/setting/desktop_workstation.ts:5-24`、`admin/src/views/setting/desktop_workstation/index.vue:330-344`），而不是把 Windows 包放在 macOS 槽位或任意自定义键下。管理页默认 Windows 类型为 `inno_setup`（Vue 文件 `:198-218`），上传 `.exe` 也会设置为 `inno_setup` 并在浏览器计算 SHA-256（`:292-315`）。
|
||||
|
||||
当前服务端校验允许整行安装包为空：空值/空行会继续通过（`server/app/adminapi/validate/setting/DesktopWorkstationValidate.php:83-110`），所以“自动检测已启用、最新版本有效、Windows 包未完整配置”是被允许保存的状态。外部 URL 缺 SHA 会被拒绝，但站内相对 URL 对应文件不存在且 SHA 为空的情形仍可能保存；服务端只会在本地文件确实存在时自动补 SHA、大小和文件名（`DesktopWorkstationLogic.php:309-331`）。
|
||||
|
||||
### 3. Python 客户端会再做一轮更严格的判定
|
||||
|
||||
`parse_update_offer()` 的规则位于 `app/src/doctor_workstation/services/app_update.py:140-215`：
|
||||
|
||||
- `package` 必须是字典；`url` 必须非空（`:152-167`）。
|
||||
- `type` 缺省为 `archive`，只接受 `archive` / `inno_setup`；`inno_setup` 只允许 Windows（`:158-167`）。
|
||||
- 响应平台、架构必须与请求时的期望值完全一致；同时必须满足服务端 `has_update`、`enabled`、合法且更高的版本（`:175-184`）。
|
||||
- SHA-256 必须恰好 64 个十六进制字符（`:185-189`）。
|
||||
- `inno_setup` URL 必须是 HTTPS，唯一例外是 HTTP localhost/loopback（`:190-194`，具体 URL 规则在 `:371-376`）。
|
||||
- 最终 `can_install` 是服务端 `can_install`、有效 package、有效 SHA、安全安装器传输、`has_update` 五者的合取（`:195-201`）。判失败后返回对象会清除 `package`，并把 `force` 一并降为 false（`:202-215`）。
|
||||
|
||||
因此若原始 API 返回 `can_install: true`，客户端仍可能因以下字段得到 false：
|
||||
|
||||
| 字段/状态 | 拒绝条件 | Windows x64 症状是否吻合 |
|
||||
|---|---|---|
|
||||
| `package` | `null`、数组、字符串等非对象 | 是 |
|
||||
| `package.url` | 空字符串 | 是 |
|
||||
| `package.sha256` | 空、长度不是 64、包含非十六进制字符 | 是 |
|
||||
| `package.type` | 非 `archive` / `inno_setup` | 是，但当前第一方后端通常会归一为 `archive` |
|
||||
| `package.type=inno_setup` + URL | 非 localhost 的 `http://` 或相对 URL | 是 |
|
||||
| `package.filename` | 空或扩展名不匹配 | **不会在 offer 阶段令 `can_install=False`**；可能在下载/应用阶段失败 |
|
||||
| `package.size` | 空、0、不可转整数 | **不会在 offer 阶段令 `can_install=False`**；解析为 0 |
|
||||
| 缺少 `package.type` | 默认 `archive` | **不会单独导致 false**；EXE 被误当 archive 会在稍后解压失败 |
|
||||
|
||||
一个重要的不一致是：PHP evaluate 目前只检查 SHA 非空（`DesktopWorkstationLogic.php:85`），Python 检查完整格式（`app_update.py:185-189`）。管理端正常保存会校验 64 位十六进制（`DesktopWorkstationValidate.php:147-151`），但旧数据、直接写配置或绕过校验的导入仍可能造成“后端说可安装、客户端说不可安装”。
|
||||
|
||||
### 4. UI session 还会因本机 TLS 设置二次降级
|
||||
|
||||
即使 `fetch_update_offer()` 返回的 Inno Setup offer 已经 `can_install=True`，`AppUpdateSession._on_offer()` 仍会以本机 `config.verify_ssl` 调用安装器下载策略；失败时把 `force=False`、`package=None`、`can_install=False`（`app/src/doctor_workstation/ui/dialogs/app_update.py:371-392`）。
|
||||
|
||||
本机配置默认 `verify_ssl=True`（`app/src/doctor_workstation/config.py:88-97`、`:124-130`），但登录页勾选“信任自签名证书（仅内网调试）”会把它反转为 false（`app/src/doctor_workstation/ui/login.py:831-844`、`:937-944`、`:1041-1053`）。`validate_installer_download_policy()` 明确拒绝 `verify_ssl=False`，也拒绝非安全的 Inno Setup URL（`app/src/doctor_workstation/services/app_update.py:379-385`）。
|
||||
|
||||
这是最容易被误判为“后台没包”的非后台原因。诊断时应比较两个时点：
|
||||
|
||||
1. `fetch_update_offer()` 刚返回时是否 `can_install=True`；
|
||||
2. `_on_offer()` 传给 `_present()` 时是否已经变成 false。
|
||||
|
||||
若只有第 2 个时点为 false，按当前代码唯一的正常降级入口就是 Inno Setup 下载策略，优先检查 `verify_ssl`。
|
||||
|
||||
审阅时工作树中已存在一项并非本文创建的未提交改善：`UpdateOffer` 增加 `install_unavailable_reason`，TLS 策略降级时生成具体原因，对话框优先展示该原因（`app_update.py` service `:53-67`；UI `:200-206`、`:379-391`）。兜底文案仍用于服务端/解析阶段没有原因的 `can_install=False`，所以根因判别和补测仍有必要。
|
||||
|
||||
### 5. 为什么平台或版本通常不是这个弹窗的根因
|
||||
|
||||
- 客户端要求响应 `platform`/`arch` 与请求期望值精确相等，错配会让 `has_update=False`（`app_update.py:175-184`）。
|
||||
- session 对 `has_update=False` 直接显示“当前已是最新版本”或静默返回，不创建更新对话框（UI `:360-368`）。
|
||||
- 当前第一方后端会把 Windows/x64 常见别名归一为响应中的 `windows`/`x64`（`DesktopWorkstationLogic.php:125-153`）。
|
||||
|
||||
所以对于已经出现该对话框的标准 Windows x64 客户端，优先查 `packages.windows_x64`，而不是先怀疑 `AMD64` 与 `x64` 名称差异。例外是非标准/旧后端没有按当前契约归一，或实际机器是 Windows ARM64；服务端没有 `windows_arm64` 包槽位，后者会天然没有对应包。
|
||||
|
||||
同理，`enabled=false`、最新版本无效、当前版本不低于最新版本都会使 `has_update=False`，与“更新弹窗出现但不可安装”不吻合。源码运行也不是该兜底文案的成因：源码模式只会取消强制属性，点击安装后才显示“当前为源码运行”（UI `:393-394`、`:401-410`）。
|
||||
|
||||
## 最短现场排查路径
|
||||
|
||||
1. 用发生问题的当前版本请求实际 API，并保留解包后的 `data`：
|
||||
|
||||
```text
|
||||
/adminapi/setting.desktop_workstation/check?current_version=<version>&platform=windows&arch=x64
|
||||
```
|
||||
|
||||
2. 若响应已经是 `can_install:false` 且 `package:null`，读取管理端配置并核对 `packages.windows_x64.url` 与 `.sha256` 是否同时非空；确认包没有误填到 `macos_x64`，也没有只保存最新版本而未保存包。
|
||||
3. 若响应是 `can_install:true`，核对 `package` 是否为对象、SHA 是否 64 位十六进制、`type` 是否精确为 `archive` 或 `inno_setup`。若为 Inno Setup，URL 应为 HTTPS。
|
||||
4. 若解析后 offer 为 true、弹窗前变成 false，检查客户端 `preferences.json` 中的 `verify_ssl`，以及登录页“信任自签名证书”是否被勾选。
|
||||
5. 对 Windows 安装程序，期望响应至少应类似：
|
||||
|
||||
```json
|
||||
{
|
||||
"has_update": true,
|
||||
"enabled": true,
|
||||
"platform": "windows",
|
||||
"arch": "x64",
|
||||
"can_install": true,
|
||||
"package": {
|
||||
"url": "https://cdn.example.com/DoctorWorkstation-Setup-Windows-x64-0.2.0.exe",
|
||||
"sha256": "<64 lowercase hex chars>",
|
||||
"size": 123456789,
|
||||
"filename": "DoctorWorkstation-Setup-Windows-x64-0.2.0.exe",
|
||||
"type": "inno_setup"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 现有测试覆盖与缺口
|
||||
|
||||
已有客户端测试覆盖：
|
||||
|
||||
- 缺 SHA 会拒绝安装（`app/tests/test_app_update.py:43-63`）。
|
||||
- 合法 HTTPS Inno Setup 会接受（`:66-89`）。
|
||||
- HTTP Inno Setup 会拒绝（`:92-115`）。
|
||||
- 未知类型会拒绝（`:118-139`）。
|
||||
- 旧版本/错误平台响应不会成为 update（`:142-163`）。
|
||||
- 检查接口会发送 `platform=windows`、`arch=x64`（`:166-208`）。
|
||||
- UI 的可选/强制升级基本行为，以及“给定 policy reason 时展示该 reason”（`app/tests/test_app_update_ui.py:49-96`）。
|
||||
|
||||
已有 PHP 契约测试覆盖 `win32 + amd64 -> windows_x64`，以及完整 Windows Inno 包可安装（`server/tests/DesktopWorkstationUpdateContractTest.php:17-62`）；缺包测试只覆盖 macOS 槽位（`:74-77`）。
|
||||
|
||||
建议新增以下测试：
|
||||
|
||||
1. **Windows x64 服务端缺字段矩阵（最高优先级）**：分别让 `packages.windows_x64.url` 为空、`sha256` 为空、整个键缺失；断言 `has_update=true`、`package=null`、`can_install=false`。这会直接固化本次症状。
|
||||
2. **服务端/客户端 SHA 契约一致性**：给 evaluate 一个“非空但不是 64 位十六进制”的 SHA。期望服务端也返回不可安装，或至少用共享 fixture 明确当前由客户端拒绝；避免两端一个 true、一个 false。
|
||||
3. **`AppUpdateSession` TLS 二次降级**：构造合法 HTTPS `inno_setup` offer，分别设置 `verify_ssl=True/False`，截获 `_present()`；true 时保持可安装，false 时断言 `can_install=False` 且原因明确指向证书策略而非后台缺包。
|
||||
4. **UI 兜底分支**：构造 `can_install=False` 且无 reason 的 offer，断言按钮禁用并展示后台/平台包缺失文案；与已有“注入 policy reason”的测试形成两条独立路径。
|
||||
5. **解析字段矩阵**：补充 `package=null`、非对象、空 URL、63 位 SHA、含非 hex SHA、缺少 type 默认 archive、Windows archive 使用 HTTP 仍可解析等边界测试。现有测试覆盖了部分，但没有把每个判定条件与原因一一锁定。
|
||||
6. **跨层契约 fixture**：把 PHP `check` 的 Windows x64 JSON 响应作为 Python `parse_update_offer()` 输入，验证 canonical `windows/x64`、包类型、SHA 和 `can_install` 不发生语义漂移。
|
||||
7. **管理端 payload 测试**：确认保存时始终发送 `packages.windows_x64` 嵌套对象，上传 `.exe` 后 `type=inno_setup` 且 URL、SHA、文件名、大小均落在同一槽位。
|
||||
|
||||
长期看，最稳妥的可观测性是让 `can_install=False` 同时带结构化原因（例如 `missing_package`、`invalid_digest`、`unsupported_type`、`insecure_installer_url`、`tls_verification_disabled`），并在客户端保留原因而不是立即清除所有包信息。这样 UI 不必用一个“后台未配置”文案覆盖所有安全门禁。
|
||||
|
||||
## 验证记录
|
||||
|
||||
- 根目录 `.trellis/` 不存在；本次按根 `AGENTS.md` 执行，只读检查生产代码，仅新增本文档。
|
||||
- `app/.venv/Scripts/python.exe -m pytest tests/test_app_update.py tests/test_app_update_ui.py -q`：通过。
|
||||
- 收集结果：`test_app_update.py` 21 项、`test_app_update_ui.py` 3 项，共 24 项。
|
||||
- `php tests/DesktopWorkstationUpdateContractTest.php`（工作目录 `server/`）：`Desktop workstation update contract: OK`。
|
||||
|
||||
@@ -0,0 +1,171 @@
|
||||
# DEBUG_MODE 与线上 API 固定策略分析
|
||||
|
||||
## 结论
|
||||
|
||||
当前启动配置不是单一的“环境变量 -> `AppConfig`”链路，而是四层覆盖：
|
||||
|
||||
1. `python-dotenv` 先加载 `.env`，且 `override=False`，所以进程环境变量优先于 `.env`（`app/src/doctor_workstation/config.py:113-118`）。
|
||||
2. `DOCTOR_API_BASE_URL` 被规范化并传入 `AppConfig`（`config.py:118-132`）。
|
||||
3. 用户目录中的 `preferences.json` 再覆盖环境配置，因此当前实际上是 `进程环境/.env < preferences.json`（`config.py:133-153`）。
|
||||
4. 登录页另有一套 Qt `QSettings`：`server/base_url` 会覆盖已经合并好的 `config.api_base_url`，保存或正式登录时再通过 `config_changed` 写回 `AppConfig`，控制器随后保存 `preferences.json` 并重建远端仓库（`app/src/doctor_workstation/ui/login.py:917-927, 1026-1054, 1067-1077, 1079-1103`；`app/src/doctor_workstation/app.py:438-504`）。
|
||||
|
||||
所以，只在 `AppConfig.load()` 里把环境变量替换成线上域名是不完整的。`DEBUG_MODE=False` 时必须同时封住：
|
||||
|
||||
- 环境变量 / `.env`；
|
||||
- `preferences.json`；
|
||||
- Qt `QSettings` 的 `server/base_url`；
|
||||
- 登录页运行期 `with_updates(api_base_url=...)`。
|
||||
|
||||
建议目标契约为：
|
||||
|
||||
| 模式 | 最终 `AppConfig.api_base_url` | 本地地址设置 |
|
||||
| --- | --- | --- |
|
||||
| `DEBUG_MODE=False` | 始终为 `https://admin.zhenyangtang.com.cn/adminapi` | 环境、JSON preference、Qt `QSettings`、登录页编辑均不得改变 |
|
||||
| `DEBUG_MODE=True` | 保留当前规则：环境/.env 初始化，`preferences.json` 覆盖，登录页可再次编辑 | 完全保留现有可配置行为 |
|
||||
|
||||
仓库内线上地址最直接的证据是 `admin/.env.production:1-3`，生产管理端使用 `https://admin.zhenyangtang.com.cn/`；`admin/vite.config.ts:54-64` 的开发代理也指向同一主机。桌面端的 `normalize_api_base_url()` 会追加 `/adminapi`（`config.py:67-85`），因此建议常量保存主机根地址，最终有效地址由同一个规范化函数产生。`TongjiUniApp/main.js:3` 当前使用的是 `https://xt.zhenyangtang.com.cn/`，它属于另一客户端，不能替代管理 API 地址。
|
||||
|
||||
## 精确修改建议
|
||||
|
||||
### 1. 包级发布策略常量
|
||||
|
||||
在 `app/src/doctor_workstation/__init__.py:1-6` 添加两个普通源码常量，并更新 `__all__`。当前该文件已有未提交的版本升级 `1.1.0 -> 1.2.0`，实现时必须保留它，只做增量编辑。
|
||||
|
||||
建议名称和取值：
|
||||
|
||||
```python
|
||||
DEBUG_MODE = False
|
||||
ONLINE_API_BASE_URL = "https://admin.zhenyangtang.com.cn"
|
||||
|
||||
__all__ = ["__version__", "DEBUG_MODE", "ONLINE_API_BASE_URL"]
|
||||
```
|
||||
|
||||
`DEBUG_MODE` 不应来自 `DOCTOR_DEBUG_MODE` 或其他环境变量，否则已安装程序仍可被本地环境切回调试地址，直接违反需求。它应是发布代码/构建产物内的策略开关。线上常量不要带查询参数、凭据或 fragment；是否在常量里带 `/adminapi` 均可，但建议只放域名根地址，让 `normalize_api_base_url()` 保持路径的唯一规范化入口。
|
||||
|
||||
`config.py` 从包根导入这两个常量不会形成循环：包 `__init__.py` 不导入 `config.py`；现有 `services/app_update.py:21` 也已经用相同方式从包根导入 `__version__`。
|
||||
|
||||
### 2. 在 AppConfig 的两个入口执行同一发布策略
|
||||
|
||||
涉及 `app/src/doctor_workstation/config.py:17-30, 67-85, 113-153, 167-176`。
|
||||
|
||||
建议在 `normalize_api_base_url()` 之后增加一个小型策略函数（名称可调整）：
|
||||
|
||||
```python
|
||||
def effective_api_base_url(candidate: str) -> str:
|
||||
if not DEBUG_MODE:
|
||||
# 源码常量无效属于发布错误，应显式失败，不要静默退回空地址。
|
||||
return normalize_api_base_url(ONLINE_API_BASE_URL)
|
||||
try:
|
||||
return normalize_api_base_url(candidate)
|
||||
except ValueError:
|
||||
return ""
|
||||
```
|
||||
|
||||
然后在两个入口复用：
|
||||
|
||||
1. `AppConfig.load()` 的 `api_url` 必须由该函数生成。这样进程环境和 `.env` 在 release 模式下即使含 `http://127.0.0.1` 也只会被读取而不会成为有效 API 地址。
|
||||
2. `_merge_preferences()` 在 `DEBUG_MODE=False` 时必须忽略 JSON 中的 `api_base_url`；也可以允许读取后在 `replace()` 前强制写回 `effective_api_base_url(...)`。关键是**发布策略必须在 preference 合并之后生效**。
|
||||
3. `with_updates()` 在 `DEBUG_MODE=False` 时必须把任何传入的 `api_base_url` 强制改为线上值，而不是仅做 URL 规范化。登录页运行期正是通过此入口更新配置。
|
||||
|
||||
实现上可选择“每个入口调用 `effective_api_base_url()`”，也可选择一个 `_apply_runtime_policy()` 在 `_merge_preferences()` 和 `with_updates()` 的 `replace()` 之后统一执行。后者更不容易遗漏，但需要保证两条返回路径都调用它。
|
||||
|
||||
不建议用 `AppConfig.__post_init__()` 强制改写所有直接构造的实例。仓库中大量单元/UI 测试直接构造带 `.test` 域名的 `AppConfig`（例如 `app/tests/test_ui_contract.py:408-412`）；发布要求针对真实运行配置入口，没必要破坏依赖注入式测试。若希望更强的防御，可提供显式 `apply_runtime_policy()`，由 `load()`、`with_updates()` 和控制器接收外部 `AppConfig` 时调用。
|
||||
|
||||
### 3. 封住 Qt QSettings 的第二套本地 preference
|
||||
|
||||
涉及 `app/src/doctor_workstation/ui/login.py:451-468, 788-851, 917-950, 956-969, 1026-1054`。
|
||||
|
||||
这是满足“本地 preference 不应把它改回调试地址”的必需修改，不是纯 UI 优化：
|
||||
|
||||
- `_restore_settings()`：`DEBUG_MODE=False` 时，`server_url_edit` 只能显示 `config.api_base_url`，不得读取 `self.settings.value("server/base_url", ...)`；`DEBUG_MODE=True` 时保持现有读取逻辑。
|
||||
- `_apply_server_settings()`：`DEBUG_MODE=False` 时使用 `config.api_base_url` 作为 `base_url`，不得信任编辑框或旧 QSettings；也不要把旧调试地址重新写入 `server/base_url`。`DEBUG_MODE=True` 时保持现状。
|
||||
- 发布模式下至少将 `server_url_edit` 设为只读。也可隐藏地址编辑入口，但不要无意中一起删除超时设置；是否同时禁止“信任自签名证书”属于另一项发布安全策略。
|
||||
- `_credential_scope()` 当前优先使用地址编辑框（`login.py:956-969`）。因此必须先确保发布模式下编辑框显示线上地址，否则实际请求虽已被 `with_updates()` 锁到线上，密码却可能错误地按旧调试地址做凭据 scope，造成跨环境凭据恢复混乱。
|
||||
|
||||
不建议启动时删除旧的 `server/base_url` QSettings。发布模式忽略它即可，这样将来显式切到 `DEBUG_MODE=True` 时仍能保留既有调试配置，也避免无必要的数据清理。
|
||||
|
||||
### 4. bootstrap / repository 侧无需另建域名来源
|
||||
|
||||
实际启动入口是 `app/src/doctor_workstation/__main__.py:5-19 -> app.py:1166-1182`。`main()` 只调用一次 `AppConfig.load()`，随后 `ApplicationController.__init__()` 立即执行 `_rebuild_remote_repository()`（`app.py:402-424`）；后者把 `self.config.api_base_url` 原样传给 `build_repository()`（`app.py:513-525`），再由 `ApiClient` 规范化为带结尾斜杠的 `/adminapi/` 地址（`services/factory.py:13-45`；`services/api_client.py:133-148`）。
|
||||
|
||||
因此 `app.py`、`factory.py`、`api_client.py` 不应复制线上域名常量。只要 `AppConfig` 在完成所有合并后保持不变量，这一段无需修改。
|
||||
|
||||
可选的纵深防御：`ApplicationController._on_config_changed()` 在收到一个完整 `AppConfig` payload 时目前直接接受（`app.py:460-489`），只有 dict payload 才经过 `self.config.with_updates()`。若未来可能有第二个发信者，建议让完整 `AppConfig` 同样经过显式 runtime policy；当前唯一连接来自 `LoginWindow`（`app.py:447`），且其正常路径会先调用 `with_updates()`，所以这不是本次最小改动的阻塞项。
|
||||
|
||||
## 当前覆盖顺序与修改后顺序
|
||||
|
||||
当前：
|
||||
|
||||
```text
|
||||
.env --(override=False)--> os.environ
|
||||
|
|
||||
v
|
||||
AppConfig(env)
|
||||
|
|
||||
v
|
||||
preferences.json 覆盖 env
|
||||
|
|
||||
v
|
||||
LoginWindow 的 QSettings/server/base_url 覆盖 config
|
||||
|
|
||||
v
|
||||
with_updates -> save_preferences -> rebuild repository
|
||||
```
|
||||
|
||||
建议修改后：
|
||||
|
||||
```text
|
||||
DEBUG_MODE=True : 保持上面的完整可配置链路
|
||||
|
||||
DEBUG_MODE=False:
|
||||
env/.env ----------- ignored for api_base_url ---+
|
||||
preferences.json --- ignored for api_base_url ---+--> ONLINE_API_BASE_URL
|
||||
QSettings ---------- ignored for api_base_url ---+ |
|
||||
runtime update ------ clamped for api_base_url ---+ v
|
||||
build_repository
|
||||
```
|
||||
|
||||
## 兼容风险与边界
|
||||
|
||||
1. **Demo 模式仍可覆盖“是否使用远端仓库”。** 当前 `demo_mode` 默认 `True`，且仍可被环境和 `preferences.json` 覆盖（`config.py:93, 126, 140-153`）；登录页也会保存它（`login.py:1002-1006`）。本需求只要求固定 API 域名，所以不应顺手强制 `demo_mode=False`。如果产品语义其实是“发布版必须始终连接线上、不能进入 Demo”，需要单独明确并给 `demo_mode` 增加相同发布策略。
|
||||
2. **TLS 校验仍可被本地 preference 关闭。** `verify_ssl` 当前可由环境、JSON preference 和 QSettings 改为 `False`（`config.py:129, 151-152, 174-175`；`login.py:937-944, 1038-1048`）。固定线上域名但允许关闭证书校验仍有中间人风险。建议产品确认是否在 `DEBUG_MODE=False` 时也强制 `verify_ssl=True`，但它超出“域名不可改”的最小范围。
|
||||
3. **调试启动脚本不会自动打开源码 DEBUG_MODE。** `app/Debug_DoctorWorkstation.bat:16-23` 只设置独立配置目录、Demo 和日志级别，没有能力改变源码布尔常量。若常量提交为 `False`，脚本仍能跑 Demo，但不能用本地 URL。不要为方便而从环境读取 `DEBUG_MODE`；更安全的方案是开发者本地改为 `True`（不提交），或由明确区分的 debug 构建生成非发布模块。
|
||||
4. **已有 preference 不需要迁移或删除。** 发布模式会忽略旧调试 URL；切回 debug 后仍按现有优先级恢复。`save_preferences()` 当前把完整 dataclass 写入 JSON（`config.py:155-165`），发布运行后可能把线上 URL写回文件，这是可接受的，但测试应覆盖“旧文件存在时首次启动仍直接得到线上 URL”。
|
||||
5. **凭据按 URL scope 隔离。** `LoginWindow._credential_scope()` 和 `TokenStore` 使用 API scope。切到线上后旧调试 token/password 不应被用于线上，这是正确行为；但若只锁 `AppConfig` 而不锁登录页 QSettings，可能出现“请求发往线上、密码却按调试 URL scope 保存/恢复”的错配，因此第 3 节不能省略。
|
||||
6. **构建 smoke 环境目前注入 loopback API。** Windows/macOS 构建与安装 smoke 分别在 `app/scripts/build_windows.ps1:28-47`、`build_macos.sh:105-123`、`smoke_windows_installer.ps1:101-109` 注入 `https://127.0.0.1:9`。发布策略生效后该变量会被忽略。正常 smoke 不应访问线上：更新检查被 `DOCTOR_SMOKE_TEST`/`--smoke-test` 阻断（`ui/dialogs/app_update.py:332-340`），且这些脚本设置 `DOCTOR_DEMO_MODE=true`，会阻断 session restore（`app.py:530-540`）。仍建议增加“smoke 期间没有发起线上请求”的断言，避免未来启动流程变化造成生产流量。
|
||||
7. **不要把线上常量的错误静默转为空地址。** 调试环境输入无效时保持当前的空地址降级合理；源码内线上常量无效则应让测试/构建立即失败，否则发布包只会落入 `_UnconfiguredRepository`（`app.py:435-436, 513-525`），错误会拖到登录时才暴露。
|
||||
8. **版本读取兼容。** PyInstaller spec 用正则只读取 `__version__` 行（`app/packaging/doctor_workstation.spec:27-37`）。只要保留当前独立的 `__version__ = "1.2.0"` 赋值，新增常量与 `__all__` 不影响版本生成。
|
||||
|
||||
## 建议测试
|
||||
|
||||
优先在 `app/tests/test_config.py` 增加以下矩阵：
|
||||
|
||||
1. `DEBUG_MODE=False`，环境 `DOCTOR_API_BASE_URL=http://127.0.0.1:8000`，无 preference：`AppConfig.load().api_base_url == "https://admin.zhenyangtang.com.cn/adminapi"`。
|
||||
2. `DEBUG_MODE=False`，环境为线上、`preferences.json` 保存调试 URL：最终仍为线上。
|
||||
3. `DEBUG_MODE=False`，先 `AppConfig.load()`，再 `with_updates(api_base_url="http://localhost:8000")`：最终仍为线上。
|
||||
4. `DEBUG_MODE=True`，环境提供 A、preference 提供 B：最终仍为 B，证明现有“preference 覆盖 env”行为未回归。
|
||||
5. `DEBUG_MODE=True`，无 preference，仅环境提供 URL：继续规范化并自动追加 `/adminapi`。
|
||||
6. 将 `ONLINE_API_BASE_URL` 临时 monkeypatch 为非法值且 `DEBUG_MODE=False`：应显式抛错，避免发布误配置静默降级。
|
||||
|
||||
在 `app/tests/test_ui_contract.py` 增加：
|
||||
|
||||
1. 发布模式的 QSettings 预置 `server/base_url=http://127.0.0.1:8000`，创建 `LoginWindow` 后地址框显示线上 URL且不可编辑。
|
||||
2. 发布模式调用 `_save_server_settings()` / 非 Demo `submit()`，`config_changed` payload 的 `api_base_url` 仍为线上，远端仓库不会以 QSettings 地址重建。
|
||||
3. 上述场景下 `_credential_scope()` 返回线上 scope，防止凭据落在旧调试 scope。
|
||||
4. `DEBUG_MODE=True` 重跑同类场景，确认地址框仍从 QSettings 恢复、保存后仍能切换服务器。
|
||||
|
||||
在 bootstrap/构建层增加或保留以下回归：
|
||||
|
||||
1. `ApplicationController` 用 `AppConfig.load()` 启动时，传给 `build_repository()` 的 release base URL 精确为 `https://admin.zhenyangtang.com.cn/adminapi`。
|
||||
2. `--smoke-test` 和 `DOCTOR_SMOKE_TEST=1` 下，无论 release URL 是否存在，都不执行更新请求或 token restore 网络调用。
|
||||
3. 冻结包 smoke 继续通过；原 smoke 脚本中的 loopback `DOCTOR_API_BASE_URL` 被忽略是预期行为，不应把断言写成“最终 URL 等于 127.0.0.1”。
|
||||
|
||||
建议验证命令：
|
||||
|
||||
```powershell
|
||||
Set-Location D:\web\zyt\app
|
||||
uv run pytest tests/test_config.py tests/test_ui_contract.py -q
|
||||
uv run ruff check src/doctor_workstation/__init__.py src/doctor_workstation/config.py src/doctor_workstation/ui/login.py tests/test_config.py tests/test_ui_contract.py
|
||||
```
|
||||
|
||||
若还修改了 bootstrap 防御或 smoke 契约，再运行相关完整测试和冻结构建门禁；仅本分析任务未修改生产代码、也未执行会连接线上环境的测试。
|
||||
@@ -0,0 +1,143 @@
|
||||
# 登录页 DEBUG_MODE 门禁分析
|
||||
|
||||
## 结论
|
||||
|
||||
当前实现不存在 `DEBUG_MODE`（项目内唯一含 `debug_mode` 的命中只是一个测试函数名）。登录页始终创建并展示“演示模式”和“服务器设置”入口；`AppConfig.demo_mode` 默认又是 `True`，且 `preferences.json` 会覆盖环境配置。因此，仅对两个控件调用 `hide()` 不能满足目标：隐藏的 checkbox 仍可能保持 checked，普通登录仍会自动读取/写回残留 `QSettings`，控制器也会接受伪造或残留的 demo 状态。
|
||||
|
||||
建议把 `DEBUG_MODE` 设计成**非用户偏好、不可由 `QSettings` 或 `preferences.json` 覆盖的单一运行时门禁**，并在配置加载、LoginWindow 行为和 ApplicationController 三层同时收口：
|
||||
|
||||
- `DEBUG_MODE=True`：显示且允许演示仓库切换和登录页服务器设置，保留现有调试行为。
|
||||
- `DEBUG_MODE=False`：隐藏完整 UI 区块，强制 effective demo 为 `False`，忽略残留服务器 QSettings，登录只能使用 composition root 提供的远程仓库；直接调用槽函数、设置隐藏 checkbox、发信号或构造 demo payload 也不能绕过。
|
||||
|
||||
`demo_mode` 只能表示 DEBUG 模式下的默认选择/当前选择，不能再充当“是否有权使用 demo”的授权位。
|
||||
|
||||
## 当前实现与风险点
|
||||
|
||||
### 1. 配置与持久化
|
||||
|
||||
| 位置 | 当前行为 | DEBUG_MODE=False 的风险 |
|
||||
| --- | --- | --- |
|
||||
| `src/doctor_workstation/config.py:88-99` | `AppConfig.demo_mode` 默认 `True`，没有 debug gate | 直接构造 `AppConfig()` 就默认允许 demo |
|
||||
| `config.py:113-133` | `DOCTOR_DEMO_MODE` 未设置时也按 `True` 加载，然后调用 `_merge_preferences()` | 生产未显式注入环境变量时默认 demo；即使环境设为 false，后续偏好仍可覆盖 |
|
||||
| `config.py:135-153` | `preferences.json` 中所有 dataclass 字段均会合并，包括 `demo_mode`、`api_base_url`、`request_timeout`、`verify_ssl` | 旧 debug profile 的 demo/server 值可覆盖本次受控配置 |
|
||||
| `config.py:155-165` | `save_preferences()` 用 `asdict(self)` 保存完整配置 | demo 切换和服务器设置会持续残留在 JSON 中 |
|
||||
| `config.py:167-176` | `with_updates()` 可随时把 demo/服务器字段改回调试值 | UI 隐藏后仍可从信号/直接调用修改 |
|
||||
|
||||
需要特别区分两套持久化：demo 当前**不写 QSettings**，它通过 `config_changed -> ApplicationController._on_config_changed -> save_preferences()` 写入 `preferences.json`；服务器地址、超时和证书校验先写 `QSettings`，随后同一信号链又写入 `preferences.json`。相关位置是 `ui/login.py:1038-1054` 和 `app.py:460-491`。
|
||||
|
||||
当前 `Debug_DoctorWorkstation.bat:16-24` 只是设置 `DOCTOR_DEMO_MODE=true` 和 `DOCTOR_LOG_LEVEL=DEBUG`，没有提供独立 debug capability。若新门禁来自环境，调试启动器应显式设置专用值（例如 `DOCTOR_DEBUG_MODE=true`）；普通/冻结启动不得设置。若门禁是构建期常量，则无需让用户偏好或 `.env` 参与。无论采用哪种来源，都不要把它作为普通 `AppConfig` dataclass 字段写入 `preferences.json`。
|
||||
|
||||
### 2. LoginWindow 组件和信号
|
||||
|
||||
| 位置 | 组件/信号链 | 当前行为与缺口 |
|
||||
| --- | --- | --- |
|
||||
| `ui/login.py:444-449` | `server_settings_changed(dict)`、`config_changed(object)`、`demo_mode_changed(bool)` | `server_settings_changed` 目前仅测试监听；另外两个信号由 controller 监听。所有发射点都无 debug gate |
|
||||
| `login.py:451-468` | 构造参数、`demo_repository`、`active_repository` | 只要传入 demo repository 就保留可切换能力；controller 当前总会传入 |
|
||||
| `login.py:739-755` | “记住密码”行和 `demo_check` | checkbox 始终加入布局；只有 repository 为空时 disabled，不会隐藏 |
|
||||
| `login.py:770-855` | “或”分隔线、`server_toggle`、`server_panel` 及 URL/timeout/self-signed/save 子控件 | toggle 始终显示，panel 只是在初始时折叠。若只隐藏 toggle，“或”分隔线和固定 spacing 仍会残留 |
|
||||
| `login.py:917-948` | `_restore_settings()` | 始终从 QSettings 恢复三项 server 值；只看 `config.demo_mode` 就勾选 demo。`setChecked(True)` 会触发已连接的 `_on_demo_toggled()` |
|
||||
| `login.py:956-969` | `_credential_scope()` | 优先读取 `server_url_edit`；即便控件隐藏，残留 QSettings URL 仍可改变凭据读取/保存 scope |
|
||||
| `login.py:1002-1013` | `demo_check.toggled -> _on_demo_toggled()` | 切换 `active_repository`，发射 `demo_mode_changed`，再经 `_emit_config_update` 发射 `config_changed`；没有权限判断 |
|
||||
| `login.py:1015-1027` | `server_toggle.clicked`、save button | 方法可被直接调用，隐藏控件并不能阻止 panel 展开或保存 |
|
||||
| `login.py:1029-1054` | `_apply_server_settings()` | 会持久化 QSettings、发射两个配置相关信号；没有权限判断 |
|
||||
| `login.py:1079-1126` | `submit()` | 直接以隐藏 checkbox 的 checked 状态决定 demo；非 demo 登录会**无条件自动应用服务器控件当前值**，所以旧 QSettings 即便不展开 panel 也会生效 |
|
||||
| `login.py:1140-1159` | `_set_loading()` | loading 结束会按 `demo_repository is not None` 重新 enable demo，并重新 enable server 子控件；需把 debug gate 合入 enable 条件 |
|
||||
| `login.py:1177-1216` | 登录成功与凭据保存 | `payload["demo_mode"]` 决定是否保存密码；凭据 scope 又可能来自隐藏的 server edit |
|
||||
| `login.py:1224-1234` | 证书错误 | 会直接勾选 toggle 并展开 panel；生产隐藏后仍可被错误路径重新显示 |
|
||||
|
||||
证书错误文案还在 `ui/widgets.py:376-383` 明确引导用户展开服务器设置、关闭证书校验。非 debug 模式必须改为不引用隐藏入口的运维提示，否则 UI 和文案契约矛盾。
|
||||
|
||||
### 3. ApplicationController 与登录可信边界
|
||||
|
||||
| 位置 | 当前行为 | 需要的防线 |
|
||||
| --- | --- | --- |
|
||||
| `app.py:402-423` | 总是实例化 `DemoDoctorRepository()`；`current_demo_mode=config.demo_mode` | 非 debug 不创建/不暴露 demo repository，并强制 current demo false |
|
||||
| `app.py:438-455` | 总把 demo repository 传给 LoginWindow；复用窗口时信任 `demo_check` | 传递显式 gate；非 debug 复用时重置 checkbox/active repository |
|
||||
| `app.py:460-506` | 接受 `demo_mode` 及全部 server 字段，保存 preferences 并重建 repository | 非 debug 拒绝 debug-only changes，避免伪造 `config_changed` 绕过 UI |
|
||||
| `app.py:508-511` | 任意 `demo_mode_changed(True)` 都会设置 current demo 并取消 session restore | 非 debug 忽略/纠正 true |
|
||||
| `app.py:530-540` | `config.demo_mode=True` 会跳过生产 token restore | 必须基于经过门禁归一化的 effective demo；残留 preference 不能阻止 restore |
|
||||
| `app.py:653-681` | 信任成功 payload 中的 `demo_mode` 与 repository | 非 debug 必须拒绝 demo payload/repository，或无条件把 effective demo 归零；这是 UI 之外的最后可信边界 |
|
||||
| `app.py:782-792` | `current_demo_mode` 决定是否打开离线 demo 视频窗 | 前述边界不收口时，伪造状态还会扩散到登录后的功能 |
|
||||
|
||||
## 精确修改建议
|
||||
|
||||
### A. 建立单一、不可持久化的 capability
|
||||
|
||||
在 `src/doctor_workstation/config.py` 定义唯一 `DEBUG_MODE`（或等价只读函数），由受控构建/专用调试启动器决定。不要从 `QSettings` 读取，不要让 `preferences.json` 覆盖，也不要随 `asdict(AppConfig)` 保存。
|
||||
|
||||
配置加载完成后必须做一次最终归一化：`effective_demo_mode = DEBUG_MODE and requested_demo_mode`。在 `DEBUG_MODE=False` 时，`_merge_preferences()` 至少忽略 `demo_mode`；若“服务器设置不可用”意味着生产连接完全由受控环境提供，还应同时忽略偏好中的 `api_base_url`、`request_timeout`、`verify_ssl`，否则旧登录页设置虽然 UI 不可见，仍会从 JSON 生效。`with_updates()` 也应拒绝或丢弃非 debug 下对这些 debug-only 字段的修改。
|
||||
|
||||
推荐把 debug capability 显式传给 `ApplicationController`/`LoginWindow` 或保存为只读实例属性，便于测试 True/False 两条路径。不要在多个模块各自复制一个可 monkeypatch 的常量，否则测试或运行时可能出现 config 判 false、UI 判 true 的分裂状态。
|
||||
|
||||
### B. LoginWindow：可见性和行为同时门禁
|
||||
|
||||
在 `ui/login.py:451-468` 记录 `self.debug_mode`，并把 `self.demo_repository` 设为 `demo_repository if debug_mode else None`。建议仍构造具名控件以保持测试和代码引用稳定，但所有状态转换都使用 `self.debug_mode` 判断。
|
||||
|
||||
UI 结构建议：
|
||||
|
||||
1. `demo_check` 仅在 debug 时 visible，并且 enabled 条件为 `debug_mode and demo_repository is not None and not loading`。
|
||||
2. 把 `login.py:770-855` 的“或”分隔线、server toggle、panel 和上下 spacing 包进一个 `self.debug_server_section` QWidget；整个 section 仅在 debug 时 visible。单独隐藏 `server_toggle` 会留下“或”和空白。
|
||||
3. panel 初始仍折叠；debug true 时保持现有 toggle 行为。
|
||||
|
||||
行为防线建议：
|
||||
|
||||
1. `_restore_settings()`：非 debug 不读取 `server/*` QSettings，不恢复 demo，明确令 demo unchecked、active repository 为 production repository；服务器控件若仍构造，只从受控 `config` 填充。是否删除旧键是迁移策略，**忽略它们才是安全要求**。
|
||||
2. `_credential_scope()`：非 debug 始终从受控 config URL 取 scope，不读取隐藏的 `server_url_edit`。
|
||||
3. `_on_demo_toggled(True)`：非 debug 立即用 signal blocker 恢复 unchecked/production repository，然后 return；不得发 `demo_mode_changed` 或 `config_changed`。
|
||||
4. `_toggle_server_panel()`、`_save_server_settings()`、`_apply_server_settings()`：非 debug 强制 panel 关闭且不写 QSettings、不发 `server_settings_changed/config_changed`。直接调用也必须无效。
|
||||
5. `submit()`：用 `demo_mode = self.debug_mode and self.demo_check.isChecked()`，并从这个 effective 值选择 repository。非 debug 跳过 `_apply_server_settings()`，只使用 composition root 已构造的 remote repository；否则会再次应用隐藏控件中的旧值。
|
||||
6. `_set_loading()`：所有 demo/server enabled 状态与 `self.debug_mode` 做 AND，防止 loading 完成后重新激活。
|
||||
7. `_on_login_error()`：仅 debug 时自动展开 certificate panel；非 debug 保持 section 隐藏，并显示“请联系管理员检查受控服务器/证书配置”之类不提供绕过证书校验的文案。
|
||||
|
||||
### C. Controller：不要信任 UI 状态或 payload
|
||||
|
||||
在 `app.py:402-423` 以同一 capability 计算 effective state；非 debug 最好根本不实例化 `DemoDoctorRepository`。`_show_login()` 显式传 gate，窗口复用时不要读取隐藏 checkbox 决定 repository。
|
||||
|
||||
`_on_config_changed()` 必须再次过滤 demo/server debug-only 字段；`_on_demo_mode_changed()` 非 debug 不接受 true；`_begin_session_restore()` 不得因未经门禁的旧 `config.demo_mode` 跳过；`_on_login_succeeded()` 应把 demo capability 作为可信边界，非 debug 收到 `demo_mode=True` 或 demo repository 时拒绝进入 shell并清理 session，而不是静默接受 payload。这样即使未来有其他代码直接调用槽函数，也不能重新开启演示路径。
|
||||
|
||||
## `tests/test_ui_contract.py` 现状与调整
|
||||
|
||||
实际文件是 `app/tests/test_ui_contract.py`，`app/tests` 下没有 `conftest.py`；这里使用的 `tmp_path`/`monkeypatch` 是 pytest 内置 fixture，相关 helper 都定义在测试函数内。
|
||||
|
||||
现有相关契约：
|
||||
|
||||
- `test_ui_contract.py:230-273`：真实 demo 登录，证明 `config.demo_mode=True` 会勾选 checkbox、使用空账号密码登录 demo，并发出 demo payload；未覆盖 debug capability。
|
||||
- `test_ui_contract.py:276-337`：同一 QSettings 跨窗口恢复账号/密码；不涉及 demo。
|
||||
- `test_ui_contract.py:340-375`：服务器 panel 在最小窗口的布局。
|
||||
- `test_ui_contract.py:378-399`：函数名虽含 `debug_mode`，实际仅验证 self-signed 值写入 QSettings，没有任何 `DEBUG_MODE` 判断。
|
||||
- `test_ui_contract.py:402-455`：普通登录前自动应用 server 值、经 `config_changed` 换成新 repository。
|
||||
- `test_ui_contract.py:458-463`：证书错误文案指向服务器设置。
|
||||
- `test_ui_contract.py:495-513`：证书错误会自动展开服务器 panel；这个契约只应在 debug true 成立。
|
||||
|
||||
引入 gate 后，`230`、`340`、`378`、`402`、`495` 这几组依赖 demo/server 的测试都应显式运行在 `DEBUG_MODE=True`，避免它们因测试默认值偶然通过。不要新增“把 demo 写入 QSettings”的契约；当前 demo 的持久化源是 AppConfig/preferences，目标反而要求非 debug 忽略该残留值。
|
||||
|
||||
## 建议回归测试矩阵
|
||||
|
||||
### `tests/test_ui_contract.py`
|
||||
|
||||
1. **debug true 可见且可用**：show 窗口后断言 demo checkbox、完整 server section/toggle 可见；原 demo 登录、panel 几何、自签名保存、登录前应用服务器设置均继续通过。
|
||||
2. **debug false 无视觉残件**：断言 demo checkbox、`debug_server_section`（包括“或”分隔线）、toggle、panel 都不可见；demo unchecked，`active_repository is remote_repository`。
|
||||
3. **残留 QSettings 不生效**：预写 `server/base_url=旧地址`、`server/read_timeout`、`server/verify_ssl=false`，用 debug false 构造窗口；断言 credential scope/实际登录 repository 使用受控 config，QSettings 值未被 `_apply_server_settings()` 写回或发射成配置更新。
|
||||
4. **直接调用不能绕过**：debug false 下程序化 `demo_check.setChecked(True)`、`_on_demo_toggled(True)`、`_toggle_server_panel(True)`、`_save_server_settings()`；断言仍 unchecked、production repository、panel hidden，`demo_mode_changed`、`server_settings_changed`、`config_changed` 均无 debug 更新。
|
||||
5. **提交强制 production**：给 debug false 窗口同时传 remote 和 demo repository，并让 stale config 的 `demo_mode=True`；输入账号密码后立即执行 worker，断言只有 remote `login()` 被调用，payload `demo_mode=False`。
|
||||
6. **证书错误分模式**：debug true 仍自动展开并给出 self-signed 指引；debug false 不展开/不显示 section，错误文案不再提隐藏的“服务器设置”或关闭证书校验。
|
||||
7. **loading 不重启入口**：debug false 执行 `_set_loading(True)` 再 `_set_loading(False)`，断言 demo/server 控件持续 hidden + disabled。
|
||||
|
||||
### `tests/test_config.py`
|
||||
|
||||
1. 在隔离 `DOCTOR_CONFIG_DIR` 写入旧 `preferences.json`（至少 `demo_mode:true`）；DEBUG false 加载后必须 `demo_mode is False`，即使 `DOCTOR_DEMO_MODE=true` 也不能越权。
|
||||
2. DEBUG true 时确认 `DOCTOR_DEMO_MODE`/允许的 demo preference 仍能选择默认 demo 状态。
|
||||
3. 若生产服务器配置要求环境权威，再写入旧 JSON server 字段，断言 DEBUG false 仍采用环境的 URL/timeout/verify_ssl。
|
||||
4. `with_updates(demo_mode=True)` 在 DEBUG false 下不能产生 effective demo true；同理覆盖 server debug-only 更新的策略。
|
||||
|
||||
### `tests/test_ui_contract.py` 中的 controller 边界（或拆到 controller 专属测试）
|
||||
|
||||
1. DEBUG false 时 `_begin_session_restore()` 不因 stale `config.demo_mode=True` 而跳过远程恢复。
|
||||
2. DEBUG false 时直接调用 `_on_demo_mode_changed(True)` 不改变 `current_demo_mode`。
|
||||
3. DEBUG false 时把 `demo_mode=True`/demo repository 的伪造 payload 传给 `_on_login_succeeded()`，断言不能创建 ShellWindow。
|
||||
|
||||
若采用专用 `DOCTOR_DEBUG_MODE` 环境变量，还应在 `tests/test_one_click_entrypoints.py:102-108` 增加调试启动器显式开启、普通启动器/打包入口不开启的静态契约，并同步 `.env.example:8-17` 与 `README.md:56-72`，避免继续把 `DOCTOR_DEMO_MODE=true` 描述成足以启用演示能力。
|
||||
|
||||
## 最小验收标准
|
||||
|
||||
非 debug 模式应同时满足以下可观察结果：登录页看不到 demo、服务器入口、“或”分隔线或相关空白；旧 demo preference 不能阻止远程 token restore；旧 server QSettings 不能改变 URL、timeout、TLS 校验或凭据 scope；程序化调用隐藏控件/槽函数/信号也不能切换仓库或进入 demo shell。只有这四层都成立，才不是单纯的视觉隐藏。
|
||||
@@ -0,0 +1,79 @@
|
||||
# Windows 1.2.0 正式包重建结果（DEBUG_MODE=False）
|
||||
|
||||
- 执行日期：2026-08-28（Asia/Shanghai）
|
||||
- 工作目录：`D:\web\zyt\app`
|
||||
- 总体结果：成功
|
||||
- 生产源码修改：无（本次仅重建产物并新增本记录）
|
||||
|
||||
## 发布配置核对
|
||||
|
||||
打包前解析 `src/doctor_workstation/__init__.py`，确认：
|
||||
|
||||
- `__version__ = "1.2.0"`
|
||||
- `DEBUG_MODE = False`
|
||||
- `ONLINE_API_BASE_URL = "https://admin.zhenyangtang.com.cn"`
|
||||
|
||||
打包完成后，使用 PyInstaller 的归档读取器打开
|
||||
`dist/DoctorWorkstation/DoctorWorkstation.exe` 内嵌的 `PYZ.pyz`，提取
|
||||
`doctor_workstation` 模块并检查其顶层字节码常量，得到：
|
||||
|
||||
- `STORE_NAME __version__` 前的常量为 `"1.2.0"`
|
||||
- `STORE_NAME DEBUG_MODE` 前的常量为 `False`
|
||||
- `STORE_NAME ONLINE_API_BASE_URL` 前的常量为
|
||||
`"https://admin.zhenyangtang.com.cn"`
|
||||
|
||||
因此本次重建的 EXE 已包含正式模式和线上 API 域名配置。
|
||||
Windows 版本资源也核对为：应用 EXE 的 `FileVersion` / `ProductVersion`
|
||||
均为 `1.2.0`，安装器的 `ProductVersion` 为 `1.2.0`。
|
||||
|
||||
## 打包
|
||||
|
||||
执行命令：
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File scripts\package_windows.ps1
|
||||
```
|
||||
|
||||
- 退出码：`0`
|
||||
- Vue/Vite 前端构建：通过（43 个模块）
|
||||
- PyInstaller 6.22.0 / Python 3.12.12：通过
|
||||
- Frozen Qt multimedia file gate：通过
|
||||
- Frozen Qt multimedia smoke gate：通过
|
||||
- Frozen application entry smoke gate：通过
|
||||
- 7-Zip ZIP 创建：通过（`Everything is Ok`）
|
||||
- Inno Setup 6.7.3：通过（`Successful compile (175.078 sec)`）
|
||||
|
||||
构建过程出现 Vite 大 chunk 提示、一个可选 Qt QML 插件缺失提示以及
|
||||
Windows 系统 DLL 解析警告；它们均未阻断构建，且上述冻结产物门禁全部通过。
|
||||
|
||||
## 安装器烟测
|
||||
|
||||
执行命令：
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File scripts\smoke_windows_installer.ps1 -Installer dist\DoctorWorkstation-Setup-Windows-x64-1.2.0.exe
|
||||
```
|
||||
|
||||
- 退出码：`0`
|
||||
- 结果：`Installer icon/install/start/uninstall smoke test passed.`
|
||||
- 隔离测试目录：
|
||||
`C:\Users\pc\AppData\Local\Temp\doctor-workstation-installer-smoke-4988cc3cc71346e49925445b9ae57fb9`
|
||||
- 覆盖项：安装器图标、静默安装、已安装 EXE 启动、静默卸载及卸载残留检查
|
||||
|
||||
## 产物与校验
|
||||
|
||||
| 文件 | 大小（字节） | 大小（MiB） | SHA-256 |
|
||||
| --- | ---: | ---: | --- |
|
||||
| `dist/DoctorWorkstation-Setup-Windows-x64-1.2.0.exe` | 162,912,808 | 155.366 | `D0A9EED88F42F7FBBF31920D7B1ED82BD241481E98964F42313DF386CB746C0A` |
|
||||
| `dist/DoctorWorkstation-Windows-x64-1.2.0.zip` | 230,810,092 | 220.118 | `9FAA8596AE0D233626B3D44676C51E6DB0BA3496B12D2EE6C984ABC0E51EB01B` |
|
||||
| `dist/SHA256SUMS.txt` | 220 | 0.000 | `2DA56F76458ACE040597916C68B265C737D270B335EA73F21C4A248A2FA41B78` |
|
||||
|
||||
`dist/SHA256SUMS.txt` 内容：
|
||||
|
||||
```text
|
||||
D0A9EED88F42F7FBBF31920D7B1ED82BD241481E98964F42313DF386CB746C0A DoctorWorkstation-Setup-Windows-x64-1.2.0.exe
|
||||
9FAA8596AE0D233626B3D44676C51E6DB0BA3496B12D2EE6C984ABC0E51EB01B DoctorWorkstation-Windows-x64-1.2.0.zip
|
||||
```
|
||||
|
||||
独立使用 `Get-FileHash -Algorithm SHA256` 重算 EXE 和 ZIP 后，两项均与
|
||||
`SHA256SUMS.txt` 逐字符匹配；清单恰好包含两条记录。
|
||||
@@ -0,0 +1,57 @@
|
||||
# Debug mode full-suite verification
|
||||
|
||||
Verification date: 2026-08-28 (Asia/Shanghai)
|
||||
|
||||
Scope: read-only verification of the current shared worktree under `D:\web\zyt\app`. No production source was modified.
|
||||
|
||||
## Pytest
|
||||
|
||||
Command:
|
||||
|
||||
```powershell
|
||||
.venv\Scripts\python.exe -m pytest
|
||||
```
|
||||
|
||||
- Exit code: `1`
|
||||
- Result: `2 failed, 684 passed`
|
||||
- Total collected/executed: `686`
|
||||
- Duration: `3195.85s` (`0:53:15`)
|
||||
|
||||
Failures:
|
||||
|
||||
1. `tests/test_diagnosis_order_video_visual.py::test_video_table_embeds_player_and_preserves_row_bound_upload`
|
||||
- Assertion location: `tests/test_diagnosis_order_video_visual.py:429`
|
||||
- Assertion: `table.rowHeight(0) >= playback.required_table_row_height()`
|
||||
- Actual: row height `246`; required row height `250`.
|
||||
|
||||
2. `tests/test_reception_parity_ui.py::test_reception_auto_loads_structured_ai_analysis_and_matches_reference_geometry`
|
||||
- Assertion location: `tests/test_reception_parity_ui.py:1575`
|
||||
- Assertion: `expand_button.size().width() == expand_button.size().height() == 28`
|
||||
- Actual: `QSize(28, 34)`; expected `QSize(28, 28)`.
|
||||
|
||||
## Ruff
|
||||
|
||||
Command:
|
||||
|
||||
```powershell
|
||||
.venv\Scripts\python.exe -m ruff check src tests
|
||||
```
|
||||
|
||||
- Exit code: `1`
|
||||
- Result: `9` errors, all `F401` unused imports and all reported as fixable with `--fix`.
|
||||
|
||||
Findings:
|
||||
|
||||
1. `src/doctor_workstation/ui/diagnosis_index_widgets.py:37:5` - unused `PySide6.QtGui.QPixmap`.
|
||||
2. `src/doctor_workstation/ui/dialogs/ai_consult.py:18:5` - unused `PySide6.QtGui.QFont`.
|
||||
3. `src/doctor_workstation/ui/dialogs/ai_consult.py:24:5` - unused `PySide6.QtGui.QPixmap`.
|
||||
4. `src/doctor_workstation/ui/dialogs/ai_consult.py:26:5` - unused `PySide6.QtGui.QTextBlockFormat`.
|
||||
5. `src/doctor_workstation/ui/dialogs/ai_consult.py:27:5` - unused `PySide6.QtGui.QTextCharFormat`.
|
||||
6. `src/doctor_workstation/ui/dialogs/ai_consult.py:28:5` - unused `PySide6.QtGui.QTextCursor`.
|
||||
7. `src/doctor_workstation/ui/dialogs/prescription.py:19:28` - unused `datetime.datetime`.
|
||||
8. `src/doctor_workstation/ui/pages/patients.py:11:75` - unused `PySide6.QtGui.QPixmap`.
|
||||
9. `src/doctor_workstation/ui/pages/prescriptions.py:10:65` - unused `PySide6.QtGui.QPixmap`.
|
||||
|
||||
## Overall result
|
||||
|
||||
The full verification gate is failing: both pytest and ruff returned exit code `1`.
|
||||
@@ -0,0 +1,166 @@
|
||||
# 强制更新对话框“退出软件”安全实现分析
|
||||
|
||||
## 结论
|
||||
|
||||
强制更新对话框可以提供“退出软件”，但不能把按钮直接连接到 `dialog.close()`、`reject()` 或 `QApplication.quit()`。当前更新下载由全局 `QThreadPool` 中的 `QRunnable` 执行，退出应用不会自动取消或等待该任务；安全的最小方案应是两阶段退出：
|
||||
|
||||
1. GUI 线程记录“退出已请求”，禁止再提交安装，并用线程安全的取消事件通知下载任务；
|
||||
2. 更新任务通过既有 `finished` 信号确认已结束后，再由 `ApplicationController` 调用 `application.quit()`；
|
||||
3. `aboutToQuit` 中的 `ApplicationController.shutdown()` 只做最终、幂等的资源清理，不能承担异步等待任务结束的职责。
|
||||
|
||||
这条顺序保证：用户选择“退出软件”后不会又启动更新助手；`.part` 文件能走现有异常清理；Qt 事件循环在工作线程仍可能发信号时不会提前消失。
|
||||
|
||||
## 当前实现与证据
|
||||
|
||||
### 1. 强制对话框目前没有退出路径
|
||||
|
||||
- `AppUpdateDialog` 对强制更新移除关闭按钮并设为应用级模态（`app/src/doctor_workstation/ui/dialogs/app_update.py:112-121`）。
|
||||
- 按钮区只有“稍后提醒”“取消下载”“立即更新”；“稍后提醒”在强制更新时隐藏（`:179-197`）。
|
||||
- `set_busy()` 只在“忙且非强制”时显示取消下载，所以强制更新下载过程中没有任何停止入口（`:208-213`）。
|
||||
- 强制更新或任意下载忙状态都会忽略窗口关闭事件，强制更新还会忽略 Escape（`:265-275`）。
|
||||
|
||||
因此新增能力应是独立的 `exit_requested` 语义，而不是复用 `download_cancelled`。后者当前在 session 中明确拒绝强制更新（`:411-415`），且它的既有语义只是“取消后留在应用内”。
|
||||
|
||||
### 2. session 没有“请求取消 -> 已经停稳”的闭环
|
||||
|
||||
- `_TaskSignals` 已声明 `finished`，`_Task.run()` 也一定会在 `finally` 发出它（`app_update.py:67-90`），但 `AppUpdateSession` 没有连接该信号。
|
||||
- session 只保留一个跨线程共享的 `_cancel: bool` 和最近一次 `_signals`，没有活动 worker/token、退出状态或完成回调（`:285-292`）。
|
||||
- 检查任务和安装准备任务均直接提交到 `QThreadPool.globalInstance()`（`:316-330`、`:467-472`）；局部 `worker` 没被 session 用来跟踪生命周期。
|
||||
- 安装准备任务直接把进度/状态连到 dialog，把结果连到 `_finish_install()`（`:467-471`）。关闭事件循环前没有撤销或门控这些回调。
|
||||
- 新 offer 到达时，session 会对旧 dialog 调用 `close()` 后立刻 `deleteLater()`（`:397-405`）。如果旧 dialog 正在强制更新/下载，它的 `closeEvent()` 会拒绝关闭，但 `deleteLater()` 仍会排队；与此同时旧 worker 仍持有连接和捕获该 dialog 的 lambda。这也是需要用“活动操作 token”阻止重入/替换的理由。
|
||||
|
||||
### 3. 当前取消只能在收到下载分块以后生效
|
||||
|
||||
- `download_package()` 把 HTTP read timeout 设为 `None`（`app/src/doctor_workstation/services/app_update.py:311`）。服务器建立连接后若不再发送数据，worker 可以无限阻塞在读取中，GUI 写入 `_cancel=True` 也不能唤醒 socket。
|
||||
- 取消回调只在 `iter_bytes()` 产出一个 chunk 后检查（`:334-337`）。取消被观察到时会抛出 `AppUpdateError`，现有异常分支会删除 `.part` 文件（`:349-351`），这一清理机制可以继续复用。
|
||||
- 下载返回以后没有再次检查取消状态；job 会继续校验安装器，或调用不可取消的 `safe_extract_zip()`（UI `app_update.py:439-465`；service `app_update.py:247-260`）。
|
||||
- 下载全部完成后，文件在 `os.replace()` 前也没有最后一次取消检查（service `app_update.py:358-367`）。即使退出请求恰好到达末尾，job 仍可能返回 `_PreparedUpdate`。
|
||||
- 工作目录在下一次同版本尝试开始时会整体删除重建（service `app_update.py:722-727`），所以取消发生在下载完成或解压阶段时，保留完整 zip/部分解压目录不会污染下一次尝试；关键仍是不能继续提交安装。
|
||||
|
||||
### 4. 直接 `quit()` 存在安装竞态
|
||||
|
||||
当前 `_finish_install()` 收到任何合法 `_PreparedUpdate` 就先启动外部更新助手，再用 300 ms 定时器调用 `application.quit()`（UI `app_update.py:483-503`）。更新助手按设计等待当前 PID 消失后才覆盖/安装并重启：archive 路径见 service `app_update.py:517-525`，Inno Setup 路径见 `:594-625`。
|
||||
|
||||
若下载中“退出软件”直接调用 `quit()`，存在以下时序：
|
||||
|
||||
1. worker 已完成最后一个 chunk，并已把 `result` 排进 GUI 事件队列；
|
||||
2. 用户的退出点击与该 queued result 先后到达 GUI 线程；
|
||||
3. 若 result 仍被处理，当前 `_finish_install()` 没有“退出已请求”门禁，会启动更新助手；
|
||||
4. 应用随后退出，于是用户选择的“只退出”实际变成“退出并安装”。
|
||||
|
||||
反向时序也不安全：如果 `quit()` 先结束事件循环，worker 仍可能在独立 `httpx.Client` 中写 `.part`、解压或发射 Qt 信号。`QApplication.quit()` 是退出事件循环的请求，不是 `QRunnable` 的 cancel/join。进程最终可能等待 Qt 线程池析构、遗留中间文件，或丢弃已经排队的结果；不能把这些析构时机当成生命周期协议。
|
||||
|
||||
### 5. `ApplicationController.shutdown()` 目前不管理 updater
|
||||
|
||||
- `aboutToQuit` 在控制器构造时连接到 `shutdown()`（`app/src/doctor_workstation/app.py:402-427`）。
|
||||
- `shutdown()` 只置 `_shutting_down`、失效 session restore、关闭视频和远端 API client；没有调用 `self.app_updater.shutdown()`（`:1081-1097`）。
|
||||
- Qt 配置了 `setQuitOnLastWindowClosed(True)`（`:1147-1162`），因此单纯关闭/拒绝 dialog 也不是统一的退出协议：父 login/shell 仍存在时未必退出，最后窗口意外关闭时又会绕过 updater 的准备阶段。
|
||||
- `ApiClient.close()` 会无超时地等待所有活跃短请求归还连接（`app/src/doctor_workstation/services/api_client.py:414-450`，尤其 `:427-432`）。更新检查使用的正是共享 remote client（UI `app_update.py:310-330`），所以若退出恰逢检查请求，`aboutToQuit -> shutdown -> client.close()` 可能在 GUI 线程等待请求超时/重试结束。强制对话框的原始检查通常已经返回，但 session 仍应在最终 shutdown 时先递增 generation，使迟到的检查结果绝不能再创建窗口。
|
||||
|
||||
`aboutToQuit` 已经处于事件循环退出阶段，不适合再启动“取消后等 finished signal”的异步流程；finished queued signal 可能已没有下一轮事件可处理。因此必须在点击“退出软件”时先完成 quiesce，再真正调用 `quit()`。
|
||||
|
||||
## 建议的最小实现
|
||||
|
||||
### A. 对话框只发意图，不自行退出
|
||||
|
||||
在 `AppUpdateDialog` 增加独立信号 `exit_requested = Signal()` 和按钮：
|
||||
|
||||
- 文案为“退出软件”，仅 `offer.force` 时显示；非强制更新继续使用“稍后提醒/取消下载”。
|
||||
- 强制更新即使 `_busy=True` 也保持该按钮可用，因为这正是下载中唯一的离开路径。
|
||||
- 点击后只 emit；session 接管状态转换。对话框增加 `set_exiting()`，禁用所有按钮、显示“正在停止更新并退出…”，防止双击。
|
||||
- `closeEvent()` 和 Escape 的现有强制拦截继续保留。不要让窗口标题栏关闭绕开协调器。
|
||||
- 一旦外部安装助手已经成功启动，进入不可逆的 `APPLY_COMMITTED` 状态，禁用“退出软件”；此后退出必然表示“退出并安装”。
|
||||
|
||||
### B. 用 `threading.Event` 和活动操作身份建立闭环
|
||||
|
||||
`AppUpdateSession` 最少需要以下 GUI 线程状态：
|
||||
|
||||
```python
|
||||
self._cancel_event = Event()
|
||||
self._active_install_signals: _TaskSignals | None = None
|
||||
self._exit_requested = False
|
||||
self._quit_when_idle: Callable[[], None] | None = None
|
||||
self._apply_committed = False
|
||||
```
|
||||
|
||||
开始安装准备时 `clear()` event，保存本次 `signals`，并把 `signals.finished` 连到带 `signals` 身份参数的 `_on_install_finished()`。进度、状态、result、error 也不要再直接连接 dialog 方法；统一经过 session handler，并同时验证：
|
||||
|
||||
- `signals is self._active_install_signals`；
|
||||
- dialog 仍是 `self.dialog`；
|
||||
- 未处于 `_exit_requested`（finished handler 除外）。
|
||||
|
||||
这会同时解决迟到回调、旧 dialog 被替换、以及上一次任务影响下一次 `_cancel` 状态的问题。活动安装存在时，`check()`/`_present()` 应拒绝再替换 dialog，避免两个 job 同时删除和使用同一版本 workspace。
|
||||
|
||||
退出请求的最小状态机是：
|
||||
|
||||
```text
|
||||
IDLE/PREPARING --点击退出--> EXIT_PENDING
|
||||
EXIT_PENDING --cancel_event.set()--> 等待当前 install signals.finished
|
||||
无活动任务或 finished 到达 --> ApplicationController.request_quit()
|
||||
aboutToQuit --> ApplicationController.shutdown() 最终幂等清理
|
||||
```
|
||||
|
||||
`_finish_install()` 的第一条业务门禁必须是“如果退出已请求、event 已 set、或 signals 已不是当前操作，则直接返回，不调用 `apply_downloaded_update()`”。这是防止“退出反而安装”的关键断言。
|
||||
|
||||
### C. 让 job 在阶段边界观察取消，并给网络读取有限上界
|
||||
|
||||
现有 `download_package(cancelled=...)` 接口无需改变，改传 `self._cancel_event.is_set`。job 至少在以下边界调用统一的 `_raise_if_cancelled()`：
|
||||
|
||||
1. 创建 workspace 前；
|
||||
2. `download_package()` 返回后；
|
||||
3. 安装器校验/zip 解压前；
|
||||
4. 校验/解压后、构造 `_PreparedUpdate` 前。
|
||||
|
||||
同时把 `download_package()` 的 `read=None` 改成有限的“单次读空闲超时”，建议沿用配置的 `request_timeout` 或默认 30 秒。这个 timeout 不是总下载时长：只要持续收到 chunk，大文件仍可继续；服务器停止发数据后，退出等待则有确定上界。
|
||||
|
||||
如果希望解压中点击退出也能很快响应，可把 `safe_extract_zip()` 从一次性 `extractall()` 改为逐 member 提取并在每个 member 前检查同一个 cancel callback。若坚持最小改动，也可以让退出等待当前 `extractall()` 完成，但必须保持 event loop 和 dialog 存活，并在解压后门禁掉安装，不能先 `quit()`。
|
||||
|
||||
### D. 由控制器统一发起真正退出
|
||||
|
||||
在 `ApplicationController` 增加与 `_shutting_down` 分离的 `_quit_requested`，以及幂等 `request_quit()`：
|
||||
|
||||
1. 首次调用时设置 `_quit_requested`；
|
||||
2. 调用 `app_updater.prepare_to_quit(self.application.quit)`；
|
||||
3. updater 无活动安装时立即以 `QTimer.singleShot(0, callback)` 完成；有任务时保存 callback，待该任务 `finished` 后完成；
|
||||
4. 重复调用不做任何事。
|
||||
|
||||
不要提前设置 `_shutting_down`，否则真正触发 `aboutToQuit` 时现有 `shutdown()` 会在 `:1084-1086` 直接返回，跳过资源释放。
|
||||
|
||||
`ApplicationController.shutdown()` 中应在 `_cancel_session_restore()` 之后、关闭视频和 remote client 之前调用幂等的 `self.app_updater.shutdown()`。该方法应：递增 `_generation`、设置 cancel event、清除退出 callback、使所有迟到 callback 失效；它是兜底，不再等待 worker。正常的强制对话框退出路径到这里时，安装准备 worker 已经 finished。
|
||||
|
||||
成功更新也应复用同一完成门：`_finish_install()` 成功启动 helper 后只记录 `_apply_committed=True` 和“任务结束后退出”；由本次 `signals.finished` 再调用控制器的 `request_quit()`。这样可以删除当前依赖经验值的 300 ms 定时退出（UI `app_update.py:501-503`），并明确保证 worker 已离开 `run()`。
|
||||
|
||||
### E. 不建议的实现
|
||||
|
||||
- 不要在退出按钮中调用 `os._exit()`、`terminate()` 或强杀线程；这会绕过 controller 的视频/API 清理，并可能截断 `.part`/日志写入。
|
||||
- 不要在 `aboutToQuit` 中调用 `QThreadPool.globalInstance().waitForDone()`；它会等待整个应用的全局线程池，而不只是更新任务，当前无限 read timeout 还可能让 GUI 永久卡住。
|
||||
- 不要用循环 `processEvents()` 等待 worker；这会允许更新按钮、窗口关闭和 queued result 重入。
|
||||
- 不要只设置现有 `_cancel=True` 后立即 `quit()`；设置取消只是请求，`finished` 才是可退出的确认。
|
||||
|
||||
## 建议补测
|
||||
|
||||
在 `app/tests/test_app_update_ui.py` 现有强制对话框测试（`:68-83`）基础上补：
|
||||
|
||||
1. 强制更新显示“退出软件”，不显示“稍后提醒”，关闭按钮/Escape 仍不能绕过；非强制更新不显示该退出按钮。
|
||||
2. 空闲时点击退出只调用一次 controller `request_quit()`。
|
||||
3. 下载中点击退出会 set event、保持应用运行且不立即调用 `application.quit()`；手工 emit 当前 signals 的 `finished` 后才调用一次。
|
||||
4. 退出请求后再投递 `progress/status/result/error` 均不更新旧 dialog；特别断言 `_finish_install()` 不调用 `apply_downloaded_update()`。
|
||||
5. 模拟“result 已排队但退出点击先处理”的边界，断言不会启动 helper；模拟 result 已先完成 helper 提交，则退出按钮已禁用且最终走“安装后退出”。
|
||||
6. 新 offer 在活动安装期间不会 `deleteLater()` 当前 dialog，也不会启动第二个 workspace job。
|
||||
7. `ApplicationController.shutdown()` 调用 updater shutdown 早于 `remote_repository.client.close()`，并保持二次调用幂等。
|
||||
|
||||
在 `app/tests/test_app_update.py` 的下载测试（现有 `:235-293`）基础上补：
|
||||
|
||||
8. 流式响应在若干 chunk 后设置 `Event`，断言抛取消错误、目标文件和 `.part` 都不存在。
|
||||
9. 下载最后一个 chunk 后、`os.replace()`/job 返回前取消，断言 session 的阶段门禁不会产出可安装结果。
|
||||
10. 读空闲超时为有限值，并被转换为 `AppUpdateError`；避免退出永久等待。
|
||||
|
||||
## 实施顺序
|
||||
|
||||
最小、低风险的提交顺序是：先加入 session 的 operation token、`Event`、finished 门和 controller `request_quit()`；再加对话框按钮；最后把 read timeout 改为有限值并补阶段取消检查。只有当“退出后 result 绝不会进入 `apply_downloaded_update()`”和“quit 只发生在 finished 以后”两条测试通过，才应开放强制更新下载中的退出按钮。
|
||||
|
||||
## 审阅说明
|
||||
|
||||
- 本次依据工作树当前内容只读分析；生产代码与现有测试均未修改。
|
||||
- 根目录 `AGENTS.md` 已读取；仓库当前不存在其中提到的 `.trellis/` 目录，因此没有额外的 workflow/spec 文件可读。
|
||||
- 工作树原本已有多项未提交修改；本次只新增本研究文档，没有覆盖或回退任何现有改动。
|
||||
@@ -0,0 +1,87 @@
|
||||
# 强制更新“退出软件”Windows 正式包重建与验证结果
|
||||
|
||||
- 执行日期：2026-08-28（Asia/Shanghai）
|
||||
- 工作目录：`D:\web\zyt\app`
|
||||
- 总体结果：成功
|
||||
- 生产源码/测试修改：无（本次仅重建发布产物并新增本报告）
|
||||
- 工作树说明：执行前 `src/doctor_workstation/__init__.py` 及其他生产/测试文件已有用户修改；本次全部保留，未覆盖或回退
|
||||
- Trellis：仓库根目录不存在 `.trellis/`，因此无 Trellis 工作流文件可继续读取
|
||||
|
||||
## 发布配置核对
|
||||
|
||||
重建前后均读取 `src/doctor_workstation/__init__.py`，确认：
|
||||
|
||||
```powershell
|
||||
rg -n "(__version__|DEBUG_MODE)" src/doctor_workstation/__init__.py
|
||||
```
|
||||
|
||||
- 退出码：`0`
|
||||
- 输出：`6:__version__ = "1.2.0"`、`10:DEBUG_MODE = False`
|
||||
|
||||
- `__version__ = "1.2.0"`
|
||||
- `DEBUG_MODE = False`
|
||||
|
||||
最终 frozen 主程序的 Windows 版本资源也复核为：
|
||||
|
||||
- `FileVersion = 1.2.0`
|
||||
- `ProductVersion = 1.2.0`
|
||||
|
||||
最终安装器的 `ProductVersion = 1.2.0`。
|
||||
|
||||
## 正式包重建
|
||||
|
||||
执行命令：
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File scripts\package_windows.ps1
|
||||
```
|
||||
|
||||
- 退出码：`0`
|
||||
- 结果：`Windows package complete.`
|
||||
- Python 构建环境：PyInstaller 6.22.0 / Python 3.12.12
|
||||
- 视频伴侣构建：通过，Vite 转换 43 个模块
|
||||
- frozen Qt 多媒体文件门禁：通过
|
||||
- frozen Qt 多媒体 smoke（`--media-smoke-test`，隔离 offscreen 环境）：通过
|
||||
- frozen 应用入口 smoke（`--smoke-test`，隔离 offscreen 环境）：通过
|
||||
- ZIP：7-Zip 报告 `Everything is Ok`
|
||||
- 安装器：Inno Setup 6.7.3 编译成功，`Successful compile (140.609 sec)`
|
||||
|
||||
构建期间有非阻断警告：Vite 报告单个压缩后 chunk 超过 500 kB；PyInstaller 报告一个 Qt QML 插件二进制缺失及若干 Windows 系统 DLL 解析警告。脚本内置的 frozen 文件门禁与两个 smoke gate 均通过，构建最终退出码为 `0`。
|
||||
|
||||
## 最终安装器冒烟验证
|
||||
|
||||
执行命令：
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File scripts\smoke_windows_installer.ps1 -Installer 'D:\web\zyt\app\dist\DoctorWorkstation-Setup-Windows-x64-1.2.0.exe'
|
||||
```
|
||||
|
||||
- 退出码：`0`
|
||||
- 结果：`Installer icon/install/start/uninstall smoke test passed.`
|
||||
- 隔离验证目录：`C:\Users\pc\AppData\Local\Temp\doctor-workstation-installer-smoke-55b6feebaa134d21ba0637549d55355b`
|
||||
- 覆盖范围：安装器品牌图标、静默安装、已安装 EXE 存在性与启动 smoke、静默卸载、卸载后主程序残留检查
|
||||
|
||||
## 产物与独立校验
|
||||
|
||||
使用以下命令模式逐项独立复核，退出码为 `0`：
|
||||
|
||||
```powershell
|
||||
Get-Item -LiteralPath <产物绝对路径>
|
||||
Get-FileHash -LiteralPath <产物绝对路径> -Algorithm SHA256
|
||||
```
|
||||
|
||||
| 产物 | 绝对路径 | 字节数 | SHA-256 |
|
||||
| --- | --- | ---: | --- |
|
||||
| 正式安装器 EXE | `D:\web\zyt\app\dist\DoctorWorkstation-Setup-Windows-x64-1.2.0.exe` | 162,907,874 | `71B4ADF7B431A3BBC53818AA2D68089977D777D18F0969C930A0A6B1777F2BA9` |
|
||||
| 发布 ZIP | `D:\web\zyt\app\dist\DoctorWorkstation-Windows-x64-1.2.0.zip` | 230,817,779 | `D41C0794568A59FB57A083425750F4A2CDBED9962B13D9EBBD42FC2EEF374604` |
|
||||
| frozen 主程序 EXE | `D:\web\zyt\app\dist\DoctorWorkstation\DoctorWorkstation.exe` | 6,300,842 | `550BF4434C6B2BEEB9DDA5A78107FB392C4FF442A6D62D01803A51197E59A893` |
|
||||
| 校验清单 | `D:\web\zyt\app\dist\SHA256SUMS.txt` | 220 | `9BD4CB7CD0A1FA7FBBED0E6D38BE2A4F98898224A6B97E0E38F35701CB8B8A20` |
|
||||
|
||||
`dist\SHA256SUMS.txt` 内容：
|
||||
|
||||
```text
|
||||
71B4ADF7B431A3BBC53818AA2D68089977D777D18F0969C930A0A6B1777F2BA9 DoctorWorkstation-Setup-Windows-x64-1.2.0.exe
|
||||
D41C0794568A59FB57A083425750F4A2CDBED9962B13D9EBBD42FC2EEF374604 DoctorWorkstation-Windows-x64-1.2.0.zip
|
||||
```
|
||||
|
||||
独立复算的安装器与 ZIP 哈希均与脚本末尾输出及 `SHA256SUMS.txt` 逐字符一致。
|
||||
@@ -0,0 +1,182 @@
|
||||
# 强制更新“退出软件”回归测试设计
|
||||
|
||||
## 结论
|
||||
|
||||
建议在 `app/tests/test_app_update_ui.py` 把“退出软件”作为强制更新对话框的独立显式动作测试，不把它等同于关闭窗口或 `reject()`：
|
||||
|
||||
- 强制更新在初始状态和下载中状态都显示且启用“退出软件”。
|
||||
- 点击只发出一次专用信号（下文假定为 `exit_requested`）；对话框自身不静默 `reject()`。
|
||||
- 普通更新仍显示“稍后提醒”，不显示“退出软件”，原有 `update_deferred` + `reject()` 行为不变。
|
||||
- 强制更新无论初始还是下载中，标题栏关闭和 Escape 都继续被拦截；用户只能通过明确的“退出软件”动作退出。
|
||||
|
||||
生产实现若采用独立控件，建议公开 `exit_button`；这比把强制退出语义塞进现有 `later_button` 更容易测试，也避免 `_defer()` 同时承担“稍后”和“退出”两种相反行为。若实现选择复用 `later_button`，下述断言可把 `exit_button` 替换为该控件，但至少应保留独立的 `exit_requested` 信号。
|
||||
|
||||
## 当前覆盖缺口
|
||||
|
||||
当前 `test_app_update_ui.py` 有以下相关覆盖：
|
||||
|
||||
- `test_optional_update_dialog_allows_later` 只断言普通更新的稍后按钮可见和更新文案，未点击按钮，也未验证 `update_deferred`。
|
||||
- `test_forced_update_dialog_hides_defer_and_blocks_escape` 断言稍后按钮隐藏，并用 `dialog.close()` 验证强更无法关闭；尽管测试名写有 `blocks_escape`，测试体没有发送 Escape。
|
||||
- 没有覆盖 `set_busy(True)`。当前 `set_busy()` 会禁用 `later_button`，因此若复用该按钮显示“退出软件”，下载中会直接回归为不可退出。
|
||||
- 没有覆盖退出信号的次数，也没有证明显式退出动作不会被当成普通 `reject()`。
|
||||
|
||||
现有 service 测试 `app/tests/test_app_update.py` 主要覆盖 offer 解析、下载、校验与更新应用，不适合承载 Qt 按钮和键盘行为；这些回归应继续留在 `test_app_update_ui.py`。
|
||||
|
||||
## 建议测试矩阵
|
||||
|
||||
| offer | 对话框状态 | 稍后按钮 | 退出按钮 | 更新按钮 | 取消下载 | 关闭 / Escape |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 强制 | 初始 | 隐藏 | 显示、启用 | 启用 | 隐藏 | 均拦截 |
|
||||
| 强制 | 下载中 | 隐藏 | 显示、启用 | 禁用 | 隐藏 | 均拦截 |
|
||||
| 普通 | 初始 | 显示、启用，文案“稍后提醒” | 隐藏 | 启用 | 隐藏 | 允许 |
|
||||
| 普通 | 下载中 | 保持现有禁用语义 | 隐藏 | 禁用 | 显示 | `closeEvent` 目前拦截；本次不要顺带定义 Escape 新语义 |
|
||||
|
||||
最后一格存在现有 Qt 行为不对称：普通更新下载中时 `closeEvent()` 会拦截标题栏关闭，但 `keyPressEvent()` 仅专门拦截强制更新的 Escape。除非产品需求明确要求调整普通更新下载中的 Escape，否则本次回归不要无意固化或改变该行为。
|
||||
|
||||
## 推荐测试拆分
|
||||
|
||||
测试文件增加：
|
||||
|
||||
```python
|
||||
import pytest
|
||||
from PySide6.QtCore import Qt
|
||||
from PySide6.QtTest import QTest
|
||||
```
|
||||
|
||||
### 1. 强制更新在初始和下载中均可显式退出
|
||||
|
||||
用参数化覆盖两个状态，避免只测初始渲染：
|
||||
|
||||
```python
|
||||
@pytest.mark.parametrize("busy", [False, True], ids=["initial", "downloading"])
|
||||
def test_forced_update_exit_action_stays_available(
|
||||
busy: bool,
|
||||
application: QApplication | None = None,
|
||||
) -> None:
|
||||
app = application or QApplication.instance() or QApplication([])
|
||||
apply_theme(app)
|
||||
dialog = AppUpdateDialog(_offer(force=True))
|
||||
dialog.show()
|
||||
if busy:
|
||||
dialog.set_busy(True)
|
||||
dialog.show_download_progress(256, 1024)
|
||||
app.processEvents()
|
||||
|
||||
assert not dialog.later_button.isVisible()
|
||||
assert dialog.exit_button.isVisible()
|
||||
assert dialog.exit_button.isEnabled()
|
||||
assert dialog.exit_button.text() == "退出软件"
|
||||
assert dialog.update_button.isEnabled() is (not busy)
|
||||
assert not dialog.cancel_button.isVisible()
|
||||
|
||||
dialog.hide()
|
||||
dialog.deleteLater()
|
||||
app.processEvents()
|
||||
```
|
||||
|
||||
这里必须在 `set_busy(True)` 后断言，才能捕获“统一禁用底部按钮”导致强制更新无法退出的回归。调用 `show_download_progress()` 同时让测试更贴近真实 `_start_install()` 顺序：先 `set_busy(True)`，再进入下载进度态。
|
||||
|
||||
### 2. 点击退出按钮只发一次专用信号
|
||||
|
||||
```python
|
||||
def test_forced_update_exit_button_emits_request(
|
||||
application: QApplication | None = None,
|
||||
) -> None:
|
||||
app = application or QApplication.instance() or QApplication([])
|
||||
dialog = AppUpdateDialog(_offer(force=True))
|
||||
requested: list[bool] = []
|
||||
dialog.exit_requested.connect(lambda: requested.append(True))
|
||||
dialog.show()
|
||||
app.processEvents()
|
||||
|
||||
dialog.exit_button.click()
|
||||
|
||||
assert requested == [True]
|
||||
assert dialog.isVisible()
|
||||
dialog.hide()
|
||||
dialog.deleteLater()
|
||||
app.processEvents()
|
||||
```
|
||||
|
||||
`assert dialog.isVisible()` 有意证明按钮在 dialog 层只表达“请求退出软件”，而不是绕开应用级清理流程直接 `reject()`。真正退出应由 `AppUpdateSession`/应用层的 slot 完成。若最终设计明确由 dialog 自身关闭，则删除这一条，但仍要保留信号次数断言。
|
||||
|
||||
还可把该测试参数化为初始/下载中并在两种状态点击；若测试数量需要控制，则第一个参数化测试负责可用性，第二个测试负责一次信号已足够定位大部分回归。
|
||||
|
||||
### 3. 普通更新仍是“稍后提醒”
|
||||
|
||||
建议增强现有 optional 测试，而不是只检查可见性：
|
||||
|
||||
```python
|
||||
def test_optional_update_dialog_keeps_defer_action(
|
||||
application: QApplication | None = None,
|
||||
) -> None:
|
||||
app = application or QApplication.instance() or QApplication([])
|
||||
dialog = AppUpdateDialog(_offer(force=False))
|
||||
deferred: list[bool] = []
|
||||
dialog.update_deferred.connect(lambda: deferred.append(True))
|
||||
dialog.show()
|
||||
app.processEvents()
|
||||
|
||||
assert dialog.later_button.isVisible()
|
||||
assert dialog.later_button.isEnabled()
|
||||
assert dialog.later_button.text() == "稍后提醒"
|
||||
assert not dialog.exit_button.isVisible()
|
||||
|
||||
dialog.later_button.click()
|
||||
|
||||
assert deferred == [True]
|
||||
assert not dialog.isVisible()
|
||||
dialog.deleteLater()
|
||||
app.processEvents()
|
||||
```
|
||||
|
||||
这条会防止实现“退出软件”时误把普通更新的次按钮文案、信号或关闭行为一起改掉。
|
||||
|
||||
### 4. 强制更新明确拦截关闭与 Escape
|
||||
|
||||
把当前名不副实的测试改成真实事件测试，并参数化初始/下载中：
|
||||
|
||||
```python
|
||||
@pytest.mark.parametrize("busy", [False, True], ids=["initial", "downloading"])
|
||||
def test_forced_update_only_allows_explicit_exit(
|
||||
busy: bool,
|
||||
application: QApplication | None = None,
|
||||
) -> None:
|
||||
app = application or QApplication.instance() or QApplication([])
|
||||
dialog = AppUpdateDialog(_offer(force=True))
|
||||
dialog.show()
|
||||
if busy:
|
||||
dialog.set_busy(True)
|
||||
dialog.show_download_progress(256, 1024)
|
||||
app.processEvents()
|
||||
|
||||
dialog.close()
|
||||
app.processEvents()
|
||||
assert dialog.isVisible()
|
||||
|
||||
QTest.keyClick(dialog, Qt.Key.Key_Escape)
|
||||
app.processEvents()
|
||||
assert dialog.isVisible()
|
||||
|
||||
dialog.hide()
|
||||
dialog.deleteLater()
|
||||
app.processEvents()
|
||||
```
|
||||
|
||||
行为断言比检查 window flags 更稳定：不同平台可能规范化窗口标志，但 `closeEvent()`/`keyPressEvent()` 是否真正保留对话框才是用户可观察契约。
|
||||
|
||||
## 会话层边界
|
||||
|
||||
dialog 信号测试只能证明点击请求已发出，不能证明应用最终退出。生产接线还应满足：
|
||||
|
||||
- `AppUpdateSession._present()` 连接 `exit_requested` 到一个应用级退出入口。
|
||||
- 下载中退出时先设置取消标志，使 `download_package(..., cancelled=...)` 尽快结束并清理 `.part` 文件，再请求 `QApplication.quit()`；否则全局线程池任务可能拖延进程退出。
|
||||
- 应用级退出必须走既有 `QApplication.aboutToQuit -> ApplicationController.shutdown`，不要从 dialog 直接调用 `sys.exit()` 或跳过资源清理。
|
||||
|
||||
若实现为可替换的 session 方法（例如 `_request_exit()`），可另补一个 session 单测，mock/monkeypatch 该方法后验证 dialog 信号接线；不要在 pytest 共享的真实 `QApplication` 上直接调用 `quit()`，以免污染同进程后续 UI 测试。本次题目明确要求的四项回归，以上 dialog 测试已经可以独立、稳定覆盖。
|
||||
|
||||
## 验证记录
|
||||
|
||||
- 已读取根 `AGENTS.md`；工作树中不存在 `.trellis/workflow.md` 和 `.trellis/spec/`，因此无法应用额外 Trellis 分层规范。
|
||||
- 只读运行现有基线：`app/.venv/Scripts/python.exe -m pytest tests/test_app_update_ui.py -q`，结果 `4 passed`。
|
||||
- 本文之外未修改生产代码或测试代码；工作树中原有的 `app_update.py` 与 `test_app_update_ui.py` 未提交改动均已保留。
|
||||
@@ -0,0 +1,52 @@
|
||||
# Windows 1.2.0 正式打包结果
|
||||
|
||||
- 打包日期：2026-08-28（Asia/Shanghai）
|
||||
- 工作目录：`D:\web\zyt\app`
|
||||
- 版本源：`src/doctor_workstation/__init__.py`
|
||||
- 确认版本：`1.2.0`
|
||||
- 执行命令：`powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File scripts\package_windows.ps1`
|
||||
- 脚本退出码：`0`
|
||||
- 总体结果：成功
|
||||
|
||||
## 发布产物核对
|
||||
|
||||
| 文件 | 大小（字节） | 大小（MiB） | SHA-256 |
|
||||
| --- | ---: | ---: | --- |
|
||||
| `dist/DoctorWorkstation-Setup-Windows-x64-1.2.0.exe` | 162,914,042 | 155.367 | `1D74966B73005B30ECB4EB7E2101BECB57BB8C91D0981392ACD00F6800D37E7D` |
|
||||
| `dist/DoctorWorkstation-Windows-x64-1.2.0.zip` | 230,810,707 | 220.118 | `A56057D95EFCE70E58FA54264CAC17A16E2F5BDB842FE515A5A153B073A4AFE9` |
|
||||
| `dist/SHA256SUMS.txt` | 220 | 0.000 | `08BD69A21BACEC86B8269ED665C50CDAF4D3ED6D252CEC4DD7BEE30E73573175` |
|
||||
|
||||
以上三个文件均存在。独立使用 `Get-FileHash -Algorithm SHA256` 重新计算 EXE 和 ZIP 哈希，结果与打包脚本末尾输出及 `SHA256SUMS.txt` 中的两条记录逐项一致。
|
||||
|
||||
## 脚本验证结果
|
||||
|
||||
- 锁定的 Python 构建依赖检查通过。
|
||||
- 视频伴侣依赖安装成功，`vue-tsc --noEmit && vite build` 成功；Vite 共转换 43 个模块。
|
||||
- PyInstaller 6.22.0 / Python 3.12.12 构建成功，输出 `dist/DoctorWorkstation`。
|
||||
- `Frozen Qt multimedia file gate passed.`
|
||||
- `Frozen Qt multimedia smoke gate passed (--media-smoke-test, isolated offscreen mode).`
|
||||
- `Frozen application entry smoke gate passed (--smoke-test, isolated offscreen mode).`
|
||||
- 7-Zip 创建 ZIP 成功，输出 `Everything is Ok`；归档包含 180 个目录、3,011 个文件。
|
||||
- Inno Setup 6.7.3 编译成功，输出 `Successful compile (165.062 sec)`。
|
||||
- 正式安装包、ZIP 和校验清单均生成，脚本最终退出码为 0。
|
||||
|
||||
## 非阻断警告
|
||||
|
||||
- Vite 报告单个压缩后 chunk 超过 500 kB，仅为体积优化提示。
|
||||
- PyInstaller 报告一个 Qt QML 插件二进制缺失，以及若干 Windows 系统 DLL 解析警告；这些警告未阻断构建，且脚本内置的多媒体文件门禁、多媒体离屏 smoke test 和应用入口 smoke test 全部通过。
|
||||
|
||||
## 真实安装器冒烟测试
|
||||
|
||||
- 执行命令：`powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File scripts\smoke_windows_installer.ps1 -Installer 'D:\web\zyt\app\dist\DoctorWorkstation-Setup-Windows-x64-1.2.0.exe'`
|
||||
- 脚本退出码：`0`
|
||||
- 脚本最终结果：`Installer icon/install/start/uninstall smoke test passed.`
|
||||
- 隔离测试目录：`C:\Users\pc\AppData\Local\Temp\doctor-workstation-installer-smoke-ac84581babe94e28a0d0ffab63dd0b5f`
|
||||
|
||||
### 分阶段核对
|
||||
|
||||
- 静默安装：通过。安装器以 `/VERYSILENT /SUPPRESSMSGBOXES /NORESTART /CURRENTUSER` 运行到隔离目录；`setup.log` 记录 `Installation process succeeded.` 和 `Need to restart Windows? No`。
|
||||
- 安装内容：通过。脚本在启动前确认 `DoctorWorkstation.exe` 与 `unins000.exe` 均存在。
|
||||
- 图标：通过。脚本分别提取安装器、已安装主程序及卸载器的 32×32 关联图标并计算 SHA-256；主程序与卸载器图标均和安装器品牌图标一致，否则脚本会失败。
|
||||
- 启动 smoke：通过。已安装主程序在隔离配置、日志目录与 `QT_QPA_PLATFORM=offscreen` 环境下执行 `--smoke-test`，退出码为 0；应用日志记录 `doctor workstation starting`，未记录异常堆栈。
|
||||
- 静默卸载：通过。卸载器以 `/VERYSILENT /SUPPRESSMSGBOXES /NORESTART` 运行，退出码为 0；`uninstall.log` 记录 `Uninstallation process succeeded.`、`Removed all? Yes` 和 `Need to restart Windows? No`。
|
||||
- 残留检查：通过。卸载完成后独立确认隔离安装目录、`DoctorWorkstation.exe`、`unins000.exe`、当前用户开始菜单快捷方式及本次当前用户卸载注册表键均不存在。隔离测试根目录按设计保留，仅包含安装/卸载日志和隔离应用日志，便于审计。
|
||||
@@ -0,0 +1,233 @@
|
||||
# 医生工作站版本发布配置与更新 API 诊断
|
||||
|
||||
## 结论
|
||||
|
||||
当前仓库中，admin、server、app 三端的**现行契约是一致的**，但字段名不是扁平的
|
||||
`package_type` / `download_url`。正式 wire contract 是：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 1,
|
||||
"data": {
|
||||
"has_update": true,
|
||||
"force": false,
|
||||
"enabled": true,
|
||||
"current_version": "1.1.0",
|
||||
"latest_version": "1.2.0",
|
||||
"min_version": "",
|
||||
"title": "...",
|
||||
"notes": "...",
|
||||
"platform": "windows",
|
||||
"arch": "x64",
|
||||
"package": {
|
||||
"url": "https://.../DoctorWorkstation-Setup-Windows-x64-1.2.0.exe",
|
||||
"sha256": "64 位十六进制值",
|
||||
"size": 123,
|
||||
"filename": "DoctorWorkstation-Setup-Windows-x64-1.2.0.exe",
|
||||
"type": "inno_setup"
|
||||
},
|
||||
"can_install": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
因此：
|
||||
|
||||
- `latest_version` 是 `data` 下的顶层字段。
|
||||
- `platform`、`arch` 是检测请求参数，同时在 `data` 下回显规范化后的值；它们不保存在发布配置中。
|
||||
- 安装包对象叫 `package`。
|
||||
- 安装包类型叫 `package.type`，不是顶层或同级的 `package_type`。
|
||||
- 下载地址叫 `package.url`，不是 `download_url`。
|
||||
- 哈希叫 `package.sha256`。
|
||||
- 如果截图或线上响应实际出现的是扁平 `package_type`、`download_url`，当前 app 不会读取这些别名。这不是当前仓库 server 的输出，优先怀疑线上后端/代理为另一版本或只部署了部分提交。
|
||||
|
||||
当前工作区还存在一个已确认的发布物版本风险：运行时版本源已经是 `1.2.0`（`app/src/doctor_workstation/__init__.py:5-6`），但 `app/dist/SHA256SUMS.txt:1-2` 只登记了 `1.1.0` 的 EXE/ZIP，且本地 `DoctorWorkstation.exe` 文件版本也是 `1.1.0`。如果管理端把 `latest_version` 设为 `1.2.0`，却填入当前 `1.1.0` 安装包，客户端安装后仍会报告 `1.1.0`，下次启动会再次发现 `1.2.0`，形成重复升级提示。打包脚本明确从同一个 `__version__` 读取版本（`app/scripts/package_windows.ps1:68-76`），并用它生成 EXE/ZIP 名称（`:169-174`）及两者哈希（`:234-244`）；发布前必须重新生成 `1.2.0` 产物。
|
||||
|
||||
> 本轮只读诊断没有修改生产代码。根目录 `AGENTS.md` 已读取；仓库中没有 `.trellis/` 目录。
|
||||
|
||||
## 1. Windows 64 位安装包字段如何进入保存请求
|
||||
|
||||
管理端类型定义把 Windows 包放在 `packages.windows_x64`，每个包固定包含
|
||||
`url`、`sha256`、`size`、`filename`、`type`；其中 `type` 只允许
|
||||
`archive | inno_setup`（`admin/src/api/setting/desktop_workstation.ts:3-24`）。保存接口是
|
||||
`POST /setting.desktop_workstation/setConfig`（同文件 `:27-34`）。
|
||||
|
||||
页面的 Windows 区块来自平台键 `windows_x64`（`admin/src/views/setting/desktop_workstation/index.vue:196-224`），默认类型是 `inno_setup`（`:198-218`）。UI 字段与请求体的对应关系如下：
|
||||
|
||||
| 截图/UI 字段 | 保存请求字段 | 证据 |
|
||||
|---|---|---|
|
||||
| Windows 64 位安装包 | `packages.windows_x64` | `index.vue:221-224, 339-343` |
|
||||
| 安装包类型 | `packages.windows_x64.type`，EXE 为 `inno_setup` | `index.vue:96-104, 305-309` |
|
||||
| 安装包地址 | `packages.windows_x64.url` | `index.vue:113-123, 318-324` |
|
||||
| SHA-256 | `packages.windows_x64.sha256` | `index.vue:144-150, 292-315` |
|
||||
| 文件名 | `packages.windows_x64.filename` | `index.vue:152-162, 300-304` |
|
||||
| 文件大小（字节） | `packages.windows_x64.size` | `index.vue:164-174, 300-304` |
|
||||
| 最新版本号 | 顶层 `latest_version` | `index.vue:34-42, 330-344` |
|
||||
|
||||
选择文件后，页面在浏览器本地读取原始文件名和字节数，`.exe` 自动切换为
|
||||
`inno_setup`，并用 Web Crypto 计算 SHA-256（`index.vue:292-315`）。上传成功后只把上传接口返回的 `data.uri`（次选 `data.url`）写入包的 `url`（`:318-328`）。最终点击保存时，页面显式组装三个平台的完整 `packages` 对象，而不是上传后自动发布（`:330-345`）。
|
||||
|
||||
虽然 API 封装调用写成 `request.post({ params })`，拦截器会在 POST 且没有 `data` 时把
|
||||
`params` 移入 JSON body（`admin/src/utils/request/index.ts:20-38`），所以 PHP 收到的是上述嵌套 JSON，而不是查询字符串。
|
||||
|
||||
## 2. 后端如何校验和持久化
|
||||
|
||||
控制器用 POST 校验器接收请求，再交给逻辑层保存（`server/app/adminapi/controller/setting/DesktopWorkstationController.php:38-46`）。
|
||||
|
||||
正常管理端保存时的关键约束：
|
||||
|
||||
- 版本号需是纯数字分段格式（`server/app/adminapi/validate/setting/DesktopWorkstationValidate.php:48-57`）。
|
||||
- 包类型只允许 `archive` / `inno_setup`，且 `inno_setup` 只允许 Windows x64（`:118-137`）。
|
||||
- Inno Setup 若填写文件名，必须以 `.exe` 结尾（`:138-140`）。
|
||||
- 显式 `http://` 的 Inno Setup 地址会被拒绝（`:141-143`）。
|
||||
- 外部 http(s) 地址必须带 SHA-256，SHA-256 若非空必须是 64 位十六进制（`:144-152`）。
|
||||
- 文件名最长 180 字节，size 必须是非负数（`:153-158`）。
|
||||
|
||||
逻辑层将标量分别保存为配置项，把所有平台包作为一个 `packages` 配置项保存：
|
||||
|
||||
- `enabled`
|
||||
- `latest_version`
|
||||
- `min_version`
|
||||
- `force_update`
|
||||
- `title`
|
||||
- `notes`
|
||||
- `packages`
|
||||
|
||||
证据为 `server/app/adminapi/logic/setting/DesktopWorkstationLogic.php:45-55`。其中
|
||||
`latest_version` / `min_version` 会被正规化为三段版本，包则逐平台正规化
|
||||
`url/sha256/size/filename/type`（`:180-205, 226-254`）。
|
||||
|
||||
`ConfigService::set()` 对数组执行 `json_encode(..., JSON_UNESCAPED_UNICODE)` 后写入 Config 模型的 `value` 字段；标量直接写入（`server/app/common/service/ConfigService.php:32-50`）。因此数据库中的逻辑形态是：
|
||||
|
||||
```text
|
||||
type = desktop_workstation, name = latest_version, value = "1.2.0"
|
||||
type = desktop_workstation, name = packages, value =
|
||||
{"windows_x64":{"url":"...","sha256":"...","size":...,"filename":"...","type":"inno_setup"},...}
|
||||
```
|
||||
|
||||
读取时，`ConfigService::get()` 会对合法 JSON 自动 `json_decode(..., true)`（同文件
|
||||
`:65-85`），所以 `packages` 回到 PHP 数组。保存 URL 时会去掉当前站点/当前存储域名，读取给 API 时再补回绝对域名（`DesktopWorkstationLogic.php:231-252, 261-280`；`server/app/common/service/FileService.php:42-59, 69-78`）。本地 `uploads/...` 文件还会在缺失/无效时由 server 计算哈希、大小和文件名（`DesktopWorkstationLogic.php:309-331`）。
|
||||
|
||||
## 3. 检测 API 如何选择包和序列化响应
|
||||
|
||||
app 请求的端点是 `setting.desktop_workstation/check`（`app/src/doctor_workstation/services/app_update.py:29-35`）。控制器把 `check` 放进免登录列表（`server/app/adminapi/controller/setting/DesktopWorkstationController.php:26-29`），并把 GET 参数直接交给逻辑层（`:48-55`）。
|
||||
|
||||
客户端发送：
|
||||
|
||||
```text
|
||||
current_version=<当前运行时版本>&platform=windows&arch=x64
|
||||
```
|
||||
|
||||
证据为 `app_update.py:217-243`。server 将 `windows/win/win32/win64` 统一成
|
||||
`windows`，把 `amd64/x86_64/x64` 统一成 `x64`，拼成配置键
|
||||
`windows_x64`（`DesktopWorkstationLogic.php:125-153`）。也就是说，`platform` / `arch`
|
||||
不是管理端发布字段，而是由客户端运行环境发给检测接口、用于选择
|
||||
`packages.windows_x64` 的请求维度。
|
||||
|
||||
server 的检测响应由 `evaluate()` 直接组成（`DesktopWorkstationLogic.php:75-103`）：
|
||||
|
||||
- `latest_version` 来自已保存的配置并正规化。
|
||||
- `platform`、`arch` 是请求值正规化后的回显。
|
||||
- `package` 是匹配平台的单个包，只有 `url` 和 `sha256` 都非空才返回，否则为 `null`。
|
||||
- 包对象的键为 `url/sha256/size/filename/type`（`:272-280`）。
|
||||
- `can_install = has_update && url 非空 && sha256 非空`。
|
||||
- `force` 只有存在更新、命中强制策略并且有可安装包时才为 true。
|
||||
|
||||
控制器的 `data()` 最终封装为 `{code, show, msg, data}`（`server/app/common/controller/BaseLikeAdminController.php:50-60`；`server/app/common/service/JsonService.php:71-91`）。app 的 `ApiClient` 对 `code == 1` 返回 envelope 中的 `data`（`app/src/doctor_workstation/services/api_client.py:504-542`），因此 `parse_update_offer()` 收到的就是上面列出的 `data` 对象，而不是整个 envelope。
|
||||
|
||||
## 4. 与 app 客户端契约逐字段对照
|
||||
|
||||
| 语义 | server 实际输出 | app 实际读取 | 是否一致 |
|
||||
|---|---|---|---|
|
||||
| 最新版本 | `latest_version` | `data.get("latest_version")` | 一致（`DesktopWorkstationLogic.php:95`; `app_update.py:174-181`） |
|
||||
| 平台 | `platform` | `data.get("platform")` | 一致（server `:99`; app `:147-150, 176-183`） |
|
||||
| 架构 | `arch` | `data.get("arch")` | 一致（server `:100`; app `:147-150, 176-183`） |
|
||||
| 安装包 | `package` object/null | `data.get("package")` | 一致（server `:101`; app `:151-153`） |
|
||||
| 下载地址 | `package.url` | `package_payload.get("url")` | 一致（server `:275`; app `:154, 166-173`） |
|
||||
| SHA-256 | `package.sha256` | `package_payload.get("sha256")` | 一致（server `:276`; app `:155, 184-188`） |
|
||||
| 包类型 | `package.type` | `package_payload.get("type")` | 一致（server `:279`; app `:157-173`） |
|
||||
| 文件大小 | `package.size` | `package_payload.get("size")` | 一致（server `:277`; app `:158-173`） |
|
||||
| 文件名 | `package.filename` | `package_payload.get("filename")` | 一致（server `:278`; app `:156-173`） |
|
||||
| 可安装 | `can_install` | `data.get("can_install")` + 客户端二次校验 | 一致但客户端更严格（server `:85-102`; app `:184-200`） |
|
||||
|
||||
客户端只认可 `archive` / `inno_setup`，且 Inno 只允许 Windows；它还要求 SHA-256
|
||||
严格为 64 位小写十六进制、响应平台/架构必须与请求一致（`app_update.py:162-200`）。对于
|
||||
`inno_setup`，下载 URL 还必须是 HTTPS（localhost 调试例外），随后下载内容要通过 SHA-256、size、`.exe` 后缀和 PE `MZ` 头校验（`:287-300, 360-397`）。UI 根据 `package.type` 分流：`inno_setup` 直接走 Windows 安装器，`archive` 则按 ZIP 解压（`app/src/doctor_workstation/ui/dialogs/app_update.py:423-449`）。
|
||||
|
||||
现有自动化也明确锁定了这个嵌套契约：server contract test 要求 Windows 包返回
|
||||
`package.type == inno_setup`（`server/tests/DesktopWorkstationUpdateContractTest.php:34-62`）；app test 用
|
||||
`package.{url,sha256,size,filename,type}` 构造响应并验证接收（`app/tests/test_app_update.py:66-90`）。本轮实跑：
|
||||
|
||||
```text
|
||||
php server/tests/DesktopWorkstationUpdateContractTest.php PASS
|
||||
uv run pytest app/tests/test_app_update.py -q PASS (21 tests)
|
||||
```
|
||||
|
||||
## 5. 根因候选（按优先级）
|
||||
|
||||
### A. `latest_version` 与实际安装包版本不一致（当前工作区已有直接证据）
|
||||
|
||||
当前版本源是 `1.2.0`，但现有 EXE/ZIP、SHA256SUMS 和冻结 exe 都是 `1.1.0`。如果截图中的管理端配置已经把最新版本发布为 `1.2.0`，当前 `1.1.0` 包不能作为它的安装包。表现为下载、安装可能成功，但应用重启后仍是旧版本并再次提示更新。
|
||||
|
||||
### B. 线上响应使用 `package_type` / `download_url` 扁平字段
|
||||
|
||||
当前 app 没有这两个 wire key 的兼容读取，仓库内也没有生成它们的 server 代码。如果截图中的实际网络响应是例如：
|
||||
|
||||
```json
|
||||
{"latest_version":"1.2.0","package_type":"inno_setup","download_url":"...","sha256":"..."}
|
||||
```
|
||||
|
||||
app 会因为没有 `package.url` 而得到 `package=None`，最终 `can_install=false`；即使把包放在
|
||||
`package` 中但只给 `package_type`，客户端也会默认当成 `archive`，对 EXE 执行 ZIP 解压并失败。该情形应视为明确的协议不一致。
|
||||
|
||||
### C. admin / server / app 部署版本分叉，或 PHP OPcache 未刷新
|
||||
|
||||
Git 历史显示提交 `43e5411b6a8d2e625140c5dca8ddeb8492ba7daa` 才同步把
|
||||
`type=inno_setup` 加入 admin、server 和 app。它之前的 server 会在保存/读取包时丢掉 `type`。
|
||||
因此“管理页面已有 Inno Setup 下拉框，但 check 响应没有 `package.type`”最符合部分部署或旧 PHP 代码仍在运行，而不是当前源码的逻辑错误。
|
||||
|
||||
### D. SHA-256 非空但无效，server 与 app 的可安装判定强度不同
|
||||
|
||||
`evaluate()` 只检查 URL/哈希非空；app 要求恰好 64 位十六进制。通过正常管理端保存不会发生，因为 validator 会拦截；但旧数据、手工改库、另一服务写入配置时，可能出现 server 返回 `can_install=true`、app 最终降级为不可安装。
|
||||
|
||||
### E. 相对上传路径在 server 输出时被扩成 HTTP
|
||||
|
||||
validator 只对输入字符串显式以 `http://` 开头的 Inno URL 拒绝；`uploads/...` 相对路径可通过。响应时 `FileService::getFileUrl()` 按 `request()->domain()` 补域名。如果生产位于 HTTPS 反向代理后但 PHP 未正确识别代理协议，响应可能变成 `http://...`。app 会安全地拒绝自动执行这个 EXE。若截图中的 `package.url` 为 HTTP，应核对反向代理的 forwarded proto / trusted proxy 配置，而不是放宽客户端安全校验。
|
||||
|
||||
## 6. 建议修复与验证顺序
|
||||
|
||||
1. **先重新打 1.2.0 正式包再发布。** 保持 `app/src/doctor_workstation/__init__.py`、EXE 的 FileVersion/ProductVersion、安装包文件名、管理端 `latest_version` 四者全部为 `1.2.0`；从新生成的 `SHA256SUMS.txt` 复制 EXE 对应哈希，不要复用 1.1.0 的值。
|
||||
2. **直接抓线上 check 响应。** 用与 app 一样的参数请求：
|
||||
`GET /adminapi/setting.desktop_workstation/check?current_version=1.1.0&platform=windows&arch=x64`。确认有效数据位于 `data`，并且字段精确为 `data.package.url/type/sha256`。
|
||||
3. **如果看到 `download_url/package_type`，统一契约。** 首选修 server 采用当前仓库的嵌套结构并整体部署；若必须兼容历史服务，可在 app 解析层短期接受别名，但 canonical 输出仍应只有 `package.{url,type,...}`，并补契约测试。
|
||||
4. **如果 `package.type` 缺失，做完整部署并清 OPcache。** 同时部署 admin 静态资源、PHP controller/logic/validator 和新 app；不要只替换管理页面。
|
||||
5. **核验 URL 与哈希。** `package.url` 必须是客户端可达的 HTTPS 绝对地址；下载文件 SHA-256 必须与 `package.sha256` 完全一致，size 若填写也必须一致。
|
||||
6. **补一条跨端端到端 fixture。** 固化一个 Windows `inno_setup` 响应，既让 PHP `evaluate()` 产出 JSON，也让 Python `parse_update_offer()` 消费同一 fixture；另外增加扁平别名必须被拒绝（或在决定兼容后明确接受）的测试，避免字段名再次漂移。
|
||||
|
||||
## 最小正确发布样例
|
||||
|
||||
管理端保存体中的 Windows 部分：
|
||||
|
||||
```json
|
||||
{
|
||||
"enabled": 1,
|
||||
"latest_version": "1.2.0",
|
||||
"min_version": "",
|
||||
"force_update": 0,
|
||||
"title": "医生工作站 1.2.0",
|
||||
"notes": "...",
|
||||
"packages": {
|
||||
"windows_x64": {
|
||||
"url": "https://cdn.example.com/DoctorWorkstation-Setup-Windows-x64-1.2.0.exe",
|
||||
"sha256": "<新 1.2.0 EXE 的 64 位 SHA-256>",
|
||||
"size": 0,
|
||||
"filename": "DoctorWorkstation-Setup-Windows-x64-1.2.0.exe",
|
||||
"type": "inno_setup"
|
||||
},
|
||||
"macos_arm64": {"url":"","sha256":"","size":0,"filename":"","type":"archive"},
|
||||
"macos_x64": {"url":"","sha256":"","size":0,"filename":"","type":"archive"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
不要把同一内容改名为顶层 `download_url` / `package_type`；当前 app 不消费该形态。
|
||||
@@ -0,0 +1,447 @@
|
||||
"""Read-only-ish timing probe for the desktop update commit sequence.
|
||||
|
||||
The probe imports production code and replaces only its external download/apply
|
||||
edges in memory. It does not modify production sources or existing tests.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import gc
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import threading
|
||||
import time
|
||||
import weakref
|
||||
from pathlib import Path
|
||||
from types import SimpleNamespace
|
||||
from typing import Any
|
||||
|
||||
os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
|
||||
|
||||
from PySide6.QtCore import QCoreApplication, QEvent, QObject, QThreadPool, QTimer
|
||||
from PySide6.QtWidgets import QApplication
|
||||
|
||||
from doctor_workstation.services import app_update as update_service
|
||||
from doctor_workstation.services.app_update import (
|
||||
PACKAGE_TYPE_INNO_SETUP,
|
||||
UpdateOffer,
|
||||
UpdatePackage,
|
||||
)
|
||||
from doctor_workstation.ui.dialogs import app_update as update_ui
|
||||
|
||||
|
||||
def _record(events: list[dict[str, Any]], name: str, started: float) -> None:
|
||||
events.append(
|
||||
{
|
||||
"event": name,
|
||||
"elapsed_ms": round((time.perf_counter() - started) * 1000, 3),
|
||||
"thread_id": threading.get_ident(),
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
def exercise_session(iterations: int = 25) -> dict[str, Any]:
|
||||
app = QApplication.instance() or QApplication([])
|
||||
main_thread = threading.get_ident()
|
||||
original_edges = {
|
||||
"is_frozen_install": update_ui.is_frozen_install,
|
||||
"frozen_install_root": update_ui.frozen_install_root,
|
||||
"download_package": update_ui.download_package,
|
||||
"apply_downloaded_update": update_ui.apply_downloaded_update,
|
||||
}
|
||||
failures: list[dict[str, Any]] = []
|
||||
samples: list[list[dict[str, Any]]] = []
|
||||
collected_signals = 0
|
||||
|
||||
try:
|
||||
with tempfile.TemporaryDirectory(prefix="zyt-update-commit-") as raw_tmp:
|
||||
temp_root = Path(raw_tmp)
|
||||
install_root = temp_root / "installed"
|
||||
install_root.mkdir()
|
||||
(install_root / "DoctorWorkstation.exe").write_bytes(b"MZ")
|
||||
update_ui.is_frozen_install = lambda: True
|
||||
update_ui.frozen_install_root = lambda: install_root
|
||||
|
||||
for index in range(iterations):
|
||||
run_root = temp_root / f"run-{index}"
|
||||
run_root.mkdir()
|
||||
events: list[dict[str, Any]] = []
|
||||
started = time.perf_counter()
|
||||
|
||||
def fake_download(
|
||||
_url: str,
|
||||
destination: Path,
|
||||
*,
|
||||
_events: list[dict[str, Any]] = events,
|
||||
_started: float = started,
|
||||
**kwargs: Any,
|
||||
) -> Path:
|
||||
_record(_events, "download_enter", _started)
|
||||
destination.parent.mkdir(parents=True, exist_ok=True)
|
||||
destination.write_bytes(b"MZ" + b"probe")
|
||||
progress = kwargs.get("progress")
|
||||
if callable(progress):
|
||||
progress(7, 7)
|
||||
_record(_events, "download_return", _started)
|
||||
return destination
|
||||
|
||||
def fake_apply(
|
||||
_payload: Path,
|
||||
*,
|
||||
package_type: str,
|
||||
_events: list[dict[str, Any]] = events,
|
||||
_started: float = started,
|
||||
) -> None:
|
||||
assert package_type == PACKAGE_TYPE_INNO_SETUP
|
||||
_record(_events, "apply_enter", _started)
|
||||
_record(_events, "apply_return", _started)
|
||||
|
||||
update_ui.download_package = fake_download
|
||||
update_ui.apply_downloaded_update = fake_apply
|
||||
|
||||
host = QObject()
|
||||
host.config = SimpleNamespace( # type: ignore[attr-defined]
|
||||
config_dir=run_root,
|
||||
verify_ssl=True,
|
||||
)
|
||||
|
||||
def request_quit(
|
||||
_events: list[dict[str, Any]] = events,
|
||||
_started: float = started,
|
||||
) -> None:
|
||||
_record(_events, "request_quit", _started)
|
||||
|
||||
host.request_quit = request_quit # type: ignore[attr-defined]
|
||||
session = update_ui.AppUpdateSession(host)
|
||||
offer = UpdateOffer(
|
||||
has_update=True,
|
||||
force=True,
|
||||
enabled=True,
|
||||
current_version="1.0.0",
|
||||
latest_version=f"1.0.{index + 1}",
|
||||
min_version="",
|
||||
title="probe",
|
||||
notes="probe",
|
||||
platform="windows",
|
||||
arch="x64",
|
||||
package=UpdatePackage(
|
||||
url="https://example.invalid/DoctorWorkstation-Setup.exe",
|
||||
sha256="a" * 64,
|
||||
size=7,
|
||||
filename="DoctorWorkstation-Setup.exe",
|
||||
type=PACKAGE_TYPE_INNO_SETUP,
|
||||
),
|
||||
can_install=True,
|
||||
)
|
||||
dialog = update_ui.AppUpdateDialog(offer)
|
||||
session.dialog = dialog
|
||||
|
||||
original_finish = session._finish_install
|
||||
original_finished = session._on_install_finished
|
||||
|
||||
def finish_probe(
|
||||
*args: Any,
|
||||
_events: list[dict[str, Any]] = events,
|
||||
_started: float = started,
|
||||
_original: Any = original_finish,
|
||||
**kwargs: Any,
|
||||
) -> None:
|
||||
_record(_events, "result_slot_enter", _started)
|
||||
_original(*args, **kwargs)
|
||||
_record(_events, "result_slot_return", _started)
|
||||
|
||||
def finished_probe(
|
||||
*args: Any,
|
||||
_events: list[dict[str, Any]] = events,
|
||||
_started: float = started,
|
||||
_original: Any = original_finished,
|
||||
**kwargs: Any,
|
||||
) -> None:
|
||||
_record(_events, "finished_slot_enter", _started)
|
||||
_original(*args, **kwargs)
|
||||
_record(_events, "finished_slot_return", _started)
|
||||
|
||||
session._finish_install = finish_probe # type: ignore[method-assign]
|
||||
session._on_install_finished = finished_probe # type: ignore[method-assign]
|
||||
session._start_install(dialog, offer)
|
||||
signal_ref = weakref.ref(session._active_install_signals)
|
||||
|
||||
deadline = time.perf_counter() + 3.0
|
||||
while time.perf_counter() < deadline:
|
||||
app.processEvents()
|
||||
if any(item["event"] == "request_quit" for item in events):
|
||||
break
|
||||
time.sleep(0.001)
|
||||
QThreadPool.globalInstance().waitForDone(3000)
|
||||
app.processEvents()
|
||||
|
||||
names = [item["event"] for item in events]
|
||||
expected = [
|
||||
"download_enter",
|
||||
"download_return",
|
||||
"result_slot_enter",
|
||||
"apply_enter",
|
||||
"apply_return",
|
||||
"result_slot_return",
|
||||
"finished_slot_enter",
|
||||
"request_quit",
|
||||
"finished_slot_return",
|
||||
]
|
||||
slot_threads = {
|
||||
item["thread_id"]
|
||||
for item in events
|
||||
if item["event"] in {"result_slot_enter", "finished_slot_enter", "request_quit"}
|
||||
}
|
||||
if names != expected or slot_threads != {main_thread}:
|
||||
failures.append(
|
||||
{
|
||||
"iteration": index,
|
||||
"events": events,
|
||||
"main_thread_id": main_thread,
|
||||
}
|
||||
)
|
||||
if index < 3:
|
||||
samples.append(events)
|
||||
|
||||
session.deleteLater()
|
||||
dialog.deleteLater()
|
||||
del session, dialog, host
|
||||
QCoreApplication.sendPostedEvents(None, QEvent.Type.DeferredDelete)
|
||||
app.processEvents()
|
||||
gc.collect()
|
||||
app.processEvents()
|
||||
if signal_ref() is None:
|
||||
collected_signals += 1
|
||||
finally:
|
||||
update_ui.is_frozen_install = original_edges["is_frozen_install"]
|
||||
update_ui.frozen_install_root = original_edges["frozen_install_root"]
|
||||
update_ui.download_package = original_edges["download_package"]
|
||||
update_ui.apply_downloaded_update = original_edges["apply_downloaded_update"]
|
||||
|
||||
return {
|
||||
"iterations": iterations,
|
||||
"failures": failures,
|
||||
"signals_collected_after_iteration": collected_signals,
|
||||
"main_thread_id": main_thread,
|
||||
"samples": samples,
|
||||
}
|
||||
|
||||
|
||||
def exercise_real_popen() -> dict[str, Any]:
|
||||
if sys.platform != "win32":
|
||||
return {"skipped": f"requires win32, got {sys.platform}"}
|
||||
with tempfile.TemporaryDirectory(prefix="zyt-update-helper-") as raw_tmp:
|
||||
temp_root = Path(raw_tmp)
|
||||
script = temp_root / "probe_helper.ps1"
|
||||
script.write_text(
|
||||
"\n".join(
|
||||
[
|
||||
"param(",
|
||||
" [int]$TargetPid, [string]$Installer, [string]$RestartExe,",
|
||||
" [string]$HelperLogFile, [string]$InstallerLogFile",
|
||||
")",
|
||||
"Set-Content -LiteralPath $HelperLogFile -Value 'child-started'",
|
||||
"Start-Sleep -Milliseconds 1200",
|
||||
"Set-Content -LiteralPath $HelperLogFile -Value 'child-complete'",
|
||||
]
|
||||
),
|
||||
encoding="utf-8-sig",
|
||||
)
|
||||
installer = temp_root / "Setup.exe"
|
||||
installer.write_bytes(b"MZ")
|
||||
restart = temp_root / "DoctorWorkstation.exe"
|
||||
restart.write_bytes(b"MZ")
|
||||
helper_log = temp_root / "helper.log"
|
||||
fixed_log = temp_root / "fixed.log"
|
||||
installer_log = temp_root / "installer.log"
|
||||
original_script = script.read_text(encoding="utf-8-sig")
|
||||
fixed_log_literal = str(fixed_log).replace("'", "''")
|
||||
script.write_text(
|
||||
original_script.replace(
|
||||
"Set-Content -LiteralPath $HelperLogFile -Value 'child-started'",
|
||||
"Set-Content -LiteralPath '"
|
||||
+ fixed_log_literal
|
||||
+ "' -Value (\"helper=<{0}> args=<{1}>\" -f $HelperLogFile, ($args -join '|'))\n"
|
||||
+ "Set-Content -LiteralPath $HelperLogFile -Value 'child-started'",
|
||||
),
|
||||
encoding="utf-8-sig",
|
||||
)
|
||||
captured: list[subprocess.Popen[Any]] = []
|
||||
captured_calls: list[tuple[tuple[Any, ...], dict[str, Any]]] = []
|
||||
real_popen = update_service.subprocess.Popen
|
||||
|
||||
def capture_popen(*args: Any, **kwargs: Any) -> subprocess.Popen[Any]:
|
||||
captured_calls.append((args, kwargs.copy()))
|
||||
process = real_popen(*args, **kwargs)
|
||||
captured.append(process)
|
||||
return process
|
||||
|
||||
update_service.subprocess.Popen = capture_popen
|
||||
try:
|
||||
started = time.perf_counter()
|
||||
update_service._spawn_inno_setup_applier(
|
||||
script,
|
||||
installer=installer,
|
||||
restart_exe=restart,
|
||||
helper_log_file=helper_log,
|
||||
installer_log_file=installer_log,
|
||||
)
|
||||
returned_ms = round((time.perf_counter() - started) * 1000, 3)
|
||||
finally:
|
||||
update_service.subprocess.Popen = real_popen
|
||||
deadline = time.perf_counter() + 2.5
|
||||
child_log = ""
|
||||
while time.perf_counter() < deadline:
|
||||
if helper_log.exists():
|
||||
child_log = helper_log.read_text(encoding="utf-8").strip()
|
||||
if child_log == "child-complete":
|
||||
break
|
||||
time.sleep(0.05)
|
||||
return_code = captured[0].poll() if captured else None
|
||||
if captured and return_code is None:
|
||||
return_code = captured[0].wait(timeout=2.0)
|
||||
matrix: dict[str, Any] = {}
|
||||
if captured_calls:
|
||||
command = list(captured_calls[0][0][0])
|
||||
flag_cases = {
|
||||
"zero": 0,
|
||||
"detached": getattr(subprocess, "DETACHED_PROCESS", 0),
|
||||
"new_process_group": getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0),
|
||||
"no_window": getattr(subprocess, "CREATE_NO_WINDOW", 0),
|
||||
"detached_new_group": getattr(subprocess, "DETACHED_PROCESS", 0)
|
||||
| getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0),
|
||||
"detached_no_window": getattr(subprocess, "DETACHED_PROCESS", 0)
|
||||
| getattr(subprocess, "CREATE_NO_WINDOW", 0),
|
||||
"new_group_no_window": getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
|
||||
| getattr(subprocess, "CREATE_NO_WINDOW", 0),
|
||||
"production_all": getattr(subprocess, "DETACHED_PROCESS", 0)
|
||||
| getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
|
||||
| getattr(subprocess, "CREATE_NO_WINDOW", 0),
|
||||
}
|
||||
running: dict[str, tuple[subprocess.Popen[Any], Path]] = {}
|
||||
helper_parameter = command.index("-HelperLogFile") + 1
|
||||
for name, flags in flag_cases.items():
|
||||
case_command = command.copy()
|
||||
case_log = temp_root / f"matrix-{name}.log"
|
||||
case_command[helper_parameter] = str(case_log)
|
||||
process = real_popen(
|
||||
case_command,
|
||||
close_fds=True,
|
||||
creationflags=flags,
|
||||
cwd=str(temp_root),
|
||||
stdout=subprocess.DEVNULL,
|
||||
stderr=subprocess.DEVNULL,
|
||||
)
|
||||
running[name] = (process, case_log)
|
||||
production_flags = flag_cases["production_all"]
|
||||
detached_flags = flag_cases["detached"]
|
||||
extra_cases = {
|
||||
"production_close_false": (production_flags, False, False),
|
||||
"production_all_devnull": (production_flags, True, True),
|
||||
"detached_close_false": (detached_flags, False, False),
|
||||
"detached_all_devnull": (detached_flags, True, True),
|
||||
}
|
||||
for name, (flags, close_fds, all_devnull) in extra_cases.items():
|
||||
case_command = command.copy()
|
||||
case_log = temp_root / f"matrix-{name}.log"
|
||||
case_command[helper_parameter] = str(case_log)
|
||||
stream_kwargs = (
|
||||
{
|
||||
"stdin": subprocess.DEVNULL,
|
||||
"stdout": subprocess.DEVNULL,
|
||||
"stderr": subprocess.DEVNULL,
|
||||
}
|
||||
if all_devnull
|
||||
else {}
|
||||
)
|
||||
process = real_popen(
|
||||
case_command,
|
||||
close_fds=close_fds,
|
||||
creationflags=flags,
|
||||
cwd=str(temp_root),
|
||||
**stream_kwargs,
|
||||
)
|
||||
flag_cases[name] = flags
|
||||
running[name] = (process, case_log)
|
||||
matrix_deadline = time.perf_counter() + 3.0
|
||||
while time.perf_counter() < matrix_deadline:
|
||||
if all(case_log.exists() for _, case_log in running.values()):
|
||||
break
|
||||
time.sleep(0.05)
|
||||
for name, (process, case_log) in running.items():
|
||||
matrix[name] = {
|
||||
"flags": flag_cases[name],
|
||||
"log_created": case_log.exists(),
|
||||
"return_code": process.poll(),
|
||||
}
|
||||
control_return_code = None
|
||||
control_stdout = ""
|
||||
control_stderr = ""
|
||||
if not fixed_log.exists() and captured_calls:
|
||||
call_args, call_kwargs = captured_calls[0]
|
||||
call_kwargs.update(
|
||||
creationflags=0,
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.PIPE,
|
||||
text=True,
|
||||
)
|
||||
control = real_popen(*call_args, **call_kwargs)
|
||||
control_stdout, control_stderr = control.communicate(timeout=5.0)
|
||||
control_return_code = control.returncode
|
||||
return {
|
||||
"command": captured_calls[0][0][0] if captured_calls else [],
|
||||
"spawn_returned_ms": returned_ms,
|
||||
"child_completed": child_log == "child-complete",
|
||||
"child_log": child_log,
|
||||
"fixed_log": fixed_log.read_text(encoding="utf-8").strip()
|
||||
if fixed_log.exists()
|
||||
else "",
|
||||
"child_return_code": return_code,
|
||||
"flag_matrix": matrix,
|
||||
"control_return_code": control_return_code,
|
||||
"control_stdout": control_stdout,
|
||||
"control_stderr": control_stderr,
|
||||
}
|
||||
|
||||
|
||||
def exercise_controller_quit() -> dict[str, Any]:
|
||||
"""Run the production request_quit method against a real Qt event loop."""
|
||||
|
||||
from doctor_workstation.app import ApplicationController
|
||||
|
||||
app = QApplication.instance() or QApplication([])
|
||||
events: list[str] = []
|
||||
holder = SimpleNamespace(application=app, _shutting_down=False)
|
||||
app.aboutToQuit.connect(lambda: events.append("aboutToQuit"))
|
||||
QTimer.singleShot(
|
||||
0,
|
||||
lambda: (
|
||||
events.append("request_quit_enter"),
|
||||
ApplicationController.request_quit(holder),
|
||||
events.append("request_quit_return"),
|
||||
),
|
||||
)
|
||||
watchdog = QTimer()
|
||||
watchdog.setSingleShot(True)
|
||||
watchdog.timeout.connect(lambda: (events.append("watchdog"), app.quit()))
|
||||
watchdog.start(1000)
|
||||
started = time.perf_counter()
|
||||
return_code = app.exec()
|
||||
return {
|
||||
"events": events,
|
||||
"return_code": return_code,
|
||||
"returned_ms": round((time.perf_counter() - started) * 1000, 3),
|
||||
}
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
iteration_count = int(sys.argv[1]) if len(sys.argv) > 1 else 25
|
||||
output = {
|
||||
"session": exercise_session(iteration_count),
|
||||
"real_popen": exercise_real_popen(),
|
||||
"controller_quit": exercise_controller_quit(),
|
||||
}
|
||||
print(json.dumps(output, ensure_ascii=False, indent=2))
|
||||
@@ -0,0 +1,200 @@
|
||||
# AppUpdateSession 更新提交时序复现报告
|
||||
|
||||
日期：2026-08-28
|
||||
环境：Windows、Python 3.12.13、PySide6 6.11.1、uv 0.11.8
|
||||
范围：只读检查生产源码和现有测试；新增的唯一测试资产是
|
||||
`app/research/update_commit_repro.py`，未修改生产源码和既有测试。
|
||||
|
||||
## 结论
|
||||
|
||||
1. **当前工作树中的 `result -> finished -> request_quit` 时序可以稳定复现为正确。**
|
||||
100 次真实 `QThreadPool` 跨线程循环没有一次乱序或丢失：下载/prepare 在 worker
|
||||
线程，`_finish_install()`、`_on_install_finished()` 和 `request_quit()` 都在 GUI 主线程。
|
||||
2. **`_TaskSignals` 不会因局部变量释放而提前消失。** 安装期间它同时被 `_Task`、
|
||||
`AppUpdateSession._signals` 和 `_active_install_signals` 强引用；`finished` 到达后才清空
|
||||
session 引用。探针在主动 `gc.collect()` 后仍观察到 wrapper 存活，风险方向是残留/泄漏，
|
||||
不是过早 GC 导致信号丢失。
|
||||
3. **`ApplicationController.request_quit()` 本身有效。** 在真实 Qt 事件循环里，调用顺序是
|
||||
`request_quit_enter -> request_quit_return -> aboutToQuit`，没有触发 1 秒 watchdog；本次
|
||||
测量从进入事件循环到退出约 0.1 ms。
|
||||
4. **`apply_downloaded_update()` 的 `Popen` 调用不阻塞 GUI。** 生产参数下
|
||||
`_spawn_inno_setup_applier()` 约 2.7--4.7 ms 返回。
|
||||
5. **真正可复现的安装失败位于 Windows helper 启动。** 当前代码组合
|
||||
`DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW` 启动 Windows
|
||||
PowerShell。调用会快速返回，PowerShell 进程退出码甚至是 0，但脚本没有执行第一条写日志
|
||||
命令。标志矩阵表明：本机上任何包含 `DETACHED_PROCESS` 的组合都失败；去掉它后，
|
||||
`CREATE_NEW_PROCESS_GROUP`、`CREATE_NO_WINDOW` 以及两者组合均能执行脚本。
|
||||
6. **本机真实 18:08 更新尝试与复现完全一致。** 安装包和 `install_update.ps1` 都在
|
||||
18:08:37 生成，证明 Qt `result` 已投递且 `_finish_install()` 已进入
|
||||
`apply_downloaded_update()`；但同目录没有 `update_helper.log` 和 `inno_setup.log`，说明
|
||||
helper 没有运行到脚本第 20 行的第一条 `Write-Log`。
|
||||
|
||||
因此，“下载完成后没有进入安装”的首要根因不是 `finished` 信号丢失，也不是
|
||||
`request_quit()` 失效，而是 **`DETACHED_PROCESS` 令 PowerShell helper 静默不执行**。
|
||||
当前源码仍会在 `finished` 后请求退出，所以如果现场描述为“窗口也一直不关闭”，这部分在当前
|
||||
工作树中未能复现；现有日志更符合“应用已走到提交/退出路径，但安装器从未启动，因此没有安装
|
||||
和重启”的用户观感。成功路径没有阶段日志，无法仅凭旧日志证明窗口具体关闭时刻。
|
||||
|
||||
## 源码时序
|
||||
|
||||
相关位置：
|
||||
|
||||
- `app/src/doctor_workstation/ui/dialogs/app_update.py:68-91`：`_Task.run()` 在同一个
|
||||
`try/else/finally` 中先 `result.emit(result)`，再 `finished.emit()`。
|
||||
- `app/src/doctor_workstation/ui/dialogs/app_update.py:503-555`：安装任务创建
|
||||
`_TaskSignals`，保存到 `_signals` 和 `_active_install_signals`，然后连接
|
||||
`progress/status/result/error/finished`。
|
||||
- `app/src/doctor_workstation/ui/dialogs/app_update.py:601-641`：`result` 槽先设置
|
||||
`_apply_committed=True` 并同步调用 `apply_downloaded_update()`；`finished` 槽随后清理活动
|
||||
signals，并在 `_apply_committed` 或 `_exit_requested` 时调用 `_complete_quit()`。
|
||||
- `app/src/doctor_workstation/app.py:1081-1086`：controller 通过
|
||||
`QTimer.singleShot(0, application.quit)` 请求正常退出。
|
||||
- `app/src/doctor_workstation/app.py:427,1088-1105`：`aboutToQuit` 同步进入幂等
|
||||
`shutdown()`，更新 session 先被 invalidated，再清理视频和 remote client。
|
||||
- `app/src/doctor_workstation/services/app_update.py:637-672`：Inno helper 的 Windows
|
||||
`Popen` 和三个 creation flags。
|
||||
|
||||
必须注意一个 Qt 细节：worker 发出 `result` 后不会等待 GUI 槽执行，紧接着就发出
|
||||
`finished`；两者作为同一 sender 的跨线程事件按连接顺序排入 GUI 队列。本次 100 次实测均为：
|
||||
|
||||
```text
|
||||
worker: download/prepare return
|
||||
-> GUI: result slot enter
|
||||
-> GUI: apply_downloaded_update enter/return
|
||||
-> GUI: result slot return
|
||||
-> GUI: finished slot enter
|
||||
-> GUI: request_quit
|
||||
```
|
||||
|
||||
这也意味着：如果 `apply_downloaded_update()` 真正阻塞，排在它后面的 `finished` 和 quit 会一起
|
||||
延迟。但本机真实 `Popen` 返回只需数毫秒，未观察到阻塞。
|
||||
|
||||
## 复现结果
|
||||
|
||||
### 1. 现有测试
|
||||
|
||||
```powershell
|
||||
$env:QT_QPA_PLATFORM='offscreen'
|
||||
uv run --project app pytest app/tests/test_app_update_ui.py app/tests/test_app_update.py -q
|
||||
```
|
||||
|
||||
结果：`28 passed`。
|
||||
|
||||
现有 `test_session_waits_for_update_worker_before_quitting` 是直接调用私有槽的同步单元测试，能够
|
||||
检查状态门禁，但没有经过 `QThreadPool`/Qt queued delivery；这正是独立探针需要补足的部分。
|
||||
|
||||
### 2. 独立跨线程与 helper 探针
|
||||
|
||||
```powershell
|
||||
$env:QT_QPA_PLATFORM='offscreen'
|
||||
uv run --project app python app/research/update_commit_repro.py 100
|
||||
```
|
||||
|
||||
关键结果：
|
||||
|
||||
```text
|
||||
session.iterations = 100
|
||||
session.failures = []
|
||||
|
||||
worker thread != GUI thread
|
||||
result_slot_enter.thread_id == finished_slot_enter.thread_id
|
||||
request_quit.thread_id == GUI main thread
|
||||
|
||||
_spawn_inno_setup_applier return = 约 3 ms
|
||||
production flags script log created = false
|
||||
production PowerShell return code = 0
|
||||
|
||||
controller quit events =
|
||||
request_quit_enter, request_quit_return, aboutToQuit
|
||||
```
|
||||
|
||||
Windows 创建标志矩阵：
|
||||
|
||||
| creation flags | 脚本是否执行 |
|
||||
|---|---:|
|
||||
| `0` | 是 |
|
||||
| `CREATE_NEW_PROCESS_GROUP` | 是 |
|
||||
| `CREATE_NO_WINDOW` | 是 |
|
||||
| `CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW` | 是 |
|
||||
| `DETACHED_PROCESS` | 否 |
|
||||
| `DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP` | 否 |
|
||||
| `DETACHED_PROCESS | CREATE_NO_WINDOW` | 否 |
|
||||
| 当前生产三标志组合 | 否 |
|
||||
|
||||
将 `close_fds` 改为 false，或给 stdin/stdout/stderr 全部接 `DEVNULL`，均不能挽救包含
|
||||
`DETACHED_PROCESS` 的组合。
|
||||
|
||||
### 3. 真实运行残留
|
||||
|
||||
本机目录：
|
||||
|
||||
```text
|
||||
C:\Users\pc\AppData\Local\ZhenYangTang\ZhenyangDoctor\updates\1_3_0\
|
||||
```
|
||||
|
||||
18:08:37 已有：
|
||||
|
||||
- `DoctorWorkstation-Setup-Windows-x64-1.1.0.exe`
|
||||
- `install_update.ps1`
|
||||
|
||||
不存在：
|
||||
|
||||
- `update_helper.log`
|
||||
- `inno_setup.log`
|
||||
|
||||
`install_update.ps1` 只会在 `_finish_install() -> apply_downloaded_update() ->
|
||||
apply_inno_setup_update()` 中生成，所以这组残留直接排除了“result 未投递”和
|
||||
“`_TaskSignals` 被提前回收”。脚本第一项业务动作就是写 `waiting for pid ...`；没有 helper log
|
||||
则失败发生在脚本业务逻辑之前。
|
||||
|
||||
另有一个独立的发布数据风险：workspace 名为 `1_3_0`，下载文件名却是 `1.1.0`，而请求中的
|
||||
当前版本是 `1.2.0`。即使 helper 启动成功，也可能尝试降级安装。服务端 offer 的
|
||||
`latest_version`、package filename、安装器 FileVersion/产品版本需要在发布端和客户端都做一致性
|
||||
校验。这不是本次 helper 不启动的直接原因，但上线前必须处理。
|
||||
|
||||
## 建议修复方向
|
||||
|
||||
1. Windows helper 不使用 `DETACHED_PROCESS`；先验证保留
|
||||
`CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW` 时，父进程结束后 helper 仍能存活并运行。
|
||||
2. 不把 `Popen()` 成功等同于 helper 已启动。让 helper 在等待目标 PID 前先原子写一个
|
||||
`ready`/`waiting` 标记，应用收到握手后才设置最终 commit 并退出；握手超时则留在应用内显示
|
||||
明确错误。
|
||||
3. 给成功路径补结构化日志：`prepare_result_received`、`helper_spawn_requested`、
|
||||
`helper_ready`、`worker_finished`、`request_quit`、`about_to_quit`。当前只有异常日志，现场无法
|
||||
区分“100% 后仍在 fsync/校验”“helper 启动失败”和“quit 清理较慢”。
|
||||
4. 对 package 声明版本和安装器版本做一致性校验，拒绝低于当前版本或不同于
|
||||
`latest_version` 的安装器。
|
||||
|
||||
## 建议回归测试
|
||||
|
||||
### Qt/session 测试
|
||||
|
||||
1. **真实 queued delivery 成功路径**：用 `QThreadPool` 启动 `_Task`，以 event loop 等待，断言
|
||||
`result slot -> apply return -> finished slot -> request_quit` 严格顺序，并断言所有 UI/controller
|
||||
槽都在 GUI 线程。
|
||||
2. **signals 生命周期**：启动任务后删除局部 worker/signals 引用并强制 GC，仍应收到 result 和
|
||||
finished；finished 后断开连接并 `deleteLater()`，最终 weakref 应释放，避免长期检查导致残留。
|
||||
3. **apply 门控**：用 `Event` 暂停 fake apply，断言暂停期间不会调用 quit；释放后 finished 只触发
|
||||
一次 quit。
|
||||
4. **apply 失败**：`apply_downloaded_update()` 抛 `AppUpdateError` 时不 quit、
|
||||
`_apply_committed` 恢复 false；另外补非 `AppUpdateError` 异常，避免意外异常留下 commit=true 后
|
||||
仍被 finished 退出。
|
||||
5. **controller 集成**：在真实 `QApplication.exec()` 中调用 controller `request_quit()`，spy
|
||||
`aboutToQuit`、`app_updater.shutdown()` 和远程 client close，断言各一次且总时长有上界。
|
||||
|
||||
### Windows helper 测试
|
||||
|
||||
1. **sentinel 启动测试（当前代码应失败）**：生成只写 sentinel 的 PowerShell 文件，使用生产
|
||||
`_spawn_inno_setup_applier()` 启动，2 秒内必须看到 sentinel；不能只断言 `Popen` 被调用。
|
||||
2. **父进程退出测试**：子 Python 进程启动 helper 后立即退出；helper 应先记录 waiting/ready，
|
||||
再观察父 PID 消失并写第二个 sentinel，证明去掉 `DETACHED_PROCESS` 后不会被父退出连带杀死。
|
||||
3. **完整握手测试**：应用只有在 helper ready 后才调用 quit；helper 未 ready、提前退出或无法写
|
||||
日志时，应用保留并展示可重试错误。
|
||||
4. **打包 smoke**：从实际 PyInstaller onedir/installer 环境执行上述测试，不能只在源码虚拟环境
|
||||
mock `subprocess.Popen`。
|
||||
|
||||
## 仓库说明
|
||||
|
||||
根 `AGENTS.md` 声明项目由 Trellis 管理，但当前工作区没有 `.trellis/` 目录，因而无法读取
|
||||
`.trellis/workflow.md` 或 layer spec；本次按根指令执行并在此记录。工作树原本已有大量未提交
|
||||
修改，本次没有改动其中任何生产源码或既有测试。
|
||||
@@ -0,0 +1,115 @@
|
||||
# Windows 更新安装交接故障诊断
|
||||
|
||||
## 结论
|
||||
|
||||
“下载完成后显示即将关闭，但程序不退出/不安装”不是下载失败。当前现场同时存在三个问题，其中第 1 项能够确定性复现用户看到的主症状，第 2 项是本次现场已经发生但被代码吞掉的 helper 启动失败，第 3 项是必须立即纠正的发布配置错误。
|
||||
|
||||
1. **确定性根因：强制更新对话框拒绝了 `QApplication.quit()` 触发的关闭事件。** 下载 job 完成后，session 启动 helper、设置 `_apply_committed=True`，随后在 `finished` 回调中调用应用级 `request_quit()`；但对话框此时仍是 `offer.force=True` 且 `_busy=True`，其 `closeEvent()` 无条件 `ignore()`。Qt 明确允许窗口通过 Close event 阻止 `quit()`，所以事件循环不退出，`aboutToQuit`/`ApplicationController.shutdown()` 也不会发生。helper 又先等待当前 PID 消失，于是交接形成闭环等待。
|
||||
2. **独立的已确认问题：PowerShell helper 进程被创建后，在执行脚本首条日志之前就退出了，而父进程把“CreateProcess 成功”误判成“helper 已接管”。** 现场有精确的 PowerShell 启动事件，但没有 `update_helper.log`、没有 `inno_setup.log`、没有存活 helper/installer 进程。代码丢弃 `Popen` 句柄、不检查早退、也没有 ready handshake，因此 UI 仍停在“即将关闭”。现有证据不足以还原该次子进程的退出码；这正是当前可观测性缺口。
|
||||
3. **发布配置错误：服务端宣称最新/最低版本为 `1.3.0`，实际下发的安装器却是 `1.1.0`。** 本机当前运行 `1.2.0`，所以即使退出与 helper 均修复，也会尝试降级安装，而不是升级到 `1.3.0`。修复客户端前应先停止这条强制更新配置。
|
||||
|
||||
## 代码交接链路与根因证据
|
||||
|
||||
### 1. UI 已经请求退出，但强制对话框否决退出
|
||||
|
||||
当前交接顺序是：
|
||||
|
||||
1. `_start_install()` 设置 busy、启动 QThreadPool 下载 job（`app/src/doctor_workstation/ui/dialogs/app_update.py:481-555`）。
|
||||
2. job 下载并校验 Inno Setup EXE，返回 `_PreparedUpdate`（`:511-545`）。
|
||||
3. `_finish_install()` 先显示“即将关闭程序并自动安装”，再调用 `dialog.set_apply_committed()`；该方法把 `_busy` 保持为 true（`:616-628`、`:275-283`）。
|
||||
4. `apply_downloaded_update()` 进入 `apply_inno_setup_update()`，写脚本并 `Popen` PowerShell helper（`app/src/doctor_workstation/services/app_update.py:429-472`）。
|
||||
5. QRunnable 随后发送 `finished`，`_on_install_finished()` 清理 active signals 并调用 `_complete_quit()`（UI `:634-641`）。
|
||||
6. `_complete_quit()` 调用 controller `request_quit()`；controller 用 `QTimer.singleShot(0, self.application.quit)` 请求正常退出（UI `:472-479`；`app/src/doctor_workstation/app.py:1081-1086`）。
|
||||
7. 但是更新对话框的 `closeEvent()` 在 `offer.force` **或** `_busy` 为真时执行 `event.ignore()`（UI `:296-300`）。此时两个条件都为真。
|
||||
|
||||
使用当前 PySide6 做了不改文件的最小事件循环复现：显示一个 modal dialog，其 `closeEvent()` 执行 `ignore()`，50 ms 后调用 `QApplication.quit()`，并设置 2 秒进程级 watchdog。输出为：
|
||||
|
||||
```text
|
||||
calling quit
|
||||
closeEvent ignored
|
||||
CODE=9
|
||||
```
|
||||
|
||||
也就是 `quit()` 确实到达了窗口，但被 Close event 否决，事件循环直到 watchdog 才终止。Qt 官方文档同样说明 `QCoreApplication.quit()` 可能被仍未关闭的窗口或被忽略的 Quit/Close event 阻止：<https://doc.qt.io/qt-6/qcoreapplication.html#quit>。
|
||||
|
||||
这也解释了为何 controller 的 `aboutToQuit -> shutdown()` 接线本身没有帮助：`aboutToQuit` 只有在退出请求未被阻止时才会发出（`app.py:425-427`、`:1088-1105`）。
|
||||
|
||||
### 2. Inno helper 的等待设计放大了 UI 退出缺陷
|
||||
|
||||
生成的 `install_update.ps1` 首先写 `waiting for pid ...`，然后无限轮询 `Get-Process -Id $TargetPid`；只有目标 PID 消失后才启动安装器（service `:566-627`）。父进程传入的是 `os.getpid()`（`:637-672`）。因此，只要 Qt 主进程被对话框留下，安装器就不可能启动。
|
||||
|
||||
安装器参数本身与 Inno 静默更新意图一致：`/VERYSILENT`、`/SUPPRESSMSGBOXES`、`/NORESTART`、`/CLOSEAPPLICATIONS`、`/NOFORCECLOSEAPPLICATIONS`、`/NORESTARTAPPLICATIONS`、`/LOG=...`；返回 `0`/`3010` 后才重启已安装的 `DoctorWorkstation.exe`，其他返回码重启旧程序（`:599-627`）。`powershell.exe -File <script> <script args>` 的排列也符合 Windows PowerShell 5.1 的 `-File` 契约：<https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_powershell_exe?view=powershell-5.1>。
|
||||
|
||||
不过当前等待还有两个健壮性问题：
|
||||
|
||||
- 循环无超时、只按整数 PID 查询；极端情况下 PID 被复用会继续等待无关进程。更安全的是先取得特定 `Process` 对象/句柄，再等待该对象退出，而不是每 400 ms 重新按 ID 查找。
|
||||
- helper 的成功标准只是 `subprocess.Popen(...)` 没有同步抛出 `OSError`。`Popen` 返回后句柄立即丢失，没有 child PID 日志、早退检测、stderr 捕获或 ready handshake（`:637-672`）。
|
||||
|
||||
当前还同时设置 `DETACHED_PROCESS`、`CREATE_NEW_PROCESS_GROUP`、`CREATE_NO_WINDOW`（`:645-670`）。Microsoft 文档指出 `CREATE_NO_WINDOW` 与 `DETACHED_PROCESS` 同用时会被忽略，因此这组 flag 至少是冗余且不能证明 helper 已进入脚本：<https://learn.microsoft.com/en-us/windows/win32/procthread/process-creation-flags>。本次现场只能确认 PowerShell 在脚本体前早退，不能仅凭事件日志断言具体是 flag、stdio、执行策略还是主机初始化中的哪一个原因；修复应以“可确认接管”为契约，而不是猜一个退出原因。
|
||||
|
||||
### 3. `apply_downloaded_update()` 的路由本身正确
|
||||
|
||||
`package_type=inno_setup` 会进入 `apply_inno_setup_update()`；后者要求 Windows、可解析的 frozen install root、存在的已安装 EXE，以及扩展名为 `.exe` 且 DOS header 为 `MZ` 的安装器（service `:390-401`、`:429-483`）。现场已经生成 `install_update.ps1`，证明路由、install root、EXE/PE 基本校验均已通过；故障发生在 helper 启动及应用退出交接之后。
|
||||
|
||||
## 本机现场证据（2026-08-28，Asia/Shanghai）
|
||||
|
||||
- 运行进程：PID `36304`，`C:\Program Files\ZYT\DoctorWorkstation\DoctorWorkstation.exe`，启动于 `18:08:13`；检查时仍 `Responding=True`、主窗口可见，文件 `ProductVersion=1.2.0`。
|
||||
- 应用日志：`C:\Users\pc\AppData\Local\Zhenyangtang\ZhenyangDoctor\Logs\doctor-workstation.log`。
|
||||
- `18:08:13`：应用启动。
|
||||
- `18:08:15`：以 `current_version=1.2.0&platform=windows&arch=x64` 检查更新成功。
|
||||
- `18:08:32`：下载 `DoctorWorkstation-Setup-Windows-x64-1.1.0.exe` 返回 HTTP 200。
|
||||
- 此后没有安装/helper/退出阶段日志，也没有 Python 异常。
|
||||
- 工作区：`C:\Users\pc\AppData\Local\Zhenyangtang\ZhenyangDoctor\updates\1_3_0`。
|
||||
- 安装器大小 `162,873,123` 字节，SHA-256 `0CDD38DB6EEF5E7B7380FFAE3FBC407B602EB916C68AE4C8F29496B621F50789`，`ProductVersion=1.1.0`，未签名。
|
||||
- `install_update.ps1` 在 `18:08:37` 生成，PowerShell AST 解析无语法错误。
|
||||
- `update_helper.log` 不存在；`inno_setup.log` 不存在。
|
||||
- Windows PowerShell Operational 日志：`18:08:37.828` 有 Event `40961`“Powershell 控制台正在启动”，没有配对的 ready `40962`；检查时也没有命令行指向 `install_update.ps1` 的 PowerShell 或 Inno Setup 进程。这证明子进程被创建过，但没有进入脚本首条 `Write-Log`。
|
||||
- crash log 只有各次进程启动标记，本次没有崩溃堆栈。
|
||||
- 实时只读请求更新接口得到：`latest_version=1.3.0`、`min_version=1.3.0`、`force=true`，但 URL、filename、size、sha256 全都对应上述 `1.1.0` 安装器。本机实测文件 hash 与接口 SHA 一致，说明下载正确，错误在发布元数据/产物绑定。
|
||||
|
||||
## 最小安全修复
|
||||
|
||||
### P0：先修发布配置
|
||||
|
||||
在正确的 `1.3.0` 安装器上传并核对 `ProductVersion`、filename、size、SHA-256 前，立即关闭这条强制更新或将其设为不可安装。不要让 `latest_version=1.3.0` 继续绑定 `1.1.0` 安装器。客户端后续应增加“offer 版本与包版本”的发布门禁；仅校验 HTTPS、SHA 和 `MZ` 不能防止签名正确的旧包被错误发布。
|
||||
|
||||
### P0：让应用级退出能够越过“用户不可关闭”的对话框门禁
|
||||
|
||||
不要把“禁止用户关闭强制更新弹窗”和“禁止应用已提交后的受控退出”共用同一个 `closeEvent` 条件。建议增加明确的 `_allow_application_exit` 状态：
|
||||
|
||||
- 用户点击标题栏关闭/Escape 时仍然拒绝；
|
||||
- helper 已确认接管，或用户点击专用“退出软件”且更新 worker 已安全结束时，session 先设置 allow 状态并关闭/隐藏该 dialog，再调用 controller `request_quit()`；
|
||||
- `closeEvent()` 仅在 `not _allow_application_exit and (offer.force or _busy)` 时 ignore。
|
||||
|
||||
直接在主线程调用 `QCoreApplication.exit(0)`也能绕过 Close event，但会绕过其他窗口的正常 close 协议；相比之下，显式放行本更新对话框后继续走既有 `QApplication.quit -> aboutToQuit -> shutdown` 更小、更安全。
|
||||
|
||||
### P0：把 helper“已接管”变成可验证状态
|
||||
|
||||
`_spawn_inno_setup_applier()` 应返回并保留 `Popen`/child PID，且 helper 在做任何 PID 等待前原子写入 ready 标记（或首条结构化 bootstrap log）。父进程应异步等待一个很短且有界的 ready 窗口：
|
||||
|
||||
- ready 到达且 child 仍存活后，才设置 `_apply_committed=True`、放行 dialog close、请求主程序退出；
|
||||
- child 在 ready 前退出时，读取退出码/bootstrap stderr，留在当前 UI 显示错误，不退出主程序；
|
||||
- 使用 `-NonInteractive`，明确重定向 stdin/stdout/stderr 到日志或 `DEVNULL`；规范化 creation flags，不同时依赖会被忽略的 `DETACHED_PROCESS + CREATE_NO_WINDOW`；
|
||||
- helper 顶层捕获脚本初始化、首条日志、PID wait、安装器启动等所有异常，并写明阶段和退出码。
|
||||
|
||||
这样即使本次 PowerShell 早退的底层原因在另一台机器上不同，也不会再出现“UI 已锁死并宣称即将关闭，但其实无人接管”的假成功。
|
||||
|
||||
## 建议测试
|
||||
|
||||
现有 `app/tests/test_app_update.py` 与 `app/tests/test_app_update_ui.py` 共 `28 passed`，但没有覆盖真实交接：service 测试只截获 `_spawn_inno_setup_applier` 并检查脚本文本；UI 测试只断言 mock `host.request_quit` 被调用，没有运行 `QApplication` 事件循环，也没有验证强制 dialog 是否会否决 quit。现有 installer smoke 直接执行安装器，也绕过了应用退出与 helper。
|
||||
|
||||
建议至少增加：
|
||||
|
||||
1. **Qt 子进程回归（必须）**：显示 `force=True` 且 busy/apply committed 的真实 `AppUpdateDialog`，触发 session 完成退出，以 watchdog 保底；断言事件循环正常返回 `0`、`aboutToQuit` 发生，而不是被 `closeEvent` 卡住。
|
||||
2. **显式退出路径**：强制更新下载中点击“退出软件”，worker `finished` 后同样能退出；result 已排队但退出先处理时不得启动 helper。
|
||||
3. **helper ready 成功**：使用临时 noop PowerShell fixture 和真实生产 creation flags，断言 child PID、ready、等待目标进程退出、后续阶段按顺序发生，并覆盖路径含空格。
|
||||
4. **helper 早退**：脚本缺失/解析失败/首条日志失败时，断言父进程取得非零退出码、不设置 committed、不退出、UI 可重试且有明确日志路径。
|
||||
5. **PID 身份**：目标进程退出后即使整数 PID 被模拟复用，也不会等待或误伤新进程；等待有诊断超时但绝不在无法确认旧进程退出时启动安装。
|
||||
6. **隔离端到端 Inno 更新**：从一个测试 frozen app 发起 handoff，确认旧 PID 消失、helper log 产生、安装器 log 产生、目标版本真正安装、只重启一次。不要只测试安装器单独运行。
|
||||
7. **发布契约**：服务端 `latest_version`、package filename/manifest `ProductVersion`、SHA/size 必须属于同一版本；构造 `latest=1.3.0 + package=1.1.0` 时发布或客户端安装必须失败。
|
||||
|
||||
## 审阅边界
|
||||
|
||||
- 已读取根 `AGENTS.md`；仓库不存在 `.trellis/`，因此没有额外 workflow/spec 可读取。
|
||||
- 工作树原本已有大量未提交改动，包括本报告涉及的生产文件和测试；本次未修改、覆盖或回退它们。
|
||||
- 除新增本文档外，没有修改生产代码或测试。
|
||||
Reference in New Issue
Block a user