astrbot_plugin_imagestudio/审计/findings/A9-前端功能组件.md

39 KiB

A9 · 前端功能模块与共享层(App.vue 之外)

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

  • frontend/shared/api/client.ts、frontend/shared/api/endpoints.ts
  • frontend/shared/types/:workflow-round.ts、workflow.ts、profile.ts、material.ts、image.ts
  • frontend/shared/utils/:presentation.ts、collections.ts
  • frontend/plugin-page/src/App.vue、frontend/plugin-page/src/main.ts、frontend/plugin-page/vite.config.ts
  • frontend/standalone-web/vite.config.ts、frontend/standalone-web/src/main.ts、frontend/package.json
  • frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue(全文 2024 行)、advanced-material-state.ts
  • frontend/standalone-web/src/features/gallery/GalleryPage.vue、gallery/types.ts
  • frontend/standalone-web/src/features/profiles/:ProfilesPage.vue、ProfileDetailPane.vue、ProfileWardrobePane.vue、profile-ui.ts
  • frontend/standalone-web/src/features/workflow/:WorkflowCandidatePool.vue、WorkflowRoundPanel.vue、WorkflowGenerationReviewDialog.vue、WorkflowMaterialDrawer.vue、WorkflowCompareDialog.vue、WorkflowBranchPanel.vue、WorkflowComposer.vue、WorkflowDependencyContextCard.vue、types.ts、workflow-lock-state.ts
  • frontend/standalone-web/src/features/settings/SettingsPage.vue 及全部子面板
  • frontend/standalone-web/src/features/quick-profile/profile-import.ts
  • frontend/standalone-web/src/components/:MaterialOperationDialog.vue、ConfirmDialog.vue、ImagePreviewDialog.vue、MaterialDetailDialog.vue、MaterialCategoryCreateDialog.vue
  • frontend/standalone-web/src/material-labels.ts、safe-backdrop-close.ts、frontend/tests/*.test.mjs
  • 交叉验证的后端文件:backend/dto/workflow_round_dto.py、backend/dto/profile_dto.py、backend/services/wardrobe_service.py、backend/services/settings_service.py、core/secret_service.py、database/repositories/profile_repository.py

摘要

plugin-page 与 standalone-web 之间没有代码重复——plugin-page/src/App.vue 只有 7 行,直接 import WorkbenchApp from "../../standalone-web/src/App.vue",两套构建共享同一份源码,这一点做得很干净。真正的问题在别处:共享层缺失导致同一逻辑在功能组件里被反复手写。ApiClientError 提供了结构化的 code/details,但唯一的中文化函数 readableApiError 被关在 App.vue 里没有导出,结果 13 个直接调 API 的组件各写各的 e instanceof Error ? e.message : String(e)(共 18+ 处),把 AstrBot Plugin Page POST request timed out after 30 seconds 这类英文原文直接抛给中文用户。焦点陷阱被复制了 6 份且行为各不相同,另有 2 个 aria-modal="true" 的对话框(WorkflowMaterialDrawer、SettingsPage 适配器弹窗)完全没有 Esc 和焦点管理。

有 3 条确凿的功能性缺陷:AdvancedMaterialImportPage.vue:1314-1316 存在编码损坏的字面量 "????????????????" 且已被模板渲染;profile-import.ts 把「性格关键词待从原文继续整理」这类占位提示当作真实值写入问卷并最终进入 base_prompt;SettingsPage.vue:98 把 UI 明确承诺「不写入配置或日志」的 API Key 以 api_key_plaintext 塞进 settings/save 请求,后端会原样落盘到 config.yaml。

类型层面与后端 DTO 目前是对齐的(逐字段比对了 WorkflowRoundCandidatePoolEntry、CharacterProfile、detailed_workflow_state 的 SQL 取值),但完全靠人工维护、无契约测试兜底,属于结构性漂移风险。此外 WorkflowDependencyContextCard.vue(279 行)已无任何引用成为死组件,package.json 里 pinia/vue-router 声明但零使用。

ProfilesPage → ProfileDetailPane → ProfileWardrobePane 是典型的三层 prop drilling:App.vue 传 24 个 props / 13 个 emits,其中 16 个 props 在 ProfilesPage 内完全不被使用、只做透传。

发现

[P1-严重] styleValidationReviewTrust 返回编码损坏的问号串,且已渲染到界面

  • 位置:frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue:1304-1317(渲染点 :1656)
  • 问题:函数的三个返回分支全部是编码损坏后残留的 ASCII 问号,中文字符在某次保存/转码中被替换成了 ?。这不是注释也不是占位常量,而是直接返回给模板的显示文本。
  • 代码:
    function styleValidationReviewTrust(validationCase: AdvancedStyleValidationCase) {
      const review = ...
      const coverage = Number(calibration.dimension_coverage)
      const inconsistent = Boolean(calibration.review_inconsistent || calibration.dimension_consistency_capped)
      const risks = Array.isArray(review.semantic_risks) && review.semantic_risks.length > 0
      if (inconsistent || risks) return "????????????????"
      if (Number.isFinite(coverage)) return `????? ? ???? ${Math.round(coverage * 100)}%`
      return "?????"
    }
    
    模板侧(1656 行):
    <small v-if="styleValidationFidelityPercent(validationCase) != null" class="advanced-style-review-trust">{{ styleValidationReviewTrust(validationCase) }}</small>
    
  • 影响:只要画风验证轮返回了 fidelity_score,进阶素材审核页就会在每个验证场景卡片下显示一串问号。审核人员本应据此判断「评分可信度/维度覆盖率」,现在这条关键信息完全丢失,等于在缺少可信度提示的情况下做封存决策。全仓库仅此一处出现 ???? 字面量,可以确定是单点编码事故而非设计。
  • 修复建议:恢复三条中文文案,例如 "评分可信度存疑:维度不一致或存在语义风险" / `评分可信 · 维度覆盖 ${pct}%` / "评分可信度未知";同时在 frontend/tests/ 增加一个断言:features/ 下所有 .vue 不得出现连续 3 个以上 ? 的字符串字面量,防止再次发生编码回退。

[P1-严重] 文本角色卡导入把「待整理」占位提示当成真实设定写入档案,最终污染 base_prompt

  • 位置:frontend/standalone-web/src/features/quick-profile/profile-import.ts:149-178、:327-337;消费点 frontend/standalone-web/src/App.vue:9721-9726、:9568-9581
  • 问题:resolveImportedProfileField 的第 4 个参数 fallback 在「没识别到」时会被写进 .value。5 个字段的 fallback 不是空串,而是给人看的提示语。调用方只用 recognizedKeys 控制 UI 高亮,却把 .value 无条件复制进问卷。
  • 代码:
    // profile-import.ts:149
    const personality = resolveImportedProfileField(source, ["性格", ...], [...], "性格关键词待从原文继续整理")
    const appearance  = resolveImportedProfileField(source, ["外观", ...], [...], "外观特征待从原文继续整理")
    const outfit      = resolveImportedProfileField(source, ["服装", ...], [...], "服装与配饰待从原文继续整理")
    const scene       = resolveImportedProfileField(source, ["场景", ...], [...], "常用场景待补充")
    
    // :327 —— fallback 直接成为 value
    function resolveImportedProfileField(source, labels, keywords, fallback) {
      ...
      return { value: fallback, recognized: false }
    }
    
    // App.vue:9721 —— 未按 recognized 过滤,整体复制
    personality: draft.personality,
    appearance: draft.appearance,
    outfit: draft.outfit,
    scene: draft.scene,
    
    // App.vue:9568 —— 进入角色实体
    personality: [questionnaire.personality, questionnaire.likes, questionnaire.dislikes]
      .map((item) => item.trim()).filter(Boolean).join(";") || "性格待细化",
    clothing: questionnaire.outfit.trim() || "服装与配饰待细化",
    
    再经 App.vue:9367 拼进 base_prompt。
  • 影响:导入一份没有「性格:」小节的角色卡后,角色档案的性格字段会变成中文句子「性格关键词待从原文继续整理」,并作为 personality: 片段进入 base_prompt 送给生图/文本模型。模型会把这句元指令当作角色描述处理,生成结果不可控;用户看到问卷里已经"填好了"也不会去清理。
  • 修复建议:把这 5 个 fallback 改为空串,把提示语移到 UI 的 placeholder 属性上(ExternalProfileImportPreviewRow 已经有 recognized 标志可用于渲染灰色提示)。若要保留提示,则在 App.vue:9721 处按 draft.recognizedKeys.includes(key) 过滤后再赋值。

[P1-严重] 「仅本次会话使用、不写入配置」的 API Key 被前端主动写进 settings/save 请求体

  • 位置:frontend/standalone-web/src/features/settings/SettingsPage.vue:98(saveAndProbeAdapter);UI 承诺文案在 :133
  • 问题:输入框标签明确写着「仅本次页面会话使用」「不写入配置或日志」,但 saveAndProbeAdapter 把该值作为 api_key_plaintext 注入 config.generation.adapters[] / config.generation.provider,然后调用 endpoints.settingsSave。后端 SettingsService.save() 会把合并后的 config 通过 write_text_atomic(config_path, dump_yaml(merged)) 原样落盘(backend/services/settings_service.py:445),_mask_sensitive 只作用于返回值和审计快照,不作用于写入磁盘的内容。
  • 代码:
    // SettingsPage.vue:98
    const key = probeApiKeyValue(a.id).trim()
    if (Array.isArray(generation.adapters)) {
      generation.adapters = generation.adapters.map(item => {
        const adapter = obj(item)
        if (String(adapter.id || adapter.provider_id) !== a.id) return item
        return { ...adapter, ...(key ? { api_key_plaintext: key } : {}) }   // ← 明文写入待保存 config
      })
    }
    const provider = obj(generation.provider)
    if (String(provider.id || provider.provider_id) === a.id && key)
      generation.provider = { ...provider, api_key_plaintext: key }
    config.generation = generation
    await postJson<ValidateSettingsResult>(endpoints.settingsValidate, { config })
    const saved = await postJson<SaveSettingsResult>(endpoints.settingsSave, { config })   // ← 落盘
    
    <!-- SettingsPage.vue:133 -->
    <label><span>探测用 API Key</span><input ... placeholder="仅本次页面会话使用" ...>
      <small>点击测试时会直接读取输入框当前值,兼容浏览器自动填充;不写入配置或日志。</small></label>
    
    另外 duplicateAdapter(:89)会把该会话密钥复制到新适配器 probeApiKeys[duplicateId],扩大扩散面。
  • 影响:用户基于「不落盘」的明确承诺输入生产环境 API Key,实际会以明文形式持久化到 config.yaml(该文件在仓库中被跟踪,见根目录 config.yaml)。这是承诺与行为的直接背离,属于凭据泄漏风险。
  • 修复建议:二选一。(a) 保持承诺:改用一个不落盘的探测端点,把明文 key 只放在 apiDiscoveryProbeProvider 的请求体里(backend/services/api_discovery_service.py:229 已经支持读取 api_key_plaintext),去掉先 save 再探测的链路;(b) 修正承诺:把 <small> 文案改成「保存后会写入插件配置文件」,并在按钮上加二次确认。无论哪种,duplicateAdapter 都不应复制会话密钥。

[P1-严重] 快速角色问卷默认值是一个完整的虚构示例角色,且绕过了 production-data-boundary 测试的防线

  • 位置:frontend/standalone-web/src/features/quick-profile/profile-import.ts:32-59;使用点 frontend/standalone-web/src/App.vue:759
  • 问题:quickProfileQuestionnaire 的初始值不是空表单,而是一个填满的示例角色。仓库里已有 frontend/tests/production-data-boundary.test.mjs 专门禁止生产 UI 内联演示数据,但该测试只读取 App.vue 和 MaterialDetailDialog.vue 两个文件,profile-import.ts 不在扫描范围内,因此这批示例数据从防线的缝隙里漏了过去。
  • 代码:
    export function createDefaultQuickProfileQuestionnaire(): QuickProfileQuestionnaire {
      return {
        roleCore: "近未来港区巡查员,负责夜间巡逻和异常记录。",
        genderPresentation: "female",
        distinctiveFeatures: "发光臂章,青绿色眼睛",
        personality: "冷静、可靠、行动快,外冷内热。",
        appearance: "黑色短发,青绿色眼睛,轻机能外套。",
        outfit: "短靴、发光臂章、便携通讯设备。",
        scene: "星港、雨夜街区、巡查终端、航灯背景。",
        ...
    
    // App.vue:759
    const quickProfileQuestionnaire = ref<QuickProfileQuestionnaire>(createDefaultQuickProfileQuestionnaire())
    
    // frontend/tests/production-data-boundary.test.mjs:5-8 —— 扫描范围不含 profile-import.ts
    const appPath = new URL("../standalone-web/src/App.vue", import.meta.url)
    const materialDialogPath = new URL("../standalone-web/src/components/MaterialDetailDialog.vue", import.meta.url)
    
  • 影响:任何用户第一次打开快速角色问卷,看到的是一个别人的角色设定。直接点「生成」就会消耗真实 API 额度生成这个虚构角色的四张图并落库。同时它与 ProfilesPage 的空态文案「新建或导入角色后即可管理生成设定」自相矛盾。
  • 修复建议:把 App.vue:759 改为 createEmptyQuickProfileQuestionnaire()(该函数已存在于同文件 :61),示例值降级为各输入框的 placeholder。同时把 production-data-boundary.test.mjs 的扫描目标改为 standalone-web/src 下全部 .vue/.ts,让防线真正覆盖 features 层。

[P2-中等] client.ts 的结构化错误在功能层完全失效:18+ 处各写各的 catch,英文超时文案直抛给中文用户

  • 位置:frontend/shared/api/client.ts:18-28(ApiClientError)、frontend/standalone-web/src/App.vue:4356(readableApiError,未导出)、frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue:1355,以及 settings/gallery/profiles 下 15+ 个内联 catch
  • 问题:ApiClientError 携带了 code 和 details,客户端有 8 种明确的错误码。但唯一做码→中文映射的 readableApiError 定义在 App.vue 内部(<script setup> 局部函数,无法被其它组件 import),所以每个直接调 API 的组件都退化成裸 err.message。全项目 13 个组件直接调用 shared/api/client,其中 12 个没有任何错误码分支。
  • 代码:
    // shared/api/client.ts:143 —— 面向用户的英文文案
    `AstrBot Plugin Page POST request timed out after ${Math.round(timeoutMs / 1000)} seconds`
    // :161
    `AstrBot Plugin Page bridge does not support ${method}`
    
    // AdvancedMaterialImportPage.vue:1355 —— 自己重造一份,丢弃 code/details
    function errorMessage(err: unknown) {
      return err instanceof Error ? err.message || "请求失败" : String(err || "请求失败")
    }
    
    // ProfileWardrobePane.vue:250 / SettingsPage.vue:109,111 / ReviewPolicyPanel.vue:8,9,10 / SystemManagementPanel.vue:8,9,10 / BackupPage.vue:15 / StorageMaintenance.vue:9 ...
    catch(e){ error.value = e instanceof Error ? e.message : String(e) }
    
    // App.vue:4356 —— 只覆盖 2/8 个错误码,其余仍落到英文原文
    function readableApiError(err: unknown) {
      if (err instanceof ApiClientError) {
        if (err.code === "invalid_api_response") return "接口返回了页面内容或非 JSON 数据..."
        if (err.code === "network_unreachable") return "无法连接 ImageStudio 后端接口。"
        return err.message || "ImageStudio 后端接口请求失败。"   // bridge_timeout / http_error / bridge_method_unavailable 走这里
      }
    
  • 影响:插件桥超时(30 秒 POST / 15 秒 GET,在慢速生图场景很常见)时,设置页、进阶素材页、衣橱模板等处会弹出纯英文的 AstrBot Plugin Page POST request timed out after 30 seconds。details 里的 endpoint/status/url 等排查信息全部被丢弃,用户和维护者都拿不到可操作线索。
  • 修复建议:把 readableApiError 提升到 frontend/shared/api/client.ts 导出(例如 export function describeApiError(err: unknown): { message: string; hint?: string }),补齐 bridge_timeout/bridge_method_unavailable/http_error 的中文分支并把 details.endpoint 作为副文本返回;然后用它替换掉全部 18 处内联 catch 和 AdvancedMaterialImportPage.vue:1355 的私有副本。

[P2-中等] ProfilesPage 三层 prop drilling:24 个 props / 13 个 emits,其中 16 个 props 纯透传

  • 位置:frontend/standalone-web/src/features/profiles/ProfilesPage.vue:10-76、:121-151;下游 ProfileDetailPane.vue:28-82、:332-346;调用点 frontend/standalone-web/src/App.vue:13336-13374
  • 问题:ProfilesPage 自身只使用 profiles/selectedId/loading/error/canWrite/backendConnected 六个 props,其余 18 个(imageTargets、selectedImageId、materialCount、selectedWorkflowsCount、workflowNodeCount、selectedAvatarUrl、wardrobeItems、wardrobeMaterials、materialCategories、wardrobePermissions、wardrobeLoading、wardrobeBusy、wardrobeError、generationBusy、generationError、deleting 等)在 <script> 中零引用,只在模板里原样往下传。wardrobe* 这一组更是穿过两层组件才到达真正的消费者 ProfileWardrobePane。emits 同理:forwardWardrobeAdd 这个纯转发函数在 ProfilesPage.vue:78 和 ProfileDetailPane.vue:137 各写了一遍,代码完全相同。
  • 代码:
    // ProfilesPage.vue:78 —— 与 ProfileDetailPane.vue:137 逐字符相同
    function forwardWardrobeAdd(materialId: string, wardrobeCategory: string) {
      emit("wardrobeAdd", materialId, wardrobeCategory)
    }
    
    <!-- ProfilesPage.vue:121 —— 21 行里 16 行是透传 -->
    <ProfileDetailPane
      :wardrobe-items="wardrobeItems" :wardrobe-materials="wardrobeMaterials"
      :material-categories="materialCategories" :wardrobe-permissions="wardrobePermissions"
      :wardrobe-loading="wardrobeLoading" :wardrobe-busy="wardrobeBusy" :wardrobe-error="wardrobeError"
      ... @wardrobe-retry="emit('wardrobeRetry')" @wardrobe-add="forwardWardrobeAdd" @wardrobe-remove="emit('wardrobeRemove', $event)" />
    
  • 影响:衣橱相关的任何一个新字段(如「常用标记」「排序」)都要在 App.vue、ProfilesPage、ProfileDetailPane、ProfileWardrobePane 四处同步修改 props/defaults/emits/模板,共 8 个改动点。withDefaults 的默认值也在 ProfilesPage 和 ProfileDetailPane 里重复声明了两遍(() => []、""、false),两处一旦不一致就会产生难以定位的行为差异。
  • 修复建议:把衣橱这一族状态收敛为一个对象 prop(:wardrobe="{ items, materials, categories, permissions, loading, busy, error }"),props 数量立刻从 24 降到 ~12;或直接让 ProfileWardrobePane 自己按 profileId 拉取衣橱数据(它已经在这么做模板部分了,见下一条),彻底断开中间两层的透传链。

[P2-中等] ProfileWardrobePane 状态归属分裂:衣橱条目走 props/emits,套装模板自己调 API

  • 位置:frontend/standalone-web/src/features/profiles/ProfileWardrobePane.vue:11-37(props/emits)对比 :59、:151、:249-252(自持状态与 API 调用)
  • 问题:同一个组件里存在两套互相矛盾的数据所有权模型。衣橱条目(wardrobeItems)、加载态(loading/busy)、错误(error)由父组件持有,增删走 emit('add')/emit('remove');而套装模板(outfitTemplates)、其加载态(templateBusy)、错误(templateMessage)由组件自己持有,增删改直接 getJson/postJson/deleteJson。
  • 代码:
    // :59 —— 自持状态,压缩成一行
    const outfitTemplates=ref<Array<Record<string,unknown>>>([]),templateName=ref(""),templateBusy=ref(false),templateMessage=ref(""),compositionPreview=ref<Record<string,unknown>|null>(null)
    
    // :151 —— 自己监听 profileId 拉数据
    watch(()=>props.profileId,()=>{void loadTemplates()},{immediate:true})
    
    // :249-252 —— 自己写库,父组件完全不知情
    async function loadTemplates(){...outfitTemplates.value=await getJson(endpoints.wardrobeTemplates(props.profileId))...}
    async function saveCurrentTemplate(){...await postJson(endpoints.wardrobeTemplates(props.profileId),{name:...,material_ids:props.wardrobeItems.map(item=>item.material_id)})...}
    async function removeTemplate(templateId:string){...await deleteJson(endpoints.wardrobeTemplate(props.profileId,templateId))...}
    
    另外 loadTemplates 的 catch{outfitTemplates.value=[]} 完全吞掉错误——权限不足或后端 500 时,用户看到的是「暂无模板」而不是失败提示。
  • 影响:busy(父级)和 templateBusy(自持)互不感知,用户可以在「添加衣橱素材」进行中同时点击「保存当前衣橱」,两个写操作并发命中同一个 profile 的 metadata——而后端 WardrobeService.save_template 是读-改-写整个 profile.metadata(backend/services/wardrobe_service.py:167),存在后写覆盖先写的丢更新风险。模板保存后父组件的衣橱数据也不会刷新。
  • 修复建议:统一到一侧。推荐让本组件全权负责衣橱域(自己按 profileId 拉取 items 和 templates),父组件只传 profileId + permissions;或反之把 templates 也提到 App.vue。同时给 loadTemplates 的 catch 加上错误展示,并让 templateBusy 与 props.busy 合并成一个 anyBusy computed 用于禁用所有写按钮。

[P2-中等] 焦点陷阱被复制 6 份且实现互不相同,另有 2 个 aria-modal 对话框完全没有键盘管理

  • 位置:
    • 6 份手写焦点陷阱:components/ConfirmDialog.vue:50-67、components/ImagePreviewDialog.vue:124-141、components/MaterialOperationDialog.vue:146-160、features/profiles/ProfileWardrobePane.vue:216-238、features/workflow/WorkflowCompareDialog.vue:48-59、features/workflow/WorkflowGenerationReviewDialog.vue:163-175
    • 零键盘管理但声明了 aria-modal="true":features/workflow/WorkflowMaterialDrawer.vue:149-155、features/settings/SettingsPage.vue:131
  • 问题:项目已经有共享的 safe-backdrop-close.ts 抽象(背景点击关闭),说明作者知道这类逻辑该提取,但焦点陷阱这块没做。6 份实现分成 3 种行为:ConfirmDialog 会检查 !dialogRef.contains(active) 从而能把逃逸的焦点拉回来;其余 5 份只比较 activeElement === first/last;WorkflowCompareDialog 在无可聚焦元素时直接 return 不做任何处理,而 ConfirmDialog/ImagePreviewDialog 会 preventDefault 并把焦点还给 dialog。
  • 代码:
    // ConfirmDialog.vue:61 —— 唯一正确处理焦点逃逸的版本
    if (event.shiftKey && (active === first || !dialogRef.value?.contains(active))) {
    
    // WorkflowGenerationReviewDialog.vue:168 / ImagePreviewDialog.vue:134 / MaterialOperationDialog.vue:153 / ProfileWardrobePane.vue:230 / WorkflowCompareDialog.vue:53 —— 焦点一旦落到 body 就锁不住
    if (event.shiftKey && document.activeElement === first) {
    
    <!-- WorkflowMaterialDrawer.vue:149 —— 没有 @keydown、没有 nextTick focus、没有 Tab 陷阱 -->
    <aside class="workflow-material-drawer" role="dialog" aria-modal="true" aria-label="节点素材抽屉" :aria-busy="busy">
    
    <!-- SettingsPage.vue:131 —— 同样只有 aria 属性,Esc 无效 -->
    <article ... class="adapter-dialog" role="dialog" aria-modal="true" :aria-label="`${a.name} 配置`">
    
  • 影响:aria-modal="true" 向屏幕阅读器承诺「焦点被限制在此对话框内」。素材抽屉和适配器配置弹窗违背了这个承诺,键盘用户 Tab 几下就会走到被 backdrop 遮住的背景内容上,并且无法用 Esc 关闭。另外 5 个对话框在 busy 态下按钮被 :disabled 后当前焦点元素会失焦到 <body>,此时 Tab 同样会逃出弹窗。
  • 修复建议:把 ConfirmDialog.vue:41-67 那份(最完整的)提取为 standalone-web/src/focus-trap.ts,导出 createFocusTrap(dialogRef) 返回 { onKeydown, focusFirst, restore },与已有的 createSafeBackdropClose 并列。8 处全部改用它,WorkflowMaterialDrawer 和 SettingsPage 的适配器弹窗补上 @keydown 绑定。

[P2-中等] 生成状态中文标签在 3 处重复定义且译法互相冲突

  • 位置:frontend/standalone-web/src/App.vue:6927-6939、frontend/standalone-web/src/features/workflow/WorkflowCandidatePool.vue:132-145、frontend/standalone-web/src/features/workflow/WorkflowRoundPanel.vue:113-129;另有基础版在 frontend/shared/utils/presentation.ts:11-29
  • 问题:同一批后端状态码在四个地方各建一张映射表,且译法不一致。
  • 代码:
    // App.vue:6927
    const labels: Record<string, string> = {
      planned: "已规划", queued: "排队中", running: "生成中",
      succeeded: "已成功", success: "已成功", completed: "已成功",
      failed: "失败", cancelled: "已取消",
    }   // 缺 retrying / dead_letter,落到 `|| status` 显示英文原文
    
    // WorkflowCandidatePool.vue:133 —— 同样的 candidate.generation_status,不同译法
    const labels: Record<string, string> = {
      planned: "待入队", queued: "排队中", running: "生成中", retrying: "重试中",
      succeeded: "已完成", failed: "生成失败", dead_letter: "重试耗尽", cancelled: "已取消",
    }
    
    // presentation.ts:11 —— 第四份,供任务队列使用
    succeeded: "已成功", dead_letter: "死信", retrying: "重试执行中", superseded: "已被重试替代",
    
  • 影响:同一个候选在候选池里显示「已完成」,在 App.vue 的其它视图(如工作流概览、对比弹窗标题)里显示「已成功」,在队列页显示「已成功」;planned 更是「待入队」和「已规划」两种说法。用户会误以为是不同状态。App.vue 那份还缺 retrying/dead_letter,重试中的候选会直接显示英文 retrying。
  • 修复建议:在 frontend/shared/utils/presentation.ts 增加 export function generationStatusLabel(status: string) 作为唯一真源,覆盖 planned|queued|running|retrying|succeeded|success|completed|failed|dead_letter|cancelled|superseded,删掉 App.vue、WorkflowCandidatePool、WorkflowRoundPanel 里的三份局部表(WorkflowRoundPanel 的轮次级状态 partial_success|all_failed|confirmed 可另建 roundStatusLabel 一并放入)。

[P2-中等] WorkflowDependencyContextCard.vue(279 行)已成为无引用的死组件

  • 位置:frontend/standalone-web/src/features/workflow/WorkflowDependencyContextCard.vue(整个文件)
  • 问题:全仓库(排除 node_modules、构建产物)搜索 WorkflowDependencyContextCard,除文件自身外零命中。而 App.vue 仍在维护对应的数据链路:workflowDependencyContextByNodeId(:792)、workflowDependencyContextLoadingId(:793)、workflowDependencyContextError(:794)、loadWorkflowDependencyContext()(:6894),并在 :4129、:7214、:8324 三处触发加载——数据被拉取了,但展示组件不再被挂载,改由 App.vue 内联渲染。
  • 代码:
    // WorkflowDependencyContextCard.vue:9-26 —— 完整的 props/emits 定义,无人调用
    const props = withDefaults(defineProps<{
      context?: WorkflowNodeDependencyContext | null
      loading?: boolean; error?: string; locked?: boolean
    }>(), { context: null, loading: false, error: "", locked: false })
    const emit = defineEmits<{ refresh: [] }>()
    
    旁证:git status 显示构建产物 web/assets/WorkflowDependencyContextCard-CVx_4GIk.js 与 pages/imagestudio/assets/WorkflowDependencyContextCard-Da-Ez1_X.js 已被删除,说明最近一次重构把它从 App.vue 的模板里摘掉了,但源文件被遗留。
  • 影响:279 行代码 + 对应的 scoped CSS 会误导后续维护者以为依赖上下文卡片有独立组件可复用,实际改它不产生任何效果。vue-tsc --noEmit 仍会检查它,拖慢类型检查。
  • 修复建议:确认 App.vue 内联版本已完全覆盖其功能后删除该文件;若打算复用,则把 App.vue 里内联的依赖上下文渲染换回该组件,并把三个 workflowDependencyContext* ref 通过 props 传入。

[P3-轻微] GalleryPage 批量操作串行执行且完全吞掉错误,用户只看到一个无解释的数字

  • 位置:frontend/standalone-web/src/features/gallery/GalleryPage.vue:115-123
  • 问题:runBatch 用 for...of 串行 await 每一张图的请求,且 catch{} 里没有任何记录,最终只把成功计数拼进文案。
  • 代码:
    for(const id of ids){try{if(action==="select")await postJson(endpoints.imageSelect(id));...else await postJson(endpoints.imageSafeDelete(id),{dry_run:false,delete_files:false});success++}catch{/* keep remaining items running */}}
    actionMessage.value=`已处理 ${success}/${ids.length} 张图片`;checkedIds.value=[];actionBusy.value=false;emit("refresh")
    
  • 影响:选中 50 张执行「安全删除」,若因引用检查全部失败,用户看到的是「已处理 0/50 张图片」,没有任何原因(后端安全删除会返回引用冲突详情,全被丢弃)。串行 50 次请求在插件桥模式下每次最多 30 秒超时,最坏情况阻塞 25 分钟且无进度反馈。此外 checkedIds 被无条件清空,用户无法只重试失败的那些。
  • 修复建议:收集失败项 const failures: Array<{id: string; reason: string}> = [],用 Promise.allSettled 配合并发上限(如 5)替代串行循环,结束后把失败 id 保留在 checkedIds 里并在 actionMessage 里展示前几条原因。

[P3-轻微] browserImageUrl / 图片 URL 白名单校验被复制 4 份,衣橱分类标签被复制 2 份且函数名与共享导出冲突

  • 位置:
    • URL 校验:features/profiles/profile-ui.ts:155(isBrowserImageUrl)、features/workflow/WorkflowCandidatePool.vue:165、features/workflow/WorkflowGenerationReviewDialog.vue:97、features/profiles/ProfileWardrobePane.vue:189(materialThumbnail 内联)
    • 分类标签:features/profiles/ProfileWardrobePane.vue:40-46 对比 standalone-web/src/material-labels.ts:30-39
  • 问题:完全相同的正则 /^(?:https?:|data:|blob:|\/)/i 出现在 4 个文件里;top/bottom/dress/shoes/accessory 五条中文标签在 ProfileWardrobePane 的 WARDROBE_CATEGORY_LABELS 和 material-labels.ts 的 MATERIAL_CATEGORY_LABELS 各存一份。更糟的是 ProfileWardrobePane.vue:158 定义了一个局部函数 materialCategoryLabel(material: Material),与 material-labels.ts 导出的 materialCategoryLabel(value: unknown) 同名但签名和语义都不同(一个吃 Material 对象,一个吃字符串)。
  • 代码:
    // ProfileWardrobePane.vue:41 —— 与 material-labels.ts:31-35 五条完全重合
    const WARDROBE_CATEGORY_LABELS: Readonly<Record<string, string>> = {
      top: "上装", bottom: "下装", dress: "连衣裙", shoes: "鞋履", accessory: "配饰",
    }
    
    // ProfileWardrobePane.vue:158 —— 与共享导出同名不同义
    function materialCategoryLabel(material: Material | undefined) { ... }
    
    // material-labels.ts:42
    export function materialCategoryLabel(value: unknown) { ... }
    
  • 影响:新增衣橱分类(例如 outerwear)需要改两个文件;material-labels.ts 已经有 outfit、style、composition 三条而 ProfileWardrobePane 没有,导致同一分类在素材库显示中文、在衣橱显示英文 key。同名函数会让 IDE 的「跳转到定义」和后续 import 产生歧义。
  • 修复建议:把 URL 白名单校验提到 frontend/shared/utils/presentation.ts(或新建 shared/utils/media-url.ts)导出 isBrowserImageUrl,4 处统一引用;ProfileWardrobePane 删除 WARDROBE_CATEGORY_LABELS 改用 materialCategoryLabel,并把局部的 materialCategoryLabel(material) 改名为 materialCategoryName(material) 消除冲突。

[P3-轻微] package.json 声明了零使用的 pinia / vue-router,且构建工具全在 dependencies、devDependencies 为空

  • 位置:frontend/package.json:16-25
  • 问题:全仓库搜索 pinia、vue-router、createRouter、defineStore,在 frontend/ 源码(排除 node_modules)中零命中——路由由 App.vue 的 activeNav + navigation-config.ts 自己实现,状态管理靠 ref/computed。同时 typescript、vite、vue-tsc、@vitejs/plugin-vue 这些纯构建期依赖被放进 dependencies,而 devDependencies 是空对象。
  • 代码:
    "dependencies": {
      "@vitejs/plugin-vue": "^5.2.0",
      "pinia": "^2.3.0",
      "typescript": "^5.7.0",
      "vite": "^6.0.0",
      "vue": "^3.5.0",
      "vue-router": "^4.5.0",
      "vue-tsc": "^2.2.0"
    },
    "devDependencies": {}
    
  • 影响:npm ci --omit=dev 在 CI/发布环境下不会减少任何体积;pinia/vue-router 会误导新维护者以为项目有 store 和路由体系,从而按错误的假设写代码(这也间接解释了 App.vue 为何膨胀到 22563 行——没有 store 层可放业务状态)。
  • 修复建议:删除 pinia 和 vue-router;把 @vitejs/plugin-vue、typescript、vite、vue-tsc 移到 devDependencies,dependencies 只保留 vue。

[P3-轻微] frontend/shared/types/ 与后端 DTO 全靠人工同步,无契约测试兜底

  • 位置:frontend/shared/types/workflow-round.ts:88-121 对比 backend/dto/workflow_round_dto.py:50-115;frontend/shared/types/profile.ts:3-21 对比 backend/dto/profile_dto.py:32-54;frontend/tests/*.test.mjs(8 个文件,无一做类型/字段比对)
  • 问题:逐字段核对后,当前没有发现实际漂移——WorkflowGenerationCandidate 的 15 个字段、WorkflowRoundCandidatePoolEntry 的 11 个字段、CharacterProfile 的可选字面量联合(detailed_workflow_state: "in_progress" | "ready_to_archive" | "archived" | null)与 database/repositories/profile_repository.py:85-115 的 SQL CASE 取值都精确对应。问题在于这种对齐纯靠人工纪律维持:endpoints.contract 端点存在但前端没有任何测试消费它,8 个前端测试全是字符串包含断言(production-data-boundary、ui-theme-contract 等),没有一个校验类型定义。
  • 代码:
    # backend/dto/workflow_round_dto.py:102 —— 后端真源
    "display_index": self.display_index, "display_code": self.display_code,
    "pool_state": self.pool_state, "preference_status": self.preference_status,
    "preference_reason": self.preference_reason, "is_final": self.is_final,
    
    // shared/types/workflow-round.ts:106 —— 手工镜像,无生成、无校验
    export interface WorkflowRoundCandidateView {
      round_id: string; candidate_id: string; display_index: number; display_code: string
      pool_state: string; preference_status: WorkflowCandidatePreference | string
      preference_reason?: string | null; is_final: boolean
    
  • 影响:后端 DTO 增删字段时 TypeScript 不会报错(多出的字段被静默忽略,删除的字段在运行时变 undefined 而类型上仍是 string)。例如 WorkflowCandidatePool.vue:129 的 String(candidate.candidate.generation_status || "planned") 已经在用防御性写法兜底,说明团队对此有隐忧但没有系统性解法。风险随 DTO 数量增长而累积(backend/dto/ 下已有多个模块)。
  • 修复建议:加一个 node 测试,读取 backend/dto/*.py 中每个 to_dict 的字面量 key 集合,与 frontend/shared/types/*.ts 对应 interface 的字段名集合做双向差集断言(正则提取即可,不需要真正解析 AST)。放进 frontend/tests/dto-contract.test.mjs,纳入 npm run test:contracts。

[P3-轻微] 多个功能文件被压成单行,等同于把源码当构建产物维护

  • 位置:features/gallery/GalleryPage.vue:113-122、:214;features/settings/SettingsPage.vue:41-42、:79-111、:126-153、:160-167;features/profiles/ProfileWardrobePane.vue:59、:249-252、:305
  • 问题:这些不是构建产物(它们在 frontend/standalone-web/src/ 源码树内、有 <script setup lang="ts">),而是被手工去掉换行和空格的源码。SettingsPage.vue:98 的 saveAndProbeAdapter 单行长度超过 2000 字符,内含 3 次 await、2 个循环、1 个 try/catch 和 6 个条件分支。
  • 代码:
    // GalleryPage.vue:113 —— 与同文件 :99-111 的正常缩进风格并存
    function toggleChecked(imageId:string){checkedIds.value=checkedIds.value.includes(imageId)?checkedIds.value.filter(id=>id!==imageId):[...checkedIds.value,imageId]}
    
    // ProfileWardrobePane.vue:59 —— 与同文件 :48-57 的每行一个 ref 风格并存
    const outfitTemplates=ref<Array<Record<string,unknown>>>([]),templateName=ref(""),templateBusy=ref(false),templateMessage=ref(""),compositionPreview=ref<Record<string,unknown>|null>(null)
    
  • 影响:git blame/git diff 在这些行上完全失效——改一个字符就是整行重写,code review 无法定位实际变更。SettingsPage.vue:98 这样的巨型单行里藏着本文档第 3 条那个凭据落盘缺陷,正是因为它被压成一行才长期未被发现。同一文件内两种排版风格并存,说明是后续增量修改时的临时做法固化了下来。
  • 修复建议:对这 3 个文件跑一次 Prettier/ESLint --fix 展开(项目当前没有 formatter 配置,可先加 .prettierrc 约定 printWidth: 120),单独提一个纯格式化 commit 以免污染后续 blame。

附:确认无问题的项

  • plugin-page 与 standalone-web 无代码重复。frontend/plugin-page/src/App.vue 全文 7 行,只做 import WorkbenchApp from "../../standalone-web/src/App.vue" 后转发;两个 vite.config.ts 仅 base 和 outDir 不同(/api/v1/plugins/.../web/ → web/,./ → pages/imagestudio/);main.ts 唯一差异是 plugin 版多调一次 installAstrBotPluginPageBridge()。这是正确的双产物单源码架构,不应因为构建产物目录看起来"重复"而误判。
  • shared/api/client.ts 的传输层抽象设计合理。插件桥/直连 fetch 双通道自动探测、PUT/PATCH/DELETE 在桥不支持时降级为带 __imagestudio_method 的 POST、长任务端点正则匹配延长超时、unwrapApiResponse 的 4 层嵌套解包上限,这些都考虑得比较周全。问题只出在错误呈现层(见 P2 那条),不在传输层本身。
  • WorkflowCandidatePool.vue(952 行)是本次审计中质量最高的组件。props 全部只读、零 API 调用、状态派生用 computed、mutationLocked/viewLocked 两级锁语义清晰、likedDisabled/compareDisabled/finalDisabled 三个约束函数各司其职。可作为其它 workflow 组件重构的参照。