Desktop mandatory-update client and blocking window
Desktop 强更客户端与阻塞窗口
A local business server does not deliver remote minimum-version policy. The Desktop shell must independently learn that an update is required, block subsequent interaction without interrupting existing tasks, and retain a recovery path when policy queries or updater preparation fail.
English
Problem
A local business server does not deliver remote minimum-version policy. The Desktop shell must independently learn that an update is required, block subsequent interaction without interrupting existing tasks, and retain a recovery path when policy queries or updater preparation fail.
Decision
Native update overlays own their parent-visibility subscription until closure. On macOS, hiding a parent hides its child windows without closing them; showing the parent does not restore those children. The overlay waits for both document readiness and a visible parent, then restores itself on subsequent parent show events. Keeping this in the shared overlay preserves ordinary and mandatory presentation without coupling update policy to onboarding or clearing an active block.
The shell polls the guest protocol in the API proposal, independently of business traffic. Configuration and application identity are embedded at packaging; packaged applications ignore environment overrides. The Desktop README owns configuration fields and defaults. Packaging requires the policy origin selected by the updater deployment before artifact preparation or signing. Test uses isolated Feishu authentication; production remains anonymous. The test login window opens detached DevTools on F12 while retaining its sandbox, navigation allowlist, and memory-only Session. Only unpackaged development can omit policy configuration. This prevents a missing policy setting from silently producing a release without mandatory checks or a test build querying production policy.
A coordinator owns one in-flight request, a deadline, interval jitter, and bounded failure backoff. The request identifies the installed client with the same five Platform client headers as account requests — platform, client version, locale, UTC offset in seconds, and an intentionally empty bundle id — and adds architecture, update channel, and bundled runtime version. Platform, architecture, update channel, and bundled runtime version are fixed at packaging, while the locale and UTC offset are sampled from the shell for each request and the version is the shared client build version rather than the Electron bundle version. Manual checks bypass scheduling but join in-flight work. Disposal aborts the request, awaits settlement, and prevents late publication. A flattened 40005 establishes blocking independently of optional title, detail, and download-page fields; localized fallback text and a retry action remain available, while an absent or unapproved page is not offered. Transport, JSON, business-code, or HTTP failures cannot clear a known block. Only a valid fresh no-force response clears it. Same-version offline persistence is not implemented because its product behavior remains undecided.
User-initiated ordinary checks trigger an independent policy refresh without waiting for or presenting its failures. A confirmed block alone cancels ordinary dialogs and transfers presentation to the mandatory dialog. Test authentication waits until an active ordinary dialog finishes; cancellation and failure leave the updater result intact. Concurrent callers reuse the active ordinary or authentication operation instead of creating competing windows.
On macOS a shell-owned modal uses a separate sandboxed preload, and the main process verifies its exact document URL and WebContents identity. Windows embeds the shell-origin dialog in the main document below the caption so maximization and resizing have one native owner; a second native window caused visibly unsynchronized resizing (#4566). The isolated application preload owns a private MessageChannel to the frame and forwards actions to main-process IPC, which verifies the current app origin and main-frame identity. Product scripts share the DOM and can hide or imitate presentation, but cannot obtain the privileged port, clear main-process policy, or approve task teardown through window message events. The caption and its Web controls remain reachable by design. Server title/detail are text, never HTML. Esc and ordinary updater prompts cannot dismiss the block; main-process guards refuse plugin-window entry and plugin mutations while it is active. The Host keeps existing work running; task-aware installation confirmation remains separate from policy. Closing the application remains available. Windows presentation and its trust limits are owned by the embedded-update decision.
The modal exposes user-initiated download and separate installation through the ordinary coordinator. Successful preparation and task inspection turn the same modal into installation confirmation without creating another window. Deferral retains the block and package; a retry inspects tasks and requests fresh confirmation. File verification and preparation share one visible phase. Restart feedback describes stopping tasks only after affected tasks are observed. Both dialog types require the owned IPC sender; closing, aborting, or losing an ordinary renderer cancels its approval.
The recovery layout keeps localized errors and folded technical details inside the block. Page actions appear only for failure or absent-artifact recovery, not beside the normal action. Exact HTTPS origins are checked before browser or clipboard use. A browser request immediately exposes copy recovery; its completion cannot prove external page loading. Only copy failure reveals the complete validated address for manual copying. Navigation and copy results are independent of updater errors and ignore completion after a changed policy destination. Neither browser opening, readiness, nor installer handoff clears policy or changes the updater target.
Background readiness requests parent-window taskbar attention on Windows or an informational Dock bounce on macOS and attempts one silent notification. Returning to the current confirmation clears native reminders without granting installation permission. Repeated state, deferral, and focus changes do not repeat a readiness reminder. Policy clearance, installation, and disposal also clear it. Unsupported or denied notifications leave the modal usable; native display requires installed-platform qualification.
This decision implements the client portion of the interaction proposal. That proposal and the API proposal remain active for backend integration, platform release qualification, and unresolved product decisions. The release policy retains artifact signing and publication requirements; none of these records is fully superseded.
Host exit and successful task teardown are separate outcomes. The process owner reports confirmed but unsuccessful exit with a dedicated error type. Backend cleanup can complete for that outcome while installation still fails; the shell restores the current-version Host and requires fresh installation confirmation without clearing mandatory policy. The replacement gets a fresh Web origin and authentication cookie, so the existing application URL reloads after Host readiness and obtains new boot data even when the port is unchanged. Other stop failures retain the backend's cleanup failure and prevent replacement, because the old process may still own profile state.
For confirmed unsuccessful teardown, localized recovery guidance remains separate from expandable technical details in both dialog types. The disclosure is closed initially and does not grant update permission. Diagnostics expose process lifecycle facts rather than arbitrary plugin stderr, which can contain credentials. The mandatory dialog preserves an expanded disclosure on unchanged state and collapses it when its diagnostic changes or clears.
Task warnings describe running agents, queued input, and running or stopping jobs, not request traffic. After installation approval, the Host refuses new API requests, waits for admitted requests to finish, and checks tasks again. This preserves admitted writes without warning about page reads. A timed-out or superseded drain cannot authorize installation; the shell unlocks admission after failure.
The product preload publishes semantic updater phase, version, progress, and classified failure fields without localized strings or raw diagnostics. Preparation failures carry a typed cause so native and Web presentations select their own locale's guidance without comparing translated messages. The account-row and collapsed-sidebar presentations resolve that data through the active Web locale, while native dialogs retain the Desktop shell locale. Intentional application quit hides the product window before Host teardown and ignores focus requests until exit, so the expected connection loss cannot appear as recovery work.
Alternatives considered
Use the system browser without a gateway handoff. Its cookies are not shared with Electron requests. Explicit test deployments instead use a sandboxed BrowserWindow and a dedicated in-memory Session, without Node integration or a preload. Document navigation permits only the configured HTTPS policy origin and the reviewed Feishu origins; permissions, downloads, new windows, and HTTP authentication are denied. The gateway needs no new token-exchange endpoint. This trades persistent sign-in and unrestricted identity-provider navigation for isolation. The default anonymous protocol and updater transport are unchanged.
Keep DevTools disabled in the test login window. This prevents local inspection of the third-party page but leaves authentication failures difficult to diagnose. F12 is an explicit local action on that window; ordinary login does not open DevTools.
Treat a completed login redirect as an update decision. The Windows gateway probe changed from unauthenticated 401 to application-level 422 and reused its Session after closing the login window. That establishes same-process cookie transport, not compatibility with the Harness policy API. The client rechecks policy after login, retains known blocks on authentication expiry or malformed responses, and never uses the gateway-provided login URL. User confirmation precedes every login window. The initial packaged startup check can explain the authentication requirement before the local backend is ready; later automatic checks stay silent. One operation owns explanation, login, and recheck, so concurrent entry points cannot create competing login windows.
Make policy availability a precondition for ordinary update feedback. A policy transport or protocol failure would suppress a valid updater result and make ordinary package delivery depend on the enforcement service. The two checks therefore share a user trigger but keep separate result handling; only an established block can preempt ordinary presentation.
Wait for business APIs to return a version error. Desktop business traffic is local, so remote policy must have an independent guest request.
Use a cancellable ordinary message box. It does not own persistent download progress, retry, page fallback, and policy refresh. A dedicated modal keeps these actions available without permitting cancellation of the requirement.
Terminate tasks when policy arrives. Policy requires future interaction to stop, not already-running work. Installation approval remains the separate authorization to stop affected tasks.
Let the policy select or revoke updater packages. This creates a second artifact authority and contradicts the approved higher-version replacement strategy. The updater alone selects and validates its version-bound package.
Keep technical details only in logs. In-dialog disclosure lets users inspect a stop failure without locating local logs, while the default recovery message stays readable.
Warn for every in-flight API request. Startup reads produce a task-interruption warning without affected tasks. Separating request draining from task inspection avoids that warning without classifying RPCs by URL or abandoning pending writes.
Send localized update strings through the preload. The Desktop shell locale can differ from the language selected inside the Web application, and transported strings cannot react to a later language change. Semantic presentation data keeps user-selected Web language ownership with the component.
Keep the product window visible during ordinary quit. Closing the owned Host first exposes its expected disconnect to the connection-recovery UI. Hiding the window before teardown preserves graceful process cleanup without presenting a retry action for intentional shutdown.
Consequences
Ordinary check and download failures separate locale-owned summaries from expandable updater diagnostics. Hover feedback contains no raw error text; download hover identifies the operation and target version. Web update status follows the active in-application locale independently of native dialog language. During shell-reported installation, update status takes precedence over connection feedback because stopping the owned backend is expected. An installation failure clears that priority so genuine reconnection remains visible. Ordinary quit removes the product window before the same expected backend disconnect. Long ordinary diagnostics scroll independently of the confirmation action; disclosure does not authorize installation.
The local qualification executes the actual Electron modal, restricted preload, renderer button handlers, network policy, and updater download. The main-entry regression verifies retained Host work and rejected business controls. A Chinese owner-local DOM expectation guards visible copy and actions. These tests do not establish production API compatibility, native browser/clipboard integration, complete-workspace visuals, signed installation, or post-restart health; verification records identify remaining evidence.
中文
问题
本地业务 server 不会传递远程最低版本策略。Desktop 壳必须独立获知强更要求，在不中断现有任务的情况下阻止后续交互，并在策略查询或 updater 准备失败时保留恢复路径。
决策
原生更新浮层在关闭前持有父窗口可见性监听。在 macOS 上，隐藏父窗口会隐藏但不会关闭其子窗口；重新显示父窗口不会恢复这些子窗口。浮层等待文档就绪且父窗口可见，并在后续父窗口显示事件中恢复自身。由公共浮层处理这一行为，既保持普通更新和强更的展示，也不将更新策略与 onboarding 耦合或清除有效阻塞。
壳独立于业务流量轮询接口提案中的游客协议。配置和应用身份在打包时嵌入；打包应用忽略环境覆盖。Desktop README负责配置字段与默认值。打包在准备产物或签名前要求提供由 updater 部署环境选定的策略源站。测试环境使用隔离的飞书鉴权；正式环境保持匿名。测试登录窗口按 F12 会打开独立的 DevTools，同时保留沙箱、导航允许列表和仅驻内存的 Session。只有未打包开发模式可以省略策略配置。这避免因遗漏策略配置而静默产出没有强更检查的发布包，或让测试包查询正式环境策略。
协调器持有单一在途请求、截止时间、间隔抖动和有上限的失败退避。请求用与账号请求相同的五个 Platform 客户端请求头标识已安装客户端——平台、客户端版本、语言、以秒为单位的 UTC 偏移，以及有意保持为空的 bundle id——并额外携带架构、更新通道和内置运行时版本。平台、架构、更新通道和内置运行时版本在打包时固定；语言与 UTC 偏移在每次请求时从壳采样，版本取自共享的客户端构建版本而非 Electron 打包版本。手动检查绕过调度，但复用在途请求。dispose（资源释放）中止请求、等待结算，并阻止迟到发布。扁平化 40005 建立阻塞不依赖可选的标题、详情和下载页面字段；本地化兜底文案与重试操作仍可使用，缺失或未获批准的页面地址不会展示。传输、JSON、业务码或 HTTP 错误都不能清除已知阻塞。只有新的有效无需强更响应才能清除它。同版本离线持久化未实现，因为其产品行为尚未确定。
用户发起常规检查时会触发独立的策略刷新，但不会等待或展示策略失败。只有已确认的强更决定会取消常规弹窗，并把展示移交给强更弹窗。测试环境鉴权会等待当前常规弹窗结束；取消和失败会保留 updater 结果。并发调用方复用当前常规操作或鉴权操作，不创建相互竞争的窗口。
macOS 的壳模态窗口使用独立沙箱预加载，主进程校验其精确文档 URL 和 WebContents 身份。Windows 将壳源站弹窗嵌入主文档顶栏下方，让最大化与缩放只有一个原生窗口负责；第二个原生窗口曾造成可见的缩放不同步（#4566）。隔离的应用预加载拥有通向 frame 的私有 MessageChannel，将操作转发至校验当前应用源站和主 frame 身份的主进程 IPC。产品脚本共享 DOM，可以隐藏或仿造展示，但不能获得特权端口、清除主进程策略，或通过 window 消息事件批准任务收尾。顶栏及其中的 Web 控件按设计保持可触达。服务端标题／详情按文本展示，绝不作为 HTML。Esc 和常规更新弹窗不能解除阻塞；阻塞期间主进程拒绝插件窗口入口和插件修改。Host 保持现有工作运行，任务影响安装确认独立于策略。仍可退出应用。 Windows 展示及其信任限制由内嵌强更决策负责。
模态窗口通过常规协调器提供用户发起的下载和独立安装。准备和任务检查成功后，同一弹窗转为安装确认，不创建另一个窗口。稍后更新保留阻塞与安装包；重试会检查任务并要求重新确认。文件校验与准备共用一个可见阶段。只有观测到受影响任务后，重启提示才描述正在停止任务。两类弹窗均要求所属 IPC 发送者；关闭、中止或失去常规渲染进程会取消其批准。
恢复界面在阻塞窗口内保留本地化错误和折叠技术详情。页面操作仅在失败或没有可用产物时出现，不与正常操作并列。浏览器或剪贴板使用前校验精确 HTTPS 源站。请求打开浏览器后立即提供复制恢复入口；请求完成不能证明外部网页加载。仅在复制失败时展示完整、经过校验的地址供手动复制。导航和复制结果独立于 updater 错误，策略目标地址改变后忽略迟到结果。打开浏览器、下载就绪和安装器交接均不清除策略或改变 updater 目标。
后台就绪时，Windows 请求父窗口任务栏提醒，macOS 请求信息级 Dock 弹跳，并尝试一次无声通知。返回当前确认界面会清理原生提醒，不授予安装权限。重复状态、稍后更新和焦点变化不会重复提醒同一次就绪。策略解除、安装和资源释放也会清理提醒。通知不受支持或被拒绝时仍可使用弹窗；原生展示需通过安装包平台验收。
此决策实现交互提案的客户端部分。该提案与接口提案仍负责后端联调、各平台发布验收和未决产品事项。发布策略保留产物签名和发布要求；这些记录均未被完整取代。
Host 退出与任务成功收尾是两个独立结果。进程所有者通过专用错误类型报告已确认但非正常的退出。该结果允许后端完成清理，但安装仍失败；壳恢复当前版本 Host，并要求重新确认安装，不清除强更策略。替代 Host 会获得新的 Web 源站和鉴权 Cookie，因此 Host 就绪后会重新加载原有应用地址，即使端口未变也会重新获取启动数据。其他停止失败会保留后端清理错误并阻止替代进程启动，因为旧进程可能仍持有 profile 状态。
对于已确认的非正常收尾，两类弹窗都将本地化恢复提示与可展开的技术详情分开展示。详情初始折叠，不授予更新权限。诊断展示进程生命周期事实，而非可能包含凭据的任意插件 stderr。强更弹窗在状态未变时保留已展开的详情，诊断改变或清除时则折叠。
任务警告描述运行中的 agent、排队输入和运行中或停止中的后台任务，而非请求流量。用户批准安装后，Host 拒绝新 API 请求，等待已接收请求结束，再检查任务。这既保护已接收的写操作，也不因页面读取弹出警告。超时或被替代的等待不能授权安装；失败后壳解除准入锁。
产品预加载只发布语义化 updater 阶段、版本、进度和失败类别，不携带本地化字符串或原始诊断。准备阶段失败携带类型化原因，原生与 Web 界面分别选用自身 locale 的提示，无需比较翻译后的文案。账户行和侧栏收起状态通过当前 Web locale 解析这些数据，原生弹窗仍使用 Desktop 壳 locale。主动退出应用时，产品窗口会在 Host 收尾前隐藏，并在进程退出前忽略聚焦请求，避免把预期连接中断展示成恢复操作。
考虑过的替代方案
没有网关交接机制时使用系统浏览器。 其 Cookie 不会与 Electron 请求共享。显式启用的测试部署改用沙箱 BrowserWindow 和独立内存 Session，不启用 Node 集成或预加载。文档导航只允许配置的 HTTPS 策略源站及已审核的飞书源站；拒绝权限、下载、新窗口和 HTTP 鉴权。网关不需要新增 token 交换接口。这以跨重启登录及不受限的身份提供方导航换取隔离。默认匿名协议及 updater 传输不变。
在测试登录窗口禁用 DevTools。 这会阻止本地检查第三方页面，却使鉴权失败难以排查。F12 是该窗口上的显式本地操作；正常登录不会自动打开 DevTools。
将登录重定向完成视为更新决定。 Windows 网关探针由未鉴权的 401 变为应用层 422，关闭登录窗口后仍复用 Session。这验证了同进程 Cookie 传输，并不证明与 Harness 策略 API 兼容。客户端在登录后重新检查策略，鉴权过期或响应畸形时保留已知阻塞，且从不使用网关提供的登录 URL。每次登录窗口都先经过用户确认。打包应用的首次启动检查可在本地后端就绪前说明鉴权要求；之后的自动检查保持静默。说明、登录和重新检查由同一个操作负责，使并发入口无法创建相互竞争的登录窗口。
把策略可用作为常规更新反馈的前置条件。 策略传输或协议失败会压制有效的 updater 结果，并使常规产物分发依赖强更服务。因此两个检查共用用户触发入口，但分别处理结果；只有已建立的强更状态可以抢占常规展示。
等待业务 API 返回版本错误。 Desktop 业务流量在本地，因此远程策略必须有独立游客请求。
使用可取消的常规消息框。 它不负责持久下载进度、重试、页面兜底和策略刷新。专用模态窗口保留这些操作，同时不允许取消强更要求。
策略到达时终止任务。 策略要求停止后续交互，而非正在运行的工作。安装批准仍是停止受影响任务的独立授权。
让策略选择或作废 updater 安装包。 这会增加第二个产物权威，并违背已确认的高版本覆盖策略。只有 updater 选择和校验其版本绑定的安装包。
技术详情仅保留在日志中。 弹窗内的折叠详情让用户无需查找本地日志即可排查停止失败，同时保持默认恢复提示可读。
对每个在途 API 请求都弹出警告。 启动读取会在没有受影响任务时触发中断警告。将请求收尾与任务检查分开，可避免这种误报，也无需按 URL 分类 RPC 或丢弃未完成的写操作。
通过预加载传递本地化更新文案。 Desktop 壳 locale 可能不同于 Web 应用内选择的语言，已传递的字符串也无法响应之后的语言切换。语义化展示数据让组件继续拥有用户所选 Web 语言下的文案。
常规退出时保持产品窗口可见。 先关闭自有 Host 会把预期断开展示到连接恢复界面。收尾前隐藏窗口既保留进程正常清理，也不会为主动关闭展示重试操作。
后果
常规检查和下载失败将语言字典提供的摘要与可展开的 updater 诊断分离。悬停提示不含原始错误文本；下载悬停提示说明操作和目标版本。Web 更新状态独立于原生弹窗语言，跟随应用内当前 locale。壳报告正在安装时，更新状态优先于连接反馈，因为停止自有后端是预期行为。安装失败会清除该优先级，使真实重连保持可见。常规退出会在发生同一预期后端断开前移除产品窗口。普通长诊断独立于确认操作滚动；展开详情不授予安装权限。
本地验证执行真实 Electron 模态窗口、受限预加载、页面按钮处理、网络策略和 updater 下载。主入口回归验证 Host 工作保留和业务控制拒绝。所属测试目录内的中文 DOM 预期输出约束可见文案和操作。这些测试不证明生产 API 兼容性、原生浏览器／剪贴板集成、完整工作区视觉效果、签名安装或重启后健康状态；验证记录列出尚缺证据。