--- id: T-610 title: AI工场原图预览默认适应窗口并支持缩放查看 phase: 7 deps: [T-609] status: TODO created: 2026-07-11 --- ## 问题 / 背景 ⑥AI工场双击已下载的蝦皮原图、照片池图片或终选图片时，当前 `ImageStudioPreviewDialog` 将原始 `QImage` 按 100% 像素尺寸放入固定约 `720×520` 的弹窗。大于可视区域的图片首次只能看到局部，用户需要发现并操作滚动条才能查看全图；这不符合“先判断整张商品图，再检查细节”的浏览习惯。 当前预览并非使用缩略图：完整本地原图会正确加载，滚动条也可用于查看细节。问题是默认视图缺少“适应窗口”策略和明确的缩放控制，导致用户误认为原图显示不全。 本任务目标：**预览打开时默认完整显示图片，并提供中文、可发现的适应窗口与倍率查看操作；需要检查细节时仍可切回 100% 或放大后滚动浏览。** ## 方案 ### 1. 默认适应窗口显示完整图片 修改 `app/gui/tabs/image_studio.py` 中的 `ImageStudioPreviewDialog`： - 保留完整原始 `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 流程。 - 不增加裁剪、旋转、滤镜、编辑、另存、打印、本地图片导入或自动上传蝦皮。 - 不修改①至⑤模块。 ## 执行记录 - 待执行。