95 lines
7.0 KiB
Markdown
95 lines
7.0 KiB
Markdown
---
|
||
id: T-610
|
||
title: AI工场原图预览默认适应窗口并支持缩放查看
|
||
phase: 7
|
||
deps: [T-609]
|
||
status: DONE
|
||
created: 2026-07-11
|
||
---
|
||
|
||
## 问题 / 背景
|
||
|
||
⑥AI工场双击已下载的蝦皮原图、照片池图片或终选图片时，当前 `ImageStudioPreviewDialog` 将原始 `QImage` 按 100% 像素尺寸放入固定约 `720×520` 的弹窗。大于可视区域的图片首次只能看到局部，用户需要发现并操作滚动条才能查看全图；这不符合“先判断整张商品图，再检查细节”的浏览习惯。
|
||
|
||
当前预览并非使用缩略图：完整本地原图会正确加载，滚动条也可用于查看细节。问题是默认视图缺少“适应窗口”策略和明确的缩放控制，导致用户误认为原图显示不全。
|
||
|
||
本任务目标：**预览打开时默认完整显示图片，并提供中文、可发现的适应窗口与倍率查看操作；需要检查细节时仍可切回 100% 或放大后滚动浏览。**
|
||
|
||
## 方案
|
||
|
||
### 1. 默认适应窗口显示完整图片
|
||
|
||
修改旧兼容 `app/gui/tabs/image_studio.py` 中的 `ImageStudioPreviewDialog`，并同步当前正式第六 Tab 使用的 `app/gui/tabs/product_suite.py::ProductSuitePreviewDialog`。两者复用同一个原生 PySide6 预览组件，避免只修复已隐藏的旧「AI工场」入口：
|
||
|
||
- 保留完整原始 `QPixmap`，不读取缩略图缓存、不重新下载、不修改本地图片。
|
||
- 对可用图片，预览首次打开默认使用「适应窗口」模式：按 `QScrollArea.viewport()` 的实际可用尺寸等比缩放，保持原始比例，不裁切、不拉伸变形。
|
||
- 小于视口的图片不强制放大到超过 100%，避免不必要模糊；大图缩小到完整可见。
|
||
- 弹窗初始尺寸可适当增大但不得超过当前屏幕可用区域；窗口标题继续显示图片类型、资产 ID 与原始分辨率，不显示本地绝对路径、远程 URL 或技术错误。
|
||
- 窗口 resize 后，若仍处于适应窗口模式，重新计算缩放，始终完整显示；若用户已切换到固定倍率，则保持该倍率并按需要显示滚动条。
|
||
|
||
### 2. 增加缩放操作与状态
|
||
|
||
- 在预览底部或顶部增加紧凑的中文预览工具区，至少包含：
|
||
- 「适应窗口」：恢复默认完整显示。
|
||
- 「100%」：按原始像素显示，图片大于视口时显示水平/垂直滚动条。
|
||
- 「缩小」「放大」：按稳定步长调整倍率，建议范围 25%~400%，不得无限放大或缩小。
|
||
- 按钮优先使用 `QToolButton` / 熟悉的缩放图标，并提供中文 tooltip；若没有可靠图标资源，使用简短中文文字按钮，不能露出英文 UI 文案。
|
||
- 显示只读倍率 label，例如 `适应窗口`、`100%`、`125%`，用户可判断当前模式。
|
||
- 不把预览控制塞进图片内容，不遮挡图片；关闭按钮保留，Esc/窗口关闭仍可退出预览。
|
||
- 原图文件缺失或不可读取时继续显示现有中文空状态，缩放按钮禁用或不执行操作，不抛出英文异常。
|
||
|
||
### 3. 保持调用与业务语义
|
||
|
||
- 原图区双击仍遵循既有语义：未下载先走原图下载队列，下载成功后再打开预览；已下载时直接打开。
|
||
- 照片池、终选区的双击预览复用同一弹窗与缩放行为。
|
||
- 不改变原图下载、缩略图缓存、照片池、终选排序、生成、导出、SQLite、cmhub 或蝦皮 CDP 流程。
|
||
- 不增加图片编辑、裁剪、旋转、保存副本、本地图片导入或对蝦皮的任何写入动作。
|
||
|
||
## 验收要点
|
||
|
||
- 双击一张大于预览视口的蝦皮原图时，首次能在弹窗内完整看到整张图，保持比例且不裁切。
|
||
- 标题仍显示原始分辨率；预览使用完整本地文件，不使用 48px/86px 缩略图替代。
|
||
- 点击「100%」后恢复原始像素尺寸，大图可通过滚动条查看细节；点击「适应窗口」后再次完整显示。
|
||
- 缩小/放大在 25%~400% 的受限范围内工作，倍率 label 与实际图片尺寸一致；适应窗口模式下调整弹窗大小会重新适配。
|
||
- 图片小于视口时不被强制放大到超过 100%。
|
||
- 文件缺失/不可读时显示中文提示，缩放操作不报错、不展示路径、URL、堆栈或英文技术异常。
|
||
- 原图区、照片池与终选区的既有双击调用语义不回归；不改任何业务数据或网络/CDP 行为。
|
||
|
||
## 测试要求
|
||
|
||
更新或新增 `tests/test_gui.py`：
|
||
|
||
- 使用临时大图（例如 1600×1200）覆盖初始适应窗口：图片显示尺寸不超过 viewport、比例正确、标题仍包含原始分辨率。
|
||
- 覆盖「100%」「适应窗口」「缩小」「放大」的倍率、按钮边界和滚动条行为。
|
||
- 覆盖适应窗口模式下 resize 后重算尺寸，以及固定倍率模式下不被自动重置。
|
||
- 覆盖小图不被放大超过原始尺寸、文件缺失中文空状态与缩放按钮禁用。
|
||
- 覆盖原图、照片池图片和终选图片均复用同一预览弹窗，不影响下载后预览、排序和导出既有测试。
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
python -m ruff check app tests main.py
|
||
py -3.10 -m compileall app main.py
|
||
py -3.10 -m unittest discover -s tests
|
||
git diff --check
|
||
```
|
||
|
||
人工验收建议：
|
||
|
||
- 用 1:1、3:4、9:16 等大图分别双击预览，确认首次完整显示、倍率切换、滚动细节和窗口 resize 行为。
|
||
- 对一张未下载原图双击，确认下载完成后仍以适应窗口模式打开完整原图；对文件缺失记录确认中文空状态。
|
||
|
||
## 边界（不改什么）
|
||
|
||
- 不改 `app/image_studio.py`、`app/image_studio_images.py`、`app/image_studio_export.py`、SQLite schema、目录结构或图片保存格式。
|
||
- 不改原图下载队列、缩略图异步缓存、照片池、终选、生成、导出、cmhub 与蝦皮 CDP 流程。
|
||
- 不增加裁剪、旋转、滤镜、编辑、另存、打印、本地图片导入或自动上传蝦皮。
|
||
- 不修改①至⑤模块。
|
||
|
||
## 执行记录
|
||
|
||
- 2026-07-16：新增 `app/gui/image_preview.py::ImagePreviewDialog`，保留完整本地图像，默认等比适应窗口且小图不放大；提供适应窗口、100%、缩小、放大和 25%～400% 固定倍率，固定倍率下窗口 resize 不重置，超大图片在适应模式下可低于 25% 以保证完整显示。
|
||
- 2026-07-16：旧兼容 `ImageStudioPreviewDialog` 与当前正式第六 Tab 的 `ProductSuitePreviewDialog` 改为复用同一预览组件；标题只显示中文上下文和原始分辨率，文件缺失时显示中文空状态并禁用缩放，不暴露本地路径。
|
||
- 2026-07-16：`tests/test_gui.py` 新增默认适应、100% 滚动查看、固定倍率 resize、缩放边界、小图不放大、旧入口复用和缺失文件回归测试。
|
||
- 验证：当前工作区定向 3 项 GUI 测试通过，ruff、compileall、`git diff --check` 通过；当前工作区全量测试仅受任务开始前未提交的默认封面提示词改名影响而失败 3 项。将本任务文件复制到基于 `HEAD` 的隔离 worktree 后，`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`py -3.10 -m unittest discover -s tests`（498 项）和 `git diff --check` 全部通过。
|