cmshoppe/docs/tasks/T-683.md

---
id: T-683
title: 禁用设置页数字微调框滚轮改值
phase: 5
deps: [T-682]
status: DONE
created: 2026-07-21
---

# T-683 禁用设置页数字微调框滚轮改值

## 问题 / 背景

设置页的连接超时、并发数、端口、重试次数和蝦皮执行参数使用 `QSpinBox`。鼠标在数字微调框上滚动时，Qt 默认会改变数值，用户浏览较长设置页时容易无意修改关键参数，且未保存标记不足以帮助用户发现具体被改动的值。

## 方案

- 为设置页专用数字微调框提供统一的无滚轮实现，并替换该页全部 `QSpinBox`：默认网关连接超时、自定义模型连接超时、标题/图片并发、失败重试、默认调试端口、端口范围、Chrome 就绪超时、每批最大更新条数、同时更新蝦皮账号。
- 指针滚轮悬停在任意上述控件上时，不改变其数值、不触发未保存更改；滚轮事件忽略并继续由外层设置滚动区处理。
- 保留直接输入、上下箭头、键盘上/下键和程序化回填的既有行为与范围校验。
- 该行为只作用于设置页，不影响其它模块的进度条、表格、下拉框或将来需要滚轮编辑的数字控件。

## 验收要点

- [ ] 设置页全部数字微调框滚动滚轮后值不变，也不产生未保存更改。
- [ ] 鼠标滚轮仍可继续滚动设置页外层内容，而非被控件吞掉。
- [ ] 上下箭头、键盘和直接输入仍能修改数值并保持现有范围/dirty 语义。
- [ ] 连接超时、并发、端口、重试和蝦皮执行参数的加载、保存、放弃未保存更改不回归。

## 测试与文档

- 更新 `tests/test_gui.py`：对设置页所有专用数字微调框发送滚轮事件，断言数值与 dirty 状态不变；覆盖箭头或键盘修改仍有效。
- 更新 `docs/routes.md` 设置页交互说明。

## 验证

```bash
py -3.10 -m unittest tests.test_gui
py -3.10 -m unittest discover -s tests
py -3.10 -m ruff check app tests main.py
py -3.10 -m compileall app main.py
git diff --check
```

## 边界（不改什么）

- 不改变任何设置字段的默认值、范围、保存路径、校验或业务含义。
- 不禁用其它模块的滚轮，不调整下拉框、文本输入、表格、日志或页面整体滚动策略。
- 不改默认网关、自定义网关、AI 请求、Chrome/CDP、采集、商品套图或更新蝦皮流程。

## 关联

- T-682：设置页自定义网关模型配置区的紧凑布局。

## 执行记录

- 新增设置页专用 `SettingsSpinBox`，其滚轮事件不调用数值步进，而是按原始位置、增量和修饰键转发给最近的 `QScrollArea` 视口；设置页保留 `settings_scroll_area` 引用供明确的交互回归。
- 设置页全部 11 个数字微调框均替换为该组件：两类连接超时、标题/图片并发、重试、三个端口、Chrome 就绪超时、每批最大更新条数和同时更新蝦皮账号。箭头、键盘与直接输入未修改。
- 更新设置页交互说明和 GUI 回归：确认全部数字框都是专用组件，滚轮后数值及 dirty 状态不变、外层页面继续滚动，键盘上箭头仍会改值并进入未保存状态。
- 验证通过：`py -3.10 -m unittest tests.test_gui`（213 项）、`py -3.10 -m unittest discover -s tests`（654 项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。