astrbot_plugin_imagestudio/审计/findings/B1-前后端耦合.md

712 行
54 KiB
Markdown

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

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

# B1 · 前后端耦合
> 审计范围(实际读过的文件):
>
> **后端**:`main.py`、`backend/route_registry.py`、`backend/services/contract_service.py`、`backend/services/ui_service.py`、`backend/services/web_hosting_service.py`、`backend/services/workflow_progression_service.py`、`backend/services/workflow_round_service.py`、`backend/services/queue_service.py`、`backend/services/generation_service.py`、`backend/services/node_injection_template_service.py`、`backend/services/event_stream_service.py`、`backend/services/image_service.py`、`backend/services/advanced_style_set_service.py`、`backend/routes/{contract,api_discovery,node,node_material,round,profile,image,advanced_material,event,job}_routes.py`、`backend/dto/{common,workflow,workflow_round,profile,job,image,advanced_material}_dto.py`、`core/model_route_chain.py`、`core/config_service.py`、`core/security.py`、`core/event_bus.py`、`engines/character_flow.py`、`database/repositories/profile_repository.py`、`adapters/astrbot_adapter.py`
>
> **前端**:`frontend/shared/api/{endpoints,client,astrbot-page-bridge}.ts`、`frontend/shared/config/timeouts.ts`、`frontend/shared/utils/{presentation,storage-uri}.ts`、`frontend/shared/types/{api,bootstrap,profile,workflow,workflow-round,job,image,advanced-material}.ts`、`frontend/standalone-web/src/App.vue`、`frontend/standalone-web/src/features/workflow/{workflow-lock-state,workflow-model-route,workflow-node-catalog}.ts`、`frontend/standalone-web/src/features/workflow/WorkflowCandidatePool.vue`、`frontend/standalone-web/src/features/materials/advanced-material-state.ts`、`frontend/standalone-web/src/features/settings/{SystemManagementPanel.vue,model-route-chain.ts}`、`frontend/{plugin-page,standalone-web}/vite.config.ts`、`frontend/package.json`、`frontend/tests/*.test.mjs`
>
> **已按要求忽略**:`.tmp/`、`.tmp_pytest_*`、`release/`、`node_modules/`、`__pycache__/`、`web/assets/`、`pages/imagestudio/assets/`(仅在"构建产物入库"一节中作为 git 事实引用,未读其内容)
## 摘要
**URL 层面的耦合治理是这个仓库做得最好的部分**:`backend/route_registry.py` 是 166 条路由的唯一真相来源(`adapters/astrbot_adapter.py:44` 的 `resolve_route` 直接消费它),前端 143 个端点全部集中在 `frontend/shared/api/endpoints.ts`,逐条比对后**零个前端调用会 404**,也**几乎没有绕过 endpoints.ts 的硬编码 URL**(表 ③ 只有 vite base 一条)。这一维度可以给高分。
**问题全部集中在"语义契约"层**:URL 对上了,但 URL 背后的规则没对上。前端在 `App.vue`、`workflow-lock-state.ts`、`workflow-model-route.ts` 里重新实现了后端的顺序进度状态机、节点写锁规则、模型路由解析链、队列状态枚举和 retry 权限矩阵——每一处都与后端存在可举证的不一致(`sealed_at` 后端根本不产出;节点写锁少判两个条件;快速角色流的路由优先级后端是反的;retry 按钮漏判 `can_write`)。后端明明有 `character_gradual_progression().to_dict()`、`PERMISSION_MATRIX`、`ContractService` 这些"可下发的真相",却没有一条路由把它们送到前端,前端只能靠复刻。
`GET contract` 已提供完整的路由 + 权限 + 错误码自检数据,但前端唯一的消费点是 `SystemManagementPanel.vue:8` 的一个 JSON dump 诊断框,**没有任何自动化测试拿它做契约校验**——而这恰恰是最低成本、最高收益的修复方向(我实测 166 条路由的 handler 全部可导入,做成 CI 断言只需十几行)。
另外,`web/` 与 `pages/imagestudio/` 两份 1.1MB 的 vite dist 产物被提交进 git,80 次提交里每次改一行 UI 源码都会带上一批内容哈希文件名的增删,这是耦合与仓库卫生的双重问题。
---
## 一、路由比对三张表
### 表 ① 后端注册但前端从不调用(死接口)
比对方法:从 `backend/route_registry.py:55-342` 提取 166 条 `RouteSpec`,与 `endpoints.ts` 143 个键 + 全前端 `endpoints.<key>` 引用做交叉。
| # | 方法 | 端点 | handler | 判定 |
|---|---|---|---|---|
| 1 | DELETE | `profiles/{profile_id}` | `profile_routes.delete_profile` | 死。UI「删除角色」实际调 `profileArchive`(`App.vue:6300`) |
| 2 | POST | `profiles/{profile_id}/delete` | `profile_routes.delete_profile_via_post` | 死。`endpoints.profileDelete` 零引用 |
| 3 | POST | `images/{image_id}/moderation-review` | `image_routes.review_moderated_image` | 死。见 P1-6 |
| 4 | POST | `advanced-material-imports/{import_id}/cancel` | `advanced_material_routes.cancel_advanced_material_import` | 死。endpoints.ts 里连键都没有 |
| 5 | POST | `nodes/{node_id}/mark-completed` | `node_routes.mark_node_completed` | 死。是 `nodes/{id}/complete` 的同 handler 别名 |
| 6 | POST | `nodes/{node_id}/select-image` | `node_routes.select_node_image` | 死。前端只用 `images/{id}/select` |
| 7 | POST | `prompts/expand` | `prompt_routes.expand_prompt` | 死。前端只用 `prompts/governance-preview` |
| 8 | GET | `profile-cards/{card_id}` | `profile_card_routes.get_profile_card` | 死 |
| 9 | DELETE | `profiles/{profile_id}/wardrobe/{wardrobe_item_id}` | `wardrobe_routes.delete_wardrobe_item` | 死。legacy 别名,前端只用 `/wardrobe/items/{id}` |
| 10 | GET | `materials/analytics` | `material_routes.material_analytics` | 死 |
| 11 | POST | `materials/renormalize-batch` | `material_routes.renormalize_materials_batch` | 死 |
| 12 | POST | `materials/{material_id}/renormalize` | `material_routes.renormalize_material` | 死 |
| 13 | GET | `integrations/logs` | `integration_routes.list_integration_logs` | 死。前端只用 `logs/integrations` |
| 14 | POST | `api-discovery/probe-model` | `api_discovery_routes.probe_model` | 死。前端只用 `probe-provider` |
> 说明:`GET media/fetch` 虽不在 endpoints.ts 中,但通过 `MediaService.sign_media()` 返回的签名 URL 被间接消费(`round_routes.py:196`、`image_routes.py:229`),**不算死接口**。
其中 #1/#2 与 `POST profiles/{id}/archive` 三条路由指向同一个函数体:
```python
# backend/routes/profile_routes.py:101-114
def delete_profile_via_post(ctx, profile_id, payload=None, service=None) -> dict:
return delete_profile(ctx, profile_id, service)
def archive_profile(ctx, profile_id, service=None) -> dict:
return delete_profile(ctx, profile_id, service)
```
### 表 ② 前端调用但后端不存在(会 404)
**空表。** 143 个 endpoints.ts 路径模板逐条与 `route_registry.ROUTES` 比对,全部命中,无一遗漏。这是本次审计中最值得肯定的一点。
### 表 ③ 前端绕过 endpoints.ts 硬编码 URL
| 位置 | 内容 | 判定 |
|---|---|---|
| `frontend/standalone-web/vite.config.ts:11` | `base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/"` | 真实重复,见 P2-13 |
| `frontend/shared/api/astrbot-page-bridge.ts:119-120` | `request<T>("api:get" ...)` | 误报,是 postMessage 的 kind 常量,不是 HTTP 路径 |
除此之外全前端**没有任何**业务组件直接拼 API 路径:所有 `getJson/postJson/putJson/deleteJson` 的第一参数都来自 `endpoints.*`,`buildUrl` 是唯一的 URL 构造点(`client.ts:297-306`)。
---
## 发现
### [P1-严重] 前端复刻了后端的顺序进度状态机,且后端从不下发权威结果
- **位置**:`frontend/standalone-web/src/App.vue:10836-10861`,对应后端 `backend/services/workflow_progression_service.py:175-199`
- **问题**:后端 `is_character_gradual_node_completed()` 是"节点是否已完成"的唯一权威判定,包含 status 白名单、node_type 特例、profile_card 别名归一、legacy 元数据兼容四层规则。前端逐条重写了这四层,连"legacy 兼容只对没有 sequential-v1 标记的工作流生效"这种极细的分支都手工复刻,并把版本号字面量抄进了 `App.vue:927`。
- **代码**:
后端:
```python
# backend/services/workflow_progression_service.py:180-199
if node.status in PROGRESSION_COMPLETED_NODE_STATUSES: # {"selected","skipped"}
return True
if node.status == "completed" and (
node.node_type in {"planning", "reference_binding"}
or canonical_gradual_node_key(node.node_key) == "profile_card"
):
return True
if allow_legacy_planning_metadata:
if node.node_key == "prompt_plan":
return "prompt_plan" in metadata and metadata.get("prompt_plan") is not None
if node.node_key == "material_bind":
return "material_bindings" in metadata and metadata.get("material_bindings") is not None
return False
```
前端(同一套规则,第二份实现):
```ts
// frontend/standalone-web/src/App.vue:10843-10859
const status = normalizeStatus(backendNode.status)
if (status === "selected" || status === "skipped") return true
if (status === "completed" && (backendNode.node_type === "planning" ||
backendNode.node_type === "reference_binding" ||
canonicalCharacterWorkflowNodeKey(backendNode.node_key) === "profile_card")) return true
const execution = selectedCharacterWorkflow.value?.metadata?.character_execution
const legacyProgression =
isRecord(execution) && execution.progression_version !== CHARACTER_WORKFLOW_PROGRESSION_VERSION
if (!legacyProgression) return false
if (backendNode.node_key === "prompt_plan") return backendNode.metadata?.prompt_plan != null
if (backendNode.node_key === "material_bind") return backendNode.metadata?.material_bindings != null
```
```ts
// frontend/standalone-web/src/App.vue:927
const CHARACTER_WORKFLOW_PROGRESSION_VERSION = "character_gradual_sequential_v1"
```
根因是后端从不下发进度:
```python
# backend/routes/node_routes.py:52-63 —— 只返回裸节点数组,无 progression
def action() -> list[dict[str, Any]]:
require_authenticated(ctx)
return [node.to_dict() for node in workflow_service.list_nodes(workflow_id)]
```
全仓库 `progression.to_dict()` 只有一个调用点:`backend/services/character_workflow_service.py:339`(`execute-character` 的响应体),列表接口拿不到。
- **影响**:后端改一条进度规则(例如给 `style_lock` 加一个完成条件、或让 `skipped` 不再算完成),前端不会报错也不会失效,只会静默地在"下一步应该点哪个节点"上给出与服务端相反的答案:UI 显示节点可用 → 用户点击 → 后端 `ensure_character_gradual_node_access` 抛 `character_gradual_progression_locked`。反之 UI 灰掉一个后端允许的节点,用户彻底卡死且无提示。前端还有一份 `execution.progression_version` 的降级分支,等于把后端的向后兼容策略也复制了一份,双份都要维护。
- **修复建议**:
1. 在 `list_workflow_nodes` 返回体外层加 `progression` 字段(`CharacterGradualProgression.to_dict()` 已经现成,含 `current_node_id`/`completed_node_ids`/`all_completed`/`import_confirmed`):
```python
def action() -> dict[str, Any]:
require_authenticated(ctx)
nodes = workflow_service.list_nodes(workflow_id)
workflow = workflow_service.get_workflow(workflow_id)
progression = character_gradual_progression(workflow, nodes)
return {
"items": [n.to_dict() for n in nodes],
"progression": progression.to_dict() if progression else None,
}
```
(返回结构变更需同步 `frontend/shared/types/workflow.ts` 并升 `contract_version`)
2. 删除 `App.vue:10836-10861` 与 `App.vue:927`,改为 `progression.completed_node_ids.includes(node.node_id)` / `node.node_id === progression.current_node_id`。
---
### [P1-严重] 节点写锁规则前后端不一致,且前端判据里有一个后端从不产出的字段
- **位置**:`frontend/standalone-web/src/features/workflow/workflow-lock-state.ts:4-27`,对应后端 `backend/services/workflow_round_service.py:1145-1155`
- **问题**:两条独立的"这个节点还能不能写"规则,条件集合不同;前端多判了一个不存在的字段,少判了两个真实条件。
- **代码**:
前端:
```ts
// frontend/standalone-web/src/features/workflow/workflow-lock-state.ts:8-27
export function isWorkflowSealed(workflowStatus, metadata) {
const status = normalizedStatus(workflowStatus)
return (
status === "archived" || status === "cancelled" ||
Boolean(metadata?.final_archive_history_id || metadata?.sealed_at) // ← sealed_at
)
}
export function isWorkflowNodeWriteLocked(nodeStatus, workflowStatus, workflowMetadata) {
return normalizedStatus(nodeStatus) === "selected" || isWorkflowSealed(workflowStatus, workflowMetadata)
}
```
后端:
```python
# backend/services/workflow_round_service.py:1145-1155
if node.status == "selected" or node.selected_image_id or (
progression is not None and node.node_id in progression.completed_node_ids
):
raise ApiError(ErrorCode.VALIDATION_FAILED,
"confirmed workflow node is locked; create a branch before adding another round",
{"node_id": node.node_id, "required_action": "create_branch"})
```
`sealed_at` 在整个 Python 源码树(`main.py`/`backend/`/`core/`/`database/`/`engines/`/`adapters/`)**零匹配**——`grep -rn "sealed_at" --include=*.py` 返回空。它只存在于前端和前端测试里。
- **影响**:三处真实分歧。
1. `node.selected_image_id` 已设但 `status != "selected"` 时(例如 `adopt-image` 后 status 仍为 `completed`),前端认为可写并放行"再跑一轮",后端返回 `VALIDATION_FAILED / required_action: create_branch`,用户看到一个无法自恢复的报错。
2. 节点已进入 `progression.completed_node_ids`(通过 `skipped` 或 planning 节点 `completed`)时同理。
3. `metadata.sealed_at` 是一个永远为 `undefined` 的死判据,给读代码的人制造"存在这个封存机制"的错觉。而 `frontend/tests/workflow-model-route.test.mjs` 只断言 `final_archive_history_id` 分支,`sealed_at` 连测试都没覆盖。
- **修复建议**:把锁状态改为服务端下发而非客户端推导。最小改动是在 `WorkflowNode.to_dict()` 增加 `writable: bool` 与 `lock_reason: str | None`(`backend/services/workflow_node_material_service` 返回的 `WorkflowNodeMaterialBindingDetail` 已经有 `writable` + `lock` 结构,直接复用同一形状即可,见 `frontend/shared/types/workflow.ts:108-123`);前端 `workflow-lock-state.ts` 退化为读 `node.writable`。若暂不改协议,至少立刻删掉 `sealed_at`,并补上 `selected_image_id` 判据。
---
### [P1-严重] 模型路由解析链在前端重实现,优先级与后端不一致(快速角色流方向相反)
- **位置**:`frontend/standalone-web/src/features/workflow/workflow-model-route.ts:33-88` + `App.vue:2211-2245`,对应后端 `backend/services/generation_service.py:167-176`、`605-643`、`2022-2044`
- **问题**:前端为了显示"当前生效模型 / 来源标签",把后端的整条路由回退链复刻了一遍——包括 `node_key → model_assignments` 键的映射表——并且直接读取原始配置文件结构 `config.model_assignments` / `config.generation.default_model`。三处不一致。
- **代码**:
后端普通节点(`generation_service.py:169-176`):
```python
requested_model_route = str(
payload.get("model_route") or node.model_route or assigned_route
or profile_model_route or self.default_model_route or "image_low")
```
后端**快速角色**节点(`generation_service.py:617-624`)—— 优先级反转,`assigned_route` 抢在 `payload.model_route` 之前:
```python
if quick_character:
route_candidate = str(
assigned_route or payload.get("model_route")
or profile_model_route or self.default_model_route or "image_low")
```
前端(唯一一条链,多了 `round` 层,少了 `"image_low"` 兜底,没有 quick_character 分支):
```ts
// frontend/standalone-web/src/features/workflow/workflow-model-route.ts:36-48
const candidates: Array<[WorkflowModelRouteSource, unknown]> = [
["override", input.overrideRoute], ["round", input.roundRoute],
["node", input.nodeRoute], ["assignment", input.assignmentRoute],
["profile", input.profileRoute], ["system", input.systemRoute],
]
for (const [source, value] of candidates) {
const route = normalizeWorkflowModelRoute(value)
if (route) return { route, source, explicitOverride: source === "override" }
}
return { route: "", source: "backend", explicitOverride: false }
```
前端自带的第二份 `node_key → assignment` 映射(`workflow-model-route.ts:61-84`)与后端 `generation_service.py:2026-2038` 也不同步:后端有 `quick_avatar/quick_bust/quick_stand/quick_sheet → "quick_generation"`、`questionnaire`、`preview`,前端一个都没有;前端多了 `portrait/avatar/standing/three_view/character_sheet/halfbody/fullbody` 七个后端不认识的别名。
- **影响**:
1. **快速角色流的模型标签会直接说谎**:用户设了本次覆盖,UI 显示"本次覆盖 → route-X",后端实际按 `assigned_route` 出图。
2. 对 `quick_*` 节点,`workflowModelAssignmentKey("quick_avatar","generation")` 返回 `"quick_avatar"`(fallback 到 `canonical`),去 `model_assignments` 里查不到,UI 显示"角色默认/系统默认",后端实际用 `quick_generation` 分配的路由。
3. 前端读取的是**配置文件的原始结构**(`currentSettings.value.config.model_assignments`、`config.generation.default_model`,`App.vue:2218/2231-2233`),后端换个配置键名前端就静默失准。
- **修复建议**:新增 `GET nodes/{node_id}/effective-model-route`,或在 `nodeDependencyContext` 响应里加 `{ effective_model_route, source }`,由 `generation_service` 抽出一个纯函数 `resolve_model_route(node, workflow, profile, assignments, default)` 同时供生成路径与该端点调用。前端 `resolveWorkflowModelRoute` 只保留"用户 override 是否非空"的判断,其余全部读服务端字段。同时删除 `workflow-model-route.ts:61-84` 的别名/分配表。
---
### [P1-严重] retry 类操作的前端权限门禁漏判 `can_write`,而后端要求两个权限
- **位置**:`frontend/standalone-web/src/App.vue:2786` + `3076` + `3139`,对应 `backend/route_registry.py:22-27` 与 `core/security.py:31-33`
- **问题**:`route_registry` 已经把 retry 定义为**复合权限**并通过 `GET contract` 对外发布,前端却只判了其中一个。
- **代码**:
后端权限矩阵(`backend/route_registry.py:22-27`):
```python
"retry": {
"auth_required": True,
"required_permission": "can_retry_tasks",
"required_permissions": ["can_write", "can_retry_tasks"],
"description": "task retry management (write + retry capabilities)",
},
```
```python
# core/security.py:31-33
def require_task_retry(ctx: RequestContext) -> None:
require_write(ctx) # ← 先判 can_write
require_permission(ctx, "can_retry_tasks")
```
前端节点重试按钮(`App.vue:2786`、`3073-3077`):
```ts
const canRetry = Boolean(permissions?.can_retry_tasks)
...
state: canRetry ? "可重试" : "无权限",
tone: canRetry ? "warn" : "neutral",
enabled: Boolean(canRetry && !selectedNodeWriteLocked && !workflowNodeActionExecuting.value),
```
同文件 `3373` 处的队列面板反而判对了(`const canManageQueue = canWrite && canRetry`),说明这是遗漏而非有意设计。
- **影响**:持有 `can_retry_tasks` 但无 `can_write` 的账号,在工作流面板看到"可重试"的可用按钮(`portrait-retry` 卡片与 `3139` 处的同类卡片),点击后 `nodes/{id}/retry` 与 `nodes/{id}/generate` 一律被 `require_write` 拒为 `FORBIDDEN`。同一份权限模型在同一个文件里出现两种实现,说明这类漏判还会再犯。
- **修复建议**:不要在前端逐个手写权限组合。`GET contract` 返回的 `routes[].required_permissions` 已经是完整数组,在 bootstrap 之后拉一次 contract,构造 `canCall(endpointKey)` 工具函数,所有按钮的 `enabled` 统一走它:
```ts
const contractRoutes = new Map(contract.routes.map(r => [`${r.method} ${r.endpoint}`, r.required_permissions]))
function canCall(method: string, endpoint: string) {
return (contractRoutes.get(`${method} ${endpoint}`) ?? []).every(p => permissions?.[p])
}
```
---
### [P1-严重] 编译产物 `web/` 与 `pages/imagestudio/` 被提交进 git,且是两份重复的 dist
- **位置**:`frontend/standalone-web/vite.config.ts:12-15`、`frontend/plugin-page/vite.config.ts:12-15`、`backend/services/web_hosting_service.py:14-17`、`.gitignore`
- **问题**:两个 vite 构建把产物直接写进受版本控制的目录,且 `emptyOutDir: true`,每次构建都会整批删除并重建内容哈希文件名。`.gitignore` 忽略了 `frontend/**/dist/`,却没有忽略这两个实际的输出目录。
- **代码**:
```ts
// frontend/standalone-web/vite.config.ts:9-15
base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/",
build: { outDir: resolve(rootDir, "../../web"), emptyOutDir: true },
```
```ts
// frontend/plugin-page/vite.config.ts:11-15
base: "./",
build: { outDir: resolve(rootDir, "../../pages/imagestudio"), emptyOutDir: true },
```
```python
# backend/services/web_hosting_service.py:14-15
PLUGIN_PAGE_DIR = REPO_ROOT / "pages" / "imagestudio"
STANDALONE_WEB_DIR = REPO_ROOT / "web"
```
两份 dist 内容同源——`frontend/plugin-page/src/App.vue` 全文只有:
```vue
<script setup lang="ts">
import WorkbenchApp from "../../standalone-web/src/App.vue"
</script>
<template><WorkbenchApp /></template>
```
git 事实:`git ls-files web/ pages/` = 38 个文件,`du -sh` 各 1.1MB;`git log --oneline -- web/assets | wc -l` = **80 次提交**;最近 15 次改 `frontend/standalone-web/src/App.vue` 的提交**每一次**都同时改了 `web/assets` 与 `pages/imagestudio/assets`。
- **影响**:
1. **每个 UI 改动的 diff 被 2MB 二进制级噪音淹没**,code review 无法看清真实变更;`git status` 首屏就是二十多行 `D web/assets/...`。
2. **产物与源码可能不同步**:目前没有任何 CI 校验 `web/` 是当前 `frontend/` 的构建结果。一个只改源码忘记 build 的提交,会让线上跑的仍是旧 JS,而 `WebHostingService.manifest()` 只检查 `index.html` 是否存在(`web_hosting_service.py:33/38`),报告 `built: true`,无法发现版本错位。
3. 内容哈希文件名 + `emptyOutDir` 让每次构建产生全新路径,git 历史里累积了大量永不复用的 blob,仓库体积单向膨胀。
4. 两份 dist 意味着**任何 UI 修复都必须记得跑两次构建**,漏一次就出现"插件页正常、独立页是旧版"的诡异现象——git 历史里 `fix: recover material library after stale asset token`、`fix: load material library page without expiring asset chunk` 两条修复正是这一类症状。
- **修复建议**:
1. `.gitignore` 增加 `/web/` 与 `/pages/imagestudio/`(保留 `.gitkeep`),`git rm -r --cached web pages/imagestudio`。
2. 发布流程改为 CI 构建 + 打包进 release artifact;仓库只保留源码。若插件分发形态要求产物随包,则用一次性的 release 分支/tag 承载,不进主干历史。
3. 若因 AstrBot 插件安装方式**必须**保留产物在主干,则退而求其次:加一条 CI 检查 `npm run build && git diff --exit-code web pages`,保证产物永远与源码一致;并把两个 vite 配置合并为一次构建两个 base(或让 plugin-page 直接复用 standalone 产物),消除"两份 dist"。
4. `WebHostingService.manifest()` 增加一个来自构建时注入的 `build_hash`,与 `metadata.yaml` 版本比对,让版本错位可被观测。
---
### [P1-严重] `events/stream` 无游标:后端把 SSE 载荷塞进 JSON,前端 5 秒轮询 20 条,事件会静默丢失
- **位置**:`backend/services/event_stream_service.py:22-32`、`backend/routes/event_routes.py:22-28`、`frontend/standalone-web/src/App.vue:4561-4608`
- **问题**:后端把事件流做成"返回最近 N 条 + 一段预渲染 SSE 文本"的普通 JSON 接口,没有 `after_event_id` / `since` 参数;前端只能轮询固定窗口,靠在返回数组里查找上次的 `event_id` 来切出增量。窗口一旦被冲掉,增量计算就退化。
- **代码**:
后端(无游标,且 `body`/`content_type` 是给 SSE 用的但走的是 JSON 通道):
```python
# backend/services/event_stream_service.py:22-32
def recent_events(self, *, event_type: str | None = None, limit: int = 50) -> dict[str, Any]:
events = self.event_bus.history(event_type)
selected = events[-_limit(limit):]
webhook_events = [_event_to_webhook(event) for event in selected]
return {
"content_type": "text/event-stream",
"events": [event.to_dict() for event in webhook_events],
"body": "".join(to_sse(event) for event in webhook_events),
"count": len(webhook_events),
}
```
前端:
```ts
// frontend/standalone-web/src/App.vue:4566-4577, 4608
const stream = await getJson<{ events: Array<{ event_id?: string; ... }> }>(
endpoints.eventStream, { limit: 20 })
const newest = stream.events.at(-1)?.event_id ?? ""
if (!newest || newest === lastEventStreamId) return
const previousIndex = hadPrevious
? stream.events.findIndex((event) => event.event_id === lastEventStreamId) : -1
const freshEvents = hadPrevious
? stream.events.slice(previousIndex >= 0 ? previousIndex + 1 : -1) // ← 找不到时只取最后 1 条
: []
...
eventStreamTimer = window.setInterval(poll, 5000)
```
- **影响**:一轮 4~8 张候选图的生成会在几秒内产生远超 20 条 `generation.*` / `workflow.*` 事件。此时 `findIndex` 返回 `-1`,`slice(-1)` 只留下**最后一条**事件,`eventTypes` 只有一个元素,于是 `generationChanged` / `workflowChanged` 的判定基于 1/20 的样本——`loadJobs()` / `loadDashboard()` / `loadWorkflowRoundDetail()` 该刷的不刷,UI 停在旧状态直到用户手动刷新。这正是"生成完了界面不动"类问题的结构性来源。同时 `body` 与 `content_type` 两个字段每次都白白序列化传输且被前端丢弃。
- **修复建议**:
1. `EventStreamService.recent_events` 增加 `after_event_id: str | None`,在 `_history` 中定位后返回其后全部事件(配合 `limit` 上限 200),并返回 `truncated: bool` 告知客户端是否发生了窗口溢出。
2. 前端改传 `{ after_event_id: lastEventStreamId, limit: 200 }`;收到 `truncated: true` 时退化为一次全量刷新(`loadJobs + loadDashboard + 当前视图`),而不是静默少刷。
3. `content_type` / `body` 两个字段要么删掉(JSON 通道用不上),要么单独开一条真正的 SSE 路由;现在这样两边都不是。
---
### [P2-中等] 队列状态枚举在前后端共 4 处独立硬编码
- **位置**:`backend/services/queue_service.py:31-34` vs `frontend/standalone-web/src/App.vue:3285`、`3293`、`frontend/shared/utils/presentation.ts:5`
- **问题**:后端已经把任务状态分类抽成了具名常量,前端把这些集合的字面量抄了三份,还多出一个后端没有的分类。
- **代码**:
后端唯一真相:
```python
# backend/services/queue_service.py:31-34
RETRYABLE_TASK_STATUSES = {"failed", "dead_letter", "cancelled"}
FAILED_TASK_STATUSES = ("failed", "dead_letter", "cancelled")
COMPLETED_TASK_STATUSES = ("completed", "succeeded", "superseded")
DELETABLE_TASK_STATUSES = frozenset((*FAILED_TASK_STATUSES, *COMPLETED_TASK_STATUSES))
```
前端三份拷贝:
```ts
// App.vue:3284-3286
const failedJobs = computed(() =>
queueItems.value.filter((job) => ["failed", "dead_letter", "cancelled"].includes(normalizeStatus(job.status))))
// App.vue:3292-3295
const completedQueueJobs = computed(() =>
queueItems.value.filter((job) => ["completed", "succeeded", "superseded"].includes(normalizeStatus(job.status))))
const terminalQueueJobs = computed(() => [...failedJobs.value, ...completedQueueJobs.value])
```
```ts
// frontend/shared/utils/presentation.ts:5 —— 第四份,且集合与后端任何一个常量都不完全相等
const TERMINAL_JOB_STATUSES = new Set(["completed", "succeeded", "failed", "cancelled", "dead_letter", "superseded"])
```
另有 `App.vue:3628` 第五次内联同一个 `["failed","dead_letter","cancelled"]`。
- **影响**:`TASK_STATUSES`(`queue_service.py:18-29`)新增一个终态(例如 `expired`)时,后端会正确把它算进 `DELETABLE`,而前端四处判定全部漏掉:任务永远停在"运行中"分组、`waitTime()` 里 `terminal` 为 false 导致耗时读数无限增长、"清理终态任务"按钮的 `enabled` 计数与后端实际清理数量对不上。
- **修复建议**:把这四个集合加进 `GET ui/bootstrap` 的返回体(`UiService.get_bootstrap` 已经在下发 `permissions` 和 `feature_flags`,加 `task_statuses: {retryable, failed, completed, terminal}` 是同一性质的元数据),前端建一个 `taskStatusSets.ts` 从 bootstrap 初始化;或退一步,至少把四份合并成 `frontend/shared/config/task-status.ts` 一份,并加一条像 `task-timeout-consistency.test.mjs` 那样的正则测试断言它与 `queue_service.py` 的字面量一致。
---
### [P2-中等] `images/{id}/moderation-review` + `include_restricted` 是一条完整但前端零对接的功能链
- **位置**:`backend/routes/image_routes.py:41-49`、`68-73`、`90-91`、`145-160`;前端零引用
- **问题**:后端为"内容审核隔离图片"实现了完整闭环——列表过滤、管理员可见开关、隐藏计数、管理员复核端点——前端一个都没接。
- **代码**:
```python
# backend/routes/image_routes.py:41-49
include_restricted = as_bool(params.get("include_restricted"), default=False, non_string_truthiness=True)
if include_restricted and not (ctx.has_permission("can_manage_materials") or ctx.has_permission("*")):
include_restricted = False
payload = _serialize_image_list(result, signer)
if not include_restricted:
visible = [item for item in payload["items"] if not _is_restricted_image(item)]
payload["restricted_hidden"] = len(payload["items"]) - len(visible)
payload["items"] = visible
payload["total"] = max(len(visible), int(payload.get("total") or 0) - payload["restricted_hidden"])
```
```python
# backend/services/image_service.py:135-143 —— approve/reject 会真实改写可见性
update = {"metadata": {**metadata,
"quarantined": False if action == "approve" else True,
"gallery_visibility": "normal" if action == "approve" else "restricted",
"moderation_admin_review": review},
**({"is_archived": True} if action == "reject" else {})}
```
前端验证:`grep -rn "include_restricted\|restricted_hidden\|quarantined\|gallery_visibility" frontend/` 全树仅命中 `App.vue:4526` 的 `include_archived: true`,与本功能无关。`frontend/shared/types/image.ts:28-33` 的 `ImageListResult` 也没有 `restricted_hidden` 字段。
- **影响**:`generation_service.py:491` / `968` 会把审核不通过的图打上 `gallery_visibility: "restricted"`。这些图对所有人(含管理员)永久不可见、不可复核、不可解除——UI 既不显示"有 N 张被隐藏",也没有任何入口调用 approve。用户视角是"生成成功了但图库里没有",没有任何解释。这是一条**后端做完、前端未接、因此在生产中表现为数据丢失**的功能链。
- **修复建议**:图库页加"显示受限图片"开关(仅 `can_manage_materials` 可见)→ 传 `include_restricted=true`;列表底部读 `restricted_hidden` 显示"另有 N 张待复核";受限图详情弹窗加 approve/reject,调 `endpoints` 新增的 `imageModerationReview(imageId)`。同时把 `restricted_hidden?: number` 补进 `ImageListResult`。
---
### [P2-中等] `AdvancedMaterialImportStatus` 双向漂移,且 `Union | string` 写法让所有状态联合类型在编译期失效
- **位置**:`frontend/shared/types/advanced-material.ts:1-49` vs `backend/services/advanced_style_set_service.py:384/527/539/787/1366` 等
- **问题**:两个方向都对不上,而且类型声明方式使 TS 完全无法发现这类漂移。
- **代码**:
后端实际写入 import.status 的取值(扫描 `update_import(..., {"status": ...})` 得到):
```
adjustment_required, cancelled, ready_for_validation, recognition_failed,
recognition_queued, recognizing_style_sources, style_consensus_failed,
style_consensus_queued, style_consensus_running, style_source_recognition_queued,
style_source_review_required, validating, validation_failed, validation_queued
```
前端联合类型(`advanced-material.ts:1-18`):
```ts
export type AdvancedMaterialImportStatus =
| "recognition_queued" | "pending_recognition" | "recognizing" | "pending_validation"
| "ready_for_validation" | "validation_queued" | "validating" | "validation_failed"
| "recognition_failed" | "pending_review" | "awaiting_review" | "adjustment_required"
| "accepted" | "rejected" | "failed" | "cancelled" | "archived"
```
**前端缺 6 个**:`recognizing_style_sources`、`style_consensus_failed`、`style_consensus_queued`、`style_consensus_running`、`style_source_recognition_queued`、`style_source_review_required`(整个 style-set 流程的状态一个没有)。
**前端多 2 个后端根本不产出的**:`pending_validation`、`pending_review`(`grep -rn '"pending_validation"' --include=*.py backend/ database/` → 0 命中)。
而声明处一律写成:
```ts
// advanced-material.ts:168
status: AdvancedMaterialImportStatus | string
```
TypeScript 会把 `"a" | "b" | string` 折叠成 `string`,**联合类型完全不产生任何类型检查**。同样的写法出现在 `AdvancedStyleSource.status`、`AdvancedStyleValidationCase.status`、`AdvancedMaterial.status`、`workflow-round.ts:73/112`(`round_kind`、`preference_status`)等十余处。
- **影响**:运行时目前靠 `advanced-material-state.ts:24-67` 的 switch 兜住(它确实手工覆盖了 style_* 状态,甚至还处理了一个后端只在两处出现的 `validation_partial_failed`),但类型层面完全没有护栏:后端加一个新状态,TS 编译通过、review 看不出、只有用户看到"未知状态"文案(`advanced-material-state.ts:65`)才暴露。`pending_validation`/`pending_review` 这两个幽灵值说明漂移已经发生过至少一次且无人察觉。
- **修复建议**:
1. 把 `| string` 去掉,改为 `status: AdvancedMaterialImportStatus`,让联合类型真正生效;确实需要容忍未知值的地方用显式 `as string` 或在解析边界处收窄。
2. 状态集合从后端生成而非手抄:把各 `*_STATUSES` 常量集中到一个 Python 模块,加一个生成脚本产出 `frontend/shared/types/generated-enums.ts`,CI 校验 `git diff --exit-code`。
---
### [P2-中等] `backend/dto/advanced_material_dto.py` 已不是进阶素材接口的响应真相来源
- **位置**:`backend/dto/advanced_material_dto.py` vs `backend/services/advanced_style_set_service.py` vs `frontend/shared/types/advanced-material.ts`
- **问题**:TS 类型里大量字段在 DTO 的 `to_dict()` 中不存在,而路由层的序列化只补了 `*_url`。
- **代码**:
路由层只做签名 URL 增强,不加业务字段:
```python
# backend/routes/advanced_material_routes.py:387-392
def _serialize_style_source(payload: dict[str, Any]) -> dict[str, Any]:
return {**payload,
"source_image_url": _signed_url(payload.get("source_image_uri")),
"source_thumbnail_url": _signed_url(payload.get("source_thumbnail_uri"))}
```
但 TS 声明了这些 DTO 里没有的字段(`advanced-material.ts:58-86`、`125-158`、`160-187`):
| TS 接口 | DTO 无此字段 | 实际来源 |
|---|---|---|
| `AdvancedStyleSource` | `excluded`、`filename`、`image_uri`、`thumbnail_uri`、`retry_count` | `advanced_style_set_service.py:409/414` 手工构造的 metadata / view dict |
| `AdvancedStyleValidationCase` | `scenario`、`title`、`style_prompt`、`style_scores`、`rendering_layers`、`content_novelty` | `advanced_style_set_service.py:2330/2354/3345/3422` |
| `AdvancedMaterialImport` | `task_id`、`workflow_kind`、`sources`、`consensus`、`validation_cases` | `advanced_style_set_service.py:389/1152` |
| `AdvancedStyleConsensus` | 整个接口无对应 DTO(`AdvancedStyleConsensusRun` 字段名完全不同:`consensus_style`/`version_id`/`variable_style_features` 都不在 DTO 里) | `advanced_style_set_service.py:1723` |
反向也有:DTO 输出但 TS 未声明的 `idempotency_key`(import)、`recognition_model_route`/`provider_id`/`provider_model`(style source)、`width`/`height`/`completed_at`(validation case)。
- **影响**:`backend/dto/` 这一层对进阶素材已经名存实亡——响应形状实际由散落在 3600 行 `advanced_style_set_service.py` 各处的 dict 字面量决定。想知道接口返回什么,只能全文搜索;改动时没有任何单点可以对照。这也是前面状态枚举漂移的同一个根因。
- **修复建议**:为 style-set 流程补 DTO(`AdvancedStyleSourceView`、`AdvancedStyleValidationCaseView`、`AdvancedStyleConsensusView`),让 service 返回 DTO 实例而非裸 dict,路由层只调 `to_dict()` + 加签名 URL。这样"接口返回什么"重新有唯一定义点,也让 `contract` 有机会未来发布响应 schema。
---
### [P2-中等] `route-chain:` 线格式编解码器被逐字移植到 TS,无任何跨语言一致性测试
- **位置**:`core/model_route_chain.py:52-66` vs `frontend/standalone-web/src/features/settings/model-route-chain.ts:27-39`
- **问题**:这不是"逻辑重复",而是**同一个序列化格式的两份独立实现**——前端写出的字符串要被后端解析,任何一边的细节改动都会破坏另一边,而目前正确性完全依赖手工对齐 `json.dumps` 与 `JSON.stringify` 的输出细节。
- **代码**:
```python
# core/model_route_chain.py:61-66
return ROUTE_CHAIN_PREFIX + json.dumps(
{"plugin": plugin_route, "astrbot": astrbot_route},
ensure_ascii=False, separators=(",", ":"), sort_keys=True)
```
```ts
// frontend/standalone-web/src/features/settings/model-route-chain.ts:33
return `${MODEL_ROUTE_CHAIN_PREFIX}${JSON.stringify({ astrbot, plugin })}`
```
目前能对上,靠的是三个巧合同时成立:Python `sort_keys=True` 产出 `astrbot` 在前 ≡ TS 对象字面量恰好写成 `{ astrbot, plugin }` 的插入顺序;`separators=(",", ":")` ≡ `JSON.stringify` 默认无空格;`ensure_ascii=False` ≡ `JSON.stringify` 默认不转义非 ASCII。
- **影响**:把 TS 那行写成 `JSON.stringify({ plugin, astrbot })`(更符合"plugin 优先"的语义直觉)就会产出 `{"plugin":...,"astrbot":...}`。Python 端 `parse_model_route_chain` 用 `json.loads` 读 dict,解析仍然成功——所以**不会立刻报错**,但两端产出的字符串不再逐字节相等,任何做字符串比较的地方(配置 diff、快照对比、`settings/diff`)都会把"没变的配置"报成"变了"。现有测试 `tests/test_model_route_chain.py` 只验 Python 内部往返,`frontend/tests/workflow-model-route.test.mjs` 根本没测这个模块,**没有一条测试断言两语言的编码结果相同**。
- **修复建议**:加一条黄金样本测试固定线格式。Python 侧断言 `encode_model_route_chain("p","astrbot:a") == 'route-chain:{"astrbot":"astrbot:a","plugin":"p"}'`,TS 侧 `frontend/tests/` 里用同一字符串断言 `encodeModelRouteChain({plugin:"p",astrbot:"astrbot:a"})`,并加反向 `parse` 用例。更彻底的做法是别让前端编码:新增 `POST settings/encode-model-route` 或让 settings 保存接口接受 `{plugin, astrbot}` 结构体、由后端编码。
---
### [P2-中等] `character_flow` 节点目录与 legacy 别名表在前端重复,且两份前端拷贝之间也不一致
- **位置**:`engines/character_flow.py:15-20` vs `frontend/standalone-web/src/features/workflow/workflow-node-catalog.ts:23-32` vs `frontend/standalone-web/src/features/workflow/workflow-model-route.ts:61-74`
- **问题**:同一张"legacy node_key → canonical node_key"映射表存在三份,其中两份在同一个前端目录下且映射结果不同。
- **代码**:
```python
# engines/character_flow.py:15-20
LEGACY_CHARACTER_GRADUAL_NODE_KEYS: dict[str, str] = {
"half_body": "upper_body",
"expression_sheet": "turnaround", # ← turnaround
"pose_sheet": "design_sheet",
"final_pack": "profile_card",
}
```
```ts
// workflow-node-catalog.ts:23-28 —— 与后端一致
export const LEGACY_CHARACTER_WORKFLOW_NODE_KEYS = {
half_body: "upper_body", expression_sheet: "turnaround",
pose_sheet: "design_sheet", final_pack: "profile_card",
}
```
```ts
// workflow-model-route.ts:61-74 —— 同一前端内的第三份,expression_sheet 映射不同
const canonicalAliases: Record<string, string> = {
portrait: "headshot", avatar: "headshot", half_body: "upper_body", halfbody: "upper_body",
standing: "full_body", fullbody: "full_body", three_view: "turnaround", three_views: "turnaround",
character_sheet: "design_sheet",
expression_sheet: "design_sheet", // ← design_sheet,与另两处冲突
pose_sheet: "design_sheet", hires_fix: "style_lock",
}
```
另外 11 个节点的 `node_key` 与展示文案在 `engines/character_flow.py:22-115`(`CHARACTER_GRADUAL_STEPS`,含 title/description/sort_order/stage_code)和 `workflow-node-catalog.ts:64-153`(`CHARACTER_WORKFLOW_PREVIEW_NODE_SPECS`,含 title/detail/badge/phase)各存一份,两边的中文标题也不同(后端"拆解人设/预选素材"vs 前端"LLM 拆解设定/参考素材绑定")。
- **影响**:`expression_sheet` 的冲突目前不产生可见 bug(`turnaround` 和 `design_sheet` 恰好都映射到 `sheet_generation`),但这是巧合而非设计。真正的风险是:`engines/character_flow.py` 加一个新节点或改一个别名,前端两份表都不会更新,`workflowUiNodeIdForNodeKey` 返回 `undefined`,该节点在工作流面板直接不显示——用户看到的步骤列表比后端实际创建的节点少一个。
- **修复建议**:`ui/bootstrap` 或新增 `GET workflows/node-catalog` 下发 `gradual_node_templates()` + `LEGACY_CHARACTER_GRADUAL_NODE_KEYS`(后端已有 `gradual_node_templates()`,`character_flow.py:131-145`,几乎可以直接返回)。前端 `workflow-node-catalog.ts` 只保留纯展示增强(badge/phase/detail 这些后端没有的字段),键与别名从接口取。同时删除 `workflow-model-route.ts:61-74` 那张私有别名表,改用 `canonicalCharacterWorkflowNodeKey`。
---
### [P2-中等] `LONG_TASK_ENDPOINT` 正则在前端重复两份,并把"哪些后端端点慢"编码进了客户端
- **位置**:`frontend/shared/api/client.ts:14` 与 `frontend/shared/api/astrbot-page-bridge.ts:6`(逐字符相同)
- **问题**:一条 18 个分支的正则,枚举了所有"耗时长"的后端端点段,在两个文件里各存一份;而它声称对齐的"后端 900 秒预算"在后端并不存在。
- **代码**:
```ts
// client.ts:14 与 astrbot-page-bridge.ts:6 —— 完全相同的两份
const LONG_TASK_ENDPOINT = /(?:^|\/)(?:generate|retry|review|execute-character|expand|governance-preview|probe-provider|probe-model|recognize|re-recognize|renormalize|renormalize-batch|import-pack|migrate|restore)(?:\/|$)/
```
```ts
// frontend/shared/config/timeouts.ts
export const LONG_TASK_TIMEOUT_SECONDS = 900
```
而 `grep -rn "\b900\b" --include=*.py`(排除 tests/release/.tmp)在后端只有一处命中,且与生成任务无关:
```python
# backend/services/advanced_style_set_service.py:57
STYLE_VALIDATION_TIMEOUT_SECONDS = 900
```
生成任务的真实预算是 180 秒(`generation_service.py:2308` `request.get("timeout_seconds") or settings.get("timeout_seconds") or 180`;`config.yaml:25/42` `timeout_seconds: 180`)。
号称守护一致性的测试其实只读前端文件:
```js
// frontend/tests/task-timeout-consistency.test.mjs:11-25
test("uses the backend 900 second task budget throughout the plugin bridge UI", async () => {
const [timeouts, client, bridge, app] = await Promise.all([...]) // ← 四个文件全在 frontend/
assert.match(timeouts, /LONG_TASK_TIMEOUT_SECONDS = 900/)
...
})
```
- **影响**:
1. 正则里 `probe-model`、`renormalize`、`renormalize-batch`、`import-pack` 对应的端点前端**根本不调用**(见表 ①),说明这份列表已经和实际调用面脱节,无人维护。
2. 测试名字断言"后端 900 秒预算",但测试没有读过任何后端文件——它固化的是一个虚构的契约。后端把 `timeout_seconds` 从 180 调到 600,前端不会知道;反过来前端这个 900 也没有任何后端依据。
3. 新增一个慢端点(例如 `advanced-material-imports/{id}/style-consensus`,实际走 900 秒的样式校验)不在正则里,客户端 30 秒就超时报错,而后端任务其实还在跑。
- **修复建议**:正则提到 `frontend/shared/config/timeouts.ts` 一份,两个 transport 共同 import。更好的做法是让后端在 `ui/bootstrap` 下发 `{ long_task_endpoint_patterns: [...], long_task_timeout_seconds: N }`,N 取 `config.generation.provider.timeout_seconds` 的上界;测试改为读 `config.yaml` / `generation_service.py` 与前端常量做真实比对。
---
### [P2-中等] `contract` 端点只被用作诊断 JSON dump,没有任何自动化契约测试消费它
- **位置**:`backend/services/contract_service.py:12-30`、`backend/routes/contract_routes.py:13-23`、唯一前端消费点 `frontend/standalone-web/src/features/settings/SystemManagementPanel.vue:8`
- **问题**:契约自检机制**已经存在且数据完备**,但没有被任何一方真正用起来。
- **代码**:
```python
# backend/services/contract_service.py:13-30 —— 数据已经很全
return {
"contract_version": "3.0",
"api_base": API_BASE,
"routes": route_manifest(), # 166 条:method/endpoint/handler/permission/required_permissions
"permissions": permission_matrix(),
"error_codes": [code.value for code in ErrorCode],
"response_shape": {...},
}
```
```ts
// SystemManagementPanel.vue:8 —— 唯一消费点,拉下来直接 JSON.stringify 塞进 <pre>
else if(props.mode==="diagnostics"){
const [contract,actions,manifest]=await Promise.all([
getJson(endpoints.contract),getJson(endpoints.uiActions),getJson(endpoints.webManifest)]);
result.value={contract,actions,manifest}}
```
`route_registry.py` 已经写好了两个自检函数,但 `grep -rln "route_manifest\|route_registry\|ROUTES" tests/` 只命中 `test_profile_card_finalize.py` 和 `test_workflow_generation_cross_review.py`(都是间接 import),**没有任何测试调用 `assert_unique_routes()` / `assert_known_permissions()`**:
```python
# backend/route_registry.py:365-377 —— 现成的自检,无人调用
def assert_unique_routes() -> None: ...
def assert_known_permissions() -> None: ...
```
- **影响**:契约漂移目前没有任何自动化拦截。本报告里的表 ①(14 条死接口)、P1-4(权限漏判)、P2-9(状态枚举漂移)全部是人工比对才发现的,任何一条都本可以由 CI 自动发现。
- **修复建议**:**这是本维度投入产出比最高的一条,建议优先做**。三条测试即可覆盖大部分问题:
1. **后端自检**(`tests/test_route_contract.py`,我已实测 166 条 handler 全部可导入,此测试当前会通过):
```python
import importlib
from backend.route_registry import ROUTES, assert_unique_routes, assert_known_permissions
def test_route_manifest_is_wellformed():
assert_unique_routes()
assert_known_permissions()
for route in ROUTES:
mod, _, fn = route.handler.rpartition(".")
assert hasattr(importlib.import_module(mod), fn), route.handler
```
2. **跨语言路由比对**(`frontend/tests/api-contract.test.mjs`):解析 `backend/route_registry.py` 的 `RouteSpec("METHOD", "endpoint"` 与 `endpoints.ts` 的模板字符串(把 `${...}` 与 `{...}` 都归一为 `{}`),断言 endpoints.ts ⊆ ROUTES(阻止表 ② 出现),并把当前 14 条死接口写成显式 allowlist,新增未使用路由时测试失败——逼迫作者要么接上要么删掉。
3. **权限门禁比对**:前端所有按钮的 `enabled` 统一走 P1-4 建议的 `canCall(method, endpoint)`,该函数的输入直接来自 contract 的 `required_permissions`,从此权限矩阵不需要在前端复写。
另外 `contract` 目前只发布路由与权限,不发布**请求/响应 schema**。若把 `backend/dto/*.py` 的 `to_dict()` 字段清单也纳入(DTO 都是 frozen dataclass,用 `dataclasses.fields()` 自动生成即可),就能把 P2-9、P2-10、P3-16 这类字段级漂移一并自动化——但前提是先修 P2-10(让 DTO 重新成为真相来源)。
---
### [P2-中等] `API_BASE` 硬编码三份,而 `bootstrap.api_base` 下发了却没人用
- **位置**:`backend/services/ui_service.py:10`、`frontend/shared/api/endpoints.ts:1`、`frontend/standalone-web/vite.config.ts:11`
- **问题**:同一个字符串三处独立字面量;后端已经通过 bootstrap 把它下发给前端,前端却只拿它拼提示文案。
- **代码**:
```python
# backend/services/ui_service.py:10(被 contract_service / astrbot_adapter 复用,后端侧是单点)
API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
```
```ts
// frontend/shared/api/endpoints.ts:1
export const API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
```
```ts
// frontend/standalone-web/vite.config.ts:11
base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/",
```
前端拿到 `bootstrap.api_base` 之后的唯一用途:
```ts
// frontend/standalone-web/src/App.vue:4330
: `已通过同源 API ${loadedBootstrap.api_base} 调用后端,写入动作会进入工作流并落库。`,
```
实际请求路径始终来自编译期常量:
```ts
// frontend/shared/api/client.ts:299
const url = new URL(`${API_BASE}/${trimmed}`, window.location.origin)
```
- **影响**:插件名一旦变更(`metadata.yaml` 改 name、或 AstrBot 调整挂载前缀),后端 `API_BASE` 改一处即可,前端要改两处且其中一处是 vite 构建配置——漏掉 vite base 会导致所有 chunk 404(这类"资产 404"症状在 git 历史里已经出现过:`fix: load material library page without expiring asset chunk`)。而 `bootstrap.api_base` 这个正确的解耦通道就在那里没被使用。
- **修复建议**:`client.ts` 的 `buildUrl` 改为优先使用运行期值:模块内维护 `let runtimeApiBase = API_BASE`,bootstrap 成功后调 `setApiBase(bootstrap.api_base)`。vite base 保持编译期常量(静态资源必须编译期确定),但加一条 `frontend/tests/` 断言 `vite.config.ts` 的 base 以 `endpoints.ts` 的 `API_BASE` 开头。
---
### [P3-轻微] `CharacterProfile` TS 类型缺 owner 四字段,`generation_kind` 联合含后端不产出的值
- **位置**:`frontend/shared/types/profile.ts:3-21` vs `backend/dto/profile_dto.py:32-52` 与 `database/repositories/profile_repository.py:32-56`
- **问题**:DTO 输出 20 个字段,TS 声明 16 个;且 TS 的枚举值比后端 SQL 实际产出的多一个。
- **代码**:
后端 `to_dict()` 输出但 TS 未声明:`owner_platform`、`owner_context_id`、`owner_user_id`、`owner_session_key`(`profile_dto.py:42-45`)。
TS 声明:
```ts
// frontend/shared/types/profile.ts:18
generation_kind?: "ungenerated" | "quick" | "detailed" | "profile_card"
```
而 SQL 表达式只可能产出三个值:
```sql
-- database/repositories/profile_repository.py:32-56
CASE WHEN EXISTS (... profile_card.status = 'sealed') THEN 'detailed'
WHEN EXISTS (... final_archive_history_id ...) THEN 'detailed'
WHEN EXISTS (... character_fast ...) THEN 'quick'
ELSE 'ungenerated' END AS generation_kind
```
- **影响**:owner 四字段是多租户归属信息,随每个 profile 响应传输但前端不认识——将来若要做"仅显示我创建的角色"这类过滤,会有人再造一份类型。`"profile_card"` 是死枚举值,`switch (profile.generation_kind)` 里为它写的分支永远不执行,读代码的人会误以为存在这个状态(`profile_category` 才有 `profile_card`)。
- **修复建议**:DTO 与 TS 字段做一次对齐(不需要的字段就从 `to_dict()` 里删,别只在 TS 侧省略);删掉 `generation_kind` 里的 `"profile_card"`。长期看应由 P2-14 建议的 DTO schema 导出自动生成。
---
### [P3-轻微] `WorkflowRoundNextRequest.count` 类型比后端窄,掩盖了 cross_review 的 1..8 区间
- **位置**:`frontend/shared/types/workflow-round.ts:48-52` vs `backend/services/workflow_round_service.py:1159-1171`
- **问题**:TS 把候选数收窄为字面量联合 `4 | 5`,后端接受的区间取决于轮次类型。
- **代码**:
```ts
// frontend/shared/types/workflow-round.ts:48-52
export interface WorkflowRoundNextRequest {
count: 4 | 5
idempotency_key: string
model_route?: string
}
```
```python
# backend/services/workflow_round_service.py:1159-1171
def _requested_count(value: Any, round_kind: str) -> int:
count = int(value) if value is not None else 4
maximum = 8 if round_kind == "cross_review" else 5
if count < 1 or count > maximum:
raise ApiError(ErrorCode.VALIDATION_FAILED,
"round candidate count is outside the supported range",
{"field": "count", "minimum": 1, "maximum": maximum})
```
- **影响**:目前是安全方向的收窄(前端发的值后端一定接受),不会产生 400。但把"业务上只允许 4 或 5"这条产品规则固化在了 TS 类型里而后端并不这么认为,两边对同一规则的理解已经分叉;将来要支持"生成 8 张交叉复核候选"时,类型会成为改动的隐性阻碍,且改动方向不明确(因为没人记得后端其实早就支持)。
- **修复建议**:改为 `count: number`,把"4 或 5"的选择限制放在 UI 控件层(下拉框选项),并在 `WorkflowGenerationRoundDetail` 或 `round.metadata` 里由后端下发 `allowed_count_range: [min, max]`,让 UI 选项跟着轮次类型走。