astrbot_plugin_imagestudio/审计/findings/A8-前端App主体.md

38 KiB

A8 — 前端主体 frontend/standalone-web/src/App.vue(22563 行)

审计范围(实际逐块读过的文件):

  • frontend/standalone-web/src/App.vue(全文分块通读:1-120、640-960、940-1050、1560-1780、2327-2410、2782-2900、3284-3600、3960-4300、4297-4720、4716-5120、5776-6090、6086-6160、6287-6460、6455-6750、6744-6930、6919-7200、7265-7400、7515-7560、8058-8360、8407-8740、9637-9950、9993-10260、10312-10510、11132-11300、模板 11359-14143、样式 14145-22540)
  • frontend/standalone-web/src/features/(组件/composable 现状清单,含 workflow/、profiles/、materials/、gallery/、settings/、quick-profile/profile-import.ts)
  • frontend/tsconfig.json、frontend/package.json(strict 已开启;npm run typecheck 实跑通过)
  • 后端对照:backend/services/character_workflow_service.py、backend/services/quick_character_consistency.py、backend/services/generation_service.py、backend/services/node_injection_template_service.py

量化数据

指标 数值
总行数 22563(script 1–11357 / template 11359–14143 / style 14145–22540)
<script setup> 行数 11356
<template> 行数 2784
<style>(非 scoped)行数 8395,约 1100 条选择器
ref() 声明 206(reactive() 0 个)
computed() 声明 203
顶层 function 声明 365
watch() 20(其中 15 个带 immediate: true)
模板 v-if / v-else(-if) / v-for 78 / 61 / 55(55 个 v-for 全部带 :key,无 index-key 问题)
API 调用点 getJson 59 + postJson 58 + putJson 9 + deleteJson 3 = 129
endpoints.* 引用 183 处 / 85 个不同端点;0 处硬编码 /api/... 字符串
try/catch 块 84 / 82
backendWriteBlockMessage(...) 前置校验样板 27 处
loading/busy 类 ref 37 个;error 类 ref
定时器 setInterval 2 / setTimeout 4;addEventListener 9 / removeEventListener 9(一一对应)
AbortController 0 个(所有请求不可取消)

摘要

App.vue 是全仓唯一的"上帝组件":22.5k 行里塞进了 9 个导航页、3 个生成子工作台、12 个受控浮层、206 个 ref、203 个 computed 和 129 个 API 调用点。值得肯定的是——v-for 的 key 全部齐备、事件监听在 onBeforeUnmount 中全部成对摘除、定时器全部清理、profile 详情/衣橱两条链路有正经的 request-generation 竞态防护、且没有任何硬编码 URL(全部走 shared/api/endpoints)。

真正的致命问题集中在三处:(1) displayMediaUrl() 是一个被 4 个 computed 和整个模板 render 直接调用的"伪纯函数",它内部会发起网络请求并写回 resolvedMediaUrls ref,把整个图库列表拖进 O(N²) 重算 + Blob 无界累积;(2) 5 秒事件轮询 startEventStreamPolling() 既无重入保护,又会在图库页触发全量分页重扫,并且 slice(-1) 的写法会在事件积压时静默丢弃最多 19 条事件导致刷新失效;(3) 前端在 quickCharacterPrompt() 里重写了后端 character_workflow_service._step_instruction() 已有的提示词模板,两边措辞已经漂移。

结构上,workflowNodeActionError 这一个 ref 被 67 处复用来同时承载成功与失败文案,workflowActionCards 是一个 441 行的巨型 computed,8395 行未 scoped 的全局 CSS 与所有子组件的 <style scoped> 形成两套并行体系。仓库里已有 44 个抽好的组件/composable(14295 行),说明拆分模式是现成的,App.vue 只是没有跟进。


发现

[P0-致命] displayMediaUrl() 在 computed 与模板 render 中产生副作用:触发网络请求 + 写回响应式 ref,导致图库 O(N²) 重算与 Blob 无界泄漏

  • 位置:frontend/standalone-web/src/App.vue:11146(定义)、:997-1011(galleryImages computed 调用)、:2341-2362(两个候选图 computed 调用)、:11668/11693/12826/12865/13961(模板 render 中经 imageUrl() 调用)
  • 问题:displayMediaUrl 看起来是格式化函数,实际做三件带副作用的事:① 读 resolvedMediaUrls.value(建立响应式依赖);② 在未命中时发起 HTTP 请求(resolveStorageMediaUrl / resolveSignedMediaUrl);③ 请求返回后 resolvedMediaUrls.value = { ...resolvedMediaUrls.value, ... } 整体替换该 ref。它同时被 computed 和 template render 调用——这是 Vue 明令禁止的"在计算属性/渲染中做副作用"。
  • 代码:
    // App.vue:11146
    function displayMediaUrl(rawUrl?: string | null): string {
      const value = String(rawUrl || "").trim()
      if (!value) return ""
      if (/^storage:\/\//i.test(value)) {
        const resolved = resolvedMediaUrls.value[value]      // ← 建立响应式依赖
        if (resolved) return resolved
        if (!resolvingMediaUrls.has(value)) {
          const resolution = resolveStorageMediaUrl(value)    // ← computed 里发请求
            .finally(() => { resolvingMediaUrls.delete(value) })
          resolvingMediaUrls.set(value, resolution)
        }
        return ""
      }
      ...
    }
    
    // App.vue:11215 —— 每张图 resolve 完成后整体替换 ref
    const objectUrl = URL.createObjectURL(new Blob([bytes], { ... }))
    ownedMediaObjectUrls.add(objectUrl)
    resolvedMediaUrls.value = { ...resolvedMediaUrls.value, [rawUrl]: objectUrl, [sourceKey]: objectUrl }
    
    // App.vue:997 —— 图库 computed 对全部图片逐张调用
    const galleryImages = computed<GalleryImage[]>(() => {
      const backendImages = uniqueImages([...]).filter(isAuthenticGenerationImage)
      return [...backendImages].sort(...).map((image) => ({
        ...image,
        image_url: displayMediaUrl(image.image_url),
        thumbnail_url: displayMediaUrl(image.thumbnail_url),
      }))
    })
    
  • 影响:
    1. O(N²) 重算:galleryImages 依赖 resolvedMediaUrls,而它自己会让 N 张图各触发一次 resolvedMediaUrls 整体替换 → 每张图解析完成都让整个 galleryImages(含排序 + N 次 displayMediaUrl)重跑一遍。loadGalleryImages()(:4511)会把整库所有页都拉下来(do...while (loaded.length < total),page_size: 100),1000 张图就是 1000 次全量重算 ≈ 100 万次 displayMediaUrl 调用,外加 watch(galleryImages, ...)(:4184)跟着抖 1000 次。
    2. Blob 内存无界增长:ownedMediaObjectUrls 只在 onBeforeUnmount(:4041)统一 revokeObjectURL。SPA 单页会话中它永不卸载,用户浏览过的每张图的完整二进制都常驻内存直到关闭标签页。
    3. 不可预期的请求风暴:render 期间发请求意味着任何一次无关的响应式变更(切主题、点通知)重渲染时都可能补发媒体请求。
  • 修复建议:把媒体解析从"渲染时惰性触发"改成"数据加载时显式预取"。
    • 新建 composables/useMediaUrls.ts,导出纯读取的 mediaUrl(raw): string(只查表,不发请求)和显式的 prefetchMediaUrls(rawUrls: string[]): Promise<void>。
    • 在 loadGalleryImages / loadWorkflowRoundDetail / hydrateGenerationImages 拿到数据后,批量调用 prefetchMediaUrls(...),一次 resolvedMediaUrls.value = {...} 写入所有结果(把 N 次 ref 替换压成 1 次)。
    • 给 resolvedMediaUrls 加 LRU 上限(如 300 条),淘汰时 URL.revokeObjectURL 并从 ownedMediaObjectUrls 移除。
    • galleryImages 改用 mediaUrl()(纯查表)。

[P1-严重] 事件流轮询无重入保护,且在图库页每 5 秒触发整库分页重扫

  • 位置:frontend/standalone-web/src/App.vue:4561-4609(startEventStreamPolling)、:4511-4542(loadGalleryImages)
  • 问题:window.setInterval(poll, 5000) 中的 poll 是 async 且内部 await Promise.allSettled(refreshes),其中 loadGalleryImages() 会把整个图库逐页拉完。没有任何 in-flight 标志,上一轮没跑完下一轮就会启动。loadGalleryImages 自身也没有并发去重(只置 loadingGalleryImages 但从不检查它)。
  • 代码:
    // App.vue:4561
    function startEventStreamPolling() {
      if (eventStreamTimer !== undefined) window.clearInterval(eventStreamTimer)
      const poll = async () => {
        if (backendConnection.value.state !== "connected" || document.hidden) return
        ...
        if (activeNav.value === "gallery" && generationChanged) refreshes.push(loadGalleryImages())
        ...
        await Promise.allSettled(refreshes)     // ← 可能远超 5s
      }
      void poll()
      eventStreamTimer = window.setInterval(poll, 5000)   // ← 无 in-flight 守卫
    }
    
    // App.vue:4519 —— 每次调用把整库翻完
    do {
      const result = await getJson<ImageListResult>(endpoints.images, { include_archived: true, page, page_size: pageSize })
      loaded.push(...result.items.filter(isAuthenticGenerationImage))
      total = result.total
      if (!result.items.length) break
      page += 1
    } while (loaded.length < total)
    
  • 影响:用户停留在图库页且后台在批量生图时,每 5 秒发起 ceil(total/100) 个 GET /images 请求;1000 张图 = 每 5 秒 10 个请求,且上一批未完成时新一批叠加,请求数指数堆积。叠加上一条 P0 的媒体 Blob 解析,页面会在几十秒内卡死。另外 loaded.length 只统计通过 isAuthenticGenerationImage 过滤后的图,而 total 是后端全量计数,只要库里有被过滤掉的占位图,循环就必然多翻一整轮直到返回空页。
  • 修复建议:
    let eventPollInFlight = false
    const poll = async () => {
      if (eventPollInFlight) return
      if (backendConnection.value.state !== "connected" || document.hidden) return
      eventPollInFlight = true
      try { /* ... */ } finally { eventPollInFlight = false }
    }
    
    同时给 loadGalleryImages 加 if (loadingGalleryImages.value) return,并把轮询触发的图库刷新改成增量(只拉第 1 页 page_size: 100 并 merge),全量扫描只保留给用户显式点"刷新"。循环条件改为按页数 page <= Math.ceil(total / pageSize) 而非按 loaded.length。

[P1-严重] 事件流 slice(-1) 在事件积压时静默丢弃最多 19 条事件,导致队列/图库/日志停止刷新

  • 位置:frontend/standalone-web/src/App.vue:4572-4582
  • 问题:lastEventStreamId 若不在本次返回的 20 条事件窗口内(findIndex 返回 -1),代码写成 slice(-1)——这是"取最后一条",而不是"取全部"。作者显然想表达"整段都是新事件"。
  • 代码:
    // App.vue:4572
    const previousIndex = hadPrevious
      ? stream.events.findIndex((event) => event.event_id === lastEventStreamId)
      : -1
    const freshEvents = hadPrevious
      ? stream.events.slice(previousIndex >= 0 ? previousIndex + 1 : -1)   // ← previousIndex === -1 时只取最后 1 条
      : []
    lastEventStreamId = newest
    if (!hadPrevious) return
    const eventTypes = freshEvents.map((event) => String(event.event_type || ""))
    const generationChanged = eventTypes.some((eventType) => eventType.startsWith("generation."))
    const workflowChanged = eventTypes.some((eventType) => eventType.startsWith("workflow."))
    
  • 影响:两个常见场景会命中:① 标签页被切走(poll 在 document.hidden 时直接 return,lastEventStreamId 停止推进),回来时游标早已滑出 20 条窗口;② 批量生图 5 秒内产生 >20 条事件。此时只有最后一条事件参与判定——如果它恰好是 workflow.*,generationChanged 就是 false,队列、图库、日志全部不会刷新,UI 显示的仍是几分钟前的旧数据,且不会有任何报错提示。reconnectBackendWhenVisible()(:4471)在已连接状态下只补刷当前轮次,补不了这些。
  • 修复建议:
    const freshEvents = hadPrevious
      ? stream.events.slice(previousIndex >= 0 ? previousIndex + 1 : 0)
      : []
    
    游标丢失时应视全窗口为新事件(宁可多刷一次也不能漏)。同时建议把 limit: 20 提高,或在 visibilitychange 恢复时主动做一次全量 loadAll() 级别的对齐。

[P1-严重] 前端重写了后端已有的快速角色提示词模板,两边文案已经漂移

  • 位置:frontend/standalone-web/src/App.vue:6120-6154(quickCharacterPrompt)、:6100-6118(quickCharacterIdentityFields) 对照后端:backend/services/character_workflow_service.py:280-285、backend/services/quick_character_consistency.py:13-28
  • 问题:后端 _step_instruction() 已经为 character_fast 的四个 node_key 定义了权威指令表,quick_character_consistency.py 也已经定义了服务端拥有的 identity 字段别名表(_FIELD_ALIASES)与身份锁(build_identity_lock)。前端把这两张表都重抄了一遍,并且措辞已经不一致。
  • 代码:
    // 前端 App.vue:6126
    const instructions: Record<string, string> = {
      quick_avatar: "square avatar, close-up portrait, clear face, stable hair and eye details",
      quick_bust: "half-body character reference, upper-body clothing, natural posture",
      quick_stand: "full-body standing character illustration, complete outfit, accurate body proportions",
      quick_sheet: "character design sheet, multiple views, outfit details, material callouts",
    }
    
    # 后端 backend/services/character_workflow_service.py:280
    fast = {
        "quick_avatar": "square avatar, face, hair, eyes, expression, keep identity consistent",
        "quick_bust": "half-body character reference, clothing, posture, keep identity consistent",
        "quick_stand": "full-body standing character illustration, complete outfit and proportions",
        "quick_sheet": "character design sheet, multiple views, outfit details and material callouts",
    }
    
    // 前端 App.vue:6138 —— 连身份一致性约束都在前端拼
    return [
      "same single character in every image",
      "preserve exact gender presentation, age, species, face identity, body type, hair, eyes and distinctive features",
      identityPrefix, persistedProfile?.base_prompt, persistedProfile?.appearance_prompt,
      profile.name, profile.identity, profile.personality, quickProfileLibraryAppearance(profile),
      profile.style, instructions[nodeKey], ...materialPrompts,
    ].filter(Boolean).join(", ")
    
  • 影响:注意前端 quick_avatar 丢掉了后端明确写的 keep identity consistent。同一个 quick_avatar 节点,走 Web 前端触发和走后端自身触发会产生不同的提示词,四联图身份一致性表现不可复现。后端改提示词策略时前端不会跟着改,这条链路上的任何 prompt 治理(prompt_expansion_service.py)都会被前端拼串绕过。
  • 修复建议:删除 quickCharacterPrompt 里的 instructions 表和身份约束前缀,只把结构化字段(identityFields、materialPrompts、用户自定义 patch)作为 payload 传给 endpoints.nodeGenerate,由后端 _step_instruction() + build_identity_lock() 负责组装最终 prompt。若前端确实需要预览,应新增一个只读的 POST /prompt/preview 端点返回后端组装结果,而不是各拼各的。

[P1-严重] generateQuickCharacterImages() 在前端编排后端工作流状态机(290 行),前端自行判定并 PUT completed/running/failed

  • 位置:frontend/standalone-web/src/App.vue:5786-6076
  • 问题:这个函数在浏览器里完成了:创建工作流 → 启动 → 提交锚点任务 → 并行提交 3 个从属任务 → 重新拉节点 → 自行推断工作流终态 → PUT 状态与 metadata → 失败时再 PUT status: "failed" 做补偿。工作流状态推进是后端职责,前端只是一个可以随时被关闭标签页打断的客户端。
  • 代码:
    // App.vue:5945-5979
    const completedTargetKeys = QUICK_CHARACTER_TARGET_SPECS.filter((spec) => { ... }).map((spec) => spec.nodeKey)
    const pendingTargetKeys = QUICK_CHARACTER_TARGET_SPECS.filter((spec) => {
      const node = nodes.find((item) => item.node_key === spec.nodeKey)
      return Boolean(node && ["created","pending","queued","running","retrying"].includes(normalizeStatus(node.status)))
    }).map((spec) => spec.nodeKey)
    const generationCompleted = completedTargetKeys.length === QUICK_CHARACTER_TARGET_SPECS.length
    const nextWorkflowStatus = generationCompleted ? "completed" : pendingTargetKeys.length ? "running" : "failed"
    ...
    if (normalizeStatus(workflow.status) !== nextWorkflowStatus) workflowUpdate.status = nextWorkflowStatus
    workflow = await putJson<ProfileWorkflow>(endpoints.workflow(workflow.workflow_id), workflowUpdate)
    
    // App.vue:6048-6061 —— 失败补偿也在前端
    if (activeWorkflowId) {
      try {
        const latestFailedWorkflow = await getJson<WorkflowDetail>(endpoints.workflow(activeWorkflowId))
        const failedWorkflow = await putJson<ProfileWorkflow>(endpoints.workflow(activeWorkflowId), {
          status: "failed", metadata: { ...(latestFailedWorkflow.workflow.metadata ?? {}), quick_character_failure: message },
        })
    
  • 影响:用户在生成过程中刷新页面/关标签页,工作流就永久停留在 draft 或 running,没有任何服务端兜底把它推到终态——数据库里会累积僵尸工作流。同时 metadata 里 quick_character_batch_id、quick_character_pending_target_keys、anchor_image_id 等 10+ 个字段的写入契约完全由前端定义,后端只是被动接收,任何字段改名都是隐式破坏。
  • 修复建议:把整段编排下沉为一个后端端点(例如 POST /workflows/{id}/quick-character/run),后端负责锚点优先 + 并行提交 + 状态推进 + 失败补偿;前端只提交一次请求并轮询 workflowRoundIsActive 式的状态。已有的 backend/services/quick_character_consistency.py 说明后端本来就有这一层,前端这段是重复实现。

[P2-中等] workflowNodeActionError 一个 ref 同时承载成功与失败文案(67 处赋值),模板按错误样式渲染

  • 位置:frontend/standalone-web/src/App.vue:786(声明)、:8292、:8452、:8536、:8732、:8776、:6666 等(成功文案写入 error ref)、:12952(模板)
  • 问题:命名为 ...Error 的 ref 被用作通用状态行,成功、失败、锁定提示混在一起,且状态永不按语义复位。
  • 代码:
    // App.vue:8292 —— 成功路径写进 Error ref
    workflowNodeActionError.value = `档案卡已原子封存:${shortId(card.card_id)} / ${card.branch_name},4 类必填资产均已入库。`
    // App.vue:8536
    workflowNodeActionError.value = `轮次 ${detail.round.display_code} 已加入生成队列。`
    // App.vue:8732
    workflowNodeActionError.value = successMessage
    // App.vue:8631 —— 同一个 ref 又装失败
    workflowNodeActionError.value = `${options.retry ? "节点重试" : "节点生成"}失败:${errorMessage(err)}`
    
    <!-- App.vue:12952 -->
    <em v-else-if="workflowNodeActionError || workflowBranchError">{{ workflowNodeActionError || workflowBranchError }}</em>
    
  • 影响:成功提示会被渲染成错误样式的 <em>;selectWorkflowNode()(:6472)切换节点时不清空它,用户在 A 节点操作失败后切到 B 节点,B 节点会继续挂着 A 的错误文案;archiveSelectedWorkflowFinal 的成功文案会一直留在界面上直到下一次操作。
  • 修复建议:拆成 workflowNodeActionError 与 workflowNodeActionNotice 两个 ref(或一个 { kind: "ok" | "error"; text: string } | null),模板按 kind 分别渲染;在 selectWorkflowNode() 里统一复位。

[P2-中等] 模板中残留字面量 \n 字符串,会在"创建角色档案问卷"弹窗标题栏渲染出可见的 \n

  • 位置:frontend/standalone-web/src/App.vue:13091
  • 问题:疑似脚本化编辑时把转义序列直接写进了 SFC 模板。\n(反斜杠 + n 两个字符)落在 <header> 元素的文本内容位置。
  • 代码(repr 结果,注意 </button> 后的两个字符):
    '                      <button type="button" title="关闭" @click="closeOverlay(\'personaQuestionnaire\')">×</button>\\n                    </header>'
    
    即模板实际内容为:
    <button type="button" title="关闭" @click="closeOverlay('personaQuestionnaire')">×</button>\n                    </header>
    
  • 影响:HTML 中反斜杠和 n 是普通文本,会原样显示在弹窗右上角关闭按钮旁边,用户可见的 UI 脏字符。这是"创建角色档案问卷"这个主入口弹窗的标题栏。
  • 修复建议:把 \n 替换成真正的换行:
    <button type="button" title="关闭" @click="closeOverlay('personaQuestionnaire')">×</button>
    </header>
    
    并在 CI 里加一条 lint:模板段内出现 \\n / \\t 字面量即失败。

[P2-中等] loadCharacterWorkflowForProfile 的缓存命中分支无条件重拉分支列表,与 watch 里的缓存守卫矛盾

  • 位置:frontend/standalone-web/src/App.vue:7271-7275(无守卫)、:4111-4122(有守卫)、:7515-7531(触发源)
  • 问题:watch([backendConnection.state, selectedCharacterWorkflow.workflow_id]) 明确用 workflowBranchesByWorkflowId.value[workflowId] 做了缓存去重,但 loadCharacterWorkflowForProfile 的早退分支绕过了这个守卫。
  • 代码:
    // App.vue:4114 —— watch 有缓存守卫
    if (connectionState !== "connected" || !workflowId || workflowBranchesByWorkflowId.value[workflowId]) return
    void loadWorkflowBranches(workflowId)
    
    // App.vue:7271 —— 这里没有
    const missingWorkflowIds = workflowIds.filter((workflowId) => !workflowNodesByWorkflowId.value[workflowId]?.length)
    if (!missingWorkflowIds.length) {
      if (profile.workflowId) await loadWorkflowBranches(profile.workflowId)   // ← 每次都发
      return
    }
    
    触发链:updateQuickProfileWorkflowLink(:7529-7530)用 .map() 重建 backendQuickProfileLibraryItems → quickProfileLibraryItems computed → selectedQuickProfileLibraryItem 得到新对象引用 → watch(selectedQuickProfileLibraryItem)(:4279)再次触发 loadCharacterWorkflowForProfile → 走进上面这个分支再发一次 GET /workflows/{id}/branches。
  • 影响:每次角色卡对象被重建(保存工作流链接、快速生成状态更新、profile 详情加载完成)都会多打一次分支列表请求,并把 workflowBranchError/workflowBranchesLoadingId 抖动一次。虽然不会死循环(第二轮不再改动角色卡数组),但属于确定性的冗余请求。
  • 修复建议:早退分支同样加缓存判断,或抽出 ensureWorkflowBranches(workflowId):
    async function ensureWorkflowBranches(workflowId: string) {
      if (!workflowId || workflowBranchesByWorkflowId.value[workflowId]) return workflowBranchesByWorkflowId.value[workflowId] ?? []
      return loadWorkflowBranches(workflowId)
    }
    
    watch 与 loadCharacterWorkflowForProfile 都调用它。

[P2-中等] 27 处写操作前置校验 + 40+ 处 busy/error/try/catch/finally 请求样板完全复制粘贴

  • 位置:典型样本 frontend/standalone-web/src/App.vue:10025-10103、:10105-10134、:10157-10177、:10179-10208、:10210-10241、:8222-8298、:8407-8460、:8462-8552、:8554-8636、:8692-8739、:8741-8782、:8784-8825
  • 问题:同一段五步骨架在文件里重复了 40 多次,只有 endpoint、busy ref、error ref 和文案不同。
  • 代码(registerMaterialUri 与 executeMaterialAssetPack 结构完全相同):
    // App.vue:10105
    async function registerMaterialUri(payload: MaterialRegistrationRequest) {
      if (materialOperationExecuting.value) return
      const blocked = backendWriteBlockMessage("登记素材 URI")
      if (blocked) { materialOperationError.value = blocked; return }
      materialOperationExecuting.value = true
      materialOperationError.value = ""
      let completed = false
      try {
        const created = await postJson<Material>(endpoints.materialUpload, { ...payload, metadata: {...} })
        await loadMaterials()
        selectedMaterialCategoryId.value = payload.category_id
        selectedMaterialId.value = created.material_id
        materialActionMessage.value = `...`
        completed = true
      } catch (err) {
        materialOperationError.value = `登记素材 URI 失败:${errorMessage(err)}`
      } finally {
        materialOperationExecuting.value = false
        if (completed) closeOverlay("materialOperation")
      }
    }
    
  • 影响:37 个 loading ref + 25 个 error ref 的生命周期各自手写,任何一处漏写 finally 就是永久卡死的按钮;新增写操作时必须记住 5 个步骤,遗漏 backendWriteBlockMessage 就绕过了权限/连接检查。
  • 修复建议:抽 composables/useWriteAction.ts:
    export function useWriteAction() {
      const busy = ref(false)
      const error = ref("")
      const notice = ref("")
      async function run<T>(label: string, fn: () => Promise<T>, opts?: { onDone?: () => void }): Promise<T | null> {
        if (busy.value) return null
        const blocked = backendWriteBlockMessage(label)
        if (blocked) { error.value = blocked; return null }
        busy.value = true; error.value = ""
        try { const r = await fn(); opts?.onDone?.(); return r }
        catch (err) { error.value = `${label}失败:${errorMessage(err)}`; return null }
        finally { busy.value = false }
      }
      return { busy, error, notice, run }
    }
    
    40 处调用点各自收缩到 5-10 行。

[P2-中等] 8395 行未 scoped 的全局样式,与全部 44 个子组件的 <style scoped> 形成两套并行体系

  • 位置:frontend/standalone-web/src/App.vue:14145(<style> 无 scoped),到 :22540
  • 问题:App.vue 的样式块占全文件 37%,约 1100 条选择器全部注入全局作用域;而 components/ConfirmDialog.vue:137、components/EmptyState.vue:20、components/ImagePreviewDialog.vue:209、features/** 等所有子组件都用 <style scoped>。
  • 代码:
    App.vue:14145  <style>            ← 无 scoped,1100 条选择器全局生效
    App.vue:14212  body { ... }       ← 直接改 body
    
  • 影响:① 类名污染——App.vue 定义的 .workflow-action-card、.quick-profile-material-slot 等泛用名一旦被子组件(或未来新组件)意外命中就会串样式,而 scoped 的子组件反过来无法覆写 App.vue 的规则(特异性相同、无 :deep() 通道);② 拆分阻力——任何把模板块搬进新组件的动作都必须同步搬走对应的几百行 CSS,否则样式立刻丢失,这也是这个文件迟迟拆不动的直接原因;③ 单文件 8395 行 CSS 无法定位归属。
  • 修复建议:按下面的拆分清单,把 CSS 同步切成 styles/generate.css、styles/materials.css、styles/queue.css、styles/overview.css、styles/dialogs.css 并在对应新组件里 <style scoped> 引入;App.vue 只保留真正全局的 shell/token 部分(已有 styles/tokens.css、styles/workbench.css 可以承接)。

[P3-轻微] queueBatchActionMessage 内部局部变量 errorMessage 遮蔽同名全局工具函数

  • 位置:frontend/standalone-web/src/App.vue:10504(局部变量)、:11354(被遮蔽的函数)
  • 问题:函数内声明 const errorMessage = ... 字符串,与文件级 function errorMessage(err: unknown) 同名。
  • 代码:
    // App.vue:10493
    function queueBatchActionMessage(result: Record<string, unknown>, fallback: string) {
      ...
      const errorMessage = errors ? `,${errors} 条处理失败` : ""   // ← 遮蔽 App.vue:11354 的 errorMessage()
      const remainingMessage = remaining > 0 ? `;仍有 ${remaining} 条,可继续清理` : ""
      return `${fallback} ${count} 条${errorMessage}${remainingMessage}。`
    }
    
  • 影响:当前逻辑正确,但这个函数体内再也无法调用错误格式化工具;后续维护者在此处加 catch 分支时会拿到一个字符串而不是函数,触发 errorMessage is not a function。
  • 修复建议:改名为 failureSuffix。

[P3-轻微] deleteSelectedProfile 遗漏清理 6 个 per-profile 缓存 Map

  • 位置:frontend/standalone-web/src/App.vue:6287-6339
  • 问题:归档角色后清理了 8 个缓存,但漏掉衣橱/档案卡/请求代次这几组。
  • 代码:
    // App.vue:6316-6319 —— 清理了这些
    profileWorkflowsByProfileId.value = omitRecordKey(profileWorkflowsByProfileId.value, profile.profile_id)
    profileAvatarUrls.value = omitRecordKey(profileAvatarUrls.value, profile.profile_id)
    profileGenerationBusyByProfileId.value = omitRecordKey(profileGenerationBusyByProfileId.value, profile.profile_id)
    profileGenerationErrorsByProfileId.value = omitRecordKey(profileGenerationErrorsByProfileId.value, profile.profile_id)
    // 未清理:profileWardrobeItemsByProfileId(:665)、profileWardrobeErrorsByProfileId(:666)、
    //          profileWardrobeLoadingByProfileId(:667)、profileCardsByProfileId(:819)、
    //          profileDetailsRequestGenerationByProfileId、profileWardrobeRequestGenerationByProfileId
    
  • 影响:长会话中反复删除角色会让这几个 Map 单调增长;若 profileWardrobeLoadingByProfileId 恰好停留在 true,同 id 记录再次出现时会显示假的加载态。
  • 修复建议:把 6 个 Map 的清理并进同一个 purgeProfileCaches(profileId) 辅助函数,deleteSelectedProfile 与 invalidateProfile*Requests 共用。

结构:这个文件里有多少个逻辑上独立的"页面/面板/对话框"?

统计:9 个导航级页面 + 3 个生成子工作台 + 12 个受控浮层(controlledOverlays,App.vue:904-917)+ 6 个已组件化但由 App 传 20-40 个 prop 驱动的面板 = 至少 30 个独立单元。

模板拆分清单(行号区间 → 目标组件)

行号区间 行数 职责 目标组件
11360-11385 26 app shell + 导航轨 + 标题栏 保留在 App.vue
11386-11424 39 全局搜索框 / 结果面板 components/GlobalSearchBox.vue + useGlobalSearch()
11425-11549 125 顶栏动作区(通知/日志/调色板/主题按钮) components/TopBarActions.vue
11551-11570 20 主题调色板浮层 components/ThemePalettePanel.vue
11571-11623 53 通知中心浮层 features/notifications/NotificationPanel.vue
11624-13334 1711 生成页(最大块) 见下方细分
├ 11626-11646 21 生成页 hero + 三模式切换 features/generate/GenerateHeader.vue
├ 11648-11806 159 单图生成工作台(提示词 / 模型选择 / 结果预览) features/generate/ImageComposerPanel.vue
├ 11807-12269 463 快速角色工作台(角色卡列表 / 图像轮播 / 素材槽位 / 动作卡) features/quick-profile/QuickProfileWorkspace.vue
├ 12270-12987 718 详细工作流工作台(节点分组 / 人设拆解 / 提示词规划 / 素材绑定 / 候选池 / 生命周期条) features/workflow/WorkflowWorkspace.vue,再内切 5 个子面板
├ 12988-13075 88 外部角色卡导入对话框 features/quick-profile/ExternalProfileImportDialog.vue
└ 13077-13329 253 角色档案问卷对话框(简单/复杂两套字段) features/quick-profile/PersonaQuestionnaireDialog.vue
13335-13376 42 ProfilesPage 挂载(已组件化,41 个 prop) 保留,但 prop 收敛为 2-3 个对象
13377-13630 254 素材库页(分类栏 / 筛选 / 卡片网格 / 动作卡 / 两个内嵌对话框) features/materials/MaterialsPage.vue
13631-13760 130 队列页(过滤 tab / 任务列表 / 详情 / 动作卡) features/queue/QueuePage.vue
13761-13810 50 GalleryPage / SettingsPage / LogsPage 挂载(已组件化) 保留
13811-13975 165 总览仪表盘(指标卡 / 队列摘要 / 建议 / 最近图片) features/overview/OverviewPage.vue
13976-14040 65 性能详情页 features/overview/PerformancePage.vue
14041-14142 102 全局对话框挂载区(图片查看器 / 对比 / 交叉审查 / 素材抽屉 / 素材操作 / 确认框) components/AppDialogHost.vue

脚本拆分清单(行号区间 → 目标 composable)

行号区间 行数 职责 目标 composable
4302-4487 186 后端连接状态机 / bootstrap / 指数退避重连 composables/useBackendConnection.ts
4561-4609 49 事件流轮询 composables/useEventStream.ts(先修 P1 两条)
4488-4547 + 4611-4698 148 dashboard / 成本 / 任务 / 日志 / 模型选项加载 composables/useDashboardData.ts
4511-4547 + 997-1011 51 图库加载与媒体 URL 映射 composables/useGalleryData.ts
4700-4786 87 设置页读写与校验 composables/useSettingsPage.ts
4787-4862 + 5316-5620 + 9993-10310 663 素材库(加载 / 分类 / 识别 / 资产包 / 衣橱导入 / 动作分发) composables/useMaterialLibrary.ts
4864-5100 + 5644-5775 + 6287-6339 340 角色档案页 + 衣橱 + 删除 composables/useProfilePage.ts
5776-6154 379 快速角色四联图生成编排 优先下沉到后端,残留部分 → composables/useQuickCharacterGeneration.ts
6460-6681 + 6919-7100 + 8462-8552 476 轮次 / 候选 / 反馈 / 确认 / 轮询 composables/useWorkflowRounds.ts
7101-7264 164 节点素材绑定抽屉 composables/useWorkflowNodeMaterials.ts
7265-7580 316 角色工作流创建/恢复/节点补齐 composables/useCharacterWorkflow.ts
7752-8056 305 图片查看器缩放拖拽 + 交叉审查对话框 composables/useImageViewer.ts + useWorkflowGenerationReview.ts
8058-9250 1193 工作流节点动作(分支 / 生成 / 完成 / 审查 / 采用 / 封存 / 快照) composables/useWorkflowNodeActions.ts
9251-9763 513 问卷 → 档案 payload 构建 + 外部角色卡导入 composables/useQuickProfileArchive.ts
9765-9940 176 12 个受控浮层的开关/外部点击/Esc 管理 composables/useOverlayManager.ts(现在是 if (key === ...) 长链,应改成注册表 Record<ControlledOverlay, { isOpen, setOpen }>)
10312-10510 199 队列动作 + 二次确认 composables/useQueueActions.ts
11024-11226 203 图片 URL / 占位图 / 媒体签名解析 composables/useMediaUrls.ts(先修 P0)
11243-11313 71 主题偏好持久化 + 颜色工具 composables/useThemePreferences.ts
1346-1458 / 1931-2018 / 2782-3222 / 3370-3511 113 / 88 / 441 / 142 四组"动作卡"配置巨型 computed 各自搬进对应 feature 目录的 *-action-cards.ts,改为接收显式参数的纯函数

按上表拆完,App.vue 应收缩到 300-500 行(shell + 路由分发 + 全局对话框挂载)。


精简机会汇总

  1. 请求样板(见 P2):40+ 处 busy/error/try/catch/finally → useWriteAction(),可删约 400 行。
  2. "选中项跟随列表"watch:App.vue:4055/4069/4083/4097/4184/4212/4226/4240 共 8 个 watch 结构完全相同(列表空 → 清空选中;选中项不在列表 → 取第一项)。抽 useSelectionSync(list, selectedId, keyOf),可删约 90 行。
  3. 分页拉全量:loadAllJobs(:4686)、loadRemainingMaterialPages(:4840)、loadRemainingProfilePages(:4884)、loadGalleryImages(:4511) 四份几乎相同的分页合并逻辑 → fetchAllPages(endpoint, params, keyOf),可删约 70 行。
  4. 四组动作卡 computed:materialActionCards/quickProfileActionCards/workflowActionCards/queueActionCards 共 784 行,卡片结构完全一致(id/title/detail/badge/state/tone/action/enabled/actionKey),可统一为一份 ActionCard 类型 + 一个 <ActionCardGrid> 组件 + 四份纯配置函数。
  5. materialColorTuple/quickProfileGeneratedColors/alphaColor/mixColor/hexToRgb/toHexByte(:11285-11313、:5392、:9627):纯色彩工具,直接移到 utils/color.ts。
  6. 两处 4 层 displayMediaUrl(...) || displayMediaUrl(...) || ... 链(:2345-2348 与 :2356-2359)逐字重复,抽 candidateImageUrl(candidate)。

与后端耦合汇总

  • ✅ 无硬编码 URL:183 处 API 调用全部经 endpoints.*(85 个端点),grep "'/api/" 零命中。这一点做得干净。
  • ❌ 提示词模板重复实现(P1,:6126 vs character_workflow_service.py:280)。
  • ❌ 工作流状态机在前端推进(P1,:5955、:5979、:6051)。
  • ⚠️ 对后端 metadata 的深层字段假设 34 处:recordString(node.metadata, "active_round_id")(:2337)、metadata.prompt_plan(:2802)、metadata.material_bindings(:2803)、metadata.final_archive_history_id(:2792)、metadata.character_execution.import_confirmed(:7539)、metadata.system_key(:4870/:6738)、metadata.source === "sample"(:4910)、recordString(image.metadata, "candidate_id")(:6461) 等。这些都是无 schema 约束的自由字典字段,后端改名前端静默降级。建议在 shared/types/workflow.ts 里为这些 metadata 键定义显式 interface,并让后端在 WorkflowNode/GenerationImage 响应里提升为一等字段。
  • ⚠️ 前端直接读原始配置树:quickGenerationModelRoute()(:6086) 从 currentSettings.config.model_assignments.quick_generation 和 config.generation.default_model 里挖路由,而后端 generation_service.py:2033-2036 已经有 node_key → quick_generation 的映射。同理 configuredImageModelOptions(:1047) 也在解析 config.generation。应改为消费后端提供的解析结果端点,而非解析原始 YAML 配置结构。
  • ⚠️ 外部角色卡双路径解析:importExternalProfileDocumentFile(:9637) 走后端 endpoints.quickProfileDocumentImport 做 LLM 识别,但 applyExternalProfileImport(:9710) 走前端本地正则 parseExternalProfileImport(features/quick-profile/profile-import.ts:90)。文件导入成功后会把原文写回 externalProfileImportText(:9698),此时用户若再点"识别并填入问卷",本地正则结果会覆盖后端 LLM 的识别结果。建议统一走后端。