38 lines
3.9 KiB
Markdown
38 lines
3.9 KiB
Markdown
---
|
||
id: T-402
|
||
title: Windows 通知区域入口与显式退出协调
|
||
phase: 4
|
||
deps: [T-303, T-305, T-307]
|
||
status: TODO
|
||
created: 2026-07-27
|
||
owner: codex
|
||
---
|
||
|
||
## 需求与背景
|
||
|
||
Chub 需要在 Windows 通知区域提供一个低干扰的长期运行入口，方便用户在浏览器实例监控期间重新显示主窗口、刷新已保存实例状态或明确退出应用。Gio `v0.10.1` 不提供通知区域 API，当前 `runWindow` 收到 `DestroyEvent` 后直接结束窗口循环，因此该功能必须以隔离的 Windows platform adapter 接入。
|
||
|
||
## 方案与边界
|
||
|
||
- 新增 Windows build-tag 的 `internal/platform/tray` adapter：使用 Shell notification-area API 和独立原生消息循环维护一个图标、Tooltip、右键菜单及 Explorer 重启后的重新注册。不得引入浏览器进程控制能力，也不得在 Gio frame 中执行 Win32 I/O。
|
||
- adapter 只发布 `TrayCommandShow`、`TrayCommandRefresh`、`TrayCommandExit`；`cmd/chub` 作为应用 coordinator 消费命令。显示窗口使用 Gio 已公开的窗口操作；刷新复用现有已保存实例快照与后台去重机制；退出通过统一应用生命周期协调器清理图标、取消监控并等待后台任务安全收束。
|
||
- 原生菜单固定为“显示 Chub”（默认项）→“刷新实例状态”→分隔线→“退出 Chub”。双击图标与默认项同效。菜单不枚举实例，不提供启动、停止、重启、删除、强制终止、CDP 或外部实例接管入口。
|
||
- `TrayState` 只携带托管运行、外部关联和需关注的计数；Tooltip 和图标状态不得出现实例名称、路径、URL、PID、端口、代理或其他敏感数据。图标资源需提供适配常用 DPI 的 16/20/24 像素版本，且图标状态不能只凭颜色传达含义。
|
||
- “退出 Chub”是应用级操作，不是停止某个浏览器。它必须沿用 `CloseOnExit` 的明确策略：仅在用户已启用且流程可安全确认时对 Chub 当前会话、可验证的托管实例发起既有优雅停止；外部关联、外部占用、未知实例绝不停止。若需要确认，先显示主窗口和明确影响数量的对话框，默认安全取消。
|
||
- 本任务不改变标题栏/Alt+F4 的关闭语义，不实现最小化或关闭窗口后隐藏到通知区域，不提供自启动或单实例激活。该行为待后续独立任务评审 Gio 的窗口消息拦截与多进程协调风险。
|
||
|
||
## 验收要点
|
||
|
||
- 自动化命令：新增 tray command/coordinator 单元测试；`go test ./...`、`go test -race ./cmd/chub ./internal/ui`、`go vet ./...`、`go build -o build/chub.exe ./cmd/chub` 通过。
|
||
- Windows smoke：运行 GUI 后通知区域出现一个 Chub 图标；双击/默认项显示并置前窗口；刷新项只检查已保存实例且重复触发被合并；退出项移除图标并按明确策略结束应用。Explorer 重启后图标自动恢复。高 DPI、键盘菜单、菜单关闭及图标创建失败均可恢复。
|
||
- 交互与无障碍：先更新 `docs/ui/browser-manager.html` 的托盘菜单模拟和 `docs/ui/README.md` 评审场景，再实现 Gio/Win32；页面内命令仍是所有托盘命令的可键盘访问等价入口。原生菜单使用具体动词，默认项为“显示 Chub”。
|
||
- 安全边界：不执行 `taskkill /IM` 或按浏览器名称的枚举/关闭；不向日志、Tooltip、菜单或 DTO 写入敏感信息；外部浏览器不因通知区域命令获得接管或关闭资格；所有 Win32 handle/回调只留在 platform adapter 内。
|
||
|
||
## 执行记录
|
||
|
||
- 状态：TODO
|
||
- 变更：已完成需求、架构、API、交互和验收边界定义；待 HTML 原型确认和代码实施。
|
||
- 验证：文档链接与 Git diff 检查待本次提交前执行。
|
||
- 阻塞：无。
|
||
- 残余风险：Gio 没有原生通知区域或关闭请求钩子；首版通过隔离 Shell adapter 降低影响面，不处理窗口关闭隐藏和单实例激活。
|