cmautobuy/docs/client/05-ui-specification.md

# 05 Client 界面交互规范

- 文档状态：基线草案，待界面评审
- 技术栈：PyQt5、Qt Widgets、PyQt-Fluent-Widgets
- 当前验证组件版本：PyQt-Fluent-Widgets 1.11.3（版本以 `client/requirements.txt` 为准）

本文档中 `[必须]` / `[建议]` / `[待定]` 的含义见 [文档索引](../README.md#文档标注说明)。没有标注的默认是 `[必须]`。看不懂的词查 [术语表](00-glossary.md)。

## 1. 设计目标

- 让操作人员在一个页面完成任务监控、搜索和异常定位。
- “获取任务”和“重新执行”会产生外部后果；后者当前只允许重新采集，不允许采购。
- 长任务状态始终可找到，不使用连续模态弹窗打断工作。
- 任务表格在数据增长后仍保持响应速度、稳定选择和可访问性。
- 界面只展示任务状态，不在 Qt 主线程执行 Admin 或手机自动化。

## 2. 应用外壳

主窗口使用 `FluentWindow`，顶级导航保持稳定顺序：

1. **PDD 任务**：主要业务页面。
2. **设置**：固定在导航底部。

页面必须使用稳定对象名：

- `pddTaskPage`
- `settingsPage`

> **现状提醒：** 当前代码里是 3 个导航项（pdd / 设备 / 设置），和这里写的 2 个不一样。这是已知差异，见 [02 架构 §3.1](02-architecture.md)。设备相关设置最终要并入设置页，但要按工单单独做，不要顺手改。

窗口建议默认尺寸为 1280×800，有效最小尺寸不低于 960×600。窗口变窄时允许表格水平滚动和顶部命令换行，不能隐藏主要任务入口。

## 3. PDD 任务页布局

```text
┌─────────────────────────────────────────────────────────────┐
│ PDD 任务                                                    │
│ [开始自动获取] [类型▼] [状态▼] [关键词...] [搜索] [刷新] [重新执行] │
├─────────────────────────────────────────────────────────────┤
│ 类型 │ 商品标题 │ 颜色 │ 尺码 │ 价格 │ 数量 │ 状态 │ 更新时间 │详情│
│                                                              │
│                        任务数据表格                           │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│ 自动获取：已开启 · 当前 PDD-0001 · 正在采集 SKU · 已完成 42 个 │
└─────────────────────────────────────────────────────────────┘
```

垂直区域依次为顶部命令区、可伸展表格区和稳定状态区。表格获得全部剩余高度，状态区不得遮挡最后一行或滚动条。

## 4. 顶部命令区

### 4.1 开始自动获取 / 停止自动获取

- 使用 `PrimaryPushButton`，是页面唯一主要强调操作。
- 初始文本为“开始自动获取”，图标表达开始。
- 启动成功后文本变为“停止自动获取”，按钮位置和宽度尽量稳定。
- `[必须]` 这两个文案是**按钮标签**。状态栏里的“自动获取：已开启/已停止”说的是**功能状态**，两者不是一回事，不要混改。
- 启动过程中禁用重复点击，显示“正在启动”。
- 停止表示不再领取新任务；当前任务进入安全停止流程。
- 如果设备、Admin 或必要设置无效，按钮可禁用，但附近必须说明缺少的条件。

每一轮先补交一条本地 Outbox；若无待提交结果则执行最早的本地采集任务，再没有
才向 Admin 领取一条。领取、手机采集和提交都在单独的工作线程完成，一轮结束且
线程完全退出后，由主线程的单次定时器安排下一轮。暂无任务时默认 5 秒后重试；
可恢复的 Admin 错误按 5、10、20、30 秒退避。需要人工处理、不可恢复错误、设备
或配置错误会停止自动获取。采购演练执行器和 Android 设备都准备好时，可以领取
采购任务；界面必须明确显示“演练”，任何路径都不得显示成真实下单。

- 补交本地 Outbox 不依赖手机，可以在 Android 设备断开时继续执行。
- 执行本地任务或向 Admin 领取新任务前，工作线程必须用 `adb devices -l` 检查已保存的精确设备号。USB 和 Wi-Fi 设备都只接受 `device` 状态。
- 设备未连接、`offline`、`unauthorized` 或 ADB 检查失败时，立即停止本轮和自动获取；不得领取新任务，也不得启动本地任务。
- 设备错误使用一条持久 `InfoBar` 提示，提供“打开设置”和“关闭提示”。重复错误替换旧提示，不得堆叠。

### 4.2 搜索与筛选

建议控件：

- 任务类型：`ComboBox`，选项为“全部、采集、采购”。
- 任务状态：`ComboBox`，选项为“全部”及标准任务状态。
- 关键词：`SearchLineEdit`，提示“任务编号、商品编号或商品标题”。
- 搜索：普通 `PushButton`。

筛选条件之间采用 AND。点击搜索或在关键词输入框按 Enter 执行本地数据库查询，不请求领取任务。活动筛选必须可见，筛选无结果时保留条件并提供清除入口。

### 4.3 刷新与重新执行

- “刷新”只重新读取本地任务列表，不请求 Admin，也不操作手机。
- “重新执行”位于刷新右侧；没有选中任务时禁用。
- 点击后先校验任务，再显示明确的“重新采集”确认弹窗。弹窗显示任务编号、商品标题，并说明新结果会覆盖 Client 和 Admin 的当前采集数据。“暂不重新采集”是默认聚焦的安全操作，点击该按钮、按 `Escape` 或关闭弹窗都不得启动任务。
- 用户确认后，工作线程必须先检查已保存 Android 设备的实际连接状态，再重置任务和创建执行记录。检查失败时保留原任务状态、采集结果和执行历史。
- 允许重新采集已经结束或处于“等待重试”的采集任务。采购、执行中、结果待提交、仍有未发送 Outbox 或自动获取忙碌时必须阻止，并用中文说明原因。
- 确认后只执行选中的稳定任务编号，不领取新任务，不先处理其他任务或 Outbox。
- 重新采集在工作线程运行。执行期间禁用“获取任务”，“重新执行”变为可点击的“停止重新采集”。
- 点击停止后按钮显示“正在停止…”并禁用重复点击；底部明确说明正在等待手机当前操作结束。uiautomator2/ADB 的单次调用返回后，采集在下一个安全检查点停止；不得强制结束工作线程。
- 重新采集的警告和错误 `InfoBar` 必须有可见的“关闭提示”按钮；同一时间只保留一条，新提示替换旧提示。
- 每次重新采集创建新的执行记录和幂等键；当前结果更新，旧结果保存在历史执行记录中。
- 采购任务始终不能通过“重新执行”入口启动；需要处理时由自动获取的安全恢复流程决定。
- “等待重试”当前没有倒计时。自动获取因可恢复采集错误停止时，底部状态显示
  “重试已暂停”，并提示选择任务点击“重新执行”或重新启动获取任务。

## 5. 任务表格

表格显示的是**本机已领取的全部任务**，包括正在做的和早已做完的。已完成任务永久保留，不会被清理，所以数据只增不减——增量加载和索引是必须的，不是优化。

使用 `qfluentwidgets.TableView`、自定义 `QAbstractTableModel` 和 Repository 查询。不得使用行号作为任务身份，也不得把完整 `pdd_data` 放入模型。

### 5.1 列定义

| 列 | 对齐 | 显示规则 |
|---|---|---|
| 任务类型 | 居中 | “采集”或“采购”，颜色只作辅助 |
| 商品标题 | 左对齐、可伸展 | 空值显示“尚未获取标题”，截断时提供完整工具提示 |
| 颜色 | 左对齐 | 无值显示 `—` |
| 尺码 | 左对齐 | 无值显示 `—` |
| 价格 | 右对齐 | 格式为 `¥39.90`；采集摘要可显示 `¥39.90 起` |
| 数量 | 右对齐 | 采购数量；采集显示 `—` |
| 状态 | 居中 | 中文状态文字和状态图标/标记 |
| 更新时间 | 左对齐 | 本地时区，精确到秒或按产品确认格式 |
| 操作 | 居中 | “详情”链接或委托绘制按钮 |

### 5.2 数据行为

- 默认排序为 `updated_at DESC, id DESC`。
- 排序、筛选和数据变化后以稳定任务编号恢复当前行。
- 初始加载有限批次，滚动时通过 `canFetchMore/fetchMore` 增量加载后续任务。
- 单击非交互区域只设置当前行和选择。
- 双击行、按 Enter 或点击“详情”执行相同的非破坏性详情命令。
- “详情”使用委托或链接语义，不为每行创建常驻 QWidget。
- 空状态要分情况，文案不能一样：
  - 加载中；
  - **从没领取过任务** —— “还没有领取过任务，点击‘获取任务’开始领取”（不要写“暂无数据”，操作人员会以为是出错了）；
  - 筛选无结果 —— 提供清除条件入口；
  - Admin 离线 —— 本地数据照常显示，只在信息条说明领取失败；
  - 加载失败。

> **界面上说的"任务编号"一律指 `remote_task_id`**（例如 `PDD-20260806-0001`），不是数据库自增 `id`，更不是表格行号。行号会随排序和筛选变化，拿它当任务身份必出错。

### 5.3 增量加载模板（照抄即可）

任务可能有几万条，一次全查出来界面会卡住。做法是：先查 50 条，用户滚到底了再查下一批。Qt 的模型/视图自带这个机制，实现 `canFetchMore` 和 `fetchMore` 两个方法就行。

```python
from PyQt5.QtCore import QAbstractTableModel, QModelIndex, Qt

PAGE_SIZE = 50


class TaskTableModel(QAbstractTableModel):
    """任务表格的数据来源。只存显示需要的几个字段。"""

    def __init__(self, repository, parent=None):
        super().__init__(parent)
        self._repository = repository
        self._rows: list[dict] = []      # 已经加载进来的行
        self._filters: dict = {}         # 当前搜索条件
        self._has_more = True            # 数据库里还有没有没取完的

    def rowCount(self, parent=QModelIndex()) -> int:
        return 0 if parent.isValid() else len(self._rows)

    def canFetchMore(self, parent=QModelIndex()) -> bool:
        """Qt 会自己调用它，问"还能再加载吗"。"""
        return not parent.isValid() and self._has_more

    def fetchMore(self, parent=QModelIndex()) -> None:
        """Qt 在用户滚到底时自己调用它。"""
        if parent.isValid():
            return

        page = self._repository.list_tasks(
            filters=self._filters, limit=PAGE_SIZE, offset=len(self._rows)
        )
        if not page:
            self._has_more = False
            return

        # 必须用 begin/end 包住，直接改 self._rows 界面不会刷新
        start = len(self._rows)
        self.beginInsertRows(QModelIndex(), start, start + len(page) - 1)
        self._rows.extend(page)
        self.endInsertRows()

        self._has_more = len(page) == PAGE_SIZE

    def apply_filters(self, filters: dict) -> None:
        """换搜索条件时整表重来。"""
        self.beginResetModel()
        self._filters = filters
        self._rows = []
        self._has_more = True
        self.endResetModel()
```

注意：

| 别这么做 | 为什么 |
|---|---|
| 直接 `self._rows.append(...)` 不加 `beginInsertRows` | 界面不刷新，或者直接崩 |
| 把整个 `pdd_data` 存进 `_rows` | 几万条 JSON 全在内存里，程序会变得很卡 |
| 在 `fetchMore` 里发网络请求 | 这是主线程，界面会卡住。这里只能查本地 SQLite |
| 给每个单元格 `setIndexWidget` 放按钮 | 几万个控件，内存直接爆。"详情"那列用委托画 |

换筛选之后要恢复用户原来选中的行：**先记下当前行的 `remote_task_id`，重新加载完再按这个编号找回来**，不要记行号。

## 6. 任务详情

详情是信息查看，不要求用户立即决策，优先使用非模态详情窗口或右侧详情面板，不使用简单消息框承载长 JSON。

当前 Client 使用可调整大小的非模态详情窗口。用户可以点击表格“详情”、双击任务行，或选中任务后按 Enter 打开。相同任务只保留一个详情窗口；再次打开时切回已有窗口。按 Esc 或“关闭”按钮返回任务列表。

详情面向采购人员，任务类型、状态、当前步骤和错误说明优先使用中文。数据库中的 `current_step` 等内部值只用于业务判断和日志，不直接显示；遇到尚未适配的新步骤时显示“未知步骤”。
采购演练和恢复至少要明确显示“演练已在提交前停止”、“结果待提交”、
“只允许核对订单”和“需要人工处理”；不能只用颜色表达安全状态。

采集规格按下面顺序展示：

1. **颜色：**放在上方，每个颜色旁边直接显示采集到的价格；未采集到价格时显示“价格未采集”。同一颜色意外出现多个价格时显示最低价到最高价，并显示“价格不一致”，方便检查采集结果。
2. **尺码：**放在颜色下方，只显示尺码文字。

颜色和尺码按采集顺序显示并去重。不可用颜色除文字外还要明确显示“不可用”，不能只改变颜色。没有规格数据时保留对应分区并显示空状态。

详情至少分为：

1. **基本信息：**任务编号、类型、商品、规格、数量、金额和状态。
2. **执行状态：**当前步骤、设备、尝试次数、开始/结束时间和最近错误。
3. **PDD 数据：**标题、店铺、销量、评价、规格维度和 SKU 表格。
4. **采购结果：**演练/真实模式、确认规格、价格、订单编号、下单时间和核对状态。
5. **原始数据与诊断：**格式化 `admin_payload`、`pdd_data`、日志和 Artifact 入口。

原始 JSON 默认折叠，提供复制或导出操作；复制前不得包含凭据和敏感信息。

## 7. 底部状态区

状态区占据稳定位置，示例：

```text
自动获取：已开启 · 当前任务 PDD-0001（采集）· 正在遍历规格 · 最近领取 16:20:31
```

应表达：

- 引擎状态：已停止、轮询中、领取中、执行中、提交中、退避等待、正在停止。
- 当前任务和当前步骤。
- 最近一次领取到任务的时间。
- 可恢复错误摘要及下一步。

高频轮询无任务时不要连续弹提示。设备断开、认证失败、结果提交持续失败等需要操作的问题使用 `InfoBar`，并提供“重试”“打开设置”或“查看详情”。

## 8. 设置页

设置页使用可滚动布局和 Fluent 设置卡片，分组如下。

### Admin

- 服务地址；
- Client 编号；
- 认证状态，不直接回显完整令牌；
- 请求超时；
- “测试连接”及最近结果。

### Android 设备

- ADB 地址；
- PDD 包名；
- “测试连接”；
- 当前设备型号、Android 版本和 PDD 当前状态摘要。
- 点击设备“搜索”时可以先尝试恢复已保存的 Wi-Fi ADB，但单台设备恢复失败
  不能中断普通设备枚举。表格仍展示 `adb devices -l` 实际找到的 USB 和 Wi-Fi
  设备，状态文字同时说明恢复失败原因以及“已保存配置仍保留”。
- 只有普通设备枚举本身失败时才显示“搜索失败”并保留旧表格；程序不得因为
  设备暂时离线自动删除已保存配置。

### 自动化

- 轮询周期；
- 任务超时；
- 最大重试次数；
- 演练模式开关。

### 安全与诊断

- 最大购买数量；
- 价格允许偏差；
- Artifact 目录；
- 保留天数；
- 打开日志目录。

设置采用显式“保存设置”或项目统一的即时保存模式，不能在同一页面随机混用。MVP 推荐显式保存，验证失败时保留输入并聚焦第一个错误字段。

## 9. 状态与反馈

| 场景 | 反馈方式 |
|---|---|
| 领取到新任务 | 更新表格和状态区，不弹模态框 |
| 暂时没有可领取的任务 | 只更新状态区，**不要连续弹提示** |
| 搜索无结果 | 表格空状态和清除条件入口 |
| Admin 暂时离线 | 持久信息条，本地数据继续可用 |
| 设备断开 | 持久信息条，提供打开设置和重试 |
| 任务运行 | 底部状态区和必要进度，不阻塞整个窗口 |
| 任务失败 | 行状态、详情和信息条，不显示原始堆栈 |
| 多个订单候选 | 状态改为“需要人工处理”，打开详情决策 |
| 普通任务成功 | 更新行和状态区，不弹“成功”对话框 |

### 9.1 错误提示模板（照抄即可）

规则很简单：**普通成功什么都不弹**（更新界面就够了）；**出错用 `InfoBar`**；**只有必须让用户当场做决定时才用对话框**。

```python
from PyQt5.QtCore import Qt
from PyQt5.QtWidgets import QPushButton
from qfluentwidgets import InfoBar, InfoBarPosition


def show_recoverable_error(self, title: str, content: str, on_retry) -> None:
    """显示一条可重试的错误提示。

    title：一句话说清出了什么事
    content：说清已经保留了什么、下一步该干什么
    on_retry：点"重试"时调用的函数
    """
    bar = InfoBar.error(
        title=title,
        content=content,
        orient=Qt.Horizontal,
        isClosable=True,
        position=InfoBarPosition.TOP_RIGHT,
        duration=-1,          # -1 = 不自动消失。重要错误必须用 -1
        parent=self,
    )

    retry_button = QPushButton("重试", bar)
    retry_button.clicked.connect(on_retry)
    retry_button.clicked.connect(bar.close)
    bar.addWidget(retry_button)
```

调用示例：

```python
self.show_recoverable_error(
    title="Admin 连接失败",
    content="本地任务仍可查看，结果已保存，联网后会自动提交。",
    on_retry=self._sync_task_list,
)
```

写提示语的三条要求（对应 [06 质量与安全](06-quality-security.md) §5）：

1. **说清发生了什么** —— "Admin 连接失败"，不是"操作失败"。
2. **说清保住了什么** —— "结果已保存"。用户最怕的是白干。
3. **说清下一步** —— 给"重试"按钮，或者给"打开设置"。

不要做的事：

| 别这么做 | 改成 |
|---|---|
| 把 Python 异常堆栈贴到界面上 | 界面显示人话，堆栈写进日志 |
| 轮询没任务也弹一条提示 | 只更新底部状态区 |
| 用 `QMessageBox` 报告普通错误 | 用 `InfoBar`，别打断用户 |
| 错误提示 3 秒自动消失 | 重要错误 `duration=-1`，让用户自己关 |

## 10. 键盘与无障碍

- Tab 顺序：自动获取 → 类型 → 状态 → 关键词 → 搜索 → 刷新 → 重新执行 → 表格 → 状态区可操作项。
- `Ctrl+F` 聚焦关键词，Enter 打开当前行详情。不绑定 `F5`——界面上没有需要刷新的远端数据。
- 仅图标按钮必须设置准确的无障碍名称和工具提示。
- 表单具有可见标签，占位符不能替代标签。
- 状态、错误和任务类型不能只依赖颜色。
- 表格焦点、当前行和选择状态必须可区分。
- 支持浅色、深色、高对比度和 100%–200% 显示缩放。

## 11. 原型与验收

该页面属于主要界面改版。正式重写桌面界面前，建议先制作使用模拟数据的可运行 HTML 原型，确认信息架构、列宽、筛选、详情和状态变化。HTML 原型只用于确认交互，不能替代 PyQt 的窗口、性能、DPI 和无障碍验证。

桌面实现至少验证：

- 空数据、少量数据、大量数据和超长标题；
- 紧凑、默认、最大化和 Windows 贴靠；
- 筛选和增量加载后的当前行保持；
- 快速重复点击、后台迟到结果和窗口关闭；
- 键盘、浅色、深色、高对比度和 200% 缩放。