cmautobuy/docs/task/4-实现-pdd-任务列表-ui.md

# 4 实现 PDD 任务列表 UI

- 类型：需求
- 父级大工单：#1
- 所属 MVP / 版本：#2 / MVP
- 状态：已完成
- 日期：2026-08-06
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/4

## 背景与目标

原来的 PDD 页面还是手工输入商品链接、颜色和尺码的旧占位页。本任务先实现可独立演示的任务列表 UI，为后续 SQLite Repository 接入提供明确的数据和事件入口。

## 最终方案

- 页面采用顶部命令区、中部任务表格、底部运行状态区。
- `TaskRow` 只保存列表展示和搜索字段，不包含 `pdd_data`。
- `TaskTableModel` 使用 `QAbstractTableModel`，当前以内存数据模拟后续 Repository 查询结果。
- 表格使用 `qfluentwidgets.TableView`，默认按更新时间倒序，每页展示 50 条。
- 页面提供自动获取、搜索、刷新和详情信号，不执行数据库、网络或手机操作。
- 表格和表头始终显示；无真实任务时，根据表格高度使用不可交互的空行填满可视区域。
- 无任务、筛选无结果、加载中和加载失败提示显示在表格上方，不替换表格。
- 提供 `set_tasks()`、`set_auto_fetch_state()` 和 `set_engine_status()` 等更新入口。

测试中发现启用表格排序会覆盖默认排序列，最终增加了对“更新时间”列的显式降序设置。首次实现使用空状态页替换表格；用户验收时要求无数据也保留空表格，因此调整为动态占位空行，并避免产生没有意义的空数据滚动条。

## 改了哪些

- `client/src/pdd_ui.py`：完成 PDD 任务列表模型、页面布局、筛选、分页、空状态、状态更新接口和界面事件信号。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 包含自动获取、类型、状态、关键词、搜索和刷新控件 | 通过 |
| 表格列与界面基线一致 | 通过 |
| 使用 `TableView + QAbstractTableModel` | 通过 |
| 模型不保存 `pdd_data`，使用稳定任务编号 | 通过 |
| 默认按更新时间倒序并支持组合筛选 | 通过 |
| 操作列和激活行发出详情信号 | 通过 |
| 空数据与筛选无结果文案不同 | 通过 |
| 无数据时表格、表头和禁用空行保持显示 | 通过 |
| Ctrl+F 和关键词 Enter 可用 | 通过 |
| 语法、分页和离屏装配测试通过 | 通过 |
| 未连接数据库、Admin 或 Android 设备 | 通过 |

## 测试

- 执行的命令：

  ```powershell
  C:/Python310/python.exe -m py_compile src/pdd_ui.py
  ```

  ```powershell
  $env:QT_QPA_PLATFORM="offscreen"
  # 使用 QApplication 创建 PDDTaskPage 和 MainWindow，注入采集、采购模拟任务，
  # 检查排序、筛选、金额、详情信号、空状态、120 条分页和 Ctrl+F。
  Remove-Item Env:QT_QPA_PLATFORM
  ```

- 结果：语法检查通过；完整离屏测试输出 `PDD_UI_OK`；分页和快捷键测试输出 `PAGINATION_AND_SHORTCUT_OK`；无数据表格、动态空行、禁用状态和无空数据滚动条测试输出 `EMPTY_GRID_OK`。
- **没验证到的部分**：未进行用户人工界面验收、真实 Windows 字体效果、深色/高对比度、200% 缩放和真机测试。离屏环境输出既存的 PyQt5 字体目录缺失警告，不影响模型和窗口断言。

## 相关提交

- `ad19700` 实现 PDD 任务列表 UI
- `2322b46` 无数据时保留任务表格和动态空行