# 2026-06-29 QuickSearch 点击修复

## 用户目标

- 修复 QuickSearch 下拉候选框中应用无法用鼠标点击打开的严重功能问题。
- 保持回车启动路径可用。
- 本轮不继续做视觉自动判断，视觉由用户人工验收。

## 已完成事项

- 在 `src/Apptag/QuickSearch.swift` 为 `QuickSearchPanel` 增加 panel-level 左键点击兜底：
  - `sendEvent(_:)` 对 `.leftMouseDown` 命中候选行时解析 `QuickSearchResultRowView`。
  - 命中后调用同一 `launchFromMouseClick()` 启动路径，避免 SwiftUI / NSHostingView / NSScrollView 层级吞掉行点击。
- 保留并调整 `QuickSearchResultRowView.mouseDown(with:)`：
  - 行自身点击仍走启动路径。
  - 未能处理时才交回 `super.mouseDown(with:)`。
- 扩展 `src/Scripts/quick_search_launch_contract_qa.sh`：
  - 覆盖 `QuickSearchPanel.sendEvent`、左键点击、`quickSearchResultRow(at:)` 和 `launchFromMouseClick()`。
- 更新版本与发布说明：
  - `src/Apptag/Info.plist`：版本更新为 `8.2.5` / build `20260629.1917`。
  - `src/CHANGELOG.md`：新增 QuickSearch 点击启动修复记录。
- 更新 `CODEGRAPH.md`：
  - 记录 QuickSearch panel-level 点击兜底为受保护行为。

## QA 与交付证据

- `bash Scripts/quick_search_launch_contract_qa.sh`：PASS。
- `bash Scripts/pro_custom_hotkeys_qa.sh`：PASS。
- `APP_BUILD=20260629.1917 bash build.sh`：PASS。
- `codesign --verify --deep --strict --verbose=2 build/TagLauncher.app`：PASS。
- `hdiutil verify build/TagLauncher.dmg`：PASS。
- `git diff --check -- CODEGRAPH.md src/Apptag/QuickSearch.swift src/Scripts/quick_search_launch_contract_qa.sh src/Apptag/Info.plist src/CHANGELOG.md`：PASS。
- 真实点击验证：
  - 点击前截图：`/Users/ar/Projects/Taglauncher/src/build/quicksearch-click-before-2.png`。
  - 点击后截图：`/Users/ar/Projects/Taglauncher/src/build/quicksearch-click-after-2.png`。
  - 实际点击落在 Tolaria 候选行并将 Tolaria 拉起，证明 QuickSearch 候选行鼠标点击启动路径生效。
- DMG：
  - `/Users/ar/Projects/Taglauncher/src/build/TagLauncher.dmg`
  - SHA256：`0f4955871c19670afcc3520a81dec7ecc7207ec8df3a607858624e7ddb2b9004`

## 关键决策

- 不只依赖 SwiftUI 行内 `mouseDown`，增加 AppKit panel 层兜底；这是本问题的最小功能修复，避免重新设计 QuickSearch UI。
- 视觉验证按用户要求停止，本轮只记录功能验证证据。

## 未决问题

- 本轮真实点击验证坐标落在 Tolaria，而非原计划的 QuickTime Player；因此不把 QuickTime 的进程检查作为证据。
- 本轮没有做新的视觉 QA。

## 后续建议

- 后续若继续改 QuickSearch UI，必须保留 `QuickSearchPanel.sendEvent` 兜底与 `QuickSearchResultRowView.launchFromMouseClick()` 统一启动路径。