chengmaandClaude Opus 5
4f920f9d8b
raw_data 不进 Git 原始报表含逐商品台币销售额等商业数据，进了 Git 就是永久历史。 - .gitignore 排除 raw_data/ - 改掉三处"仓库里有一份样本"的失真表述，改为向项目负责人索取 - 06 §2.1 相应加强：既然大样本不进库，admin/testdata/ 下的脱敏小样本 就必须提交，否则别人拉下来测试跑不了；并写明脱敏做法 主按钮文案 开始自动获取 → 获取任务 ⇄ 停止获取 只改按钮标签。"自动获取"作为功能名保留（状态栏、Tab 顺序、 协调器开关等处不动），05 §4.1 加了一句说明两者不是一回事。 已知遗留：pdd_ui.py 自身仍不一致——构造时用「获取任务」， 但状态机 485/487 行仍是「开始自动获取」/「停止自动获取」， 会覆盖掉构造时的文字。该文件有未提交改动，本次未触碰， 差异已记入 02 §3.1，需另开工单修。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
338 lines
15 KiB
Markdown
338 lines
15 KiB
Markdown
# 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 或必要设置无效，按钮可禁用，但附近必须说明缺少的条件。
|
|
|
|
### 4.2 搜索与筛选
|
|
|
|
建议控件：
|
|
|
|
- 任务类型：`ComboBox`，选项为“全部、采集、采购”。
|
|
- 任务状态：`ComboBox`，选项为“全部”及标准任务状态。
|
|
- 关键词：`SearchLineEdit`，提示“任务编号、商品编号或商品标题”。
|
|
- 搜索：普通 `PushButton`。
|
|
|
|
筛选条件之间采用 AND。点击搜索或在关键词输入框按 Enter 执行本地数据库查询，不请求领取任务。活动筛选必须可见，筛选无结果时保留条件并提供清除入口。
|
|
|
|
## 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。
|
|
|
|
详情至少分为：
|
|
|
|
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 当前状态摘要。
|
|
|
|
### 自动化
|
|
|
|
- 轮询周期；
|
|
- 任务超时；
|
|
- 最大重试次数；
|
|
- 演练模式开关。
|
|
|
|
### 安全与诊断
|
|
|
|
- 最大购买数量；
|
|
- 价格允许偏差；
|
|
- 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% 缩放。
|