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

490 行
38 KiB
Markdown

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# 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 | 25 个 |
| 定时器 | `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 明令禁止的"在计算属性/渲染中做副作用"。
- **代码**:
```ts
// 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` 但从不检查它)。
- **代码**:
```ts
// 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` 是后端全量计数,只要库里有被过滤掉的占位图,循环就必然多翻一整轮直到返回空页。
- **修复建议**:
```ts
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)`——这是"取最后一条",而不是"取全部"。作者显然想表达"整段都是新事件"。
- **代码**:
```ts
// 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`)在已连接状态下只补刷当前轮次,补不了这些。
- **修复建议**:
```ts
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`)。前端把这两张表都重抄了一遍,并且**措辞已经不一致**。
- **代码**:
```ts
// 前端 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",
}
```
```python
# 后端 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",
}
```
```ts
// 前端 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"` 做补偿。工作流状态推进是后端职责,前端只是一个可以随时被关闭标签页打断的客户端。
- **代码**:
```ts
// 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)
```
```ts
// 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 被用作通用状态行,成功、失败、锁定提示混在一起,且状态永不按语义复位。
- **代码**:
```ts
// 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)}`
```
```html
<!-- 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>'
```
即模板实际内容为:
```html
<button type="button" title="关闭" @click="closeOverlay('personaQuestionnaire')">×</button>\n </header>
```
- **影响**:HTML 中反斜杠和 `n` 是普通文本,会原样显示在弹窗右上角关闭按钮旁边,用户可见的 UI 脏字符。这是"创建角色档案问卷"这个主入口弹窗的标题栏。
- **修复建议**:把 `\n` 替换成真正的换行:
```html
<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` 的早退分支绕过了这个守卫。
- **代码**:
```ts
// 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)`:
```ts
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` 结构完全相同):
```ts
// 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`:
```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)` 同名。
- **代码**:
```ts
// 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 个缓存,但漏掉衣橱/档案卡/请求代次这几组。
- **代码**:
```ts
// 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 的识别结果。建议统一走后端。