astrbot_plugin_imagestudio/审计/findings/C2-前端精简空间.md

40 KiB

C2 — 前端代码精简空间

审计范围(实际 Read 过的文件):

  • frontend/package.json、frontend/tsconfig.json、frontend/env.d.ts
  • frontend/plugin-page/vite.config.ts、frontend/plugin-page/src/App.vue、frontend/plugin-page/src/main.ts
  • frontend/standalone-web/vite.config.ts、frontend/standalone-web/src/main.ts
  • frontend/standalone-web/src/App.vue(22563 行,逐段抽样通读 + 全量脚本分析)
  • frontend/standalone-web/src/styles/workbench.css、styles/tokens.css
  • frontend/standalone-web/src/components/{ConfirmDialog,ImagePreviewDialog,MaterialCategoryCreateDialog,MaterialDetailDialog,EmptyState,StateCard,MetricCardGrid}.vue
  • frontend/standalone-web/src/features/workflow/{WorkflowCompareDialog,WorkflowGenerationReviewDialog,WorkflowBranchPanel,WorkflowRoundPanel}.vue
  • frontend/standalone-web/src/features/profiles/{ProfileDetailPane,ProfileMasterPane,ProfileWardrobePane,ProfilesPage}.vue
  • frontend/standalone-web/src/features/gallery/GalleryPage.vue
  • frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue
  • frontend/standalone-web/src/features/settings/{SettingsPage,BackupPage}.vue
  • frontend/shared/utils/{presentation,collections,storage-uri}.ts、frontend/shared/types/{workflow,workflow-material,integration}.ts

全量静态分析脚本(自写,跑在真实源码树上):CSS 类引用可达性、CSS 声明块重复度、导出符号可达性、组件样式归属泄漏。

摘要

前端源码 40182 行,其中 CSS 占 14698 行(36.6%),standalone-web/src/App.vue 一个文件就占 22563 行(56%),其样式块 8396 行、模板块 2785 行、脚本块 11357 行,是典型的 god component。

可确证的"净删除"空间约 1900–2000 行(≈ 全部前端源码的 5%,CSS 的 13%),主要来自:App.vue 内 413 行永远不会命中的死 CSS 规则、SettingsPage.vue 里一整段重构后遗留的 .backup-* 死样式、素材选择器弹层模板被逐字复制两份(109 行)、4 份几乎一字不差的焦点陷阱实现(130 行)、图片查看器缩放/拖拽逻辑与 ImagePreviewDialog.vue 完全重复(脚本 60 行 + 样式 104 行)、以及 2251 行上限的重复 CSS 声明块。

"迁移拆分"空间约 6000 行(不减总量但把 App.vue 压到 6000–7000 行):quick-profile 前缀样式 1268 行、workflow-* 约 1400 行、materials-* 约 600 行可直接切成 feature CSS 文件;workflowActionCards(441 行)/generateFeatureCards(171)/queueActionCards(143)/materialActionCards(113)/quickProfileActionCards(88) 五个卡片工厂 + 4 张标签映射表共约 1080 行是纯数据,应搬到独立模块。

pinia 与 vue-router 声明了但整个代码库零引用(grep -rn "pinia\|vue-router" 在 src 下 0 命中),App.vue 用 206 个 ref + 135 个 computed 的巨型局部状态树代替 store。devDependencies 为空,typescript/vite/vue-tsc/@vitejs/plugin-vue 全部错放在 dependencies。

好消息:plugin-page 与 standalone-web 两套构建之间没有代码重复——plugin-page/src/App.vue 只有 7 行、直接 re-export standalone-web/src/App.vue,两份 vite.config.ts 各 16 行仅 base/outDir 不同。这一项无精简空间。


发现

[P2-中等] App.vue 样式块内 413 行 CSS 规则永远不会命中(死代码)

  • 位置:frontend/standalone-web/src/App.vue:17323、:17764-17845、:19007-19059、:20075-20101、:21129-21286、:21484-21499、:21662-21703(共 41 条规则);另 :17213-17316、:21491-21499 等

  • 问题:全量扫描 903 个 CSS 类,其中 63 个在任何 .vue 模板/脚本(含 Vue <Transition name> 派生类、动态 :class 绑定)中都无法被引用到。逐条核实后,App.vue 内由纯死类构成的完整规则块合计 277 行;另有 136 行是子组件已有 scoped 副本的重复定义。

  • 代码(真实片段,App.vue:21129-21145):

    .generate-status-grid {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
      gap: 12px;
    }
    
    .generate-status-grid article,
    .generate-feature-card {
      position: relative;
      overflow: hidden;
      display: grid;
      gap: 6px;
      border: 1px solid var(--border);
      border-radius: 12px;
      padding: 14px;
      background: var(--panel);
      box-shadow: var(--shadow);
    }
    

    generate-status-grid / generate-feature-card / generate-section / generate-card-grid / generate-card-top / feature-state 这一整组类在整个前端模板中零出现(generateFeatureCards computed 仍在,但渲染它的模板早已改用 quick-profile-command-card)。

    同样死掉的还有 App.vue:17764-17787:

    .workflow-node-card {
      position: relative;
      display: grid;
      grid-template-columns: 26px minmax(0, 1fr);
      align-items: start;
      gap: 10px;
      border: 1px solid var(--border);
      border-radius: 10px;
      padding: 11px;
      background: var(--panel-muted);
    }
    
    .workflow-node-card::after {
      position: absolute;
      left: 24px;
      top: 100%;
      width: 1px;
      height: 8px;
      background: var(--border);
      content: "";
    }
    

    模板里节点卡实际用的是 workflow-node-item,workflow-node-card 从未出现。

  • 影响:约 413 行 CSS 每次构建都被打进 web/assets/index-*.css 与 pages/imagestudio/assets/index-*.css 两份产物;改样式时会误导人以为在改生效的规则(.workflow-node-card 这种名字极具迷惑性)。

  • 修复建议:

    1. 把我这次的可达性扫描固化成一个 frontend/tests/dead-css.test.mjs(项目已有 node --test tests/*.test.mjs 的契约测试习惯),断言"App.vue 样式块内的类必须能在某个模板中被引用",白名单里放 Transition 派生类与动态拼接类。
    2. 直接删除上述行区间。删除时注意保留 .image-viewer-backdrop(App.vue 模板里 4 个内联弹层仍在用),只删 .image-viewer-card/-actions/-stage。

[P2-中等] .image-viewer-* 的 104 行样式与 60 行缩放/拖拽逻辑在 App.vue 和 ImagePreviewDialog.vue 中各存在一份

  • 位置:frontend/standalone-web/src/App.vue:17213-17316(CSS)与 frontend/standalone-web/src/components/ImagePreviewDialog.vue:221-324(CSS,scoped);App.vue:7952-8011(脚本)与 ImagePreviewDialog.vue:58-114(脚本)
  • 问题:两处 CSS 逐字节相同(diff 除去尾部一条无关规则后无差异)。App.vue 侧那 104 行的使用者只有 ImagePreviewDialog.vue 的模板,而该组件自带 scoped 副本,所以 App.vue 的这份是纯冗余。脚本侧同理:同一套 MIN/MAX 缩放、指针捕获拖拽逻辑写了两遍,只是变量名从 scale/offset/dragging 改成 imageViewerScale/imageViewerOffset/imageViewerDragging。
  • 代码(App.vue:7982-8011):
    function startImageViewerDrag(event: PointerEvent) {
      if (imageViewerScale.value <= 1) return
      imageViewerDragging.value = true
      imageViewerDragStart.value = {
        pointerId: event.pointerId,
        x: event.clientX,
        y: event.clientY,
        offsetX: imageViewerOffset.value.x,
        offsetY: imageViewerOffset.value.y,
      }
      if (event.currentTarget instanceof HTMLElement) {
        event.currentTarget.setPointerCapture(event.pointerId)
      }
    }
    
    对照 ImagePreviewDialog.vue:85-98:
    function startDrag(event: PointerEvent) {
      if (scale.value <= 1) return
      dragging.value = true
      dragStart.value = {
        pointerId: event.pointerId,
        x: event.clientX,
        y: event.clientY,
        offsetX: offset.value.x,
        offsetY: offset.value.y,
      }
      if (event.currentTarget instanceof HTMLElement) {
        event.currentTarget.setPointerCapture(event.pointerId)
      }
    }
    
    两处的魔数也各写一遍:0.5/4/0.12/2.2 vs MIN_SCALE/MAX_SCALE/WHEEL_STEP/DOUBLE_CLICK_SCALE。
  • 影响:约 164 行冗余;更糟的是缩放行为会漂移——改 ImagePreviewDialog 的手感不会同步到 quick-profile 查看器。
  • 修复建议:抽 standalone-web/src/composables/useImageZoomPan.ts:
    export function useImageZoomPan(opts?: { min?: number; max?: number }) {
      const scale = ref(1), offset = ref({ x: 0, y: 0 }), dragging = ref(false)
      // reset / zoom / zoomFromWheel / toggleZoom / startDrag / drag / endDrag
      return { scale, offset, dragging, transform, ...handlers }
    }
    
    ImagePreviewDialog.vue 与 App.vue 的 quick-profile 查看器都用它;删掉 App.vue:17213-17316 的 CSS,让 quick-profile 查看器直接复用 <ImagePreviewDialog>(模板 App.vue:12218-12266 的 49 行也一并消失)。

[P2-中等] 素材选择器弹层模板被逐字复制两份(109 行)

  • 位置:frontend/standalone-web/src/App.vue:12009-12117(quickProfile 模式)与 App.vue:12658-12769(workflow 模式)
  • 问题:把两段去掉缩进后 diff,97 行中只有 5 行不同:material.category → binding.category(3 处)、一句文案 取消这个素材参考 → 默认不注入这个参考、多一条 <small v-if="reference.advanced">。其余包括分组 tab、TransitionGroup、"不使用"选项、缩略图渲染全部一致。
  • 代码(App.vue:12021-12042 与 12672-12693 完全同构):
    <header class="quick-profile-material-picker-header">
      <div>
        <span>{{ material.category }}参考</span>
        <strong>选择素材</strong>
      </div>
      <small>{{ activeQuickProfileMaterialPickerCountLabel }}</small>
    </header>
    <div
      v-if="material.category === QUICK_PROFILE_ACCESSORY_CATEGORY"
      class="quick-profile-material-picker-groups"
      aria-label="配饰分类"
    >
      <button
        v-for="group in quickProfileAccessoryGroups"
        :key="group"
        type="button"
        :class="{ active: activeQuickProfileMaterialAccessoryGroup === group }"
        @click="setQuickProfileAccessoryGroup(group)"
      >
        {{ group }}
      </button>
    </div>
    
  • 影响:约 109 行模板重复;两侧已经开始漂移(reference.advanced 的"进阶素材 · 高优先级"标记只有 workflow 侧有,quickProfile 侧看不到),这是双份维护必然的结果。
  • 修复建议:抽 standalone-web/src/features/materials/MaterialPickerPopover.vue,props 为 { category: string; placement?: 'up'|'down'; extraClass?: string },事件 select / clear。两处调用点各缩到 8 行左右,净省约 100 行,同时消除功能漂移。

[P2-中等] 4 份几乎一字不差的焦点陷阱(focus trap)实现

  • 位置:frontend/standalone-web/src/components/ConfirmDialog.vue:30,42-83、components/ImagePreviewDialog.vue:27,116-151、features/workflow/WorkflowCompareDialog.vue:20,34-78、features/workflow/WorkflowGenerationReviewDialog.vue:53,149-205
  • 问题:每个弹窗组件都自己写了 previousFocus / focusableElements() / trapFocus()(或 handleKeydown) / restoreFocus() / watch(() => props.open, ...) 这一套约 45 行的样板。四份实现还不一致:
    • ConfirmDialog 与 ImagePreviewDialog 的选择器包含 input/select/textarea,WorkflowCompareDialog 只有 'button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])' —— 对比弹窗里如果出现输入框,Tab 会跳出弹窗。
    • ConfirmDialog 额外做了 !dialogRef.value?.contains(active) 的兜底,另外三份没有。
  • 代码(WorkflowCompareDialog.vue:34-40 vs ConfirmDialog.vue:42-47):
    // WorkflowCompareDialog.vue
    function focusableElements() {
      return Array.from(
        dialogRef.value?.querySelectorAll<HTMLElement>(
          'button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])',
        ) ?? [],
      )
    }
    
    // ConfirmDialog.vue
    function focusableElements() {
      return Array.from(
        dialogRef.value?.querySelectorAll<HTMLElement>(
          'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
        ) ?? [],
      ).filter((element) => !element.hasAttribute("hidden"))
    }
    
  • 影响:约 180 行样板,抽成 composable 后剩约 50 行,净省 130 行;顺带统一无障碍行为,消除 WorkflowCompareDialog 的 Tab 逃逸。
  • 修复建议:新增 standalone-web/src/composables/useDialogFocusTrap.ts:
    export function useDialogFocusTrap(open: Ref<boolean>, opts: {
      dialogRef: Ref<HTMLElement | null>
      initialFocus?: () => HTMLElement | null | undefined
      onEscape?: () => void
    }) { /* previousFocus / focusables / onKeydown / restore */ return { onKeydown } }
    
    项目已有 safe-backdrop-close.ts 这种单一职责工具模块的先例,放在同级即可。

[P2-中等] SettingsPage.vue 里遗留一整段 1796 字符的 .backup-* 死样式

  • 位置:frontend/standalone-web/src/features/settings/SettingsPage.vue:165(单物理行,1796 字符,格式化后约 45 行)
  • 问题:备份面板早已拆成独立的 features/settings/BackupPage.vue,且该组件用的是自己的 scoped 类名(.page / .hero / .cards / .full / .snapshots / .file / .list)。SettingsPage.vue 的 scoped 样式里却仍保留着旧类名的全套定义,而 SettingsPage.vue 模板里这些类零出现——因为是 scoped,它们绝无可能作用到 BackupPage.vue 上。
  • 代码(SettingsPage.vue:165 开头片段):
    .backup-page{display:grid;gap:15px}.backup-hero{display:flex;align-items:center;gap:13px;border:1px solid var(--border);border-radius:10px;padding:15px;background:linear-gradient(105deg,var(--primary-soft),var(--panel-muted))}.backup-hero>div:last-child{display:grid;gap:4px}.backup-hero p,.backup-grid p{color:var(--text-soft);font-size:12px;line-height:1.5}.backup-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:13px}...
    
    对照 BackupPage.vue 模板实际使用的类:
    <div class="page">
      <section class="hero"><b>↕</b>...</section>
      <div class="cards"><article>...</article></div>
    
  • 影响:约 1.8 KB / 45 逻辑行死样式;SettingsPage.vue:167 的媒体查询里还引用了 .backup-grid / .backup-scope>div,同样死。
  • 修复建议:删除 SettingsPage.vue:165 整行,以及 :167 媒体查询中的 .backup-grid,.backup-scope>div 选择器项。

[P2-中等] App.vue 全局样式里躺着 5 个已抽离组件的样式,其中 691 行属于"隐式全局依赖"

  • 位置:frontend/standalone-web/src/App.vue(样式块);受影响组件 components/AppNavigationRail.vue(整个文件没有 <style>)、components/MaterialCategoryCreateDialog.vue(没有 <style>)、components/MaterialDetailDialog.vue(只有 4 行 <style scoped>)
  • 问题:静态分析发现 31 个类在 App.vue 的全局 <style> 中定义、但只被子组件模板使用。分成两类:
    • 隐式依赖(691 行):AppNavigationRail 的 rail / brand / brand-mark / brand-copy / icon-nav / nav-scroll / nav-group / nav-group-label / nav-group-items / nav-glyph / nav-copy / nav-label / rail-pin / rail-pin-label 共 347 行;MaterialCategoryCreateDialog 的 4 个类共 173 行;MaterialDetailDialog 的 materials-detail-card* 共 171 行。这些组件离开 App.vue 就没有样式。
    • 纯重复(136 行):image-viewer-card/-actions/-stage(104 行,见上一条)、state-card / empty-state-actions / workflow-chat-panel / workflow-composer-panel(32 行),子组件已有等价 scoped 副本。
  • 代码(components/AppNavigationRail.vue 全文 97 行,无 <style> 块;其模板):
    <aside :class="['rail', { pinned, visible }]" ...>
      <div class="brand"><span class="brand-mark">IS</span><div class="brand-copy">...</div></div>
      <nav class="icon-nav">...
    
    样式却在 App.vue 全局块里。
  • 影响:组件不自洽,无法单独测试/复用;App.vue 样式块虚胖 691 行;136 行是纯冗余可直接删。
  • 修复建议:把 347/173/171 三组规则分别剪切进 AppNavigationRail.vue、MaterialCategoryCreateDialog.vue、MaterialDetailDialog.vue 的 <style scoped>(.rail 这类需要父级配合的定位规则用 :deep() 或保留在 workbench.css);136 行重复的直接删。App.vue 样式块净减 827 行。

[P2-中等] 全局重复 CSS 声明块:上限 2251 行,保守可回收 800–1200 行

  • 位置:frontend/standalone-web/src/App.vue(8396 行样式)、features/gallery/GalleryPage.vue(916)、features/profiles/*.vue(1741)、features/workflow/*.vue(1516)等,全前端 CSS 共 14698 行
  • 问题:扫描所有 .vue/.css 的声明块(≥2 条声明),完全相同的声明体重复出现 —— 按 (出现次数-1) × (声明数+2) 计,冗余上限 2251 行。高频样本:
    • overflow:hidden; text-overflow:ellipsis; white-space:nowrap —— 21 次
    • color: var(--text-soft); font-size: 12px; font-weight: 800 —— 21 次(其中 14 次在 App.vue 内且声明完全一致)
    • display: grid; gap: 4px; min-width: 0 —— 18 次
    • height:100%; object-fit:cover; width:100% —— 14 次
    • background: var(--primary); border-color: var(--primary); color: #ffffff —— 10 次
  • 代码(App.vue 内 14 处完全相同的"眼眉标签"规则,各 5 行):
    App.vue:15423  .queue-hero span, .queue-board-panel header span, ...
    App.vue:15659  .queue-detail-panel dt
    App.vue:15810  .materials-hero span, .materials-library-panel header span, ...
    App.vue:16233  .materials-detail-card-preview span, ...
    App.vue:16358  .materials-category-create-card header span, ...
    App.vue:16612  .generate-hero span, .generate-section header span
    App.vue:16712  .image-preview-panel header span, .image-info-card header span, ...
    App.vue:16899  .image-info-card dt
    App.vue:17238  .image-viewer-card header span
    App.vue:19236  .quick-profile-detail-card-portrait span, ...
    App.vue:19427  .quick-profile-viewer-info header span, .quick-profile-viewer-info dt
    App.vue:19925  .quick-profile-profile-field span
    App.vue:20725  .external-profile-import-card > header span, ...
    App.vue:20959  .persona-questionnaire-card header span, ...
    
    每处都是:
    {
      color: var(--text-soft);
      font-size: 12px;
      font-weight: 800;
    }
    
    以及 6 个组件各自重复定义主按钮(GalleryPage.vue:473、AdvancedMaterialImportPage.vue:1791、ProfileDetailPane.vue:614、ProfilesPage.vue:236、ProfileWardrobePane.vue:501、WorkflowMaterialDrawer.vue:528):
    button.primary-button {
      border-color: var(--primary);
      color: #fff;
      background: var(--primary);
    }
    
  • 影响:约 10% 的 CSS 是复读;主色/字号改一次要改 20 处,workbench.css 的存在恰恰证明改不动——它是一层 458 行的"事后覆盖层",专门用超长选择器列表去覆盖 App.vue 的既有规则。
  • 修复建议:
    1. styles/tokens.css(当前仅 24 行)扩成真正的 token/utility 层:.u-truncate、.u-eyebrow、.u-stack-4、.u-cover-img、.u-btn-primary。
    2. App.vue 内那 14 处合并成一条选择器列表规则(70 行 → 20 行)。
    3. 把 workbench.css 的覆盖规则回填进各自的基础规则,删掉这一层(458 行可减到 150 行以内)。
    4. workbench.css:431-451 是同一个媒体查询写了两遍(第二遍只是加了 .navigation-shell 前缀提高优先级),可直接删掉 10 行:
      @media (max-width: 1360px) and (min-width: 901px) {
        .overview-strip { grid-template-columns: minmax(220px, 1.2fr) repeat(3, minmax(120px, 0.8fr)) minmax(200px, 0.9fr); gap: 10px; }
        .overview-strip > * { min-width: 0; }
      }
      @media (max-width: 1360px) and (min-width: 901px) {
        .navigation-shell .overview-strip { grid-template-columns: minmax(220px, 1.2fr) repeat(3, minmax(120px, 0.8fr)) minmax(200px, 0.9fr); gap: 10px; }
        .navigation-shell .overview-strip > * { min-width: 0; }
      }
      

[P2-中等] 25 个 loader 函数复读同一套 loading/error/try/catch/finally 样板

  • 位置:frontend/standalone-web/src/App.vue:4488(loadDashboard)、:4511(loadGalleryImages)、:4611(loadDailyCostUsage)、:4624(loadJobs)、:4638(loadLogs)、:4673(loadModelOptions)、:4700(loadSettingsPage)、:4787(loadMaterials)、:4864(loadBackendQuickProfiles)、:5010(loadProfileWardrobe)、:6872(loadWorkflowBranches)、:6894(loadWorkflowDependencyContext)、:7028(loadWorkflowRounds)、:7115(loadSelectedWorkflowNodeMaterials) 等
  • 问题:App.vue 声明了 10 个 loadingXxx ref + 25 个 xxxError ref + 5 个 xxxBusy ref(:869-892 集中区 + :666-814 分散区),每个 loader 手写同一套开关。全文件 82 处 try {、76 处 catch (err)。
  • 代码(App.vue:4611-4622,与 4488/4624/4700/4787 结构完全一致):
    async function loadDailyCostUsage() {
      loadingDailyCostUsage.value = true
      dailyCostUsageError.value = ""
      try {
        dailyCostUsage.value = await getJson<CostUsageSummary>(endpoints.costUsage, { days: 1 })
      } catch (err) {
        dailyCostUsage.value = null
        dailyCostUsageError.value = `今日用量读取失败:${errorMessage(err)}`
      } finally {
        loadingDailyCostUsage.value = false
      }
    }
    
  • 影响:约 125 行纯样板 + 40 个平行 ref。样板本身还不一致:loadModelOptions(:4673) 忘了 try/finally,直接在末尾赋 loadingModelOptions.value = false,请求抛错时 loading 会永久卡死;loadJobs(:4624) 的 error 清理带条件分支。
  • 修复建议:抽 standalone-web/src/composables/useAsyncResource.ts:
    export function useAsyncResource<T>(loader: () => Promise<T>, opts?: {
      initial?: T; errorPrefix?: string; onError?: (e: unknown) => void
    }) {
      const data = ref(opts?.initial), loading = ref(false), error = ref("")
      async function reload() { loading.value = true; error.value = ""
        try { data.value = await loader() } catch (e) { error.value = `${opts?.errorPrefix ?? ""}${errorMessage(e)}`; opts?.onError?.(e) } finally { loading.value = false } }
      return { data, loading, error, reload }
    }
    
    25 个 loader 各缩到 1–3 行,40 个 ref 缩到 25 个解构,净省约 90–120 行,并顺手修掉 loadModelOptions 的 loading 泄漏。

[P2-中等] pinia 与 vue-router 声明为依赖但整个代码库零引用;构建工具全部错放在 dependencies

  • 位置:frontend/package.json:15-23
  • 问题:
    "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": {}
    
    实测 grep -rn "pinia" --include=*.ts --include=*.vue frontend/{shared,standalone-web,plugin-page,tests} → 0 命中;vue-router 同样 0 命中。两者在 node_modules 里占 1.1 MB(pinia 407 K + vue-router 691 K)。 同时 devDependencies 为空,typescript(23 MB) / vite(2.7 MB) / vue-tsc / @vitejs/plugin-vue 这些纯构建期工具全在 dependencies。插件发布时只带预构建产物(web/、pages/imagestudio/),运行期完全不需要 node_modules,所以严格说 7 个依赖全部应该是 devDependencies。
  • 影响:npm ci --omit=dev 得不到任何东西(无法只装运行期依赖);任何基于 dependencies 的 SCA/许可证扫描会把 23 MB 的 TypeScript 编译器算作运行期依赖;pinia/vue-router 的存在会误导人以为项目有路由和 store,实际上导航是 App.vue 里的 activeNav ref(:5102 setActiveNav)+ navigation-config.ts。
  • 修复建议:
    "dependencies": {},
    "devDependencies": {
      "@vitejs/plugin-vue": "^5.2.0",
      "typescript": "^5.7.0",
      "vite": "^6.0.0",
      "vue": "^3.5.0",
      "vue-tsc": "^2.2.0"
    }
    
    删除 pinia、vue-router,同步更新 package-lock.json。

[P2-中等] App.vue 用 206 个 ref + 135 个 computed 的巨型局部状态树代替 store

  • 位置:frontend/standalone-web/src/App.vue:644-893(集中 ref 区)、:894-4296(computed 区)、:9834-9935(overlay 状态机)
  • 问题:统计 App.vue 顶层符号:206 个 ref、135 个 computed、264 个 function、101 个 async function。整个文件只有 1 条区块注释(:903)。跨模块状态(bootstrap/permissions、素材库、角色档案、工作流轮次、队列)全部平铺在同一个 setup 作用域里,子组件靠 props 逐层透传 + emit 回传。 最典型的症状是 overlay 状态机被写成两条 12 分支的 if 链:
    // App.vue:9846-9894
    function setOverlayOpen(key: ControlledOverlay, open: boolean) {
      if (key === "search") { searchFocused.value = open; searchPanelOpen.value = open }
      if (key === "palette") { showPalette.value = open }
      if (key === "notifications") { showNotificationPanel.value = open }
      if (key === "logs") { showLogPanel.value = open }
      if (key === "imageViewer") { showImageViewer.value = open; if (!open) { imageViewerDragging.value = false } }
      ... // 共 12 个分支
    }
    
    // App.vue:9896-9931
    function isOverlayOpen(key: ControlledOverlay) {
      if (key === "search") { return searchPanelOpen.value }
      ... // 共 11 个分支
      return showLogPanel.value   // ← 兜底返回 logs,新增 overlay 忘了加分支就会静默错判
    }
    
  • 影响:85 行可被 25 行的注册表替代;更重要的是 isOverlayOpen 的 fallback 是 showLogPanel.value,新增一个 ControlledOverlay 而忘记加分支时不报错、行为诡异。整体上 App.vue 的状态树使得任何一个功能改动都要打开 22563 行的文件。
  • 修复建议:
    1. 低成本、立刻可做:overlay 改注册表驱动 ——
      const overlayRegistry: Record<ControlledOverlay, { isOpen(): boolean; setOpen(v: boolean): void }> = {
        search: { isOpen: () => searchPanelOpen.value, setOpen: (v) => { searchFocused.value = v; searchPanelOpen.value = v } },
        ...
      }
      const isOverlayOpen = (k: ControlledOverlay) => overlayRegistry[k].isOpen()
      
      省 40 行并消除 fallback 陷阱。
    2. 中成本:不必上 pinia。按 feature 抽 composable(useWorkflowWorkspace() / useMaterialLibrary() / useQuickProfile() / useQueue()),每个返回自己的 state + actions,App.vue 只负责组装。这条路子和现有 features/*/xxx-state.ts(如 advanced-material-state.ts)的组织方式一致,迁移成本低于引入 store。
    3. 若坚持要 store,pinia 已在 package.json 里但 main.ts(4 行)从未 createPinia(),需要先接入;考虑到本项目是嵌入式插件页、无 SSR、无跨路由状态共享需求,建议走 composable 路线并删掉 pinia。

[P3-轻微] shared/types/workflow.ts 里 35 行类型是 workflow-material.ts 的过期副本

  • 位置:frontend/shared/types/workflow.ts:88-130 与 frontend/shared/types/workflow-material.ts:1-62
  • 问题:WorkflowMaterialNavigationContext 在两个文件里逐字段完全相同地定义了两遍;workflow.ts 的 WorkflowNodeMaterialBindingDetail(:108-123) 与 WorkflowNodeMaterialBindingSaveRequest(:125-130) 是 workflow-material.ts 的 WorkflowNodeMaterialBindingsResult / WorkflowNodeMaterialBindingsSaveRequest 的旧版本。全代码库检索显示 WorkflowNodeMaterialBindingDetail、WorkflowNodeMaterialBindingSaveRequest、WorkflowTemporaryReference 只在 workflow.ts 内部互相引用,无任何外部使用者(App.vue:129 导入的是 workflow-material.ts 那一版)。
  • 代码:
    // shared/types/workflow.ts:88-94
    export interface WorkflowMaterialNavigationContext {
      workflow_id: string
      branch_name: string
      node_id: string
      round_id?: string | null
      return_view: string
    }
    
    // shared/types/workflow-material.ts:1-7  ← 一模一样
    export interface WorkflowMaterialNavigationContext {
      workflow_id: string
      branch_name: string
      node_id: string
      round_id?: string | null
      return_view: string
    }
    
  • 影响:35 行死类型;两份定义如果后端字段变更时只改一份,类型检查会给出互相矛盾的结论。
  • 修复建议:删除 workflow.ts:96-130(WorkflowTemporaryReference + 两个绑定接口);workflow.ts:88-94 改成 export type { WorkflowMaterialNavigationContext } from "./workflow-material"(:82 仍需引用它)。

[P3-轻微] 19 个导出符号无任何使用者

  • 位置:frontend/shared/types/integration.ts:1(整个文件 7 行只有 DailyOutfitResult,零引用)、shared/api/client.ts(patchJson)、shared/types/advanced-material.ts(AdvancedMaterialImportListResult / AdvancedMaterialValidationAttemptListResult / AdvancedMaterialListResult / MaterialCatalogResult / AdvancedMaterialValidationAttemptRequest / AdvancedStyleConsensusRequest)、shared/types/logs.ts(EventStreamResult / LogBundle)、shared/types/storage.ts(StorageStatus / StorageMigrationPlan)、shared/types/ui.ts(UiAction)、shared/types/wardrobe.ts(WardrobeMatchResult)、shared/types/workflow-round.ts(WorkflowRoundNextRequest / WorkflowRoundConfirmRequest)、features/workflow/types.ts(WorkflowRoundKnownStatus)
  • 问题:全量扫描 93 个 .ts/.vue/.mjs 源文件,这 19 个导出的标识符在整个代码库中只出现 1 次(即声明自身)。
  • 代码(shared/types/integration.ts 全文):
    export interface DailyOutfitResult {
      matched: boolean
      selected_materials: Array<Record<string, unknown>>
      final_prompt: string
      job_id?: string | null
      fallback_used: boolean
    }
    
    App.vue:4566-4568 手写了内联的事件流类型而不用 EventStreamResult:
    const stream = await getJson<{
      events: Array<{ event_id?: string; event_type?: string; data?: Record<string, unknown> }>
    }>(endpoints.eventStream, { limit: 20 })
    
  • 影响:约 45 行死类型;EventStreamResult 这种"定义了但调用方手写内联类型"的情况还会导致后端字段变更时类型失去保护作用。
  • 修复建议:删掉 integration.ts(整文件)与其余 18 个;App.vue:4566 改用 getJson<EventStreamResult>(...) 而不是删 EventStreamResult。删除前建议先跑 npm run typecheck 确认(该脚本已存在于 package.json:12)。

[P3-轻微] errorMessage 在两处独立实现且行为不一致

  • 位置:frontend/standalone-web/src/App.vue:11354-11356 与 frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue:1354-1356
  • 问题:
    // App.vue:11354
    function errorMessage(err: unknown) {
      return readableApiError(err)   // 会识别 ApiClientError、区分预览模式、给中文可读文案
    }
    
    // AdvancedMaterialImportPage.vue:1354
    function errorMessage(err: unknown) {
      return err instanceof Error ? err.message || "请求失败" : String(err || "请求失败")
    }
    
    同一个 ApiClientError 在主界面显示"后端未连接,当前为预览模式"之类的可读提示,在进阶素材页只会显示原始 message。AdvancedMaterialImportPage.vue:1350 还独立重实现了 normalizeStatus(shared/utils/presentation.ts:7 已有同名导出)。
  • 影响:行数很小(约 8 行),但错误提示体验不一致,属于"共享工具没被共享"的信号。
  • 修复建议:把 readableApiError / backendWriteBlockMessage(App.vue:4356-4387)下沉到 shared/utils/api-error.ts,两处都导入;AdvancedMaterialImportPage.vue:1350 的 normalizeStatus 改为从 shared/utils/presentation 导入。

[P3-轻微] tsconfig.json 的 @shared/* 路径别名无人使用,且 Vite 侧没有对应 alias

  • 位置:frontend/tsconfig.json:15-17、frontend/plugin-page/vite.config.ts、frontend/standalone-web/vite.config.ts
  • 问题:
    "baseUrl": ".",
    "paths": {
      "@shared/*": ["shared/*"]
    }
    
    全代码库检索 @shared/ → 0 命中。所有引用走的是相对路径,App.vue 里是 "../../shared/api/endpoints",features/settings/BackupPage.vue:3 甚至写到 "../../../../shared/api/client"。而且两个 vite.config.ts 都没有配 resolve.alias,即便有人开始用 @shared/,vue-tsc 能过、vite build 会失败。
  • 代码(BackupPage.vue:3-5):
    import { getJson, postJson } from "../../../../shared/api/client"
    import { endpoints } from "../../../../shared/api/endpoints"
    import type { DiffSettingsResult, ... } from "../../../../shared/types/settings"
    
  • 影响:配置死代码 + 潜在的"类型检查通过但构建失败"陷阱;../../../../ 这种路径也让文件移动变得昂贵。
  • 修复建议:二选一 —— 要么删掉 tsconfig.json 的 paths/baseUrl;要么在两个 vite.config.ts 补上
    resolve: { alias: { "@shared": resolve(rootDir, "../../shared") } }
    
    并把全部 ../../shared / ../../../../shared 批量替换为 @shared(约 60 处 import)。推荐后者。

[P3-轻微] App.vue 内出现压缩风格代码,与文件其余部分格式冲突

  • 位置:frontend/standalone-web/src/App.vue:4549-4559;同样风格见 components/MaterialDetailDialog.vue:34-58、features/settings/BackupPage.vue:14-25、features/settings/ReviewPolicyPanel.vue:14
  • 问题:同一文件里既有 Prettier 风格的展开代码,又有手工压行的代码:
    async function expandImageGenerationPrompt() {
      const prompt=imageGenerationPrompt.value.trim()
      if(!prompt||promptExpansionBusy.value)return
      promptExpansionBusy.value=true
      try{
        const result=await postJson<{selected_prompt?:string;translation?:{translated_text?:string;status?:string;error?:string}}>(endpoints.promptGovernancePreview,{prompt,entrypoint:"web",translation_consent:true,selection:"translated",model_route:selectedImageModelRoute()})
        const expanded=String(result.selected_prompt||result.translation?.translated_text||"").trim()
        if(!expanded||result.translation?.status==="unavailable_fallback"||result.translation?.status==="failed_fallback")throw new Error(result.translation?.error||"未找到可用的提示词扩写模型")
        imageGenerationPrompt.value=expanded
      }catch(err){imageGenerationError.value=`提示词扩写失败:${errorMessage(err)}`}finally{promptExpansionBusy.value=false}
    }
    
    ReviewPolicyPanel.vue:14 更极端:整个 <style scoped> 是一行 1000+ 字符。
  • 影响:行数统计失真(压行让"精简"的账面收益被掩盖)、git diff 一行全红/全绿无法审查、无法用 lint 自动格式化。
  • 修复建议:引入 Prettier(配 printWidth: 110,与现有多数代码一致)并加一个 npm run format:check 到 CI。展开后 CSS/TS 总行数会上升约 800 行,但这是把隐藏的复杂度显性化,后续所有重复检测/删除都会更可靠。

量化汇总

A. 净删除空间(可直接减少的行数)

# 项目 位置 预计削减
1 App.vue 死 CSS 规则(41 条,纯死类构成) App.vue:17323 / 17764-17845 / 19007-19059 / 20075-20101 / 21129-21286 / 21484-21499 / 21662-21703 277
2 .image-viewer-card/-actions/-stage 与子组件 scoped 重复 App.vue:17213-17316 104
3 state-card/empty-state-actions/workflow-chat-panel/workflow-composer-panel 与子组件 scoped 重复 App.vue 样式块 32
4 SettingsPage.vue 遗留 .backup-* 死样式 SettingsPage.vue:165,167 45(1 物理行)
5 workbench.css 重复媒体查询 workbench.css:442-451 10
6 素材选择器弹层模板重复 App.vue:12009-12117 / 12658-12769 100
7 4 份焦点陷阱 → composable ConfirmDialog / ImagePreviewDialog / WorkflowCompareDialog / WorkflowGenerationReviewDialog 130
8 图片缩放/拖拽逻辑重复 → composable App.vue:7952-8011 + 12218-12266 95
9 App.vue 内 14 处相同"眼眉"规则等,选择器列表合并 App.vue(14 处,各 5 行) 50
10 跨组件重复声明块(truncate / cover-img / primary-button / grid-gap 等)→ utility class 全前端 CSS 14698 行 700–1100(上限 2251)
11 25 个 loader 样板 → useAsyncResource App.vue:4488-7185 各 loader 90
12 setOverlayOpen/isOverlayOpen 表驱动 App.vue:9846-9931 40
13 shared/types/workflow.ts 过期类型副本 workflow.ts:96-130 35
14 19 个零引用导出(含 integration.ts 整文件) shared/types/*、shared/api/client.ts 45
15 errorMessage/normalizeStatus 重复实现 App.vue:11354 / AdvancedMaterialImportPage.vue:1350-1356 8
16 tsconfig.json 死别名配置 tsconfig.json:15-17 4
17 pinia + vue-router 依赖(源码 0 行,node_modules 1.1 MB) package.json:17,21 2 行 / 1.1 MB
合计 约 1770–2170 行(取中值 ≈ 1970 行)

占前端源码 40182 行的 4.9%,占 CSS 14698 行的 约 13%。

B. 迁移拆分空间(不减总量,但把 App.vue 从 22563 压到 6000–7000)

目标 当前位置 迁出行数
styles/quick-profile.css App.vue 样式块 quick-profile-* 1268
styles/workflow.css workflow-*(node/profile/persona/prompt/draft/material/subnode/preview/action/group/section/generation) ~1400
styles/materials.css materials-* ~600
styles/image-workspace.css image-* (composer/preview/info/stage) ~400
剪进 AppNavigationRail.vue App.vue 的 rail/brand/nav-* 规则 347
剪进 MaterialCategoryCreateDialog.vue / MaterialDetailDialog.vue App.vue 的对应规则 344
features/workflow/WorkflowStages.vue(×6 stage 子组件) App.vue:12440-12772、12842-12988 ~530
features/quick-profile/QuickProfileWorkspace.vue App.vue:11809-12268 ~460
features/image/ImageGenerateWorkspace.vue App.vue:11648-11807 ~160
features/quick-profile/ExternalProfileImportDialog.vue App.vue:12988-13075 ~88
features/quick-profile/PersonaQuestionnaireDialog.vue App.vue:13077-13329 ~252
features/workflow/workflow-action-cards.ts App.vue:2782-3222(441 行)+ 标签表 3223-3282 ~500
features/*/action-cards.ts(generate/queue/material/quickProfile) App.vue:3751-3921、3370-3512、1346-1458、1931-2041 ~580
features/quick-profile/quick-character-generation.ts App.vue:5786-6077 292
合计迁出 ≈ 7200 行

拆分后 App.vue 预计:脚本 ~3500 行 + 模板 ~350 行 + 样式 <300 行 ≈ 4200 行。

C. 无精简空间的项(已核实)

  • plugin-page vs standalone-web 重复:0 行。plugin-page/src/App.vue 仅 7 行(import WorkbenchApp from "../../standalone-web/src/App.vue"),plugin-page/src/main.ts 6 行,两个 vite.config.ts 各 16 行且只有 base/outDir 不同。这套双构建方案已经是最优解,不要动。
  • 未被引用的组件:无。standalone-web/src/components/ 与 features/ 下 25 个 .vue 全部有引用者(WorkflowCompareDialog 等 7 个走 defineAsyncComponent,App.vue:39-45)。
  • 仓库卫生:frontend/node_modules、frontend/.pytest_cache 均未被 git 跟踪(git ls-files 0 命中),无需清理。

D. 建议执行顺序(按 收益/风险 比)

  1. 零风险,立刻做(约 550 行):#4 SettingsPage.vue:165、#5 workbench.css:442-451、#13 workflow.ts:96-130、#14 19 个死导出、#16 tsconfig 别名、#17 删 pinia/vue-router + 依赖分类。跑 npm run typecheck + npm run test:contracts 验证。
  2. 低风险,需视觉回归(约 460 行):#1/#2/#3 死 CSS 删除。建议先加 tests/dead-css.test.mjs 把规则固化,再删。
  3. 中风险,需功能验证(约 465 行):#6 素材选择器组件化、#7 focus trap composable、#8 图片查看器复用。这三项都触及交互,建议逐项 PR。
  4. 大工程(#10 CSS utility 层 + B 表全部迁移):建议先做 #10 的 token/utility 层(它是所有后续 CSS 迁移的前置),再按 feature 逐个迁样式和模板。