diff --git a/admin/src/api/first_visit.ts b/admin/src/api/first_visit.ts index 1ead7ef01..adb5f43f6 100644 --- a/admin/src/api/first_visit.ts +++ b/admin/src/api/first_visit.ts @@ -238,10 +238,30 @@ export function wecomPromotionSavePool(params: Record) { return request.post({ url: '/firstvisit.wecomPromotion/savePool', params, timeout: 120000 }) } -export function wecomPromotionSaveWidget(params: Record) { - return request.post({ url: '/firstvisit.wecomPromotion/saveWidget', params }) -} - +export function wecomPromotionSaveWidget(params: Record) { + return request.post({ url: '/firstvisit.wecomPromotion/saveWidget', params }) +} + +export interface WecomPromotionBatchSetOperatorsParams { + pool_ids: number[] + operator_admin_ids: number[] + action: 'grant' | 'revoke' +} + +export interface WecomPromotionBatchSetOperatorsResult { + action: 'grant' | 'revoke' + pool_ids: number[] + operator_admin_ids: number[] + affected: number +} + +export function wecomPromotionBatchSetOperators(params: WecomPromotionBatchSetOperatorsParams) { + return request.post({ + url: '/firstvisit.wecomPromotion/batchSetOperators', + params + }) +} + export function wecomPromotionDeletePool(params: { id: number }) { return request.post({ url: '/firstvisit.wecomPromotion/deletePool', params, timeout: 120000 }) } diff --git a/admin/src/views/first_visit/wecom_promotion/index.vue b/admin/src/views/first_visit/wecom_promotion/index.vue index 62f7227f3..11287557f 100644 --- a/admin/src/views/first_visit/wecom_promotion/index.vue +++ b/admin/src/views/first_visit/wecom_promotion/index.vue @@ -51,28 +51,51 @@
-
+

获客助手分流方案

选择几名医助就生成几条成员规则；官方链接只在方案顶部复制，成员行不重复展示链接。

-
- 新建分流方案 -
- -
- +
+
+ 已选 {{ selectedPoolIds.length }} 个方案 + 批量设置访问操作 + 新建分流方案 +
+
+ +
+
@@ -90,8 +113,9 @@ 验证 API 复制链接 复制 JS - 编辑方案 - 删除 + 设置访问操作 + 编辑方案 + 删除
@@ -142,12 +166,12 @@ @@ -393,6 +417,70 @@ + + + + + + 添加操作人 + 移除操作人 + + 批量添加不会覆盖各方案已有操作人；批量移除只撤销本次选中的账号。 + + + + + + 添加时仅可选择已启用且拥有本页面权限的账号；失效账号仍可用于移除历史授权。 + +
+ 当前授权 +
+ {{ pool.name }} + {{ operatorNames(pool) }} +
+

另有 {{ accessDialogPools.length - 5 }} 个方案

+
+ + + + @@ -424,6 +512,7 @@ import { Promotion, Refresh, Search, SetUp, User, Warning } from '@element-plus/icons-vue' import { + wecomPromotionBatchSetOperators, wecomPromotionCheckApiPermission, wecomPromotionCustomerStats, wecomPromotionDeletePool, @@ -454,6 +543,16 @@ interface PromotionMemberOption { dept_names: string[] } +interface PromotionOperatorOption { + id: number + name: string + disable: number + can_grant: boolean + display_dept_id?: number + dept_ids: number[] + dept_names: string[] +} + interface PromotionMemberTreeNode { value: number | string label: string @@ -466,12 +565,13 @@ interface PromotionMemberTreeNode { } const emptyOverview = () => ({ - meta: { scope_label: '', generated_at: '' }, + meta: { admin_id: 0, scope_label: '', generated_at: '' }, config: { mode: 'internal', configured: false, ready: false, missing: [] as string[], corp_id_masked: '', agent_id: '', secret_configured: false, callback_ready: false, callback_url: '', official_doc: '' }, summary: { configured_apps: 0, pool_count: 0, online_links: 0, today_clicks: 0 }, pools: [] as any[], links: [] as any[], member_options: [] as PromotionMemberOption[], + operator_options: [] as PromotionOperatorOption[], department_options: [] as PromotionDepartmentOption[], customer_acquisition_link_example: 'https://work.weixin.qq.com/ca/xxxxxxxx' }) @@ -481,6 +581,7 @@ const loading = ref(false) const activeTab = ref('links') const selectedPoolId = ref() const selectedInstallPoolId = ref() +const selectedPoolIds = ref([]) const poolDialogVisible = ref(false) const savingPool = ref(false) const checkingApi = ref(false) @@ -488,7 +589,10 @@ const memberDialogVisible = ref(false) const savingMember = ref(false) const togglingMemberId = ref(0) const deletingPoolId = ref(0) +const accessDialogVisible = ref(false) +const savingAccess = ref(false) const poolForm = reactive({ id: 0, name: '', fallback_url: '', status: 1, member_admin_ids: [] as number[], skip_verify: 0, main_url: '' }) +const accessForm = reactive({ pool_ids: [] as number[], operator_admin_ids: [] as number[], action: 'grant' as 'grant' | 'revoke' }) const memberForm = reactive({ id: 0, name: '', userid: '', daily_limit: 0, status: 1, active_range: [] as string[], remark: '' }) const customerStatsLoading = ref(false) const customerStatsLoaded = ref(false) @@ -510,6 +614,7 @@ const customerStats = reactive({ const selectedPool = computed(() => overview.pools.find((item: any) => Number(item.id) === selectedPoolId.value)) const selectedMemberRules = computed(() => Array.isArray(selectedPool.value?.member_rules) ? selectedPool.value.member_rules : []) const selectedInstallPool = computed(() => overview.pools.find((item: any) => Number(item.id) === selectedInstallPoolId.value)) +const accessDialogPools = computed(() => overview.pools.filter((item: any) => accessForm.pool_ids.includes(Number(item.id)))) const memberTreeProps = { value: 'value', label: 'label', children: 'children', disabled: 'disabled' } const memberDepartmentTree = computed(() => buildMemberDepartmentTree(overview.department_options, overview.member_options)) const memberTreeDefaultExpandedKeys = computed(() => memberDepartmentTree.value.map((node) => node.value)) @@ -527,17 +632,29 @@ const customerMemberOptions = computed(() => customerStats.member_options.length department_name: Array.isArray(item.dept_names) ? item.dept_names.join(' / ') : (item.department_name || item.dept_name || '') }))) -watch(() => overview.pools.map((item: any) => Number(item.id)).join(','), () => { - const ids = overview.pools.map((item: any) => Number(item.id)) - if (!selectedPoolId.value || !ids.includes(selectedPoolId.value)) selectedPoolId.value = ids[0] - if (!selectedInstallPoolId.value || !ids.includes(selectedInstallPoolId.value)) selectedInstallPoolId.value = ids[0] -}, { immediate: true }) +watch(() => overview.pools.map((item: any) => `${Number(item.id)}:${item.can_manage_access ? 1 : 0}`).join(','), () => { + const ids = overview.pools.map((item: any) => Number(item.id)) + const manageableIds = new Set(overview.pools + .filter((item: any) => item.can_manage_access) + .map((item: any) => Number(item.id))) + if (!selectedPoolId.value || !ids.includes(selectedPoolId.value)) selectedPoolId.value = ids[0] + if (!selectedInstallPoolId.value || !ids.includes(selectedInstallPoolId.value)) selectedInstallPoolId.value = ids[0] + selectedPoolIds.value = selectedPoolIds.value.filter((id) => manageableIds.has(id)) +}, { immediate: true }) -watch(activeTab, (tab) => { - if (tab === 'customer-stats' && !customerStatsLoaded.value) loadCustomerStats() -}) +watch(activeTab, (tab) => { + if (tab === 'customer-stats' && !customerStatsLoaded.value) loadCustomerStats() +}) + +watch(() => accessForm.action, (action) => { + if (action !== 'grant') return + const grantableIds = new Set(overview.operator_options + .filter((operator) => operator.can_grant) + .map((operator) => Number(operator.id))) + accessForm.operator_admin_ids = accessForm.operator_admin_ids.filter((id) => grantableIds.has(Number(id))) +}) -async function loadOverview() { +async function loadOverview() { loading.value = true try { const result: any = await wecomPromotionOverview() @@ -546,9 +663,79 @@ async function loadOverview() { ElMessage.error(error?.message || '企业微信推广配置加载失败') } finally { loading.value = false - } -} - + } +} + +function togglePoolSelection(pool: any, checked: unknown) { + if (!pool?.can_manage_access) return + const id = Number(pool.id) + const next = new Set(selectedPoolIds.value) + checked ? next.add(id) : next.delete(id) + selectedPoolIds.value = [...next] +} + +function openAccessDialog(poolIds: number[] = selectedPoolIds.value) { + const manageableIds = new Set(overview.pools + .filter((pool: any) => pool.can_manage_access) + .map((pool: any) => Number(pool.id))) + const ids = [...new Set(poolIds.map(Number).filter((id) => manageableIds.has(id)))] + if (!ids.length) return ElMessage.warning('请先选择可管理的分流方案') + Object.assign(accessForm, { + pool_ids: ids, + operator_admin_ids: [], + action: 'grant' + }) + accessDialogVisible.value = true +} + +async function savePoolOperators() { + if (!accessForm.pool_ids.length) return ElMessage.warning('请至少选择一个分流方案') + if (!accessForm.operator_admin_ids.length) return ElMessage.warning('请至少选择一名操作人') + savingAccess.value = true + try { + const result = await wecomPromotionBatchSetOperators({ + pool_ids: [...accessForm.pool_ids], + operator_admin_ids: [...accessForm.operator_admin_ids], + action: accessForm.action + }) + accessDialogVisible.value = false + selectedPoolIds.value = [] + await loadOverview() + const actionLabel = accessForm.action === 'grant' ? '添加' : '移除' + ElMessage.success(result?.affected + ? `已批量${actionLabel} ${result.affected} 条方案操作权限` + : '权限设置已检查，没有需要变更的记录') + } catch (error: any) { + ElMessage.error(error?.message || '批量设置访问操作失败') + } finally { + savingAccess.value = false + } +} + +function operatorOptionLabel(operator: PromotionOperatorOption) { + const departments = Array.isArray(operator.dept_names) && operator.dept_names.length + ? operator.dept_names.join(' / ') + : '未分部门' + const unavailable = Number(operator.disable) === 1 + ? ' · 已禁用' + : (!operator.can_grant ? ' · 无页面权限' : '') + return `${operator.name} · ${departments}${unavailable}` +} + +function operatorNames(pool: any) { + const operators = Array.isArray(pool?.operators) ? pool.operators : [] + if (!operators.length) return '仅原管理范围可操作' + return operators + .map((operator: any) => `${operator.name || `账号 ${operator.id}`}${Number(operator.disable) === 1 ? '（已禁用）' : ''}`) + .join('、') +} + +function accessSummary(pool: any) { + const linkState = pool?.main_url ? '官方链接已生成' : '待生成链接' + const operatorCount = Array.isArray(pool?.operator_admin_ids) ? pool.operator_admin_ids.length : 0 + return operatorCount > 0 ? `${linkState} · ${operatorCount} 人可操作` : linkState +} + function openPoolDialog(pool?: any) { const selectableMemberIds = new Set(overview.member_options.map((member) => Number(member.id))) Object.assign(poolForm, pool ? { @@ -1074,12 +1261,17 @@ h1, h2, h3, p { margin: 0; } .tab-nav button { display: flex; align-items: center; gap: 7px; min-width: 132px; height: 54px; justify-content: center; border: 0; border-bottom: 3px solid transparent; color: #5e6d80; background: transparent; cursor: pointer; font-size: 14px; } .tab-nav button.active { border-bottom-color: var(--teal); color: #0d8277; font-weight: 700; } .tab-content { min-height: 460px; padding: 20px; } -.section-heading { display: flex; align-items: center; justify-content: space-between; gap: 20px; margin-bottom: 16px; } -.section-heading h2 { font-size: 17px; }.section-heading p { margin-top: 5px; color: var(--muted); font-size: 12px; } -.pool-layout { display: grid; grid-template-columns: 252px minmax(0, 1fr); min-height: 430px; border: 1px solid var(--line); border-radius: 11px; overflow: hidden; } -.pool-sidebar { padding: 8px; border-right: 1px solid var(--line); background: #f7f9fa; } -.pool-item { display: grid; grid-template-columns: 9px 1fr 16px; align-items: center; gap: 9px; width: 100%; min-height: 62px; margin-bottom: 5px; padding: 10px; border: 1px solid transparent; border-radius: 8px; text-align: left; background: transparent; cursor: pointer; } -.pool-item:hover { background: #fff; }.pool-item.active { border-color: #bfe1dc; background: #fff; box-shadow: 0 5px 16px rgba(25,69,70,.05); } +.section-heading { display: flex; align-items: center; justify-content: space-between; gap: 20px; margin-bottom: 16px; } +.section-heading h2 { font-size: 17px; }.section-heading p { margin-top: 5px; color: var(--muted); font-size: 12px; } +.section-heading-actions { display: flex; align-items: center; flex-wrap: wrap; justify-content: flex-end; gap: 8px; } +.section-heading-actions .el-button + .el-button { margin-left: 0; } +.selection-count { color: #117f75; font-size: 11px; font-weight: 600; } +.pool-layout { display: grid; grid-template-columns: 252px minmax(0, 1fr); min-height: 430px; border: 1px solid var(--line); border-radius: 11px; overflow: hidden; } +.pool-sidebar { padding: 8px; border-right: 1px solid var(--line); background: #f7f9fa; } +.pool-select-row { display: grid; grid-template-columns: 22px minmax(0, 1fr); align-items: center; gap: 4px; margin-bottom: 5px; } +.pool-select-row :deep(.el-checkbox) { justify-content: center; margin-right: 0; } +.pool-item { display: grid; grid-template-columns: 9px minmax(0, 1fr) 16px; align-items: center; gap: 9px; width: 100%; min-height: 62px; padding: 10px; border: 1px solid transparent; border-radius: 8px; text-align: left; background: transparent; cursor: pointer; } +.pool-item:hover { background: #fff; }.pool-select-row.active .pool-item { border-color: #bfe1dc; background: #fff; box-shadow: 0 5px 16px rgba(25,69,70,.05); } .pool-item strong, .pool-item small { display: block; }.pool-item strong { overflow: hidden; color: #253348; font-size: 12px; text-overflow: ellipsis; white-space: nowrap; }.pool-item small { margin-top: 4px; color: #8c98a7; font-size: 10px; } .pool-status { width: 8px; height: 8px; border-radius: 50%; }.pool-status.online { background: #18a277; }.pool-status.offline { background: #aab3bf; }.pool-item > .el-icon { color: #9ca7b4; } .pool-main { min-width: 0; }.pool-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 16px; min-height: 78px; padding: 12px 15px; border-bottom: 1px solid var(--line); } @@ -1113,6 +1305,14 @@ h1, h2, h3, p { margin: 0; } .member-tree-option__count { flex: 0 0 auto; color: #98a2b3; font-size: 11px; } .member-tree-option__detail { overflow: hidden; color: #8b97a6; font-size: 11px; text-overflow: ellipsis; white-space: nowrap; } .form-grid, .rule-form-grid { display: grid; grid-template-columns: repeat(2, minmax(0,1fr)); gap: 14px; }.form-tip { display: block; margin-top: 5px; color: #8b97a6; font-size: 10px; }.link-form .el-select, .link-form .el-input-number { width: 100%; } -@media (max-width: 1100px) { .heading-actions { flex-wrap: wrap; justify-content: flex-end; }.metric-grid, .customer-metric-grid { grid-template-columns: repeat(2, minmax(0,1fr)); }.pool-layout { grid-template-columns: 210px minmax(0,1fr); }.pool-toolbar { align-items: flex-start; flex-direction: column; } } -@media (max-width: 760px) { .promotion-page { padding: 10px; }.page-header, .section-heading { align-items: flex-start; flex-direction: column; }.update-time { display: none; }.metric-grid, .customer-metric-grid, .form-grid, .rule-form-grid { grid-template-columns: 1fr; }.tab-nav { overflow-x: auto; }.tab-nav button { min-width: 112px; }.tab-content { padding: 14px; }.pool-layout { grid-template-columns: 1fr; }.pool-sidebar { display: flex; overflow-x: auto; border-right: 0; border-bottom: 1px solid var(--line); }.pool-item { min-width: 190px; }.callback-list > div { grid-template-columns: 1fr 48px; padding: 8px 0; }.callback-list dt { grid-column: 1 / -1; }.install-pool-select { width: 100%; }.customer-heading-actions { width: 100%; justify-content: flex-end; }.customer-filter-bar :deep(.el-form-item) { width: 100%; margin-right: 0; }.customer-filter-bar :deep(.el-form-item__content), .customer-filter-bar .el-select { width: 100%; }.customer-filter-bar .filter-actions :deep(.el-form-item__content) { justify-content: flex-end; }.customer-pagination { align-items: flex-start; flex-direction: column; }.customer-pagination :deep(.el-pagination) { max-width: 100%; flex-wrap: wrap; justify-content: flex-start; } } +.access-form { margin-top: 16px; } +.access-pool-preview { padding: 12px 14px; border: 1px solid var(--line); border-radius: 8px; background: #f8fafb; } +.access-pool-preview > strong { display: block; margin-bottom: 7px; font-size: 12px; } +.access-pool-preview > div { display: grid; grid-template-columns: minmax(120px, .8fr) minmax(0, 1.6fr); gap: 12px; padding: 6px 0; border-top: 1px solid #edf0f2; font-size: 11px; } +.access-pool-preview span { overflow: hidden; color: #344054; text-overflow: ellipsis; white-space: nowrap; } +.access-pool-preview small, .access-pool-preview p { color: #8491a2; font-size: 10px; } +.access-pool-preview small { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +.access-pool-preview p { margin-top: 7px; } +@media (max-width: 1100px) { .heading-actions { flex-wrap: wrap; justify-content: flex-end; }.metric-grid, .customer-metric-grid { grid-template-columns: repeat(2, minmax(0,1fr)); }.pool-layout { grid-template-columns: 210px minmax(0,1fr); }.pool-toolbar { align-items: flex-start; flex-direction: column; } } +@media (max-width: 760px) { .promotion-page { padding: 10px; }.page-header, .section-heading { align-items: flex-start; flex-direction: column; }.section-heading-actions { width: 100%; justify-content: flex-start; }.update-time { display: none; }.metric-grid, .customer-metric-grid, .form-grid, .rule-form-grid { grid-template-columns: 1fr; }.tab-nav { overflow-x: auto; }.tab-nav button { min-width: 112px; }.tab-content { padding: 14px; }.pool-layout { grid-template-columns: 1fr; }.pool-sidebar { display: flex; overflow-x: auto; border-right: 0; border-bottom: 1px solid var(--line); }.pool-select-row { min-width: 220px; }.pool-item { min-width: 190px; }.callback-list > div { grid-template-columns: 1fr 48px; padding: 8px 0; }.callback-list dt { grid-column: 1 / -1; }.install-pool-select { width: 100%; }.customer-heading-actions { width: 100%; justify-content: flex-end; }.customer-filter-bar :deep(.el-form-item) { width: 100%; margin-right: 0; }.customer-filter-bar :deep(.el-form-item__content), .customer-filter-bar .el-select { width: 100%; }.customer-filter-bar .filter-actions :deep(.el-form-item__content) { justify-content: flex-end; }.customer-pagination { align-items: flex-start; flex-direction: column; }.customer-pagination :deep(.el-pagination) { max-width: 100%; flex-wrap: wrap; justify-content: flex-start; }.access-pool-preview > div { grid-template-columns: 1fr; gap: 3px; } } diff --git a/app/artifacts/debug-mode-off-login.png b/app/artifacts/debug-mode-off-login.png new file mode 100644 index 000000000..466a46480 Binary files /dev/null and b/app/artifacts/debug-mode-off-login.png differ diff --git a/app/artifacts/forced-update-exit.png b/app/artifacts/forced-update-exit.png new file mode 100644 index 000000000..f7f5c7ed5 Binary files /dev/null and b/app/artifacts/forced-update-exit.png differ diff --git a/app/research/client_update_diagnosis.md b/app/research/client_update_diagnosis.md new file mode 100644 index 000000000..8b137f529 --- /dev/null +++ b/app/research/client_update_diagnosis.md @@ -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=&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`。 + diff --git a/app/research/debug_mode_config_analysis.md b/app/research/debug_mode_config_analysis.md new file mode 100644 index 000000000..cbe4e0797 --- /dev/null +++ b/app/research/debug_mode_config_analysis.md @@ -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 契约，再运行相关完整测试和冻结构建门禁；仅本分析任务未修改生产代码、也未执行会连接线上环境的测试。 diff --git a/app/research/debug_mode_login_analysis.md b/app/research/debug_mode_login_analysis.md new file mode 100644 index 000000000..5bb7cc142 --- /dev/null +++ b/app/research/debug_mode_login_analysis.md @@ -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。只有这四层都成立，才不是单纯的视觉隐藏。 diff --git a/app/research/debug_mode_package_result.md b/app/research/debug_mode_package_result.md new file mode 100644 index 000000000..2bbbd3372 --- /dev/null +++ b/app/research/debug_mode_package_result.md @@ -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` 逐字符匹配；清单恰好包含两条记录。 diff --git a/app/research/debug_mode_test_result.md b/app/research/debug_mode_test_result.md new file mode 100644 index 000000000..732f75495 --- /dev/null +++ b/app/research/debug_mode_test_result.md @@ -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`. diff --git a/app/research/forced_update_exit_analysis.md b/app/research/forced_update_exit_analysis.md new file mode 100644 index 000000000..75cdd6304 --- /dev/null +++ b/app/research/forced_update_exit_analysis.md @@ -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 文件可读。 +- 工作树原本已有多项未提交修改；本次只新增本研究文档，没有覆盖或回退任何现有改动。 diff --git a/app/research/forced_update_exit_package_result.md b/app/research/forced_update_exit_package_result.md new file mode 100644 index 000000000..ef8bf8da6 --- /dev/null +++ b/app/research/forced_update_exit_package_result.md @@ -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` 逐字符一致。 diff --git a/app/research/forced_update_exit_tests.md b/app/research/forced_update_exit_tests.md new file mode 100644 index 000000000..f6e4dfaa7 --- /dev/null +++ b/app/research/forced_update_exit_tests.md @@ -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` 未提交改动均已保留。 diff --git a/app/research/package_1_2_0_result.md b/app/research/package_1_2_0_result.md new file mode 100644 index 000000000..b041252fc --- /dev/null +++ b/app/research/package_1_2_0_result.md @@ -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`、当前用户开始菜单快捷方式及本次当前用户卸载注册表键均不存在。隔离测试根目录按设计保留，仅包含安装/卸载日志和隔离应用日志，便于审计。 diff --git a/app/research/server_release_diagnosis.md b/app/research/server_release_diagnosis.md new file mode 100644 index 000000000..f9e3882ff --- /dev/null +++ b/app/research/server_release_diagnosis.md @@ -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 不消费该形态。 diff --git a/app/research/update_commit_repro.py b/app/research/update_commit_repro.py new file mode 100644 index 000000000..24b99c6c0 --- /dev/null +++ b/app/research/update_commit_repro.py @@ -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)) diff --git a/app/research/update_commit_reproduction.md b/app/research/update_commit_reproduction.md new file mode 100644 index 000000000..ee12030da --- /dev/null +++ b/app/research/update_commit_reproduction.md @@ -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；本次按根指令执行并在此记录。工作树原本已有大量未提交 +修改，本次没有改动其中任何生产源码或既有测试。 diff --git a/app/research/update_install_handoff_diagnosis.md b/app/research/update_install_handoff_diagnosis.md new file mode 100644 index 000000000..f186b37d7 --- /dev/null +++ b/app/research/update_install_handoff_diagnosis.md @@ -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 阻止：。 + +这也解释了为何 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 + diff --git a/server/sql/1.9.20260828/add_wecom_promotion_pool_operators.sql b/server/sql/1.9.20260828/add_wecom_promotion_pool_operators.sql new file mode 100644 index 000000000..0c8ecffd8 --- /dev/null +++ b/server/sql/1.9.20260828/add_wecom_promotion_pool_operators.sql @@ -0,0 +1,20 @@ +-- 企业微信获客助手：分流方案共享操作人 +-- 执行后，方案可批量授权给当前数据范围内的其他后台账号访问和操作。 + +START TRANSACTION; + +CREATE TABLE IF NOT EXISTS `zyt_qywx_promotion_pool_operator` ( + `id` int unsigned NOT NULL AUTO_INCREMENT, + `pool_id` int unsigned NOT NULL DEFAULT 0 COMMENT '分流方案 ID', + `admin_id` int unsigned NOT NULL DEFAULT 0 COMMENT '被授权后台账号 ID', + `granted_by_admin_id` int unsigned NOT NULL DEFAULT 0 COMMENT '最近授权人 ID', + `create_time` int unsigned NOT NULL DEFAULT 0, + `update_time` int unsigned NOT NULL DEFAULT 0, + `delete_time` int unsigned NULL DEFAULT NULL, + PRIMARY KEY (`id`), + UNIQUE KEY `uk_pool_admin` (`pool_id`,`admin_id`), + KEY `idx_admin_active` (`admin_id`,`delete_time`), + KEY `idx_granted_by` (`granted_by_admin_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='企微获客分流方案共享操作人'; + +COMMIT; diff --git a/server/tests/WecomPromotionOverviewSmokeTest.php b/server/tests/WecomPromotionOverviewSmokeTest.php index b595d16c9..e9d4220b8 100644 --- a/server/tests/WecomPromotionOverviewSmokeTest.php +++ b/server/tests/WecomPromotionOverviewSmokeTest.php @@ -16,7 +16,7 @@ if (!$admin) { throw new RuntimeException('未找到 root 管理员，无法执行数据范围冒烟测试'); } $overview = WecomPromotionLogic::overview((int) $admin['id'], $admin, 'https://example.test'); -foreach (['meta', 'config', 'summary', 'pools', 'links', 'member_options', 'department_options'] as $key) { +foreach (['meta', 'config', 'summary', 'pools', 'links', 'member_options', 'operator_options', 'department_options'] as $key) { if (!array_key_exists($key, $overview)) { throw new RuntimeException("overview 缺少 {$key}"); } @@ -42,19 +42,40 @@ if ($memberIds !== []) { if (!is_array($overview['department_options'])) { throw new RuntimeException('department_options 必须是部门树数组'); } +foreach ($overview['pools'] as $pool) { + foreach (['operators', 'operator_admin_ids', 'can_operate', 'can_manage_access', 'can_delete'] as $key) { + if (!array_key_exists($key, $pool)) { + throw new RuntimeException("pools 缺少共享操作权限字段 {$key}"); + } + } +} $scopedAdmin = Db::name('admin')->where('root', 0)->whereNull('delete_time')->order('id', 'asc')->find(); if ($scopedAdmin) { $visibleIds = DataScopeService::getVisibleAdminIds((int) $scopedAdmin['id'], $scopedAdmin); $scopedOverview = WecomPromotionLogic::overview((int) $scopedAdmin['id'], $scopedAdmin, 'https://example.test'); if ($visibleIds !== null) { + $scopedPoolIds = array_values(array_filter(array_map('intval', array_column($scopedOverview['pools'], 'id')))); + $sharedPoolMemberIds = $scopedPoolIds === [] + ? [] + : array_map('intval', Db::name('qywx_promotion_pool_member') + ->whereIn('pool_id', $scopedPoolIds) + ->whereNull('delete_time') + ->column('admin_id')); foreach ($scopedOverview['member_options'] as $member) { - if (!in_array((int) $member['id'], $visibleIds, true)) { + if (!in_array((int) $member['id'], $visibleIds, true) + && !in_array((int) $member['id'], $sharedPoolMemberIds, true)) { throw new RuntimeException('member_options 泄露了当前角色或部门范围外的成员'); } } + foreach ($scopedOverview['operator_options'] as $operator) { + if (!in_array((int) $operator['id'], $visibleIds, true)) { + throw new RuntimeException('operator_options 泄露了当前角色或部门范围外的账号'); + } + } foreach ($scopedOverview['pools'] as $pool) { - if (!in_array((int) $pool['owner_admin_id'], $visibleIds, true)) { + if (!in_array((int) $pool['owner_admin_id'], $visibleIds, true) + && !in_array((int) $scopedAdmin['id'], array_map('intval', $pool['operator_admin_ids'] ?? []), true)) { throw new RuntimeException('pools 泄露了当前角色或部门范围外的数据'); } } diff --git a/server/tests/WecomPromotionPoolOperatorContractTest.php b/server/tests/WecomPromotionPoolOperatorContractTest.php new file mode 100644 index 000000000..a47fe69eb --- /dev/null +++ b/server/tests/WecomPromotionPoolOperatorContractTest.php @@ -0,0 +1,61 @@ + $path) { + $source = file_get_contents($path); + if (!is_string($source)) { + throw new RuntimeException("无法读取 {$name}: {$path}"); + } + $sources[$name] = $source; +} + +$migration = $sources['migrationPath']; +foreach (['qywx_promotion_pool_operator', 'uk_pool_admin', 'granted_by_admin_id'] as $needle) { + if (!str_contains($migration, $needle)) { + throw new RuntimeException("共享操作人迁移缺少 {$needle}"); + } +} + +$logic = $sources['logicPath']; +foreach (['batchSetOperators', 'applyPoolAccessScope', 'isPoolOperator', 'can_manage_access', 'operator_options'] as $needle) { + if (!str_contains($logic, $needle)) { + throw new RuntimeException("获客助手共享权限逻辑缺少 {$needle}"); + } +} +$deleteStart = strpos($logic, 'public static function deletePool('); +$deleteEnd = strpos($logic, 'public static function batchSetOperators(', $deleteStart === false ? 0 : $deleteStart); +if ($deleteStart === false || $deleteEnd === false) { + throw new RuntimeException('无法定位 deletePool/batchSetOperators'); +} +$deleteMethod = substr($logic, $deleteStart, $deleteEnd - $deleteStart); +if (!str_contains($deleteMethod, "assertScopedRow('qywx_promotion_pool', \$id, \$adminId, \$adminInfo, false)")) { + throw new RuntimeException('共享操作人不得永久删除分流方案'); +} + +if (!str_contains($sources['customerLogicPath'], 'operatorPoolIds($adminId)') + || !str_contains($sources['customerLogicPath'], "whereOr('p.id', 'in', \$operatorPoolIds)")) { + throw new RuntimeException('共享操作人尚未接入获客客户统计权限'); +} +if (!str_contains($sources['controllerPath'], 'public function batchSetOperators()')) { + throw new RuntimeException('控制器缺少批量设置操作人接口'); +} +if (!str_contains($sources['apiPath'], '/firstvisit.wecomPromotion/batchSetOperators')) { + throw new RuntimeException('前端 API 缺少批量设置操作人接口'); +} +foreach (['批量设置访问操作', '添加操作人', '移除操作人', 'selectedPoolIds', 'can_manage_access'] as $needle) { + if (!str_contains($sources['viewPath'], $needle)) { + throw new RuntimeException("前端共享权限交互缺少 {$needle}"); + } +} + +echo "WECOM_PROMOTION_POOL_OPERATOR_CONTRACT_OK\n";