fix: 合并图库吸顶区域并关闭自动刷新

README.md

@@ -96,7 +96,7 @@ Oxfmt 不负责代码质量，Oxlint 不负责 Vue 的完整类型推导；Vue S
 
 - 外层应用固定为视口高度；侧栏、顶栏、项目标题和工作流导航不会随正文滚动。
 - 工作流只保留左侧导航，项目标题下不再重复展示相同标签。主体身份、分镜设计、镜头生产和图库采用内容优先布局：常用筛选／剧集选择／刷新在固定的紧凑工具栏，列表占据剩余高度。
-- 项目标题栏只显示返回入口和名称，不再放置状态标签与刷新按钮；项目仍每 6 秒自动刷新，读取失败时在错误提示内提供重试入口。
+- 项目标题栏只显示返回入口和名称，不再放置状态标签与刷新按钮；除形态图库使用手动刷新外，其他项目工作区每 6 秒自动刷新，读取失败时在错误提示内提供重试入口。
 - 只有当前项目正式状态为 `completed` 才解锁下游工作区；草稿、生成中、待审核、失败和读取期间默认禁用下游导航。直接访问下游链接只显示返回剧本创作的引导，不挂载操作组件；轮询确认完成后自动解锁，切换项目立即重新判定。页面内提交守卫同步检查完成状态；这是前端交互限制，不代替后端权限与业务校验。
 - 项目列表采用固定表头表格；剧本、分镜、身份与生产页的目录和详情独立滚动，其他工作区只滚动内容区。
 - “我的剧本”状态筛选采用中号控件，与搜索框等高并扩大点击区域；刷新、主题、折叠和关闭等单图标按钮统一使用直角正方形，加载时保持尺寸不变，保留可访问名称。
@@ -199,7 +199,7 @@ API 层也提供 `state` 与 `breakdown/latest` 方法。页面通过共享 chec
 
 1. `POST /projects` 返回顶层 `202 { projectId, status }`，其他接口通常返回 `{ data }`；HTTP 层分别兼容。
 2. Breakdown、Storyboard 和恢复接口目前是**长 HTTP 请求**。不设客户端短超时，不自动重试 POST。关闭页面只会丢失请求连接，**不会取消后端任务**。
-3. 项目列表每 12 秒、项目详情每 6 秒串行刷新。隐藏页面暂停自动查询。切换项目或离开布局时取消查询，旧响应不会覆盖新项目。
+3. 项目列表每 12 秒、项目详情每 6 秒串行刷新。形态图库暂停父布局和页面定时查询，返回其他工作区恢复轮询；图库直接链接被未完成状态拦截时可手动刷新项目状态。隐藏页面暂停自动查询。切换项目或离开布局时取消查询，旧响应不会覆盖新项目。
 4. 抽取任务进度不是全流程进度。抽取完成之后还需要主体合并、形态、节拍、镜头和持久化。
 5. 后端失败 checkpoint 可能只有错误。页面回看最近可用的完整快照以保留成果，同时使用最新记录的 execution 状态。显示的是**最近可用快照**，并不保证全部成果来自最后一次执行。
 6. 后端并不为每个阶段提供持久化的 running 状态。没有明确终态时，页面显示“阶段快照 · 执行状态待确认”，不会猜测成功或失败。
@@ -227,7 +227,7 @@ API 层也提供 `state` 与 `breakdown/latest` 方法。页面通过共享 chec
 4. 单图宽高同时留空使用后端默认 2K，自定义时必须同时提供正整数，具体尺寸限制仍由模型校验。当前 后端图片模型 Provider 没有使用 negativePrompt，所以页面不提供无效的负向提示词输入。
 5. 单图生成新增历史记录，不删除旧图。无主图时默认勾选“生成成功后设为主图”；已有主图时默认不替换。候选图可以在历史弹窗二次确认后通过 PUT 设为主图，只允许已完成图片。
 6. 批量默认跳过已有主图的形态；勾选“已有主图也新增候选图”发送 `force: true`。后端批量 force 只生成新图，**不会替换已有主图**。批量作用于整个项目，不受类型／文字／缺图筛选影响，也不接收单图的尺寸与自定义 Prompt。
-7. 图库每 6 秒读取一次真实记录，弹窗只在打开时查询该形态图片。数据库存在 pending / generating 时暂停再次生图；网络错误不自动重试有费用的请求。HTTP 200 中的批量部分失败单独展示。
+7. 图库、镜头影响检查、关联素材和图片历史均不定时刷新；首次进入、切换查询目标、手动刷新及本次写操作完成后按需读取。“刷新图库”同时更新项目状态。数据库存在 pending / generating 时暂停再次生图；网络错误不自动重试有费用的请求。HTTP 200 中的批量部分失败单独展示。当前形态列表接口返回完整数组，无分页参数或游标，因此不显示分页或触底加载入口。筛选栏与有值的关联素材行共用一个不透明背景的吸顶容器，内部无 margin 断层；关联素材保持单行横向滚动、上下居中，图片区域沿正文向下滚动。
 8. 图片使用持久化后的 `/storage/...` 地址，开发代理已配置。生产环境也必须代理 `/storage/`，不能让 SPA 回退返回 index.html。无效 URL、加载失败、无图和后端生成失败有各自提示；不会自动使用可能过期的 Provider 临时地址。
 9. 设为主图后，回到分镜点击“刷新参考图”读取最新绑定。已有视频提示词不会自动重生成，需要按需覆盖。本页面不会调用 `/production/start` 或实际视频生成。
 10. 人物、场景、道具均仅继承已锁定身份的当前母版；无母版或未锁定不继承。刷新过期形态只生成候选，验图后手动切换主图。批量图片可限制本次数量，回执独立展示因上限未执行数，不把它算作已有结果的跳过数。

src/App.vue

@@ -170,7 +170,7 @@ const menuOptions = computed<MenuOption[]>(() => [
                 <dt>生产环境</dt>
                 <dd>为 /api、/storage 配置反向代理，并为长工作流设置足够的超时。</dd>
                 <dt>状态更新</dt>
-                <dd>项目详情每 6 秒刷新；关闭页面不会取消后端任务。</dd>
+                <dd>形态图库使用手动刷新，其他项目工作区每 6 秒更新；关闭页面不会取消后端任务。</dd>
             </dl>
         </AppDialog>
     </NConfigProvider>

src/admin.css

@@ -458,13 +458,16 @@ body {
 .gallery-workspace-page .workspace-scroll-content {
     padding-top: 8px;
 }
-/* 图库只使用正文纵向滚动；筛选栏在同一滚动上下文吸顶，不再被头部高度限制。 */
-.gallery-workspace-page .form-image-filter-region {
+/* 筛选与关联素材整体吸顶；间距由内部 padding 承担，避免出现透明断层。 */
+.gallery-workspace-page .gallery-sticky-controls {
     position: sticky;
     top: 0;
     z-index: 10;
     background: var(--app-subtle);
-    margin-block: 10px 12px;
+    margin-block: 10px 0;
+}
+.gallery-sticky-controls > .form-image-filter-region {
+    margin-block: 0;
 }
 .gallery-workspace-page .workspace-scroll > .n-scrollbar-container {
     overflow-anchor: none;
@@ -1511,7 +1514,7 @@ body {
     gap: 10px;
     padding: 14px 16px;
     background: var(--app-subtle);
-    margin-bottom: 12px;
+    margin: 0;
     min-width: 0;
 }
 /* 关联素材始终单行横向浏览，数量和长名称不会撑高定位区或压缩图片区域。 */
@@ -1526,7 +1529,8 @@ body {
     gap: 12px;
     width: max-content;
     white-space: nowrap;
-    padding-bottom: 8px;
+    min-height: 32px;
+    padding-block: 6px;
 }
 .asset-impact-links > * {
     flex-shrink: 0;

src/components/ui/flatTheme.test.ts

@@ -145,12 +145,16 @@ describe('全站平面主题', () => {
         // 静态保护吸顶和横向尺寸规则；真实视口滚动与位置仍需浏览器验收。
         const css = readFileSync('src/admin.css', 'utf8')
         expect(css).toMatch(
-            /\.gallery-workspace-page \.form-image-filter-region\s*\{[^}]*position:\s*sticky;[^}]*top:\s*0;[^}]*z-index:\s*10;[^}]*background:\s*var\(--app-subtle\);/
+            /\.gallery-workspace-page \.gallery-sticky-controls\s*\{[^}]*position:\s*sticky;[^}]*top:\s*0;[^}]*z-index:\s*10;[^}]*background:\s*var\(--app-subtle\);/
         )
         expect(css).toMatch(
             /\.gallery-workspace-page \.workspace-scroll > \.n-scrollbar-container\s*\{[^}]*overflow-anchor:\s*none;/
         )
         expect(css).toMatch(/\.asset-impact-links\s*\{[^}]*width:\s*max-content;[^}]*white-space:\s*nowrap;/)
+        expect(css).toMatch(/\.gallery-sticky-controls > \.form-image-filter-region\s*\{[^}]*margin-block:\s*0;/)
+        expect(css).toMatch(
+            /\.asset-impact-links\s*\{[^}]*align-items:\s*center;[^}]*min-height:\s*32px;[^}]*padding-block:\s*6px;/
+        )
         expect(css).toMatch(/\.asset-impact-links-scroll\.n-scrollbar\s*\{[^}]*height:\s*auto;[^}]*max-width:\s*100%;/)
         expect(readFileSync('src/features/subject-images/SubjectImagesPage.vue', 'utf8')).toMatch(
             /<WorkspacePage\b[^>]*>\s*<template #default>/
@@ -171,7 +175,7 @@ describe('全站平面主题', () => {
             /@container \(max-width: 1200px\)\s*\{\s*\.form-image-toolbar\.has-impact-picker,\s*\.form-image-toolbar\.has-impact-picker\.has-impact-actions\s*\{[^}]*grid-template-columns:\s*minmax\(0, 1fr\);/
         )
         expect(css).toMatch(/\.asset-impact-picker\s*\{[^}]*align-items:\s*center;[^}]*gap:\s*8px;/)
-        expect(css).toMatch(/\.asset-impact-context\s*\{[^}]*gap:\s*10px;[^}]*margin-bottom:\s*12px;/)
+        expect(css).toMatch(/\.asset-impact-context\s*\{[^}]*gap:\s*10px;[^}]*margin:\s*0;/)
     })
 
     it('单图标按钮以当前控件高度为边长，尺寸与内容按钮互不影响', () => {

src/composables/usePolling.test.ts

@@ -5,6 +5,47 @@ import { usePolling } from './usePolling'
 afterEach(() => vi.useRealTimers())
 
 describe('异步轮询生命周期', () => {
+    it('关闭定时刷新后仍支持首次读取、手动刷新及查询目标切换', async () => {
+        vi.useFakeTimers()
+        const key = ref('first')
+        const loader = vi.fn<(id: string) => Promise<string>>(async id => id)
+        const scope = effectScope()
+        const query = scope.run(() => usePolling(key, loader, false))!
+        await Promise.resolve()
+        expect(query.data.value).toBe('first')
+        await vi.advanceTimersByTimeAsync(30_000)
+        expect(loader).toHaveBeenCalledTimes(1)
+        await query.refresh()
+        expect(loader).toHaveBeenCalledTimes(2)
+        key.value = 'second'
+        await nextTick()
+        await Promise.resolve()
+        expect(query.data.value).toBe('second')
+        await vi.advanceTimersByTimeAsync(30_000)
+        expect(loader).toHaveBeenCalledTimes(3)
+        scope.stop()
+    })
+
+    it('响应式暂停清除旧定时器，恢复只创建一个轮询链', async () => {
+        vi.useFakeTimers()
+        const interval = ref<number | false>(1000)
+        const loader = vi.fn<() => Promise<string>>(async () => '数据')
+        const scope = effectScope()
+        scope.run(() => usePolling(ref('p'), loader, interval))
+        await Promise.resolve()
+        interval.value = false
+        await nextTick()
+        await vi.advanceTimersByTimeAsync(5000)
+        expect(loader).toHaveBeenCalledTimes(1)
+        interval.value = 1000
+        await nextTick()
+        await vi.advanceTimersByTimeAsync(2000)
+        expect(loader).toHaveBeenCalledTimes(3)
+        scope.stop()
+        await vi.advanceTimersByTimeAsync(5000)
+        expect(loader).toHaveBeenCalledTimes(3)
+    })
+
     it('切换项目忽略旧响应，卸载时不再排队请求', async () => {
         vi.useFakeTimers()
         const key = ref('first')

src/composables/usePolling.ts

@@ -1,11 +1,11 @@
-import { onScopeDispose, ref, watch, type Ref } from 'vue'
+import { onScopeDispose, ref, toValue, watch, type MaybeRefOrGetter, type Ref } from 'vue'
 import { errorMessage } from '../lib/http'
 
 /** 串行轮询：请求完成后才计时；切换项目立即取消，过期响应不会覆盖新项目。 */
 export function usePolling<T>(
     key: Ref<string>,
     loader: (key: string, signal: AbortSignal) => Promise<T>,
-    interval = 6000
+    interval: MaybeRefOrGetter<number | false> = 6000
 ) {
     const data = ref<T | null>(null) as Ref<T | null>
     const loading = ref(false)
@@ -18,10 +18,13 @@ export function usePolling<T>(
 
     /** 隐藏页面只安排下一次检查，不继续拉取完整 checkpoint。 */
     function schedule() {
+        const delay = toValue(interval)
+        if (disposed || delay === false) return
         timer = setTimeout(() => {
+            if (toValue(interval) === false) return
             if (document.visibilityState === 'hidden') schedule()
             else void refresh()
-        }, interval)
+        }, delay)
     }
 
     /** 手动刷新也取消上一次查询，避免同时存在多个轮询链。 */
@@ -49,6 +52,14 @@ export function usePolling<T>(
         }
     }
 
+    // 页面可关闭定时刷新；首次读取、切换查询目标和手动刷新仍然有效。
+    watch(
+        () => toValue(interval),
+        () => {
+            clearTimeout(timer)
+            if (!loading.value) schedule()
+        }
+    )
     watch(
         key,
         () => {

src/features/production/useShotReferences.ts

@@ -1,16 +1,29 @@
-import { computed, type Ref } from 'vue'
+import { computed, type MaybeRefOrGetter, type Ref } from 'vue'
 import { usePolling } from '../../composables/usePolling'
 import { storyboardApi } from '../storyboard/api'
 
 /** 仅查询已由当前项目列表确认的镜头，切换目标自动取消旧响应。 */
-export function useShotReferences(projectId: Ref<string>, shotId: Ref<string>) {
+export function useShotReferences(
+    projectId: Ref<string>,
+    shotId: Ref<string>,
+    interval: MaybeRefOrGetter<number | false> = 6000
+) {
     const key = computed(() => JSON.stringify([projectId.value, shotId.value]))
-    return usePolling(key, async (value, signal) => {
+    return usePolling(
+        key,
+        async (value, signal) => {
             const [project, shot] = JSON.parse(value) as [string, string]
             if (!project || !shot) return null
             const result = await storyboardApi.references(shot, signal)
-        if (!result || result.shotId !== shot || !Array.isArray(result.references) || !Array.isArray(result.missing))
+            if (
+                !result ||
+                result.shotId !== shot ||
+                !Array.isArray(result.references) ||
+                !Array.isArray(result.missing)
+            )
                 throw new Error('镜头参考素材返回不匹配，请刷新后重试。')
             return result
-    })
+        },
+        interval
+    )
 }

src/features/projects/ProjectLayout.vue

@@ -11,7 +11,12 @@ import { isProjectComplete, projectAccessKey, type ProjectAccess } from './acces
 const route = useRoute()
 const router = useRouter()
 const id = computed(() => String(route.params.projectId))
-const context = useProjectData(id)
+// 图库使用手动刷新，父布局也停止轮询，避免浏览素材时被周期性更新打断。
+const isGallery = computed(() => route.path.replace(/\/+$/, '').endsWith('/subject-images'))
+const context = useProjectData(
+    id,
+    computed(() => (isGallery.value ? false : 6000))
+)
 provide(projectContextKey, context)
 const operation = computed(() => getOperation(id.value))
 const complete = computed(() => isProjectComplete(context.project.value, id.value))
@@ -60,9 +65,12 @@ onScopeDispose(() => {
                 v-else-if="context.project.value?.id === id"
                 class="project-access-gate"
                 title="请先完成剧本创作"
-                description="剧本完成后，才能使用拆解、视觉风格、主体身份、形态图片、分镜设计与镜头生产。状态会自动更新。"
+                :description="`剧本完成后，才能使用拆解、视觉风格、主体身份、形态图片、分镜设计与镜头生产。${isGallery ? '请手动刷新项目状态。' : '状态会自动更新。'}`"
             >
                 <NButton type="primary" @click="router.push(`/projects/${id}/create-drama`)">返回剧本创作</NButton>
+                <NButton v-if="isGallery" class="ml-3" :loading="context.loading.value" @click="context.refresh"
+                    >刷新项目状态</NButton
+                >
             </EmptyState>
             <NSpin
                 v-else-if="context.loading.value"

src/features/projects/access.test.ts

@@ -67,6 +67,40 @@ async function openProject(initialPath: string) {
 }
 
 describe('剧本完成前的下游访问限制', () => {
+    it('进入图库暂停父级轮询，返回其他工作区恢复定时更新', async () => {
+        vi.useFakeTimers()
+        const detail = vi.spyOn(projectsApi, 'detail').mockResolvedValue(project('manual-gallery', 'completed'))
+        const checkpoints = vi.spyOn(projectsApi, 'checkpoints').mockResolvedValue([])
+        const { router } = await openProject('/projects/manual-gallery/production')
+        await router.push('/projects/manual-gallery/subject-images')
+        await flushPromises()
+        await vi.advanceTimersByTimeAsync(30_000)
+        expect(detail).toHaveBeenCalledTimes(1)
+        expect(checkpoints).toHaveBeenCalledTimes(1)
+        await router.push('/projects/manual-gallery/production')
+        await flushPromises()
+        await vi.advanceTimersByTimeAsync(6000)
+        expect(detail).toHaveBeenCalledTimes(2)
+        expect(checkpoints).toHaveBeenCalledTimes(2)
+    })
+
+    it('图库直接链接只读取一次项目，未完成时可手动刷新解锁', async () => {
+        vi.useFakeTimers()
+        let status: ProjectStatus = 'generating'
+        const detail = vi.spyOn(projectsApi, 'detail').mockImplementation(async id => project(id, status))
+        vi.spyOn(projectsApi, 'checkpoints').mockResolvedValue([])
+        await openProject('/projects/manual-gate/subject-images')
+        await vi.advanceTimersByTimeAsync(30_000)
+        expect(detail).toHaveBeenCalledTimes(1)
+        expect(wrapper!.get('.project-access-gate').text()).not.toContain('状态会自动更新')
+        status = 'completed'
+        const refresh = wrapper!.findAll('button').find(button => button.text() === '刷新项目状态')!
+        await refresh.trigger('click')
+        await flushPromises()
+        expect(detail).toHaveBeenCalledTimes(2)
+        expect(wrapper!.get('.workspace-probe').text()).toBe('subject-images')
+    })
+
     it.each(['draft', 'generating', 'need_review', 'failed'] as const)(
         '%s 不解锁导航，也不挂载直接链接对应的工作区',
         async status => {

src/features/projects/context.ts

@@ -1,4 +1,4 @@
-import { computed, inject, type InjectionKey } from 'vue'
+import { computed, inject, type InjectionKey, type MaybeRefOrGetter } from 'vue'
 import { usePolling } from '../../composables/usePolling'
 import { projectsApi } from './api'
 import type { ProjectDetail } from './types'
@@ -6,14 +6,18 @@ import type { Checkpoint } from '../workflows/types'
 import type { Ref } from 'vue'
 
 /** 同一项目的各个 graph 共用一份查询，避免每个面板重复请求。 */
-export function useProjectData(id: Ref<string>) {
-    const query = usePolling(id, async (projectId, signal) => {
+export function useProjectData(id: Ref<string>, interval: MaybeRefOrGetter<number | false> = 6000) {
+    const query = usePolling(
+        id,
+        async (projectId, signal) => {
             const [project, checkpoints] = await Promise.all([
                 projectsApi.detail(projectId, signal),
                 projectsApi.checkpoints(projectId, signal)
             ])
             return { project, checkpoints }
-    })
+        },
+        interval
+    )
     const project = computed<ProjectDetail | null>(() => query.data.value?.project ?? null)
     const checkpoints = computed<Checkpoint[]>(() => query.data.value?.checkpoints ?? [])
     return { ...query, project, checkpoints }

src/features/subject-images/SubjectImagesPage.vue

@@ -31,7 +31,7 @@ import FormPromptBatch from './components/FormPromptBatch.vue'
 import { useKeyframeImpact } from './useKeyframeImpact'
 import { queryText, referenceLocation, referenceTargets } from '../production/asset-links'
 
-/** 形态图库以正式数据库为准，自动显示已在后端生成的图片。 */
+/** 形态图库以正式数据库为准；首次读取、手动刷新和自身操作完成后更新，不定时刷新。 */
 const route = useRoute()
 const router = useRouter()
 const {
@@ -39,6 +39,7 @@ const {
     forms,
     staleForms,
     query,
+    refreshProject,
     operation,
     session,
     concurrency,
@@ -205,7 +206,7 @@ function selectImpactShot(shotId: string | null) {
 
 /** 同时刷新素材和镜头影响状态，查询仍不启动生成。 */
 async function refreshAssets() {
-    await Promise.all([query.refresh(), impact.query.refresh(), impact.references.refresh()])
+    await Promise.all([refreshProject(), query.refresh(), impact.query.refresh(), impact.references.refresh()])
 }
 
 /** 全局过期筛选不沿用深链接的单个素材限制。 */
@@ -279,8 +280,7 @@ async function showStaleForms() {
                                 </p>
                             </div>
                             <p class="mt-2 text-[11px] leading-6 text-muted">
-                                每 6
-                                秒更新图片记录；主图供分镜引用，候选图和历史失败记录均保留。过期主图不会自动删除，也不会被批量任务静默替换。
+                                图库不自动刷新，可点击“刷新图库”读取最新记录。主图供分镜引用，候选图和历史失败记录均保留；过期主图不会自动删除或替换。
                             </p>
                             <NAlert v-if="staleForms.length" type="error" :show-icon="false" class="mt-4"
                                 ><div class="flex flex-wrap items-center justify-between gap-3">
@@ -420,6 +420,7 @@ async function showStaleForms() {
                 >镜头影响检查失败，暂时无法确认有无过期首帧：{{ impact.query.error.value }}
                 <NButton text size="small" @click="impact.query.refresh">重试检查</NButton></NAlert
             >
+            <div class="gallery-sticky-controls">
                 <div class="form-image-filter-region">
                     <div
                         class="form-image-toolbar"
@@ -494,7 +495,7 @@ async function showStaleForms() {
                         </div>
                     </div>
                 </div>
-            <div v-if="showImpactDetails" class="asset-impact-context mt-3" aria-label="镜头与素材定位">
+                <div v-if="showImpactDetails" class="asset-impact-context" aria-label="镜头与素材定位">
                     <p v-if="sourceMissing" class="text-danger">来源镜头不存在或不属于当前项目，未读取其素材。</p>
                     <p v-if="sourceCurrent" class="text-xs">
                         当前检查：{{
@@ -532,6 +533,7 @@ async function showStaleForms() {
                         <NButton text size="small" @click="impact.references.refresh">重试读取素材</NButton>
                     </p>
                 </div>
+            </div>
             <NAlert
                 v-if="targetFormId"
                 :type="targetForm ? 'info' : 'warning'"

src/features/subject-images/asset-impact.test.ts

@@ -18,6 +18,7 @@ afterEach(() => {
     wrapper?.unmount()
     wrapper = undefined
     document.body.innerHTML = ''
+    vi.useRealTimers()
     vi.unstubAllGlobals()
 })
 
@@ -132,14 +133,34 @@ async function gallery(query = '') {
 }
 
 describe('过期首帧到具体素材定位', () => {
+    it('图库与关联检查不定时刷新，手动刷新仍能更新数据', async () => {
+        vi.useFakeTimers()
+        const { fetcher } = await gallery('?sourceShotId=shot-target')
+        const count = fetcher.mock.calls.length
+        const grid = wrapper!.get('.form-image-grid').element
+        await vi.advanceTimersByTimeAsync(30_000)
+        await flushPromises()
+        expect(fetcher).toHaveBeenCalledTimes(count)
+        expect(wrapper!.get('.form-image-grid').element).toBe(grid)
+        const refresh = wrapper!.findAll('button').find(button => button.text().includes('刷新图库'))!
+        await refresh.trigger('click')
+        await flushPromises()
+        expect(fetcher.mock.calls.length).toBeGreaterThan(count)
+        const refreshed = fetcher.mock.calls.length
+        await vi.advanceTimersByTimeAsync(30_000)
+        expect(fetcher).toHaveBeenCalledTimes(refreshed)
+    })
+
     it('切换镜头时筛选、关联说明和图片共用稳定纵向容器，长关联列表单独横向滚动', async () => {
         const { keyframes, videos, references, fetcher } = await gallery('?sourceShotId=shot-target')
         expect(wrapper!.find('.workspace-heading-scroll').exists()).toBe(false)
         const scroll = wrapper!.get<HTMLElement>('.workspace-scroll > .n-scrollbar-container').element
         const content = wrapper!.get('.workspace-scroll-content').element
+        const sticky = wrapper!.get('.gallery-sticky-controls').element
         const toolbar = wrapper!.get('.form-image-filter-region').element
-        expect(toolbar.parentElement).toBe(content)
-        expect(wrapper!.get('.asset-impact-context').element.parentElement).toBe(content)
+        expect(sticky.parentElement).toBe(content)
+        expect(toolbar.parentElement).toBe(sticky)
+        expect(wrapper!.get('.asset-impact-context').element.parentElement).toBe(sticky)
         expect(wrapper!.get('.form-image-grid').element.parentElement).toBe(content)
         scroll.scrollTop = 480
         keyframes.items.push({ ...keyframes.items[0]!, shotId: 'shot-next', shotNo: 2 })
@@ -184,7 +205,8 @@ describe('过期首帧到具体素材定位', () => {
         expect(wrapper!.get('.workspace-scroll > .n-scrollbar-container').element).toBe(scroll)
         expect(wrapper!.get('.form-image-filter-region').element).toBe(toolbar)
         expect(scroll.scrollTop).toBe(480)
-        expect(wrapper!.get('.asset-impact-context').element.parentElement).toBe(content)
+        expect(wrapper!.get('.gallery-sticky-controls').element).toBe(sticky)
+        expect(wrapper!.get('.asset-impact-context').element.parentElement).toBe(sticky)
         expect(wrapper!.get('.form-image-grid').element.parentElement).toBe(content)
         const links = wrapper!.get('.asset-impact-links-scroll')
         expect(links.findAll('a')).toHaveLength(24)

src/features/subject-images/components/ImageGalleryDialog.vue

@@ -19,12 +19,16 @@ const emit = defineEmits<{ changed: [] }>()
 const selectedId = ref('')
 const confirming = ref(false)
 const key = computed(() => (open.value ? (props.form?.id ?? '') : ''))
-const query = usePolling(key, async (id, signal) => {
+const query = usePolling(
+    key,
+    async (id, signal) => {
         if (!id) return null
         const rows = await subjectImagesApi.listImages(id, signal)
         if (rows.some(image => image.subjectFormId !== id)) throw new Error('图片记录与当前形态不匹配，请刷新后重试。')
         return rows
-})
+    },
+    false
+)
 const images = computed(() => query.data.value ?? [])
 const selected = computed(
     () => images.value.find(image => image.id === selectedId.value) ?? primaryImage(images.value) ?? images.value[0]

src/features/subject-images/images.test.ts

@@ -19,6 +19,7 @@ afterEach(() => {
     wrapper?.unmount()
     wrapper = undefined
     document.body.innerHTML = ''
+    vi.useRealTimers()
     vi.unstubAllGlobals()
     Object.assign(getOperation('gallery-test'), { pending: false, label: '', error: '', notice: '' })
 })
@@ -134,6 +135,7 @@ describe('形态图片选择与操作', () => {
     })
 
     it('图库不自动生图，主图切换经确认后 PUT，失败图片不能设主图', async () => {
+        vi.useFakeTimers()
         let primary = false
         const fetcher = vi.fn<typeof fetch>().mockImplementation(async (_url, init) => {
             if (init?.method === 'PUT') {
@@ -162,6 +164,8 @@ describe('形态图片选择与操作', () => {
         })
         await flushPromises()
         expect(fetcher.mock.calls).toHaveLength(1)
+        await vi.advanceTimersByTimeAsync(30_000)
+        expect(fetcher.mock.calls).toHaveLength(1)
         await expandSections()
         expect(document.body.textContent).toContain('<script>模型提示词</script>')
         expect(document.querySelector('[role="dialog"] script')).toBeNull()

src/features/subject-images/useKeyframeImpact.ts

@@ -5,7 +5,9 @@ import { useShotReferences } from '../production/useShotReferences'
 
 /** 镜头影响检查与素材查询独立；检查失败不把素材误判为正常或阻断独立的素材操作。 */
 export function useKeyframeImpact(projectId: Ref<string>, sourceShotId: Ref<string>) {
-    const query = usePolling(projectId, async (id, signal) => {
+    const query = usePolling(
+        projectId,
+        async (id, signal) => {
             if (!id) return null
             const [keyframes, videos] = await Promise.all([
                 productionApi.keyframeReadiness(id, false, signal),
@@ -19,7 +21,8 @@ export function useKeyframeImpact(projectId: Ref<string>, sourceShotId: Ref<stri
             return {
                 ...keyframes,
                 items: keyframes.items.map(item => {
-                const issues = byShot.get(item.shotId)?.issues.filter(issue => issue.code === 'stale_keyframe') ?? []
+                    const issues =
+                        byShot.get(item.shotId)?.issues.filter(issue => issue.code === 'stale_keyframe') ?? []
                     return {
                         ...item,
                         primaryKeyframeStale: !!item.primaryKeyframeStale || issues.length > 0,
@@ -27,13 +30,16 @@ export function useKeyframeImpact(projectId: Ref<string>, sourceShotId: Ref<stri
                     }
                 })
             }
-    })
+        },
+        false
+    )
     const stale = computed(() => query.data.value?.items.filter(item => item.primaryKeyframeStale) ?? [])
     // 不根据 URL 中的任意镜头 ID 发请求，必须属于当前项目的就绪列表。
     const source = computed(() => query.data.value?.items.find(item => item.shotId === sourceShotId.value))
     const references = useShotReferences(
         projectId,
-        computed(() => source.value?.shotId ?? '')
+        computed(() => source.value?.shotId ?? ''),
+        false
     )
     const relatedForms = computed(
         () => new Set(references.data.value?.references.map(item => item.subjectFormId) ?? [])

src/features/subject-images/useSubjectImages.ts

@@ -17,7 +17,9 @@ export function useSubjectImages() {
     const limit = ref<number | ''>('')
     const promptConcurrency = ref(3)
     const promptForce = ref(false)
-    const query = usePolling(id, async (projectId, signal) => {
+    const query = usePolling(
+        id,
+        async (projectId, signal) => {
             if (!projectId) return []
             try {
                 const forms = await subjectImagesApi.listForms(projectId, signal)
@@ -38,7 +40,9 @@ export function useSubjectImages() {
                     )
                 throw error
             }
-    })
+        },
+        false
+    )
     const forms = computed(() => query.data.value ?? [])
     const staleForms = computed(() => forms.value.filter(form => isPrimaryIdentityStale(form)))
     const operation = computed(() => getOperation(id.value))
@@ -188,6 +192,7 @@ export function useSubjectImages() {
         forms,
         staleForms,
         query,
+        refreshProject: context.refresh,
         operation,
         session,
         concurrency,