# 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 问号,中文字符在某次保存/转码中被替换成了 `?`。这不是注释也不是占位常量,而是直接返回给模板的显示文本。
- **代码**:
```ts
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 行):
```html
{{ styleValidationReviewTrust(validationCase) }}
```
- **影响**:只要画风验证轮返回了 `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` 无条件复制进问卷。
- **代码**:
```ts
// 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 }
}
```
```ts
// App.vue:9721 —— 未按 recognized 过滤,整体复制
personality: draft.personality,
appearance: draft.appearance,
outfit: draft.outfit,
scene: draft.scene,
```
```ts
// 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` 只作用于返回值和审计快照,不作用于写入磁盘的内容。
- **代码**:
```ts
// 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(endpoints.settingsValidate, { config })
const saved = await postJson(endpoints.settingsSave, { config }) // ← 落盘
```
```html
```
另外 `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) 修正承诺:把 `` 文案改成「保存后会写入插件配置文件」,并在按钮上加二次确认。无论哪种,`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` 不在扫描范围内,因此这批示例数据从防线的缝隙里漏了过去。
- **代码**:
```ts
export function createDefaultQuickProfileQuestionnaire(): QuickProfileQuestionnaire {
return {
roleCore: "近未来港区巡查员,负责夜间巡逻和异常记录。",
genderPresentation: "female",
distinctiveFeatures: "发光臂章,青绿色眼睛",
personality: "冷静、可靠、行动快,外冷内热。",
appearance: "黑色短发,青绿色眼睛,轻机能外套。",
outfit: "短靴、发光臂章、便携通讯设备。",
scene: "星港、雨夜街区、巡查终端、航灯背景。",
...
```
```ts
// App.vue:759
const quickProfileQuestionnaire = ref(createDefaultQuickProfileQuestionnaire())
```
```js
// 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` 内部(`