@skopon-cool/form-sdk 0.2.1 → 0.2.3

package/dist/submit/buildAnswerAgentBody.d.ts

@@ -0,0 +1,19 @@
+import type { FormSchema } from '../types/index';
+import { type PayloadBlocksDefinition } from './intersectPayloadBlocksWithForm';
+export interface AskUserAnswerAgentContext {
+    missionId?: number | string | null;
+    tenantId?: number | null;
+    tenantUserId?: string | null;
+    requestId?: string | null;
+    askUserQueryDescription?: string | null;
+    callbackUrl?: string | null;
+}
+export interface BuildAnswerAgentBodyOptions {
+    context: AskUserAnswerAgentContext;
+    payload: unknown;
+    form?: PayloadBlocksDefinition | FormSchema | null;
+    answer: Record<string, unknown>;
+}
+/** 组装 answer-agent 外包消息体（与 mock AskUserAnswerMockVo 对齐）。 */
+export declare function buildAnswerAgentBody({ context, payload, form, answer, }: BuildAnswerAgentBodyOptions): Record<string, unknown>;
+//# sourceMappingURL=buildAnswerAgentBody.d.ts.map

package/dist/submit/buildAnswerAgentBody.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildAnswerAgentBody.d.ts","sourceRoot":"","sources":["../../src/submit/buildAnswerAgentBody.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,kCAAkC,CAAA;AAEzC,MAAM,WAAW,yBAAyB;IACxC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAClC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAmBD,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,yBAAyB,CAAA;IAClC,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,uBAAuB,GAAG,UAAU,GAAG,IAAI,CAAA;IAClD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC;AAED,4DAA4D;AAC5D,wBAAgB,oBAAoB,CAAC,EACnC,OAAO,EACP,OAAO,EACP,IAAI,EACJ,MAAM,GACP,EAAE,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAevD"}

package/dist/submit/submitAnswerAgent.d.ts

@@ -0,0 +1,9 @@
+import { type SkoponAuthStorageOptions } from '../client/authStorage';
+import { type SubmitFormJsonOptions, type SubmitFormJsonResult } from './submitFormJson';
+export interface SubmitAnswerAgentOptions extends SubmitFormJsonOptions {
+    authStorage?: SkoponAuthStorageOptions;
+    /** 显式覆盖 auth_user 中的 answer_agent_callback_url */
+    answerAgentCallbackUrl?: string | null;
+}
+export declare function submitAnswerAgent(body: Record<string, unknown>, options?: SubmitAnswerAgentOptions): Promise<SubmitFormJsonResult>;
+//# sourceMappingURL=submitAnswerAgent.d.ts.map

package/dist/submit/submitAnswerAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submitAnswerAgent.d.ts","sourceRoot":"","sources":["../../src/submit/submitAnswerAgent.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAC1B,MAAM,kBAAkB,CAAA;AAEzB,MAAM,WAAW,wBAAyB,SAAQ,qBAAqB;IACrE,WAAW,CAAC,EAAE,wBAAwB,CAAA;IACtC,kDAAkD;IAClD,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAkB/B"}

package/dist/submit/validateFormSubmit.d.ts

@@ -0,0 +1,10 @@
+import type { FormBlock } from '../types/index';
+export interface FormSubmitValidationError {
+    fieldName: string;
+    label: string;
+    message: string;
+}
+export declare function matchesValidationRegexp(value: string, pattern: string): boolean;
+/** 提交前校验 renderBlocks 对应字段值；首个错误即返回。 */
+export declare function validateFormSubmitValues(blocks: FormBlock[], values: Record<string, unknown>): FormSubmitValidationError | null;
+//# sourceMappingURL=validateFormSubmit.d.ts.map

package/dist/submit/validateFormSubmit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateFormSubmit.d.ts","sourceRoot":"","sources":["../../src/submit/validateFormSubmit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAM/C,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAO/E;AA6BD,wCAAwC;AACxC,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,EAAE,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,yBAAyB,GAAG,IAAI,CA0DlC"}

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Skopon form rendering SDK (A2UI + form_definition) with submit helpers",
   "type": "module",
   "sideEffects": [

package/src/adapter/a2uiAdapter.ts

@@ -27,7 +27,7 @@ import { getBlockTypeAdapter, getComponentAdapter } from '../blocks/registry'
 const ROOT_ID = 'root'
 const TITLE_ID = '__title__'
 const DESC_ID = '__desc__'
-const EMAIL_REGEXP = '^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$'
+export const EMAIL_REGEXP = '^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$'
 
 function pathFor(name: string): string {
   return `/${name}`

package/src/adapter/formSchema.test.ts

@@ -3,6 +3,7 @@
  */
 import { describe, it, expect } from 'vitest'
 import { coerceToggleValue, normalizeFormDefinition } from './formSchema'
+import { mapFormDefinitionFromDto } from './resolveSurface'
 
 describe('coerceToggleValue', () => {
   it('accepts boolean, string, and numeric truthy/falsy values', () => {
@@ -36,4 +37,27 @@ describe('normalizeFormDefinition toggle default', () => {
     })
     expect(def.blocks[0]?.defaultValue).toBe(true)
   })
+
+  it('preserves jsonSchema from raw definition', () => {
+    const schema = { type: 'object', properties: { title: { type: 'string' } } }
+    const def = normalizeFormDefinition({
+      title: '',
+      description: '',
+      blocks: [],
+      jsonSchema: schema,
+    })
+    expect(def.jsonSchema).toEqual(schema)
+  })
+})
+
+describe('mapFormDefinitionFromDto jsonSchema', () => {
+  it('reads json_schema snake_case from DTO', () => {
+    const schema = { type: 'object' }
+    const def = mapFormDefinitionFromDto({
+      title: 'T',
+      blocks: [{ id: 'b1', type: 'text', name: 'x', label: 'X' }],
+      json_schema: schema,
+    })
+    expect(def?.jsonSchema).toEqual(schema)
+  })
 })

package/src/adapter/formSchema.ts

@@ -1,4 +1,4 @@
-import type { FormBlock, FormBlockType, FormCaseFilter, FormResumeFilter, FormSchema } from '../types/index'
+import type { FormBlock, FormBlockType, FormCaseFilter, FormResumeFilter, FormJsonSchema, FormSchema } from '../types/index'
 import { isInputBlockType, isMediaBlockType } from '../types/index'
 import { generateId } from './id'
 import {
@@ -13,6 +13,13 @@ import {
 
 const DEFAULT_MEDIA_URL_MAX = 10
 
+export function normalizeJsonSchema(raw: unknown): FormJsonSchema {
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    return raw as FormJsonSchema
+  }
+  return {}
+}
+
 export function coerceToggleValue(raw: unknown): boolean {
   if (raw === true || raw === 'true' || raw === 1 || raw === '1') return true
   if (raw === false || raw === 'false' || raw === 0 || raw === '0') return false
@@ -180,7 +187,7 @@ export function normalizeFormDefinition(raw: FormSchema | undefined): FormSchema
     title: typeof raw.title === 'string' ? raw.title : '',
     description: typeof raw.description === 'string' ? raw.description : '',
     blocks,
-    jsonSchema: {},
+    jsonSchema: normalizeJsonSchema(raw.jsonSchema),
   })
 }
 

package/src/adapter/resolveSurface.ts

@@ -1,6 +1,6 @@
 import type { A2uiSurfaceDoc, FormBlock, FormDefinitionPayload, FormSchema } from '../types/index'
 import { a2uiToBlocks, blocksToA2ui, isA2uiSurfaceEmpty, type BlocksToA2uiOptions } from './a2uiAdapter'
-import { normalizeFormDefinition } from './formSchema'
+import { normalizeFormDefinition, normalizeJsonSchema } from './formSchema'
 
 function isA2uiSurfaceDoc(raw: unknown): raw is A2uiSurfaceDoc {
   return (
@@ -27,7 +27,7 @@ export function resolveSurfaceFromFormDefinition(
     title: typeof payload.title === 'string' ? payload.title : '',
     description: typeof payload.description === 'string' ? payload.description : '',
     blocks,
-    jsonSchema: {},
+    jsonSchema: normalizeJsonSchema(payload.jsonSchema ?? payload.json_schema),
   })
   const doc = blocksToA2ui(normalized, options)
   return isA2uiSurfaceEmpty(doc) ? null : doc
@@ -61,6 +61,6 @@ export function mapFormDefinitionFromDto(raw: unknown): FormSchema | undefined {
     title: typeof obj.title === 'string' ? obj.title : '',
     description: typeof obj.description === 'string' ? obj.description : '',
     blocks: Array.isArray(obj.blocks) ? (obj.blocks as FormSchema['blocks']) : [],
-    jsonSchema: {},
+    jsonSchema: normalizeJsonSchema(obj.jsonSchema ?? obj.json_schema),
   })
 }

package/src/catalog/a2uiCustomCatalog.tsx

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { useEffect, type ReactNode } from 'react'
+import { useEffect, useState, type ReactNode } from 'react'
 import { Catalog, type ComponentContext } from '@a2ui/web_core/v0_9'
 import {
   basicCatalog,
@@ -21,6 +21,7 @@ import {
 import dayjs, { type Dayjs } from 'dayjs'
 import type { FormFilePlaceholderIcon, FormMediaSize } from '../types/index'
 import { coerceToggleValue } from '../adapter/formSchema'
+import { matchesValidationRegexp } from '../submit/validateFormSubmit'
 import {
   buildFileAcceptAttribute,
   formatFileAcceptSummary,
@@ -589,8 +590,22 @@ function TextFieldPreview({ context }: { context: ComponentContext }) {
   const label = readString(props.label)
   const placeholder = readString(props.placeholder)
   const variant = readString(props.variant) || 'shortText'
+  const validationRegexp = readString(props.validationRegexp)
   const stringValue = asOptionalString(value) ?? ''
   const disabled = !interactive
+  const [formatError, setFormatError] = useState('')
+
+  const validateFormat = (text: string) => {
+    if (!validationRegexp || !text.trim()) {
+      setFormatError('')
+      return
+    }
+    setFormatError(matchesValidationRegexp(text, validationRegexp) ? '' : '格式不正确')
+  }
+
+  useEffect(() => {
+    validateFormat(stringValue)
+  }, [validationRegexp, stringValue])
 
   const controlClassName = 'form-block-preview-control'
 
@@ -603,7 +618,13 @@ function TextFieldPreview({ context }: { context: ComponentContext }) {
         placeholder={placeholder || '长文本回答...'}
         autoSize={{ minRows: 2, maxRows: 6 }}
         value={stringValue}
-        onChange={(e) => setValue(e.target.value)}
+        status={formatError ? 'error' : undefined}
+        onChange={(e) => {
+          const next = e.target.value
+          setValue(next)
+          validateFormat(next)
+        }}
+        onBlur={(e) => validateFormat(e.target.value)}
       />
     )
   } else if (variant === 'number') {
@@ -636,7 +657,13 @@ function TextFieldPreview({ context }: { context: ComponentContext }) {
         className={controlClassName}
         placeholder={placeholder}
         value={stringValue}
-        onChange={(e) => setValue(e.target.value)}
+        status={formatError ? 'error' : undefined}
+        onChange={(e) => {
+          const next = e.target.value
+          setValue(next)
+          validateFormat(next)
+        }}
+        onBlur={(e) => validateFormat(e.target.value)}
       />
     )
   }
@@ -645,6 +672,11 @@ function TextFieldPreview({ context }: { context: ComponentContext }) {
     <div className="form-block-preview">
       {label ? <div className="form-block-preview-label">{label}</div> : null}
       {control}
+      {formatError ? (
+        <Typography.Text type="danger" className="form-block-preview-help">
+          {formatError}
+        </Typography.Text>
+      ) : null}
     </div>
   )
 }

package/src/catalog/textFieldPreview.test.tsx

@@ -85,4 +85,35 @@ describe('SkoponFormRenderer TextField longText', () => {
     expect(warnSpy.mock.calls.some((call) => String(call[0]).includes('[useMarkdown]'))).toBe(false)
     warnSpy.mockRestore()
   })
+
+  it('shows format error for invalid email TextField', () => {
+    const doc = blocksToA2ui(
+      {
+        title: '',
+        description: '',
+        blocks: [
+          {
+            id: 'b-email',
+            type: 'email',
+            name: 'contact',
+            label: '邮箱',
+          },
+        ],
+      },
+      { includeHeader: false },
+    )
+    const { container, getByText } = render(
+      createElement(SkoponFormRenderer, {
+        doc,
+        surfaceId: 'test-email',
+        fieldNames: ['contact'],
+      }),
+    )
+    const input = container.querySelector('input.ant-input')
+    expect(input).toBeTruthy()
+    if (input) {
+      fireEvent.change(input, { target: { value: 'not-an-email' } })
+    }
+    expect(getByText('格式不正确')).toBeTruthy()
+  })
 })

package/src/client/apiEnvelope.ts

@@ -0,0 +1,21 @@
+export interface ApiEnvelope<T> {
+  success?: boolean
+  data?: T
+  message?: string
+}
+
+export async function parseEnvelope<T>(response: Response): Promise<T> {
+  let json: ApiEnvelope<T>
+  try {
+    json = (await response.json()) as ApiEnvelope<T>
+  } catch {
+    throw new Error(`响应非 JSON (${response.status})`)
+  }
+  if (!response.ok || json.success === false) {
+    throw new Error(json.message || `请求失败 (${response.status})`)
+  }
+  if (json.data === undefined || json.data === null) {
+    throw new Error(json.message || `响应缺少 data (${response.status})`)
+  }
+  return json.data
+}

package/src/client/authStorage.test.ts

@@ -0,0 +1,87 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  DEFAULT_AUTH_ANSWER_AGENT_CALLBACK_URL_FIELD,
+  DEFAULT_AUTH_STORAGE_KEY,
+  resolveAnswerAgentCallbackUrl,
+  resolveSkoponAuthHeaders,
+} from './authStorage'
+
+describe('resolveSkoponAuthHeaders', () => {
+  afterEach(() => {
+    sessionStorage.clear()
+    localStorage.clear()
+  })
+
+  it('reads Bearer token from sessionStorage auth_user by default', () => {
+    sessionStorage.setItem(
+      DEFAULT_AUTH_STORAGE_KEY,
+      JSON.stringify({ username: 'u', displayName: 'U', token: 'abc123' }),
+    )
+    expect(resolveSkoponAuthHeaders()).toEqual({
+      Authorization: 'Bearer abc123',
+    })
+  })
+
+  it('strips existing Bearer prefix from stored token', () => {
+    sessionStorage.setItem(
+      DEFAULT_AUTH_STORAGE_KEY,
+      JSON.stringify({ token: 'Bearer xyz' }),
+    )
+    expect(resolveSkoponAuthHeaders()).toEqual({
+      Authorization: 'Bearer xyz',
+    })
+  })
+
+  it('returns empty object when session is missing', () => {
+    expect(resolveSkoponAuthHeaders()).toEqual({})
+  })
+
+  it('returns empty object when token field is empty', () => {
+    sessionStorage.setItem(DEFAULT_AUTH_STORAGE_KEY, JSON.stringify({ token: '' }))
+    expect(resolveSkoponAuthHeaders()).toEqual({})
+  })
+
+  it('supports custom storageKey and tokenField', () => {
+    sessionStorage.setItem('my_session', JSON.stringify({ accessToken: 'tok-1' }))
+    expect(
+      resolveSkoponAuthHeaders({ storageKey: 'my_session', tokenField: 'accessToken' }),
+    ).toEqual({ Authorization: 'Bearer tok-1' })
+  })
+
+  it('supports localStorage', () => {
+    localStorage.setItem(
+      DEFAULT_AUTH_STORAGE_KEY,
+      JSON.stringify({ token: 'local-tok' }),
+    )
+    expect(resolveSkoponAuthHeaders({ storage: 'localStorage' })).toEqual({
+      Authorization: 'Bearer local-tok',
+    })
+  })
+})
+
+describe('resolveAnswerAgentCallbackUrl', () => {
+  afterEach(() => {
+    sessionStorage.clear()
+    localStorage.clear()
+  })
+
+  it('reads answer_agent_callback_url from sessionStorage auth_user', () => {
+    sessionStorage.setItem(
+      DEFAULT_AUTH_STORAGE_KEY,
+      JSON.stringify({
+        token: 'tok',
+        [DEFAULT_AUTH_ANSWER_AGENT_CALLBACK_URL_FIELD]:
+          '/api/v1/mock/ask_user_answer_mock',
+      }),
+    )
+    expect(resolveAnswerAgentCallbackUrl()).toBe('/api/v1/mock/ask_user_answer_mock')
+  })
+
+  it('returns empty string when field is missing', () => {
+    sessionStorage.setItem(DEFAULT_AUTH_STORAGE_KEY, JSON.stringify({ token: 'tok' }))
+    expect(resolveAnswerAgentCallbackUrl()).toBe('')
+  })
+})

package/src/client/authStorage.ts

@@ -0,0 +1,102 @@
+export interface SkoponAuthStorageOptions {
+  /** 默认 sessionStorage（与 skopon-admin / HiAUTH 约定一致） */
+  storage?: 'sessionStorage' | 'localStorage'
+  /** 默认 auth_user */
+  storageKey?: string
+  /** JSON 内 token 字段名，默认 token */
+  tokenField?: string
+}
+
+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'
+
+function readStorage(
+  kind: 'sessionStorage' | 'localStorage',
+): Storage | null {
+  if (typeof window === 'undefined') return null
+  try {
+    return kind === 'localStorage' ? window.localStorage : window.sessionStorage
+  } catch {
+    return null
+  }
+}
+
+function readSessionJson(raw: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+    return parsed as Record<string, unknown>
+  } catch {
+    return null
+  }
+}
+
+function readTokenFromSessionJson(
+  raw: string,
+  tokenField: string,
+): string {
+  const parsed = readSessionJson(raw)
+  if (!parsed) return ''
+  const token = parsed[tokenField]
+  return typeof token === 'string'
+    ? token.trim().replace(/^bearer\s+/i, '').trim()
+    : ''
+}
+
+/** 从宿主登录缓存读取 answer_agent_callback_url（无则返回空串）。 */
+export function resolveAnswerAgentCallbackUrl(
+  options: SkoponAuthStorageOptions & {
+    answerAgentCallbackUrlField?: string
+  } = {},
+): string {
+  const storageKind = options.storage ?? 'sessionStorage'
+  const storageKey = options.storageKey ?? DEFAULT_AUTH_STORAGE_KEY
+  const field =
+    options.answerAgentCallbackUrlField ?? DEFAULT_AUTH_ANSWER_AGENT_CALLBACK_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() : ''
+}
+
+/** 从宿主登录缓存读取 Bearer token，返回 Authorization 头（无 token 时返回空对象）。 */
+export function resolveSkoponAuthHeaders(
+  options: SkoponAuthStorageOptions = {},
+): Record<string, string> {
+  const storageKind = options.storage ?? 'sessionStorage'
+  const storageKey = options.storageKey ?? DEFAULT_AUTH_STORAGE_KEY
+  const tokenField = options.tokenField ?? DEFAULT_AUTH_TOKEN_FIELD
+
+  const storage = readStorage(storageKind)
+  if (!storage) return {}
+
+  const raw = storage.getItem(storageKey)
+  if (!raw) return {}
+
+  const token = readTokenFromSessionJson(raw, tokenField)
+  return token ? { Authorization: `Bearer ${token}` } : {}
+}
+
+export interface ClientHeadersOptions {
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>
+  authStorage?: SkoponAuthStorageOptions
+}
+
+/** 显式 getHeaders 优先；否则从本地登录缓存读取。 */
+export async function resolveClientHeaders(
+  options: ClientHeadersOptions = {},
+): Promise<Record<string, string>> {
+  if (options.getHeaders) {
+    return (await options.getHeaders()) ?? {}
+  }
+  return resolveSkoponAuthHeaders(options.authStorage)
+}

package/src/client/caseSearchClient.ts

@@ -0,0 +1,107 @@
+import type { FormCaseFilter } from '../types/index'
+import type { CaseSearchFn, CaseSearchItem } from '../catalog/caseSearchContext'
+import { parseEnvelope } from './apiEnvelope'
+import {
+  type ClientHeadersOptions,
+  resolveClientHeaders,
+} from './authStorage'
+
+export interface CaseSearchClientOptions extends ClientHeadersOptions {
+  baseUrl?: string
+  listPath?: string
+  fetch?: typeof fetch
+  /** 默认 1（已发布） */
+  published?: number
+}
+
+interface CaseListItemDto {
+  case_id: number
+  flow_id: number
+  name: string
+  link: string
+  platform?: string | null
+  description?: string | null
+  case_unique_id: string
+}
+
+interface PagedListDto<T> {
+  list: T[]
+  total: number
+  page: number
+  page_size: number
+}
+
+function isCaseFilterReady(filter: FormCaseFilter): boolean {
+  const hasFlowIds = Boolean(filter.flowUniqueIds?.length)
+  const hasCategory = Boolean(
+    filter.agentUniqueId?.trim()
+    && filter.flowType?.trim()
+    && filter.category?.trim(),
+  )
+  return hasFlowIds || hasCategory
+}
+
+function mapCaseListItem(dto: CaseListItemDto): CaseSearchItem {
+  return {
+    caseUniqueId: dto.case_unique_id,
+    caseId: dto.case_id,
+    flowId: dto.flow_id,
+    name: dto.name,
+    link: dto.link,
+    platform: dto.platform ?? null,
+    description: dto.description ?? undefined,
+  }
+}
+
+function buildCaseListQuery(
+  filter: FormCaseFilter,
+  page: number,
+  published: number,
+): URLSearchParams {
+  const params = new URLSearchParams()
+  params.set('page', String(page))
+  params.set('page_size', String(filter.pageSize ?? 20))
+  params.set('published', String(published))
+  if (filter.agentUniqueId?.trim()) {
+    params.set('agent_unique_id', filter.agentUniqueId.trim())
+  }
+  if (filter.flowType?.trim()) {
+    params.set('flow_type', filter.flowType.trim())
+  }
+  if (filter.category?.trim()) {
+    params.set('category_unique_id', filter.category.trim())
+  }
+  for (const flowId of filter.flowUniqueIds ?? []) {
+    if (flowId) params.append('flow_unique_ids', flowId)
+  }
+  return params
+}
+
+export function createCaseSearchClient(
+  options: CaseSearchClientOptions = {},
+): CaseSearchFn {
+  const baseUrl = (options.baseUrl ?? '/api/v1').replace(/\/$/, '')
+  const listPath = options.listPath ?? '/univ/case/list'
+  const fetchFn = options.fetch ?? fetch
+  const published = options.published ?? 1
+
+  return async ({ filter, page }) => {
+    if (!isCaseFilterReady(filter)) {
+      return { list: [], total: 0, page: 1, pageSize: filter.pageSize ?? 20 }
+    }
+
+    const headers = await resolveClientHeaders(options)
+    const params = buildCaseListQuery(filter, page, published)
+    const response = await fetchFn(`${baseUrl}${listPath}?${params.toString()}`, {
+      method: 'GET',
+      headers,
+    })
+    const data = await parseEnvelope<PagedListDto<CaseListItemDto>>(response)
+    return {
+      list: (data.list ?? []).map(mapCaseListItem),
+      total: data.total ?? 0,
+      page: data.page ?? page,
+      pageSize: data.page_size ?? filter.pageSize ?? 20,
+    }
+  }
+}

package/src/client/formClient.test.ts

@@ -80,4 +80,29 @@ describe('createFormClient', () => {
     const client = createFormClient({ fetch: fetchMock })
     await expect(client.fetchDetail({ formUniqueId: 'missing' })).rejects.toThrow('表单不存在')
   })
+
+  it('uses getHeaders when provided', async () => {
+    const fetchMock = vi.fn(async () =>
+      mockResponse({
+        json: async () => ({
+          success: true,
+          data: {
+            form_id: 1,
+            form_unique_id: 'form-abc',
+            name: 'Test',
+            disabled: 0,
+            form_definition: { title: 'T', blocks: [] },
+          },
+        }),
+      }),
+    ) as unknown as typeof fetch
+
+    const client = createFormClient({
+      fetch: fetchMock,
+      getHeaders: async () => ({ Authorization: 'Bearer custom' }),
+    })
+    await client.fetchDetail({ formUniqueId: 'form-abc' })
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit]
+    expect(init.headers).toEqual({ Authorization: 'Bearer custom' })
+  })
 })