@skopon-cool/form-sdk 0.2.4 → 0.3.0

package/src/client/authStorage.ts

@@ -10,6 +10,7 @@ export interface SkoponAuthStorageOptions {
 export const DEFAULT_AUTH_STORAGE_KEY = 'auth_user'
 export const DEFAULT_AUTH_TOKEN_FIELD = 'token'
 export const DEFAULT_AUTH_ANSWER_AGENT_CALLBACK_URL_FIELD = 'answer_agent_callback_url'
+export const DEFAULT_AUTH_REALTIME_WS_URL_FIELD = 'realtime_ws_url'
 /** 与 skopon-admin 登录写入的 mock answer-agent 路径一致 */
 export const DEFAULT_ANSWER_AGENT_CALLBACK_URL = '/api/v1/mock/ask_user_answer_mock'
 
@@ -46,7 +47,10 @@ function readTokenFromSessionJson(
     : ''
 }
 
-/** 从宿主登录缓存读取 answer_agent_callback_url（无则返回空串）。 */
+/**
+ * 从宿主登录缓存读取 answer_agent_callback_url。
+ * 无 session / 无法读取时返回空串；session 存在但字段缺失或为空时回落到默认 mock 路径（与 skopon-admin 登录迁移一致）。
+ */
 export function resolveAnswerAgentCallbackUrl(
   options: SkoponAuthStorageOptions & {
     answerAgentCallbackUrlField?: string
@@ -58,19 +62,56 @@ export function resolveAnswerAgentCallbackUrl(
     options.answerAgentCallbackUrlField ?? DEFAULT_AUTH_ANSWER_AGENT_CALLBACK_URL_FIELD
 
   const storage = readStorage(storageKind)
-  if (!storage) return DEFAULT_ANSWER_AGENT_CALLBACK_URL
+  if (!storage) return ''
 
   const raw = storage.getItem(storageKey)
-  if (!raw) return DEFAULT_ANSWER_AGENT_CALLBACK_URL
+  if (!raw) return ''
 
   const parsed = readSessionJson(raw)
-  if (!parsed) return DEFAULT_ANSWER_AGENT_CALLBACK_URL
+  if (!parsed) return ''
 
   const url = parsed[field]
   const trimmed = typeof url === 'string' ? url.trim() : ''
   return trimmed || DEFAULT_ANSWER_AGENT_CALLBACK_URL
 }
 
+/**
+ * 从宿主登录缓存读取 realtime_ws_url。
+ * 无 session / 无字段 / 空串时返回 ''（不建连）；SDK 不负责写入该字段。
+ */
+export function resolveRealtimeWsUrl(
+  options: SkoponAuthStorageOptions & {
+    realtimeWsUrlField?: string
+  } = {},
+): string {
+  const storageKind = options.storage ?? 'sessionStorage'
+  const storageKey = options.storageKey ?? DEFAULT_AUTH_STORAGE_KEY
+  const field = options.realtimeWsUrlField ?? DEFAULT_AUTH_REALTIME_WS_URL_FIELD
+
+  const storage = readStorage(storageKind)
+  if (!storage) return ''
+
+  const raw = storage.getItem(storageKey)
+  if (!raw) return ''
+
+  const parsed = readSessionJson(raw)
+  if (!parsed) return ''
+
+  const url = parsed[field]
+  return typeof url === 'string' ? url.trim() : ''
+}
+
+/** 合并 session 鉴权头与宿主显式 headers；显式 headers 优先。 */
+export function resolveSubmitAuthHeaders(
+  explicit?: Record<string, string>,
+  authStorage?: SkoponAuthStorageOptions,
+): Record<string, string> {
+  return {
+    ...resolveSkoponAuthHeaders(authStorage),
+    ...(explicit ?? {}),
+  }
+}
+
 /** 从宿主登录缓存读取 Bearer token，返回 Authorization 头（无 token 时返回空对象）。 */
 export function resolveSkoponAuthHeaders(
   options: SkoponAuthStorageOptions = {},

package/src/components/AskUserFormCard.tsx

@@ -1,6 +1,10 @@
-import { useEffect, useMemo, useRef, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { Button, Spin, Tag, Tooltip } from 'antd'
 import type { FormDetailResult, FormSchema, SubmitMode } from '../types/index'
+import {
+  resolveRealtimeWsUrl,
+  resolveSubmitAuthHeaders,
+} from '../client/authStorage'
 import { buildAskUserSurface } from '../adapter/resolveSurface'
 import {
   buildAnswerAgentBody,
@@ -22,6 +26,10 @@ import {
 import { validateFormSubmitValues } from '../submit/validateFormSubmit'
 import type { CaseSearchFn } from '../catalog/caseSearchContext'
 import type { ResumeSearchFn } from '../catalog/resumeSearchContext'
+import { FormRuntimeProvider, useFormRuntime } from '../runtime/formRuntimeContext'
+import { FormRuntimeWsClient } from '../runtime/formRuntimeWs'
+import { executeFormAutoControl } from '../runtime/formAutoControl'
+import type { FormAutoControlEventData } from '../runtime/types'
 import SkoponFormRenderer, { type SkoponFormRendererRef } from './SkoponFormRenderer'
 import CurlSubmitBlock from './CurlSubmitBlock'
 import SkoponFormProvider from './SkoponFormProvider'
@@ -43,9 +51,16 @@ export interface AskUserFormCardProps {
   payload: unknown
   /** 可选；无则跳过拉取 vt_forms，仅用 payload blocks fallback */
   formUniqueId?: string | null
+  /**
+   * ask_source_unique_id（Flow/QA 业务 id）。
+   * 有值且 sessionStorage.auth_user.realtime_ws_url 存在、且渲染出表单控件时按卡建连。
+   */
+  askUserMessageId?: string | null
   callbackUrl?: string | null
   submitMode?: SubmitMode
   answerAgentContext?: AskUserAnswerAgentContext
+  /** 显式提交 headers，与 session 鉴权合并；显式优先 */
+  submitHeaders?: Record<string, string>
   /** 需 useCallback 稳定引用，避免重复拉取 */
   fetchFormDetail: (ref: { formUniqueId: string }) => Promise<FormDetailResult>
   onNotify?: (type: 'success' | 'error', message: string) => void
@@ -55,27 +70,44 @@ export interface AskUserFormCardProps {
   caseSearch?: CaseSearchFn | null
 }
 
-export default function AskUserFormCard({
+interface AskUserFormCardBodyProps extends AskUserFormCardProps {
+  onSurfaceReadyChange: (ready: boolean) => void
+  onAutoControlReady: (handler: ((data: FormAutoControlEventData) => void) | null) => void
+}
+
+function AskUserFormCardBody({
   payload,
   formUniqueId,
+  askUserMessageId,
   callbackUrl,
   submitMode = 'curl',
   answerAgentContext,
+  submitHeaders,
   fetchFormDetail,
   onNotify,
   resumeSearch = null,
   caseSearch = null,
-}: AskUserFormCardProps) {
+  onSurfaceReadyChange,
+  onAutoControlReady,
+}: AskUserFormCardBodyProps) {
   const [formDef, setFormDef] = useState<FormSchema | null>(null)
   const [formDisabled, setFormDisabled] = useState(false)
   const [loading, setLoading] = useState(true)
   const [submitting, setSubmitting] = useState(false)
   const rendererRef = useRef<SkoponFormRendererRef>(null)
+  const cardRootRef = useRef<HTMLDivElement>(null)
   const mountedRef = useRef(true)
   const onNotifyRef = useRef(onNotify)
   onNotifyRef.current = onNotify
+  const runtime = useFormRuntime()
 
   const resolvedFormUniqueId = formUniqueId?.trim() ?? ''
+  const resolvedAskUserMessageId = askUserMessageId?.trim() ?? ''
+
+  const resolvedSubmitHeaders = useMemo(
+    () => resolveSubmitAuthHeaders(submitHeaders),
+    [submitHeaders],
+  )
 
   const resolvedAnswerAgentContext = useMemo(
     (): AskUserAnswerAgentContext => ({
@@ -171,31 +203,14 @@ export default function AskUserFormCard({
     ? `ask-user-${resolvedFormUniqueId}`
     : 'ask-user-payload'
 
-  if (loading) {
-    return (
-      <SkoponFormProvider>
-        <div className="ask-user-form-card">
-          <Spin size="small" />
-        </div>
-      </SkoponFormProvider>
-    )
-  }
+  const hasFormSurface = Boolean(!loading && payloadDef && renderBlocks.length > 0 && surfaceDoc)
 
-  if (!payloadDef || renderBlocks.length === 0) {
-    return (
-      <SkoponFormProvider>
-        <CurlSubmitBlock
-          payload={payload}
-          callbackUrl={callbackUrl}
-          answerAgentContext={resolvedAnswerAgentContext}
-          unpublishedFormId={formDisabled && resolvedFormUniqueId ? resolvedFormUniqueId : undefined}
-          onNotify={onNotify}
-        />
-      </SkoponFormProvider>
-    )
-  }
+  useEffect(() => {
+    onSurfaceReadyChange(hasFormSurface)
+    return () => onSurfaceReadyChange(false)
+  }, [hasFormSurface, onSurfaceReadyChange])
 
-  async function handleSubmit() {
+  const handleSubmit = useCallback(async () => {
     if (submitting) return
     setSubmitting(true)
     try {
@@ -207,13 +222,21 @@ export default function AskUserFormCard({
       }
       const answer = { ...cardValues, ...extraValues }
 
+      runtime.reportData(answer)
+      runtime.reportEvent({
+        action: 'submit',
+        component: 'SubmitButton',
+      })
+
       if (submitMode === 'post') {
         const url = (callbackUrl ?? '').trim()
         if (!url) {
           onNotifyRef.current?.('error', 'callback_url 为空，无法提交')
           return
         }
-        const result = await submitFormJson(url, answer)
+        const result = await submitFormJson(url, answer, {
+          headers: resolvedSubmitHeaders,
+        })
         if (!mountedRef.current) return
         if (result.ok) {
           onNotifyRef.current?.('success', '提交成功')
@@ -229,7 +252,9 @@ export default function AskUserFormCard({
         form: formDef ?? payloadDef,
         answer,
       })
-      const result = await submitAnswerAgent(body)
+      const result = await submitAnswerAgent(body, {
+        headers: resolvedSubmitHeaders,
+      })
       if (!mountedRef.current) return
       const notify = formatAnswerAgentSubmitMessage(result)
       onNotifyRef.current?.(notify.type, notify.message)
@@ -240,11 +265,79 @@ export default function AskUserFormCard({
     } finally {
       if (mountedRef.current) setSubmitting(false)
     }
+  }, [
+    submitting,
+    fieldNames,
+    renderBlocks,
+    extraValues,
+    runtime,
+    submitMode,
+    callbackUrl,
+    resolvedSubmitHeaders,
+    resolvedAnswerAgentContext,
+    payload,
+    formDef,
+    payloadDef,
+  ])
+
+  const handleSubmitRef = useRef(handleSubmit)
+  handleSubmitRef.current = handleSubmit
+
+  const applyAutoControl = useCallback(
+    (data: FormAutoControlEventData) => {
+      executeFormAutoControl(
+        data,
+        {
+          setValues: (values) => rendererRef.current?.setValues(values),
+          getValues: (names) => rendererRef.current?.getValues(names) ?? {},
+          submit: () => handleSubmitRef.current(),
+          rootElement: cardRootRef.current,
+        },
+        {
+          reportEvent: runtime.reportEvent,
+          runAutoControl: runtime.runAutoControl,
+        },
+      )
+    },
+    [runtime],
+  )
+
+  useEffect(() => {
+    if (!hasFormSurface) {
+      onAutoControlReady(null)
+      return
+    }
+    onAutoControlReady(applyAutoControl)
+    return () => onAutoControlReady(null)
+  }, [hasFormSurface, applyAutoControl, onAutoControlReady])
+
+  if (loading) {
+    return (
+      <div className="ask-user-form-card">
+        <Spin size="small" />
+      </div>
+    )
+  }
+
+  if (!payloadDef || renderBlocks.length === 0) {
+    return (
+      <CurlSubmitBlock
+        payload={payload}
+        callbackUrl={callbackUrl}
+        answerAgentContext={resolvedAnswerAgentContext}
+        submitHeaders={submitHeaders}
+        unpublishedFormId={formDisabled && resolvedFormUniqueId ? resolvedFormUniqueId : undefined}
+        onNotify={onNotify}
+      />
+    )
   }
 
   return (
-    <SkoponFormProvider>
-      <div className="ask-user-form-card">
+    <div
+      className="ask-user-form-card"
+      ref={cardRootRef}
+      data-ask-user-message-id={resolvedAskUserMessageId || undefined}
+    >
       {formDisabled && resolvedFormUniqueId ? (
         <div className="ask-user-form-card-status">
           <Tooltip title={resolvedFormUniqueId}>
@@ -282,7 +375,61 @@ export default function AskUserFormCard({
           </Button>
         </Tooltip>
       </div>
-      </div>
+    </div>
+  )
+}
+
+export default function AskUserFormCard(props: AskUserFormCardProps) {
+  const resolvedAskUserMessageId = props.askUserMessageId?.trim() ?? ''
+  const realtimeWsUrl = useMemo(() => resolveRealtimeWsUrl(), [])
+  const [surfaceReady, setSurfaceReady] = useState(false)
+  const [wsClient, setWsClient] = useState<FormRuntimeWsClient | null>(null)
+  const autoControlHandlerRef = useRef<((data: FormAutoControlEventData) => void) | null>(null)
+
+  const onSurfaceReadyChange = useCallback((ready: boolean) => {
+    setSurfaceReady(ready)
+  }, [])
+
+  const onAutoControlReady = useCallback(
+    (handler: ((data: FormAutoControlEventData) => void) | null) => {
+      autoControlHandlerRef.current = handler
+    },
+    [],
+  )
+
+  const shouldConnect = Boolean(
+    realtimeWsUrl && resolvedAskUserMessageId && surfaceReady,
+  )
+
+  useEffect(() => {
+    if (!shouldConnect || !realtimeWsUrl || !resolvedAskUserMessageId) {
+      setWsClient(null)
+      return
+    }
+    const client = new FormRuntimeWsClient({
+      url: realtimeWsUrl,
+      askUserMessageId: resolvedAskUserMessageId,
+      onAutoControl: (data) => {
+        autoControlHandlerRef.current?.(data)
+      },
+    })
+    client.connect()
+    setWsClient(client)
+    return () => {
+      client.close()
+      setWsClient(null)
+    }
+  }, [shouldConnect, realtimeWsUrl, resolvedAskUserMessageId])
+
+  return (
+    <SkoponFormProvider>
+      <FormRuntimeProvider client={wsClient}>
+        <AskUserFormCardBody
+          {...props}
+          onSurfaceReadyChange={onSurfaceReadyChange}
+          onAutoControlReady={onAutoControlReady}
+        />
+      </FormRuntimeProvider>
     </SkoponFormProvider>
   )
 }

package/src/components/CurlSubmitBlock.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { Button, Tag, Tooltip, Typography } from 'antd'
+import { resolveSubmitAuthHeaders } from '../client/authStorage'
 import { buildCurlStatement } from '../submit/buildCurlStatement'
 import {
   buildAnswerAgentBody,
@@ -25,6 +26,8 @@ export interface CurlSubmitBlockProps {
   /** display：复制与显示一致；submitFields：复制向 callback 提交返回字段的 curl */
   copyMode?: CurlSubmitBlockCopyMode
   answerAgentContext?: AskUserAnswerAgentContext
+  /** 显式提交 headers，与 session 鉴权合并；显式优先 */
+  submitHeaders?: Record<string, string>
   onNotify?: (type: 'success' | 'error', message: string) => void
 }
 
@@ -44,6 +47,7 @@ export default function CurlSubmitBlock({
   unpublishedFormId,
   incompleteFormId,
   answerAgentContext,
+  submitHeaders,
   onNotify,
 }: CurlSubmitBlockProps) {
   const [submitting, setSubmitting] = useState(false)
@@ -56,9 +60,14 @@ export default function CurlSubmitBlock({
     }
   }, [])
 
+  const resolvedSubmitHeaders = useMemo(
+    () => resolveSubmitAuthHeaders(submitHeaders),
+    [submitHeaders],
+  )
+
   const displayCurl = useMemo(
-    () => buildCurlStatement(payload, callbackUrl),
-    [payload, callbackUrl],
+    () => buildCurlStatement(payload, callbackUrl, resolvedSubmitHeaders),
+    [payload, callbackUrl, resolvedSubmitHeaders],
   )
 
   const resolvedContext = useMemo(
@@ -79,7 +88,9 @@ export default function CurlSubmitBlock({
         payload,
         answer,
       })
-      const result = await submitAnswerAgent(body)
+      const result = await submitAnswerAgent(body, {
+        headers: resolvedSubmitHeaders,
+      })
       if (!mountedRef.current) return
       const notify = formatAnswerAgentSubmitMessage(result)
       onNotify?.(notify.type, notify.message)

package/src/components/SkoponFormRenderer.tsx

@@ -21,6 +21,7 @@ import SkoponFormProvider from './SkoponFormProvider'
 
 export interface SkoponFormRendererRef {
   getValues: (fieldNames?: string[]) => Record<string, unknown>
+  setValues: (values: Record<string, unknown>) => void
 }
 
 export interface SkoponFormRendererProps {
@@ -104,6 +105,17 @@ const SkoponFormRenderer = forwardRef<SkoponFormRendererRef, SkoponFormRendererP
           const resolvedNames = (names ?? fieldNamesRef.current).map((n) => n.trim()).filter(Boolean)
           return extractSurfaceValues(processor, surfaceId, resolvedNames)
         },
+        setValues(values) {
+          const processor = processorRef.current
+          if (!processor) return
+          const surface = processor.model.surfacesMap.get(surfaceId)
+          if (!surface) return
+          for (const [name, value] of Object.entries(values)) {
+            const trimmed = name.trim()
+            if (!trimmed) continue
+            surface.dataModel.set(`/${trimmed}`, value)
+          }
+        },
       }),
       [surfaceId],
     )

package/src/index.ts

@@ -79,11 +79,14 @@ export {
 } from './submit/submitAnswerAgent'
 export {
   resolveAnswerAgentCallbackUrl,
+  resolveRealtimeWsUrl,
   resolveSkoponAuthHeaders,
+  resolveSubmitAuthHeaders,
   resolveClientHeaders,
   DEFAULT_AUTH_STORAGE_KEY,
   DEFAULT_AUTH_TOKEN_FIELD,
   DEFAULT_AUTH_ANSWER_AGENT_CALLBACK_URL_FIELD,
+  DEFAULT_AUTH_REALTIME_WS_URL_FIELD,
   DEFAULT_ANSWER_AGENT_CALLBACK_URL,
   type SkoponAuthStorageOptions,
   type ClientHeadersOptions,

package/src/runtime/formAutoControl.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { executeFormAutoControl } from './formAutoControl'
+import type { FormAutoControlEventData } from './types'
+
+describe('executeFormAutoControl', () => {
+  it('writes values and reports bac change event', () => {
+    const setValues = vi.fn()
+    const reportEvent = vi.fn()
+    const runAutoControl = vi.fn((fn: () => unknown) => fn())
+    const data: FormAutoControlEventData = {
+      action: 'change',
+      field: 'name',
+      value: 'Alice',
+      component: 'TextField',
+    }
+    executeFormAutoControl(
+      data,
+      {
+        setValues,
+        getValues: () => ({}),
+        submit: vi.fn(),
+        rootElement: null,
+      },
+      { reportEvent, runAutoControl },
+    )
+    expect(runAutoControl).toHaveBeenCalled()
+    expect(setValues).toHaveBeenCalledWith({ name: 'Alice' })
+    expect(reportEvent).toHaveBeenCalledWith({
+      action: 'change',
+      component: 'TextField',
+      field: 'name',
+      value: 'Alice',
+    })
+  })
+
+  it('ignores change without field', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const setValues = vi.fn()
+    executeFormAutoControl(
+      { action: 'change', value: 'x' },
+      {
+        setValues,
+        getValues: () => ({}),
+        submit: vi.fn(),
+        rootElement: null,
+      },
+      { reportEvent: vi.fn(), runAutoControl: (fn) => fn() },
+    )
+    expect(setValues).not.toHaveBeenCalled()
+    expect(warn).toHaveBeenCalled()
+    warn.mockRestore()
+  })
+
+  it('invokes submit for submit action', () => {
+    const submit = vi.fn()
+    executeFormAutoControl(
+      { action: 'submit' },
+      {
+        setValues: vi.fn(),
+        getValues: () => ({}),
+        submit,
+        rootElement: null,
+      },
+      { reportEvent: vi.fn(), runAutoControl: (fn) => fn() },
+    )
+    expect(submit).toHaveBeenCalled()
+  })
+})

package/src/runtime/formAutoControl.ts

@@ -0,0 +1,109 @@
+import type { FormAutoControlEventData, FormRuntimeEventData } from './types'
+
+export interface FormAutoControlTargets {
+  setValues: (values: Record<string, unknown>) => void
+  getValues: (fieldNames?: string[]) => Record<string, unknown>
+  submit: () => void | Promise<void>
+  /** 卡片根节点，用于按 data-skopon-field 定位 DOM */
+  rootElement: HTMLElement | null
+}
+
+export interface FormAutoControlHelpers {
+  reportEvent: (event: FormRuntimeEventData) => void
+  runAutoControl: <T>(fn: () => T) => T
+}
+
+function escapeAttrSelector(value: string): string {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
+    return CSS.escape(value)
+  }
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+function focusField(root: HTMLElement | null, field: string): boolean {
+  if (!root) return false
+  const container = root.querySelector(`[data-skopon-field="${escapeAttrSelector(field)}"]`)
+  if (!(container instanceof HTMLElement)) return false
+  const focusable =
+    container.querySelector<HTMLElement>(
+      'input, textarea, select, button, [tabindex]:not([tabindex="-1"])',
+    ) ?? container
+  focusable.focus()
+  return true
+}
+
+function clickField(root: HTMLElement | null, field: string): boolean {
+  if (!root) return false
+  const container = root.querySelector(`[data-skopon-field="${escapeAttrSelector(field)}"]`)
+  if (!(container instanceof HTMLElement)) return false
+  const clickable =
+    container.querySelector<HTMLElement>(
+      'button, [role="button"], .skopon-resume-select-card, input, label',
+    ) ?? container
+  clickable.click()
+  return true
+}
+
+/** 执行下行 form_auto_control_event；缺参或未知 action 时 warn 并忽略。 */
+export function executeFormAutoControl(
+  data: FormAutoControlEventData,
+  targets: FormAutoControlTargets,
+  helpers: FormAutoControlHelpers,
+): void {
+  const action = data.action
+  if (
+    action !== 'change' &&
+    action !== 'select' &&
+    action !== 'focus' &&
+    action !== 'click' &&
+    action !== 'submit'
+  ) {
+    console.warn('[FormAutoControl] unknown action', action)
+    return
+  }
+
+  helpers.runAutoControl(() => {
+    if (action === 'submit') {
+      void targets.submit()
+      return
+    }
+
+    const field = typeof data.field === 'string' ? data.field.trim() : ''
+    if (!field) {
+      console.warn('[FormAutoControl] missing field for action', action)
+      return
+    }
+
+    const component = data.component?.trim() || 'Unknown'
+
+    if (action === 'change' || action === 'select') {
+      if (data.value === undefined) {
+        console.warn('[FormAutoControl] missing value for action', action)
+        return
+      }
+      targets.setValues({ [field]: data.value })
+      helpers.reportEvent({
+        action,
+        component,
+        field,
+        value: data.value,
+      })
+      return
+    }
+
+    if (action === 'focus') {
+      focusField(targets.rootElement, field)
+      helpers.reportEvent({
+        action: 'focus',
+        component,
+        field,
+      })
+      return
+    }
+
+    // click：由组件 onClick 打点回传（autoControlDepth 生效）
+    if (!clickField(targets.rootElement, field)) {
+      console.warn('[FormAutoControl] click target not found', field)
+    }
+  })
+}