# 浏览器按需验收

项目不依赖 Playwright 或其他固定浏览器测试框架，不下载或维护专用浏览器。界面、导航、剪贴板、响应式布局等浏览器行为变更，使用现有浏览器人工或通过 computer-use 工具按需验收。外部工具由操作者选择，不作为仓库安装、构建或 CI 的前置依赖。

`make check` 保留 Go 单元/集成测试、前端 Vitest、Lint、类型检查、OpenAPI 一致性检查与生产前端构建；它不验证真实浏览器交互。构建成功、单元测试通过或截图不能替代浏览器验收。以下清单承接原桌面/手机 E2E 场景，不表示这些场景已执行或仍由 CI 自动覆盖。

## 准备

- 按 README 构建并启动本地二进制，使用独立测试数据目录和测试管理员，禁止使用生产数据或凭据。通过实际 Go 服务访问生产前端，而不只查看 Vite 页面。
- 本机 HTTP 调试仅在回环地址使用 `IMAGESILO_COOKIE_SECURE=false`；远程环境使用 HTTPS，保持安全 Cookie。
- 准备一张微型有效 WebP 图片；桌面和手机各上传一张。需要验证滚动、删除或排队时，仅额外创建满足场景所需的最少测试图片。
- 涉及迁移管理时，按[导入指南](./imports.md)在独立测试目录准备 `/i/2026/08/migration-desktop.webp` 和 `/i/2026/08/migration-mobile.webp`，仅对这些可丢弃文件启用 `IMAGESILO_MIGRATION_MUTATIONS=true`。删除验收不得指向真实迁移目录。
- 桌面至少检查 1280 × 720 与 1024 × 768；响应式变更按需覆盖 320、375、768 和 1440px 及短横屏。手机可使用现有浏览器的移动视口模拟（例如 393 × 851），注明是否为真机。授予必要的剪贴板权限；不能读取时实际粘贴到本地输入框核验，不记录敏感内容。

## 桌面清单

- [ ] 登录页页脚可见，无意外纵向溢出；登录后进入上传页。
- [ ] 品牌 Logo 真实加载，`/brand/favicon-64.png` 返回 200；页脚年份、仓库、License 和版本链接正确。
- [ ] 上传 WebP 成功并显示完成状态；复制直链得到 `/image/` URL，切换 Markdown 后实际复制内容包含 `![`。
- [ ] 上传两张测试图片，令会话在开始前失效：首个上传返回 401 后跳转登录，排队图片不会继续发起上传；检查网络请求数量。
- [ ] 有未完成上传时选择离开，分别验证「留在此页」和「停止并离开」；停止后排队请求不再启动，返回上传页无残留队列或迟到提示。
- [ ] 在 1024 × 768 下，上传链接格式菜单不越出内容区；恢复宽屏后布局正常。
- [ ] 图片库显示真实缩略图（`/api/v1/images/{id}/thumbnail`）；选中图片后的批量复制主按钮与下拉按钮等高，格式菜单在工具栏上方且无遮挡。
- [ ] 打开详情进入 `/admin/images/{id}`，图片名正确，Markdown 复制有效；从筛选后的长列表进入再返回，筛选与滚动位置保持。
- [ ] 从筛选列表进入详情并永久删除：返回原筛选结果，已删除项消失，滚动位置限制在剩余页面范围内；直接访问详情并删除时回到默认列表。
- [ ] 在删除后的列表刷新尚未完成时使用浏览器返回，延迟响应完成后保持当前页面与筛选，不发生二次跳转。
- [ ] 迁移管理在慢速网络下显示扫描中状态；文件缩略图可见，刷新/应用筛选按钮样式一致（14px），键盘 Enter 刷新有成功反馈。
- [ ] 迁移永久删除开关状态明确，复制链接指向原路径；确认删除测试文件后卡片消失，该路径返回 404。
- [ ] 路径映射上传另一份测试图片并创建 `/legacy/browser-check.webp`，旧 URL 返回 200 与 `image/webp`。
- [ ] 创建带 `images:upload`、`images:read_private` Scope 的测试 Token；通过 API 上传私密图片返回 201，匿名读取返回 401，携带 Token 读取返回 200。可使用[API Token 指南](./api-token-usage.md)中的请求方式，不把 Token 写入 URL 或验收记录。
- [ ] 按图片名、私密可见性和 API Token 来源筛选，找到该图片；详情显示 API Token 来源。确认永久删除后返回列表，携带 Token 读取原 URL 返回 404。
- [ ] 全新数据目录下，同格式压缩和 JPEG/PNG 转 WebP 默认关闭；系统页数据库与图片/别名索引数量一致。
- [ ] 切换深色与 English 后，刷新仍保持主题和语言，导航文字正确；各管理页标题、长路径和长名称无横向溢出或遮挡。
- [ ] 底部导航在滚动、快速切页及浏览器历史前进/后退后保持可用且当前项正确。使用 Cmd/Ctrl+K 搜索，Escape 关闭菜单和弹窗，焦点回到触发器；弹窗关闭后背景可交互。
- [ ] 慢速或失败的图库请求显示加载、失败和重试状态，恢复后仍能导航；减少动态效果设置下交互立即完成。

## 手机清单

- [ ] 登录页与页脚适配窄屏，无意外溢出；登录、上传 WebP 成功。
- [ ] 通过菜单进入图片库，图片卡片可见；切换私密/公开后状态正确，直链复制有效。
- [ ] 选中图片，批量工具栏切换 BBCode，实际复制内容包含 `[img]`；菜单和按钮可见、可操作。
- [ ] 可用键盘 Enter 打开菜单并进入迁移管理，测试迁移文件可见，复制 BBCode 包含正确的原路径；导航弹窗内焦点可循环，Escape 后返回触发器。
- [ ] 中英文及深浅主题下，窄屏筛选、长文件名和菜单不溢出，主要触摸目标可操作；横图、竖图和方图在单列图库中完整显示。

## 记录与清理

每次根据变更选择相关场景，涉及跨页面流程时执行完整桌面和手机闭环。记录：

| 项目 | 内容 |
| --- | --- |
| 版本 | 提交或工作区、构建方式 |
| 环境 | 浏览器名称/版本、操作系统、视口、真机或模拟 |
| 场景 | 执行的清单项、输入与预期结果（不含秘密） |
| 结果 | 实际观察、通过/失败/未验证；未执行或受阻的原因 |
| 证据 | 必要的截图、HTTP 状态、控制台/网络错误；遮盖 Cookie、Token 与私密内容 |

无法取得浏览器证据时明确写“未执行”或“未验证”，不得用 CI 通过替代。验收后停止测试服务、吊销测试 Token，并仅清理本次创建的测试数据和图片，保留需要的脱敏验收记录。

## 2026-10-31 合并验收记录

- 版本：`worktree/prism-ui` 的 `df25e18` 合并 `origin/main` 的 `aecbdc4`；采用 main 的工具链与按需浏览器验收策略，保留本分支安全依赖补丁。`web/src`、`internal`、`api` 和 `db` 与合并前一致。
- 自动检查：Node.js 24.22.1、Go 1.26.10 下 `npm --prefix web ci` 和 `make check build` 通过，包含 71 项前端单测、Go 测试及工具链策略测试、Lint、类型检查、OpenAPI 一致性和生产构建。项目依赖与安装目录中均无 Playwright。
- 浏览器：macOS 内置 Chromium，访问隔离数据目录的真实 Go 服务；桌面实际视口 1600×900、1280×720、1024×767，手机模拟实际视口 320×640、394×851。工具的视口缩放以页面实际尺寸为准，未使用真机。
- 已验证：登录、三张 PNG 实际上传、批量直链及 BBCode 实际复制、图库/详情返回、改为私密、手机更多菜单与设置页、中文/English 和深浅主题。横图、竖图、方图均完整显示；手机单列保持原比例，所测视口无横向溢出，页面错误日志为空。
- 范围限制：本轮未逐项重跑上述全部清单，也未执行真机 Safari 或双架构容器 smoke。401 队列、普通错误重试等既有单测仍保留并通过，不将历史 E2E 结果当作本轮浏览器验收结果。