docs(tasks): add gateway radio layout task

2026-07-21 08:59:17 +08:00
parent b803a2a15a
commit 4217f855ac
1 changed files with 65 additions and 0 deletions
@@ -0,0 +1,65 @@
+---
+id: T-680
+title: 设置页生成网关改为同行单选框
+phase: 5
+deps: [T-677]
+status: TODO
+created: 2026-07-21
+---
+
+# T-680 设置页生成网关改为同行单选框
+
+## 问题 / 背景
+
+设置页的「默认网关 / 自定义网关」当前使用两个可勾选按钮组成的分段控件。虽然配置加载时会选中已保存的来源，但选中态不够醒目，用户无法一眼判断当前使用哪个网关。
+
+`settings-gateway-radio-prototype-v1.html` 的初版把选项重排为上下两行，并扩展了其它字段与状态展示；这超出本次范围，用户明确不接受。用户只要求保留原来同一行的位置，将两枚按钮替换为标准单选框。
+
+## 方案
+
+- 在 `SettingsTab` 保持现有「生成网关」区域、原 `gateway_selector` 的同行位置、相邻间距和整体表单布局不变。
+- 将原本的 `QPushButton` 分段选择器替换为同一 `QButtonGroup` 中的两个 `QRadioButton`：
+  - `默认网关`
+  - `自定义网关`
+- 程序加载设置时，`ai.backend="cmhub"` 自动勾选「默认网关」；`ai.backend="direct"` 自动勾选「自定义网关」。勾选状态必须使用标准圆点与焦点样式表达，不能只依赖颜色。
+- 点击单选框仍沿用已有行为：立即切换当前网关对应的配置面板并标记“未保存更改”；只有点击「保存设置」才写入 `ai.backend`，保存/放弃未保存更改时继续按现有逻辑回填选择。
+- 先将 `docs/ui/settings-gateway-radio-prototype-v1.html` 调整为两个单选框同一行、位于现有选择器位置；删除原型中本次不需要的网关选项重排、额外状态侧栏、运行中任务说明和其它输入框改版，使原型只表达控件替换与已有保存语义。
+- 仅按现有浅色桌面主题实现；键盘 Tab 可聚焦单选组、方向键可切换两个选项，焦点清晰可见。
+
+## 验收要点
+
+- [ ] 打开设置时，已保存默认网关显示为同行左侧单选框已勾选；已保存自定义网关显示为同行右侧单选框已勾选。
+- [ ] 两个选项位置保持在原选择器的同一行，不换行、不增设侧栏、说明卡或额外状态组件。
+- [ ] 切换单选框只改变待保存状态和已有面板显隐；点击保存前，实际配置文件值不变。
+- [ ] 保存、放弃未保存更改、切换其它页面的既有未保存处理不回归。
+- [ ] Base URL、API Key、别名、模型详情、生成参数、路径端口及蝦皮更新设置的控件顺序、宽度、可见性和业务逻辑不因本任务改变。
+- [ ] 键盘 Tab/方向键、鼠标点击、焦点样式和 200% 缩放下可用；用户可见文案均为中文。
+
+## 测试与文档
+
+- 更新 `tests/test_settings_gui.py`（或现有设置页 GUI 测试）：两种已保存来源的回填、切换后的 dirty 状态、保存和放弃回填、互斥性与键盘焦点。
+- 更新 `docs/routes.md` 的设置页控件说明，以及 `docs/ui/settings-gateway-radio-prototype-v1.html` 与 `docs/ui/README.md`。
+- 验证：
+
+```bash
+py -3.10 -m unittest tests.test_settings_gui tests.test_gui
+py -3.10 -m ruff check app tests main.py
+py -3.10 -m compileall app main.py
+git diff --check
+```
+
+## 边界（不改什么）
+
+- 不改变 `ai.backend` 的字段名、取值、默认值、保存路径或已有网关调用逻辑。
+- 不新增“已保存网关”侧栏、运行任务来源提示、深色主题开关或新的配置字段。
+- 不调整除两个网关选择控件外的任何设置输入框、label、帮助文字、面板结构、布局尺寸或按钮。
+- 不改默认网关/自定义网关的模型校验、余额、图片理解、商品套图、Chrome/CDP、Excel 或蝦皮更新逻辑。
+
+## 关联
+
+- T-677：生成网关来源选择器与保存语义。
+- T-679b/T-679c：商品套图按保存/持久化来源执行与展示，不能受本任务影响。
+
+## 执行记录
+
+（做完在这里写：控件替换范围、原型同步、GUI 验证和回归结果。）