create-bubbles 0.1.26 → 0.1.28

package/template-vp-monorepo-react-nestjs/.spaces/{server/04.upload.md → 02./344/270/212/344/274/240/344/270/216/346/226/207/344/273/266//345/210/206/347/211/207/344/270/212/344/274/240//345/256/236/346/226/275/346/225/231/347/250/213.md}

@@ -5,6 +5,8 @@
 > 适用技术栈：NestJS 11、Fastify、Drizzle、PostgreSQL、MinIO、React。
 >
 > 本文面向以前端开发为主、刚开始写 NestJS 的开发者。请严格按顺序操作，不要跳过数据库迁移、原始流解析和字节数校验。
+>
+> 当前状态（2026-09-17）：仓库已经包含上传模块、分片上传接口、流式中转和 `upload_sessions` 表；本文保留为实施教程，不等同于当前代码验收报告。活动分片租约、定时清理等第 18 步生产加固能力尚未落地。
 
 ## 先看最终方案
 
@@ -99,13 +101,13 @@ uploading ──完成请求──> completing ──MinIO 合并成功──> c
 
 ### 必要说明
 
-当前模板有三个容易踩坑的现状：
+当前模板有三个需要先确认的现状：
 
 1. `apps/server/.env` 当前端口是 `13000`。
-2. `apps/web/.env.dev` 当前代理目标是 `http://localhost:10000`。联调前应把它改成 `http://localhost:13000`，或者让 Server 改为 10000，两边必须一致。
-3. `apps/web/src/utils/request/index.ts` 的封装默认按“有 `code/data` 外壳”解析，但 Server 成功响应是直接对象。本文的上传控制接口会使用 `isWrapped: false`。
+2. `apps/web/.env.dev` 当前 API 目标也是 `http://localhost:13000`；修改任一端口后必须同步另一端配置。
+3. `apps/web/src/utils/request/index.ts` 当前使用 `isWrapped: false`，与 Server 直接返回业务对象的响应形式一致。
 
-`.spaces/server/todo.md` 是历史规划，其中部分状态已经落后于当前源码。写代码时应以 `apps/server/src` 的实际内容为准。
+旧版后端待办已经退出正式文档体系，其中部分状态也落后于当前源码。写代码时应以 `apps/server/src` 的实际内容和 `.spaces/` 中的现行专题文档为准。
 
 ### 验证
 
@@ -123,9 +125,9 @@ pnpm --filter server build
 
 ### 常见错误
 
-- 前端一直报网络错误，却只检查上传代码，没有检查 10000/13000 端口不一致。
+- 前端一直报网络错误，却只检查上传代码，没有确认前后端当前端口是否一致。
 - 把 MinIO 控制台端口 9001 当成 S3 API 端口。S3 API 是 9000。
-- 使用 `.spaces/server/todo.md` 覆盖当前源码事实。
+- 使用已经退出正式文档体系的历史待办覆盖当前源码事实。
 
 ---
 
@@ -677,14 +679,15 @@ drizzle
 
 ### 生成迁移
 
+当前仓库完整迁移链受企业层级残留 `0003` 和未确认邀请实现 `0004` 阻断。此处当前只生成并审阅上传迁移，不得执行完整 `db:migrate`，也不得用 `db:push` 或手工跳号绕过。阻断解除后的执行流程以[数据库迁移指南](../../05.运行维护/数据库迁移/操作指南.md)为准。
+
 在模板根目录执行：
 
 ```powershell
 pnpm --filter server db:generate
-pnpm --filter server db:migrate
 ```
 
-不要手写迁移 SQL，也不要只在本地执行 `db:push` 后就结束。模板需要可重复执行、可提交的迁移历史。
+不要手写迁移 SQL，也不要只在本地执行 `db:push` 后就结束。模板需要可重复执行、可提交的迁移历史；当前生成结果只能进入审阅，不能据此修改数据库。
 
 ### 验证
 
@@ -2996,12 +2999,7 @@ import { envVariables } from '@/utils/env'
 import alovaRequest from '@/utils/request'
 
 export type UploadSessionStatus =
-  | 'uploading'
-  | 'completing'
-  | 'completed'
-  | 'aborting'
-  | 'aborted'
-  | 'expired'
+  'uploading' | 'completing' | 'completed' | 'aborting' | 'aborted' | 'expired'
 
 export interface UploadedPart {
   partNumber: number
@@ -3983,11 +3981,10 @@ docker-compose.yml
 
 ### 启动位置
 
-全部命令都从模板根目录运行：
+全部命令都从模板根目录运行。数据库必须预先使用经审阅的合规基线准备完成；当前不得在启动前执行仓库完整迁移链：
 
 ```powershell
 docker compose up -d postgres redis minio minio-init
-pnpm --filter server db:migrate
 pnpm --filter server dev
 ```
 
@@ -4499,6 +4496,12 @@ apps/web/src/router/index.tsx
 - [ ] 对公网/多实例部署已实现活动分片租约，Complete/Abort 会先封口并等待租约归零。
 - [ ] 应用有过期清理，Bucket 有未完成 Multipart 生命周期兜底。
 - [ ] Multipart ETag 没有被当作整个文件 MD5。
-- [ ] `vp run ready`、数据库迁移和 25 MiB 三片验收全部通过。
+- [ ] 全仓迁移阻断已经解除，`vp run ready`、经审阅的数据库迁移和 25 MiB 三片验收全部通过。
+
+当前仓库已经具备“浏览器 10 MiB 分片 → NestJS 流式中转 → MinIO Multipart → 断点续传”的主要代码，但是否完整满足第 1～17 步仍应以专项测试和实际联调为准；当前尚缺上传专项测试。完成第 18 步的竞态、清理和权限加固后，才适合对公网或多实例上线。后端仍承担双向带宽，容量规划必须按“用户上传流量约两次经过 Server 网络栈”计算。
+
+## 文档变更记录
 
-完成并验证第 1～17 步后，模板才会具备“浏览器 10 MiB 分片 → NestJS 流式中转 → MinIO Multipart → 断点续传”的教学基础方案；当前仓库只是写入了这份教程，并没有自动实施教程里的业务代码。完成第 18 步的竞态、清理和权限加固后，才适合对公网或多实例上线。后端仍承担双向带宽，容量规划必须按“用户上传流量约两次经过 Server 网络栈”计算。
+| 日期       | 变更摘要                                                                         | 影响范围                 |
+| ---------- | -------------------------------------------------------------------------------- | ------------------------ |
+| 2026-09-18 | 标明当前仓库完整迁移链受 `0003`／`0004` 阻断，移除可被直接复制执行的全量迁移命令 | 迁移生成、启动与上线检查 |

package/template-vp-monorepo-react-nestjs/.spaces/{server/06./345/205/254/345/205/261/351/230/237/345/210/227/346/216/245/345/205/245/346/226/271/346/241/210/README.md → 03./344/273/273/345/212/241/351/230/237/345/210/227//345/205/254/345/205/261/351/230/237/345/210/227//350/256/276/350/256/241/346/226/271/346/241/210.md}

@@ -1,11 +1,14 @@
 # NestJS BullMQ 公共任务队列接入方案
 
-> 状态：实施方案，尚未修改代码  
+> 状态：历史实施方案；公共队列基础能力已进入当前源码，本文保留设计依据和接入说明，不作为当前验收报告  
 > 基线日期：2026-09-03  
+> 当前事实复核：2026-09-17  
 > 适用范围：apps/server、Redis、BullMQ  
 > 面向读者：以前端开发为主、刚开始搭建 NestJS 后端的开发者  
 > 本文目标：先建立一套所有后端业务都能复用的公共队列能力，不实现上传清理或其他真实业务任务。
 
+当前源码已经包含 BullMQ 依赖、队列配置、`TaskQueueModule`、`TaskQueueService`、`TaskQueueProcessor`、Worker 启停注册器及相关测试文件。上传清理仍是独立设计，不能因公共队列已落地而视为已经实现。
+
 ## 0. 结论先行
 
 本项目第一版公共队列采用：
@@ -172,13 +175,15 @@ HTTP 状态可使用 202 Accepted。前端不能直接连接 Redis。如果前
 - 独立 Worker 应用
 - Transactional Outbox
 
-上传清理只作为未来附加项，详细说明见 [上传清理.md](./上传清理.md)，当前不实现。
+上传清理只作为后续附加项，详细说明见 [上传清理设计方案](../../02.上传与文件/上传清理/设计方案.md)，当前源码尚未实现该业务。
 
 ---
 
-## 3. 当前项目基线
+## 3. 历史项目基线（2026-09-03）
+
+下表记录公共队列实施前的源码状态，仅用于理解当时为何需要本方案；判断当前能力时应以源码和本文开头的当前事实复核为准。
 
-| 项目               | 当前状态                  | 本方案处理                            |
+| 项目               | 当时状态                  | 本方案处理                            |
 | ------------------ | ------------------------- | ------------------------------------- |
 | NestJS             | 11.1.x，Fastify           | 使用 @nestjs/bullmq 12                |
 | Redis              | Redis 8，已开启 AOF       | 本地复用 Redis，队列使用 DB 1         |
@@ -1805,7 +1810,9 @@ vp run ready
 
 第一次 `vp run --filter server test` 验证普通测试，并确认真实 Redis 测试默认跳过；设置 RUN_QUEUE_INTEGRATION 后的第二次测试才验证真实 Redis 链路。finally 会清理环境开关，确保后面的 `vp run ready` 恢复默认行为。
 
-### 验收清单
+### 历史实施验收清单
+
+以下复选框保留原实施方案的验收范围，不表示当前代码尚未完成；当前结论应以专项测试和交付记录为准。
 
 - [ ] 使用 @nestjs/bullmq，不是 @nestjs/bull。
 - [ ] @nestjs/bullmq 和 bullmq 已加入 workspace catalog。
@@ -1833,7 +1840,7 @@ vp run ready
 
 ## 附录 A：未来上传清理如何接入
 
-详细方案已经拆分到独立文件：[上传清理.md](./上传清理.md)。该文件只说明未来如何复用公共队列，不属于当前实施内容。
+详细方案已经拆分到独立文件：[上传清理设计方案](../../02.上传与文件/上传清理/设计方案.md)。该文件说明如何复用公共队列，但相关清理业务尚未进入当前源码。
 
 以后可能增加：
 

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//344/270/207/347/211/251/346/242/246/345/271/273//345/267/245/345/205/267/fixtures.mjs

@@ -0,0 +1,132 @@
+/** 虚构数据，仅供视觉验证的独立浏览器上下文使用。 */
+export const user = { id: 'qa-user', name: '林间', account: 'qa.visual@example.invalid' }
+export const companyScope = { type: 'company', companyId: 'qa-company' }
+export const projectScope = { ...companyScope, type: 'project', projectId: 'qa-project' }
+export const workspaces = [
+  { scope: { type: 'platform' }, name: '平台管理', administrator: 'platform' },
+  { scope: companyScope, name: '星屿科技', administrator: 'company' },
+  { scope: projectScope, name: '月光计划', companyName: '星屿科技', administrator: 'project' },
+]
+
+const pageDefinitions = {
+  platform: [
+    ['home', '平台工作台', 'dashboard'],
+    ['companies', '企业管理', 'companies'],
+    ['accounts', '全局账号', 'accounts'],
+    ['roles', '平台角色', 'roles'],
+    ['menus', '菜单管理', 'menus'],
+    ['audit', '平台操作日志', 'audit-log'],
+  ],
+  company: [
+    ['home', '企业工作台', 'home'],
+    ['profile', '企业资料', 'profile'],
+    ['members', '企业成员', 'members'],
+    ['roles', '企业角色', 'roles'],
+    ['projects', '项目管理', 'projects'],
+    ['audit', '企业操作日志', 'audit-log'],
+  ],
+  project: [
+    ['home', '项目工作台', 'home'],
+    ['profile', '项目资料', 'profile'],
+    ['members', '项目成员', 'members'],
+    ['roles', '项目角色', 'roles'],
+    ['audit', '项目操作日志', 'audit-log'],
+  ],
+}
+
+function access(scope) {
+  const menus = pageDefinitions[scope.type].map(([page, name, icon], sort) => ({
+    id: `qa-${scope.type}-${page}`,
+    scopeType: scope.type,
+    parentId: null,
+    type: 'page',
+    name,
+    icon,
+    sort,
+    hidden: false,
+    status: 'active',
+    routeKey: `${scope.type}.${page}`,
+    permissionKey: `${scope.type}.${page}.read`,
+    protected: false,
+    children: [],
+  }))
+  return {
+    user,
+    scope,
+    administrator: scope.type,
+    permissionKeys: menus.flatMap(({ routeKey }) =>
+      ['read', 'create', 'update', 'status', 'administrator', 'add', 'roles'].map(
+        (operation) => `${routeKey}.${operation}`,
+      ),
+    ),
+    menus,
+    menuVersion: 1,
+    catalogVersion: '2026-09-19.1',
+  }
+}
+
+const date = '2026-09-10T02:20:00.000Z'
+const company = {
+  id: 'qa-company',
+  name: '星屿科技',
+  code: 'STARISLE',
+  description: '连接灵感，创造日常中的新可能。',
+  status: 'active',
+  version: 1,
+  createdAt: date,
+  updatedAt: date,
+}
+const project = {
+  ...company,
+  id: 'qa-project',
+  companyId: 'qa-company',
+  name: '月光计划',
+  code: 'MOONLIGHT',
+}
+const companies = [
+  company,
+  {
+    ...company,
+    id: 'qa-company-2',
+    name: '云间设计',
+    code: 'CLOUD',
+    description: '让想象拥有形状。',
+  },
+  { ...company, id: 'qa-company-3', name: '远山工作室', code: 'FARHILL', status: 'disabled' },
+]
+
+function page(items, url) {
+  const query = url.searchParams.get('query') ?? ''
+  const status = url.searchParams.get('status')
+  const filtered = items.filter(
+    (item) =>
+      (!query || `${item.name} ${item.code ?? ''}`.includes(query)) &&
+      (!status || item.status === status),
+  )
+  return { items: filtered, total: filtered.length, page: 1, pageSize: 20 }
+}
+
+export function fixtureResponse(url, scenario) {
+  const path = url.pathname.replace(/^\/api/, '')
+  if (path === '/workspaces') {
+    return { user, workspaces: scenario === 'empty-workspaces' ? [] : workspaces }
+  }
+  if (path === '/platform/access') return access({ type: 'platform' })
+  if (path === '/companies/qa-company/access') return access(companyScope)
+  if (path === '/companies/qa-company/projects/qa-project/access') return access(projectScope)
+  if (path === '/platform/companies') return page(scenario === 'empty' ? [] : companies, url)
+  if (path === '/companies/qa-company/projects') return page([project], url)
+  if (path === '/companies/qa-company') return { ...company, administrators: [] }
+  if (path === '/companies/qa-company/projects/qa-project')
+    return { ...project, administrators: [] }
+  if (path === '/platform/accounts') {
+    return page(
+      [{ ...user, status: 'active', createdAt: date, updatedAt: date, platformRoleIds: [] }],
+      url,
+    )
+  }
+  if (path.endsWith('/roles') || path.endsWith('/members') || path.endsWith('/audit-logs')) {
+    return page([], url)
+  }
+  return undefined
+}

package/template-vp-monorepo-react-nestjs/.spaces/04./347/225/214/351/235/242/344/270/216/344/270/273/351/242/230//344/270/207/347/211/251/346/242/246/345/271/273//345/267/245/345/205/267/visual-check.mjs

@@ -0,0 +1,274 @@
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { fixtureResponse } from './fixtures.mjs'
+
+// 运行：node .spaces/04.界面与主题/万物梦幻/工具/visual-check.mjs --base-url http://127.0.0.1:9999
+// 仅检查浏览器可启动：node .spaces/04.界面与主题/万物梦幻/工具/visual-check.mjs --check-launch
+const require = createRequire(import.meta.url)
+const bundled =
+  'C:/Users/Administrator/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/node_modules/playwright'
+const { chromium } = require(process.env.PLAYWRIGHT_MODULE || bundled)
+const args = process.argv.slice(2)
+const baseUrl = args.includes('--base-url')
+  ? args[args.indexOf('--base-url') + 1]
+  : 'http://127.0.0.1:9999'
+const only = args.includes('--only') ? args[args.indexOf('--only') + 1] : undefined
+const featureRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const uiOutput = resolve(featureRoot, 'ui')
+const reportOutput = resolve(featureRoot, '测试证据')
+const browserPaths = [
+  process.env.PLAYWRIGHT_EXECUTABLE_PATH,
+  chromium.executablePath(),
+  'C:/Users/Administrator/AppData/Local/ms-playwright/chromium-1208/chrome-win64/chrome.exe',
+  'C:/Users/Administrator/AppData/Local/ms-playwright/chromium-1187/chrome-win/chrome.exe',
+].filter(Boolean)
+const executablePath = browserPaths.find(existsSync)
+assert(executablePath, '未找到 Chromium，请通过 PLAYWRIGHT_EXECUTABLE_PATH 指定已安装浏览器。')
+const browser = await chromium.launch({ executablePath, headless: true })
+if (args.includes('--check-launch')) {
+  console.log(JSON.stringify({ executablePath, version: browser.version(), baseUrl }, null, 2))
+  await browser.close()
+  process.exit(0)
+}
+
+const report = { baseUrl, browser: browser.version(), mockData: true, checks: [], failures: [] }
+await mkdir(uiOutput, { recursive: true })
+await mkdir(reportOutput, { recursive: true })
+const selected = (name) => !only || name === only || name.startsWith(`${only}-`)
+if (only && existsSync(resolve(reportOutput, 'visual-report.json'))) {
+  const previous = JSON.parse(
+    await readFile(resolve(reportOutput, 'visual-report.json'), 'utf8'),
+  )
+  if (previous.baseUrl === baseUrl) {
+    report.checks = previous.checks.filter(({ name }) => !selected(name))
+    report.failures = previous.failures.filter(({ name }) => !selected(name))
+  }
+}
+
+async function scenario({ name, viewport, data = 'filled', check }) {
+  if (!selected(name)) return
+  const context = await browser.newContext({
+    viewport,
+    deviceScaleFactor: 1,
+    reducedMotion: 'reduce',
+  })
+  await context.addCookies([{ name: 'token', value: 'qa-only-noncredential', url: baseUrl }])
+  const unexpected = []
+  const pageErrors = []
+  await context.route('**/*', async (route) => {
+    const request = route.request()
+    const url = new URL(request.url())
+    if (!url.pathname.startsWith('/api/')) return route.continue()
+    if (request.method() !== 'GET') {
+      unexpected.push(`禁止真实写入：${request.method()} ${url.pathname}`)
+      return route.fulfill({ status: 405, json: { message: '视觉验证不提交写入请求。' } })
+    }
+    const body = fixtureResponse(url, data)
+    if (body === undefined) {
+      unexpected.push(`未配置 fixture：${url.pathname}`)
+      return route.fulfill({ status: 501, json: { message: '视觉验证 fixture 未配置。' } })
+    }
+    return route.fulfill({ status: 200, json: body })
+  })
+  const page = await context.newPage()
+  page.on('pageerror', (error) => pageErrors.push(error.message))
+  try {
+    await check(page)
+    assert.deepEqual(unexpected, [], '存在未 mock 的 API 请求')
+    assert.deepEqual(pageErrors, [], '存在未处理的页面错误')
+    report.checks.push({ name, viewport, passed: true })
+    console.log(`PASS ${name}`)
+  } catch (error) {
+    const failure = { name, viewport, error: error.message, unexpected, pageErrors }
+    report.failures.push(failure)
+    console.error(`FAIL ${name}: ${error.message}`)
+    await page.screenshot({ path: resolve(uiOutput, `${name}-failure.png`), fullPage: true })
+  } finally {
+    await context.close()
+  }
+}
+
+async function settle(page, path) {
+  await page.goto(`${baseUrl}${path}`, { waitUntil: 'networkidle' })
+  await page.locator('.workspace-brand:visible').first().waitFor({ state: 'visible' })
+  assert.match(await page.locator('.workspace-brand:visible').first().innerText(), /万物/)
+  assert.equal(await page.locator('.scope-strip').count(), 0, '原作用域横条应移除')
+  await page.evaluate(() => document.fonts.ready)
+}
+
+async function noPageOverflow(page) {
+  const dimensions = await page.evaluate(() => ({
+    viewport: innerWidth,
+    document: document.documentElement.scrollWidth,
+    body: document.body.scrollWidth,
+  }))
+  assert(
+    dimensions.document <= dimensions.viewport + 1,
+    `文档横向溢出：${JSON.stringify(dimensions)}`,
+  )
+  assert(dimensions.body <= dimensions.viewport + 1, `页面横向溢出：${JSON.stringify(dimensions)}`)
+}
+
+async function visibleWorkspace(page, text) {
+  const matches = page.locator('.workspace-context strong').filter({ hasText: text })
+  await matches.first().waitFor({ state: 'visible' })
+  const visible = await matches.evaluateAll((elements) =>
+    elements.some((element) => {
+      const rect = element.getBoundingClientRect()
+      const style = getComputedStyle(element)
+      return (
+        rect.width > 0 &&
+        rect.height > 0 &&
+        rect.right > 0 &&
+        rect.left < innerWidth &&
+        rect.bottom > 0 &&
+        rect.top < innerHeight &&
+        style.visibility !== 'hidden' &&
+        style.display !== 'none'
+      )
+    }),
+  )
+  assert(visible, `当前工作空间“${text}”应在视口内可见`)
+}
+
+async function capture(page, name) {
+  await noPageOverflow(page)
+  await page.screenshot({
+    path: resolve(uiOutput, `${name}.png`),
+    fullPage: true,
+    animations: 'disabled',
+  })
+}
+
+try {
+  await scenario({
+    name: 'companies-desktop-empty',
+    viewport: { width: 1440, height: 960 },
+    data: 'empty',
+    check: async (page) => {
+      await settle(page, '/platform/companies')
+      await page.locator('.workspace-table-empty').waitFor()
+      await visibleWorkspace(page, '平台管理')
+      await capture(page, 'companies-desktop-empty')
+    },
+  })
+  await scenario({
+    name: 'companies-desktop-data',
+    viewport: { width: 1440, height: 960 },
+    check: async (page) => {
+      await settle(page, '/platform/companies')
+      await page.getByText('星屿科技', { exact: true }).waitFor()
+      assert.equal(await page.locator('tr.ant-table-row').count(), 3)
+      await capture(page, 'companies-desktop-data')
+      await page.getByPlaceholder('搜索企业名称或编码').fill('云间')
+      await page.getByRole('button', { name: /查\s*询/ }).click()
+      await page.waitForFunction(() => document.querySelectorAll('tr.ant-table-row').length === 1)
+      await page.getByRole('button', { name: /重\s*置/ }).click()
+      await page.waitForFunction(() => document.querySelectorAll('tr.ant-table-row').length === 3)
+      await page.getByRole('button', { name: '开通企业' }).click()
+      await page.getByRole('dialog').waitFor()
+      await capture(page, 'company-create-dialog')
+      await page
+        .getByRole('dialog')
+        .getByRole('button', { name: /取\s*消/ })
+        .click()
+    },
+  })
+  for (const width of [390, 360, 320]) {
+    await scenario({
+      name: `companies-mobile-${width}`,
+      viewport: { width, height: 844 },
+      check: async (page) => {
+        await settle(page, '/platform/companies')
+        await page.getByText('星屿科技', { exact: true }).waitFor()
+        await visibleWorkspace(page, '平台管理')
+        await page.locator('.workspace-switch .anticon').waitFor({ state: 'visible' })
+        await page.locator('.workspace-logout .anticon').waitFor({ state: 'visible' })
+        await capture(page, `companies-mobile-${width}`)
+        const menu = page
+          .locator('.ant-pro-global-header-collapsed-button, .ant-pro-layout-collapsed-button')
+          .first()
+        await menu.click()
+        const accountLink = page.locator('a[href="/platform/accounts"]:visible')
+        await accountLink.click()
+        await page.waitForURL('**/platform/accounts')
+        await page.locator('td').filter({ hasText: 'qa.visual@example.invalid' }).waitFor()
+        await capture(page, `accounts-mobile-${width}`)
+      },
+    })
+  }
+  for (const width of [1440, 390]) {
+    await scenario({
+      name: `workspaces-${width}`,
+      viewport: { width, height: 960 },
+      check: async (page) => {
+        await settle(page, '/workspaces')
+        await page.locator('.workspace-card').first().waitFor()
+        assert.equal(await page.locator('.workspace-card').count(), 3)
+        await capture(page, `workspaces-${width}`)
+        await page.getByLabel('搜索工作空间').fill('月光')
+        assert.equal(await page.locator('.workspace-card').count(), 1)
+        await page.locator('.workspace-card').getByRole('link').click()
+        await page.waitForURL('**/companies/qa-company/projects/qa-project')
+        await page.getByRole('heading', { name: '项目工作台' }).waitFor({ state: 'visible' })
+        await visibleWorkspace(page, '月光计划')
+        await capture(page, `project-home-${width}`)
+        await settle(page, '/companies/qa-company/projects')
+        await visibleWorkspace(page, '星屿科技')
+        await page.getByText('月光计划', { exact: true }).waitFor()
+        await capture(page, `company-projects-${width}`)
+      },
+    })
+  }
+  await scenario({
+    name: 'workspaces-empty',
+    viewport: { width: 390, height: 844 },
+    data: 'empty-workspaces',
+    check: async (page) => {
+      await settle(page, '/workspaces')
+      await page.getByText('暂未加入企业，请联系管理员添加', { exact: true }).waitFor()
+      await capture(page, 'workspaces-empty')
+    },
+  })
+  for (const width of [1440, 390]) {
+    for (const authPage of ['login', 'register']) {
+      await scenario({
+        name: `${authPage}-${width}`,
+        viewport: { width, height: 960 },
+        check: async (page) => {
+          await page.goto(`${baseUrl}/${authPage}`, { waitUntil: 'networkidle' })
+          await page.locator('.login-brand').waitFor({ state: 'visible' })
+          assert.match(await page.locator('.login-brand').innerText(), /万物/)
+          const fields =
+            authPage === 'login' ? ['账号', '密码'] : ['姓名', '账号', '密码', '确认密码']
+          for (const label of fields) {
+            const field = page.getByLabel(label, { exact: true })
+            await field.waitFor({ state: 'visible' })
+            await field.scrollIntoViewIfNeeded()
+            const rect = await field.boundingBox()
+            assert(
+              rect && rect.width > 100 && rect.x >= 0 && rect.x + rect.width <= width + 1,
+              `字段“${label}”应完整显示`,
+            )
+          }
+          await page.evaluate(() => scrollTo(0, 0))
+          await capture(page, `${authPage}-${width}`)
+        },
+      })
+    }
+  }
+} finally {
+  await writeFile(
+    resolve(reportOutput, 'visual-report.json'),
+    `${JSON.stringify(report, null, 2)}\n`,
+  )
+  await browser.close()
+}
+console.log(
+  `完成：${report.checks.length} 通过，${report.failures.length} 失败；截图：${uiOutput}；报告：${reportOutput}`,
+)
+process.exitCode = report.failures.length ? 1 : 0