refactor(web-v2): centralize error CTA copy for byok provider failures

Author: echowang1

apps/web-v2/src/lib/error-presenter.ts

@@ -12,9 +12,11 @@ export type UiErrorKind =
 export type UiErrorPresentation = {
   kind: UiErrorKind
   message: string
-  ctaKey?: "refresh_shots" | "check_api_base" | "retry" | "check_fields" | "check_provider_quota"
+  ctaKey?: UiErrorCtaKey
 }
 
+export type UiErrorCtaKey = "refresh_shots" | "check_api_base" | "retry" | "check_fields" | "check_provider_quota"
+
 export function classifyUiError(error: unknown): UiErrorKind {
   if (error instanceof HttpError) {
     const payloadMsg = (() => {
@@ -93,3 +95,22 @@ export function getUiErrorPresentation(error: unknown, locale: "en" | "zh-CN"):
   }
   return { kind, message, ctaKey: ctaByKind[kind] }
 }
+
+export function getUiErrorCtaText(locale: "en" | "zh-CN", ctaKey?: UiErrorCtaKey): string {
+  if (!ctaKey) return ""
+  const zh: Record<UiErrorCtaKey, string> = {
+    refresh_shots: "建议：刷新分镜列表",
+    check_api_base: "建议：检查 API 地址与连接状态",
+    retry: "建议：稍后重试",
+    check_fields: "建议：检查输入字段",
+    check_provider_quota: "建议：检查 BYOK Provider 的余额/额度",
+  }
+  const en: Record<UiErrorCtaKey, string> = {
+    refresh_shots: "Tip: refresh shot list",
+    check_api_base: "Tip: check API base URL and connection",
+    retry: "Tip: retry later",
+    check_fields: "Tip: check form fields",
+    check_provider_quota: "Tip: check BYOK provider credits / balance",
+  }
+  return locale === "zh-CN" ? zh[ctaKey] : en[ctaKey]
+}

apps/web-v2/src/pages/script-desk/ScriptDesk.tsx

@@ -15,7 +15,7 @@ import {
 } from "lucide-react"
 import { useGlobalApiConnectionState, useGlobalDirectorModeState, useGlobalLocaleState } from "@/lib/workbench-ui"
 import { createApiClient } from "@/lib/http-client"
-import { getUiErrorPresentation } from "@/lib/error-presenter"
+import { getUiErrorCtaText, getUiErrorPresentation } from "@/lib/error-presenter"
 import { useQueryTask } from "@/lib/use-query-task"
 import { typo } from "@/components/workbench/typography"
 import { getProviderLabelFromAny, getProviderOptionsFromCapabilities, type ProviderUiValue, uiProviderToApi } from "@/lib/provider-registry"
@@ -156,26 +156,6 @@ function t(locale: Locale) {
   return copy[locale]
 }
 
-function errorCtaText(locale: Locale, ctaKey?: "refresh_shots" | "check_api_base" | "retry" | "check_fields" | "check_provider_quota") {
-  if (!ctaKey) return ""
-  const map = locale === "zh-CN"
-    ? {
-        refresh_shots: "建议：刷新分镜列表",
-        check_api_base: "建议：检查 API 地址与连接状态",
-        retry: "建议：稍后重试",
-        check_fields: "建议：检查输入字段",
-        check_provider_quota: "建议：检查 BYOK Provider 的余额/额度",
-      }
-    : {
-        refresh_shots: "Tip: refresh shot list",
-        check_api_base: "Tip: check API base URL and connection",
-        retry: "Tip: retry later",
-        check_fields: "Tip: check form fields",
-        check_provider_quota: "Tip: check BYOK provider credits / balance",
-      }
-  return map[ctaKey]
-}
-
 function Skeleton({ className }: { className?: string }) {
   return <div className={cn("animate-pulse rounded-md bg-zinc-800/80", className)} />
 }
@@ -461,7 +441,7 @@ export function ScriptDesk() {
       onError: (err) =>
         (() => {
           const ui = getUiErrorPresentation(err, locale)
-          const cta = errorCtaText(locale, ui.ctaKey)
+          const cta = getUiErrorCtaText(locale, ui.ctaKey)
           addLog(`${locale === "zh-CN" ? "加载分镜失败" : "Failed to load shots"} · ${ui.message}${cta ? ` · ${cta}` : ""}`, err, "error")
         })(),
     }
@@ -489,7 +469,7 @@ export function ScriptDesk() {
       return true
     } catch (err) {
       const ui = getUiErrorPresentation(err, locale)
-      const cta = errorCtaText(locale, ui.ctaKey)
+      const cta = getUiErrorCtaText(locale, ui.ctaKey)
       addLog(`${locale === "zh-CN" ? `生成失败 ${shotId}` : `Generate failed ${shotId}`} · ${ui.message}${cta ? ` · ${cta}` : ""}`, err, "error")
       return false
     }

apps/web-v2/src/pages/video-desk/VideoDesk.tsx

@@ -13,7 +13,7 @@ import {
 
 import { Button } from "@/components/ui/Button"
 import { Card, CardContent } from "@/components/ui/Card"
-import { getUiErrorPresentation } from "@/lib/error-presenter"
+import { getUiErrorCtaText, getUiErrorPresentation } from "@/lib/error-presenter"
 import { cn } from "@/lib/utils"
 import { useGlobalApiConnectionState, useGlobalDirectorModeState, useGlobalLocaleState } from "@/lib/workbench-ui"
 import { CinematicWorkspaceShell } from "@/components/workbench/CinematicWorkspaceShell"
@@ -146,24 +146,6 @@ interface CandidateTileProps {
 
 function CandidateTile({ shotId, candidate, locale, onSelect, onReplace, disabled, compact }: CandidateTileProps) {
   const txt = t(locale)
-  const errorCtaLabel = (ctaKey?: string) => {
-    if (!ctaKey) return ""
-    const mapEn: Record<string, string> = {
-      check_provider_quota: "check BYOK provider quota",
-      check_api_base: "check API connection",
-      refresh_shots: "refresh shots",
-      check_fields: "check fields",
-      retry: "retry",
-    }
-    const mapZh: Record<string, string> = {
-      check_provider_quota: "检查 BYOK Provider 额度",
-      check_api_base: "检查 API 连接",
-      refresh_shots: "刷新分镜列表",
-      check_fields: "检查输入字段",
-      retry: "重试",
-    }
-    return (locale === "zh-CN" ? mapZh : mapEn)[ctaKey] || ""
-  }
   const score = candidate.score?.total ?? 0
   const isSelected = candidate.selected || (candidate.id && candidate.id === candidate.candidateId)
   const previewSrc = candidate.thumbnailUrl
@@ -343,7 +325,7 @@ export function VideoDesk() {
       addLog(locale === "zh-CN" ? `已加载 ${data.shots?.length || 0} 个分镜` : `Loaded ${data.shots?.length || 0} shots`, undefined, "success")
     } catch (error) {
       const ui = getUiErrorPresentation(error, locale)
-      const cta = errorCtaLabel(ui.ctaKey)
+      const cta = getUiErrorCtaText(locale, ui.ctaKey)
       addLog(`${locale === "zh-CN" ? "加载分镜失败" : "Load shots failed"} · ${ui.message}${cta ? ` · ${cta}` : ""}`, error, "error")
     } finally {
       setIsLoading(false)
@@ -373,7 +355,7 @@ export function VideoDesk() {
       await loadShots()
     } catch (error) {
       const ui = getUiErrorPresentation(error, locale)
-      const cta = errorCtaLabel(ui.ctaKey)
+      const cta = getUiErrorCtaText(locale, ui.ctaKey)
       addLog(`${locale === "zh-CN" ? `选择候选失败 (${shotId})` : `Select candidate failed (${shotId})`} · ${ui.message}${cta ? ` · ${cta}` : ""}`, error, "error")
     } finally {
       setActiveShotId(null)
@@ -395,7 +377,7 @@ export function VideoDesk() {
       await loadShots()
     } catch (error) {
       const ui = getUiErrorPresentation(error, locale)
-      const cta = errorCtaLabel(ui.ctaKey)
+      const cta = getUiErrorCtaText(locale, ui.ctaKey)
       addLog(`${locale === "zh-CN" ? `低分替换失败 (${shotId})` : `Replace low-score failed (${shotId})`} · ${ui.message}${cta ? ` · ${cta}` : ""}`, error, "error")
     } finally {
       setActiveShotId(null)

docs/providers/byok-setup.md

@@ -61,3 +61,23 @@ Do **not** expose provider keys to frontend env vars.
 - provider account credits are insufficient
 - this is a provider account issue, not a Cineweave transport issue
 
+### Kling `1102` (`Account balance not enough`)
+
+This is a common real-provider BYOK failure when Cineweave has already reached Kling successfully.
+
+What it means:
+
+- AK/SK is valid enough for request authentication
+- Cineweave request/signature path is working
+- Kling rejected the task because provider credits/balance are insufficient
+
+Recommended actions:
+
+1. Recharge / top up the Kling account used by your AK/SK
+2. Confirm the key belongs to the expected account/workspace
+3. Retry the generation request from `Script Desk` or `Video Desk`
+
+How Cineweave surfaces it:
+
+- UI error category: `provider_quota_error`
+- CTA hint: check BYOK provider quota / balance