cmshoppe/docs/tasks/T-649.md

---
id: T-649
title: 商品套图历史店铺下拉筛选和结果目录入口精简
phase: 7
deps: [T-646]
status: DONE
created: 2026-07-17
---

## 问题 / 背景

T-646 的全局「历史生成」窗口目前使用自由文本输入框按店铺/账号模糊筛选。账号名和别名可能相近，模糊匹配会让用户难以确认当前筛选对象，也无法清楚表达已从账号管理中删除、但历史记录仍应可查看的店铺。

⑥顶部另有「打开结果文件夹」入口，直接打开内部生成目录。该目录可能包含中间文件、失败输出或内部存储结构，不适合作为正式用户导出路径；用户已经可以在历史窗口按轮次导出成功结果。

## 方案

### 1. 历史店铺改为结构化下拉筛选

修改全局历史查询和 `ProductSuiteGlobalHistoryDialog`：

- 将「店铺」自由文本框替换为 `QComboBox`，首项固定为「全部店铺」；商品 ID 关键字输入和「仅当前商品」筛选保留，三者可叠加；
- 下拉项展示当前账号管理中可用账号，标签使用「账号名（账号别名）」；实际筛选值始终使用稳定的 `account_alias`，不能依赖显示文字反查；
- 同时从未软删除的历史商品项目中收集账号别名。若某历史别名已不在账号管理列表，仍须保留为可选项，标签明确标为「历史店铺：别名（账号已删除）」；不伪造账号名，也不丢失历史查询能力；
- 新增或扩展结构化查询参数（如 `account_alias`），在 SQLite 查询层使用精确匹配 `projects.account_alias = ?`；不再把下拉选择转换为 `LIKE` 模糊文本；如保留旧 `account_query` 参数，必须仅作为兼容入口并有明确优先级；
- 打开窗口、刷新、筛选或加载更多时保持稳定排序和分页；刷新下拉列表时尽量保留当前仍存在的选择，否则回退到「全部店铺」；不能一次把所有原图加载进内存；
- 顶部「历史生成」仍默认查看全部商品和全部店铺。T-648 从生成确认框打开历史时可单独启用“仅当前商品”，不能改变此默认行为。

### 2. 移除直接打开内部结果目录的正式入口

修改⑥「商品套图」顶部上下文区：

- 移除可见的「打开结果文件夹」按钮、信号连接、可用状态和相关 GUI 测试断言；
- 不删除内部 `generated` 目录、已有图片、项目文件、导出能力、预览能力或历史窗口中的「导出本轮」；
- 用户需要取得图片时，统一从历史窗口选择某一轮后使用「导出本轮」，由用户选择外部目标目录并只复制成功且存在的输出图；
- 若保留无 UI 引用的内部辅助方法，必须不再能通过普通用户界面直接访问原始目录，且不得影响现有内部调用；优先清理确定无引用的死代码。

### 3. 文档与交互一致性

- 所有下拉项、空态、筛选提示和导出引导使用中文，不显示完整本地路径、接口 URL、模型别名、Key 或上游错误；
- 同步更新 `docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`，说明历史店铺的精确别名筛选、历史账号兼容和结果导出入口；
- 如顶部区域布局或历史筛选 UI 需要更新效果图，保存到 `docs/ui/` 并在 `docs/ui/README.md` 登记。

## 验收要点

- [ ] 全局历史窗口的店铺筛选为下拉框，首项是「全部店铺」；不再提供店铺自由文本模糊输入。
- [ ] 当前账号显示为「账号名（账号别名）」，选择后按精确 `account_alias` 查询，不会把相近别名、账号名或商品 ID 误匹配进来。
- [ ] 已删除账号但仍有未软删除历史项目的别名可被选择，且标签明确标识为历史店铺。
- [ ] 店铺、商品 ID 和仅当前商品筛选可正确叠加，刷新/分页后排序与结果稳定。
- [ ] 顶部「历史生成」初次打开仍默认全局视图，不会被上一商品或生成确认路径永久改变。
- [ ] ⑥顶部不再显示「打开结果文件夹」；历史窗口的「导出本轮」仍能把成功图片复制到用户选择的目录。
- [ ] 不删除或修改内部生成图片、历史轮次、job、asset、项目或导出数据。
- [ ] 不影响套图生成、单图重试、历史预览、AI帮写、cmhub 调用、Shopee CDP、采集、AI生成、更新蝦皮、账号管理或设置。

## 测试

- `tests/test_image_studio.py`：
  - `account_alias` 精确筛选、全部店铺、商品 ID 与当前项目组合筛选；
  - 相近别名不误匹配；历史别名可返回；软删除项目继续被排除；
  - 分页与稳定排序不回归，兼容参数的优先级明确。
- `tests/test_product_suite_gui.py`：
  - 下拉项的显示标签和 `itemData` 正确，当前账号与历史店铺均可选；
  - 切换店铺、商品 ID、仅当前商品后刷新结果正确；
  - 历史窗口默认全局，外部指定当前项目的路径只影响该次窗口状态；
  - 顶部不存在「打开结果文件夹」入口，历史导出入口和中文空态仍可用。
- 运行：

```bash
py -3.10 -m unittest tests.test_image_studio tests.test_product_suite_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
```

- 人工建立至少两个当前账号、一个已删除账号的历史项目和相近别名测试数据，检查 Windows 100% / 125% / 150% 缩放下下拉框、筛选、分页和导出路径。

## 边界（不改什么）

- 不删除账号、项目、轮次、job、asset、图片或任何历史记录。
- 不实现批量导出、全部历史导出、历史删除、历史重跑、从历史恢复当前轮或直接更新蝦皮。
- 不修改 cmhub API、模型别名、图片理解、生图、下载、轮询、超时、并发或计费逻辑。
- 不修改 Shopee CDP、商品采集、AI生成、更新蝦皮、账号登录或设置模块。

## 执行记录

- 2026-07-17：根据全局历史筛选和结果目录入口精简的产品讨论创建任务。待实现。
- 2026-07-17：历史窗口店铺筛选改为以 `account_alias` 为值的下拉框，保留全部店铺、当前账号和已删除账号的历史别名；查询层新增精确别名参数并保留旧文本参数兼容。移除⑥顶部「打开结果文件夹」，历史按轮导出和结果卡单图文件操作保持可用；同步更新架构、接口、路由说明及回归测试。
- 验证通过：`py -3.10 -m unittest tests.test_image_studio tests.test_product_suite_gui`（74 项）、`py -3.10 -m unittest discover -s tests`（569 项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。