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

54 KiB

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 三条路由指向同一个函数体:

# 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。

  • 代码:

    后端:

    # 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
    

    前端(同一套规则,第二份实现):

    // 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
    
    // frontend/standalone-web/src/App.vue:927
    const CHARACTER_WORKFLOW_PROGRESSION_VERSION = "character_gradual_sequential_v1"
    

    根因是后端从不下发进度:

    # 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):
      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

  • 问题:两条独立的"这个节点还能不能写"规则,条件集合不同;前端多判了一个不存在的字段,少判了两个真实条件。

  • 代码:

    前端:

    // 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)
    }
    

    后端:

    # 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):

    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 之前:

    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 分支):

    // 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):

    "retry": {
        "auth_required": True,
        "required_permission": "can_retry_tasks",
        "required_permissions": ["can_write", "can_retry_tasks"],
        "description": "task retry management (write + retry capabilities)",
    },
    
    # 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):

    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 统一走它:

    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/,却没有忽略这两个实际的输出目录。
  • 代码:
    // frontend/standalone-web/vite.config.ts:9-15
    base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/",
    build: { outDir: resolve(rootDir, "../../web"), emptyOutDir: true },
    
    // frontend/plugin-page/vite.config.ts:11-15
    base: "./",
    build: { outDir: resolve(rootDir, "../../pages/imagestudio"), emptyOutDir: true },
    
    # 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 全文只有:
    <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 通道):

    # 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),
        }
    

    前端:

    // 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

  • 问题:后端已经把任务状态分类抽成了具名常量,前端把这些集合的字面量抄了三份,还多出一个后端没有的分类。

  • 代码:

    后端唯一真相:

    # 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))
    

    前端三份拷贝:

    // 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])
    
    // 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;前端零引用
  • 问题:后端为"内容审核隔离图片"实现了完整闭环——列表过滤、管理员可见开关、隐藏计数、管理员复核端点——前端一个都没接。
  • 代码:
    # 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"])
    
    # 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):

    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 命中)。 而声明处一律写成:

    // 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 增强,不加业务字段:

    # 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 的输出细节。
  • 代码:
    # 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)
    
    // 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"映射表存在三份,其中两份在同一个前端目录下且映射结果不同。
  • 代码:
    # 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",
    }
    
    // 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",
    }
    
    // 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 秒预算"在后端并不存在。
  • 代码:
    // 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)(?:\/|$)/
    
    // frontend/shared/config/timeouts.ts
    export const LONG_TASK_TIMEOUT_SECONDS = 900
    
    而 grep -rn "\b900\b" --include=*.py(排除 tests/release/.tmp)在后端只有一处命中,且与生成任务无关:
    # 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)。 号称守护一致性的测试其实只读前端文件:
    // 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

  • 问题:契约自检机制已经存在且数据完备,但没有被任何一方真正用起来。

  • 代码:

    # 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": {...},
    }
    
    // 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():

    # 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 全部可导入,此测试当前会通过):

      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 把它下发给前端,前端却只拿它拼提示文案。
  • 代码:
    # backend/services/ui_service.py:10(被 contract_service / astrbot_adapter 复用,后端侧是单点)
    API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
    
    // frontend/shared/api/endpoints.ts:1
    export const API_BASE = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio"
    
    // frontend/standalone-web/vite.config.ts:11
    base: "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/web/",
    
    前端拿到 bootstrap.api_base 之后的唯一用途:
    // frontend/standalone-web/src/App.vue:4330
    : `已通过同源 API ${loadedBootstrap.api_base} 调用后端,写入动作会进入工作流并落库。`,
    
    实际请求路径始终来自编译期常量:
    // 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 声明:
    // frontend/shared/types/profile.ts:18
    generation_kind?: "ungenerated" | "quick" | "detailed" | "profile_card"
    
    而 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,后端接受的区间取决于轮次类型。
  • 代码:
    // frontend/shared/types/workflow-round.ts:48-52
    export interface WorkflowRoundNextRequest {
      count: 4 | 5
      idempotency_key: string
      model_route?: string
    }
    
    # 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 选项跟着轮次类型走。