cmshoppe/docs/tasks/T-680.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-680	设置页生成网关改为同行单选框	5	T-677	DONE	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。
• 验证：

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：商品套图按保存/持久化来源执行与展示，不能受本任务影响。

执行记录

• 将 gateway_selector 内原有的两个可勾选 QPushButton 替换为同一 QButtonGroup 管理的两个 QRadioButton，保留对象名、同行顺序、零间距布局、每项最小宽度以及原有选中、保存、放弃未保存更改和面板切换方法。
• 选中状态改由标准圆点、鼠标悬停色和键盘焦点边框表达；加载 cmhub/direct、鼠标点击和方向键切换均保持互斥。没有改动其它设置输入框、label、面板结构、表单网格或业务配置字段。
• 已将 docs/ui/settings-gateway-radio-prototype-v1.html 收缩为原位置的同行单选框方案，移除上下重排、侧栏、运行任务说明、深色预览和其它输入框改版；更新设置路由与 UI 索引。
• 测试：更新 tests/test_gui.py，覆盖控件类型、同行布局、已保存默认来源、方向键互斥切换、待保存状态、保存和放弃回填。验证：py -3.10 -m unittest tests.test_gui（211 项）、HTML 解析、内嵌 JavaScript 语法检查、py -3.10 -m ruff check app tests main.py、py -3.10 -m compileall app main.py、git diff --check 均通过；完整 py -3.10 -m unittest discover -s tests 通过（651 项）。