From 967047f876d39c46d1031363c89feaabfd4e41b9 Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Wed, 8 Jul 2026 14:04:45 +0800
Subject: [PATCH] docs: add T-557 chrome path picker

---
 docs/tasks/T-557.md | 46 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 docs/tasks/T-557.md

diff --git a/docs/tasks/T-557.md b/docs/tasks/T-557.md
new file mode 100644
index 0000000..82a7847
--- /dev/null
+++ b/docs/tasks/T-557.md
@@ -0,0 +1,46 @@
+---
+id: T-557
+title: ⑤设置 Chrome 路径增加文件选择按钮
+phase: 7
+deps: [T-539, T-543]
+status: TODO
+created: 2026-07-08
+---
+
+## 问题 / 背景
+
+⑤「设置」里的 Chrome 路径目前只能手动输入。正式用户不一定知道 Chrome 安装路径，也容易把路径拼错、少写 `.exe` 或复制到目录路径，导致④「启动登录」或登录检测前置流程失败。Windows 上 Chrome 可能安装在 `C:\Program Files\Google\Chrome\Application\chrome.exe`、`C:\Program Files (x86)\...`，也可能是用户自定义路径；只靠文本输入不够友好。
+
+从全栈开发工程师角度看，这属于低风险的 GUI 易用性补齐：配置 schema 已有 `chrome_path`，保存逻辑已稳定，只需要在现有输入框旁增加文件选择入口，不改 Chrome 启动参数、不改账号管理和 CDP。
+
+## 方案
+
+1. **⑤设置页增加选择按钮**
+   - 在 `SettingsTab` 的 Chrome 路径输入框右侧增加按钮，文案 `选择...`。
+   - 按钮对象名建议为 `chromePathBrowseButton`，便于 GUI 单测定位。
+   - 使用横向容器包住 `chrome_path_edit` + `chrome_path_browse_button`，整体仍放在「Chrome路径」这一项里，保持三列表单布局中长字段跨 3 格。
+
+2. **文件选择行为**
+   - 点击按钮调用 `QFileDialog.getOpenFileName()`。
+   - 弹窗标题使用中文：`选择 Chrome 程序`。
+   - 文件过滤建议：`Chrome 程序 (chrome.exe);;可执行文件 (*.exe);;所有文件 (*)`。
+   - 初始目录优先取当前 `chrome_path_edit` 的父目录；若当前值为空或父目录不存在，则不强行猜测，交给系统默认目录。
+   - 用户选中后，把路径写入 `chrome_path_edit`；现有 `textChanged` dirty 机制会显示未保存状态。
+   - 用户取消时不改变输入框、不标记 dirty、不弹错误。
+
+3. **保存与配置边界**
+   - 保存仍走现有 `save_app_settings()` / `_app_settings_payload()`，把 `chrome_path_edit.text().strip()` 写入 `config.json` 的 `chrome_path`。
+   - 不校验文件是否真实存在，不自动搜索 Chrome，不自动启动 Chrome。路径有效性仍由后续启动/检测流程给出错误提示。
+
+## 验收要点
+
+- ⑤设置页 Chrome 路径右侧出现 `选择...` 按钮。
+- 点击按钮并选择 `chrome.exe` 后，`chromePathEdit` 回填所选路径，并显示「● 未保存更改」。
+- 点击按钮后取消，原 Chrome 路径不变化，未保存状态不被误触发。
+- 保存设置后，所选路径写入 `config.json` 的 `chrome_path`。
+- GUI 单测覆盖按钮存在、选择回填、取消不改值、保存写入。
+- `python -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`py -3.10 -m unittest discover -s tests` 通过。
+
+## 边界（不改什么）
+
+只改⑤设置页 Chrome 路径的 GUI 选择入口和测试；不改 `config.json` schema、不改 `appconfig.chrome_path()`、不改 `app/chrome.py` 启动参数、不改④账号管理、不改 CDP/Shopee 逻辑、不引入自动搜索/自动安装/自动启动 Chrome。