@skopon-cool/form-sdk 0.6.2 → 0.6.4

package/src/catalog/a2uiCustomCatalog.tsx

@@ -8,9 +8,12 @@ import {
 } from '@a2ui/react/v0_9'
 import {
   Checkbox,
+  Button,
   DatePicker,
   Input,
   InputNumber,
+  Image,
+  Modal,
   Radio,
   Select,
   Switch,
@@ -29,6 +32,7 @@ import {
 } from '../adapter/formFileAccept'
 import { buildMediaListClassName, normalizeMediaSize } from '../adapter/formMedia'
 import { normalizeFormOptions } from '../adapter/formOptions'
+import { normalizeAssetOptions } from '../adapter/formAssetOptions'
 import {
   getRegisteredCatalogComponentNames,
   getRegisteredCatalogComponents,
@@ -56,6 +60,7 @@ export const SKOPON_CATALOG_ID = 'skopon-form-v0_9'
 const SKOPON_COMPONENT_NAMES = new Set([
   'SkoponMedia',
   'SkoponSelect',
+  'SkoponModulePanel',
   'Image',
   'Video',
   'AudioPlayer',
@@ -279,6 +284,58 @@ const SkoponSelectImpl = createBinderlessComponentImplementation(
   SkoponSelectPreview,
 )
 
+const SkoponModulePanelImpl = createBinderlessComponentImplementation(
+  {
+    name: 'SkoponModulePanel',
+    schema: z.object({
+      children: z.array(z.string()).optional(),
+      description: z.any().optional(),
+      reviewCriteria: z.any().optional(),
+      exampleUrls: z.any().optional(),
+    }).passthrough(),
+  },
+  ({ context, buildChild }) => {
+    const props = context.componentModel.properties as Record<string, unknown>
+    const children = Array.isArray(props.children) ? props.children.map(String) : []
+    const description = readString(props.description).trim()
+    const requirementsTitle = readString(props.requirementsTitle).trim() || '本类素材要求'
+    const reviewCriteria = readString(props.reviewCriteria).trim()
+    const exampleUrls = Array.isArray(props.exampleUrls)
+      ? props.exampleUrls.map(String).map((url) => url.trim()).filter(Boolean)
+      : []
+    return (
+      <section className="skopon-module-panel">
+        {description ? <Typography.Paragraph type="secondary" className="skopon-module-panel__description">{description}</Typography.Paragraph> : null}
+        <div className="skopon-module-panel__grid">
+          {children.map((id) => <div className="skopon-module-panel__field" key={id}>{buildChild(id)}</div>)}
+        </div>
+        {reviewCriteria || exampleUrls.length > 0 ? (
+          <aside className="skopon-module-panel__guide">
+            {reviewCriteria ? (
+              <div className="skopon-module-panel__requirements">
+                <Typography.Text strong>{requirementsTitle}</Typography.Text>
+                <Typography.Paragraph type="secondary">{reviewCriteria}</Typography.Paragraph>
+              </div>
+            ) : null}
+            {exampleUrls.length > 0 ? (
+              <div className="skopon-module-panel__examples">
+                <Typography.Text strong>参考示例</Typography.Text>
+                <div className="skopon-module-panel__example-list">
+                  <Image.PreviewGroup>
+                    {exampleUrls.map((url, index) => (
+                      <Image key={`${url}-${index}`} src={url} alt={`参考示例 ${index + 1}`} width={88} height={88} style={{ objectFit: 'cover' }} />
+                    ))}
+                  </Image.PreviewGroup>
+                </div>
+              </div>
+            ) : null}
+          </aside>
+        ) : null}
+      </section>
+    )
+  },
+)
+
 function ChoicePickerPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
   const { value, setValue, setValueSilent, fieldName } = useSkoponBoundField(context, 'value', {
@@ -545,8 +602,21 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
     changeAction: 'change',
   })
   const props = context.componentModel.properties as Record<string, unknown>
+  const sourceMode = props.fileSourceMode === 'asset_only' || props.fileSourceMode === 'upload_or_asset' ? props.fileSourceMode : 'upload_required'
+  const assetOptions = normalizeAssetOptions(props.fileAssetOptions)
+  const [assetPickerOpen, setAssetPickerOpen] = useState(false)
   const label = readString(props.label)
   const accept = readString(props.accept)
+  const help = readString(props.help)
+  const reviewCriteria = readString(props.fileReviewCriteria)
+  const reviewStatus = props.fileReviewStatus === 'passed' || props.fileReviewStatus === 'failed'
+    ? props.fileReviewStatus
+    : undefined
+  const reviewMessage = readString(props.fileReviewMessage)
+  const rejectedUrls = asStringArray(props.fileRejectedUrls)
+    .filter((url) => /^https?:\/\//i.test(url))
+  const exampleUrls = asStringArray(props.fileExampleUrls)
+    .filter((url) => /^https?:\/\//i.test(url))
   const fileAcceptTypes = Array.isArray(props.fileAcceptTypes)
     ? props.fileAcceptTypes.map(String)
     : undefined
@@ -561,18 +631,29 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
     )
       ? (props.filePlaceholderIcon as FormFilePlaceholderIcon)
       : 'document'
+  const compact = props.compact === true
   const minCount = typeof props.minCount === 'number' ? Math.max(0, props.minCount) : 0
   const maxCount = typeof props.maxCount === 'number' ? props.maxCount : 1
   const hasMaxLimit = maxCount > 0
+  const sourceLabel = sourceMode === 'asset_only'
+    ? '素材 · 仅选择'
+    : sourceMode === 'upload_or_asset'
+      ? '物料或素材'
+      : '物料 · 仅上传'
   const initialUrls = normalizeFileUrls(value)
   const externalUidRef = useRef(0)
   const mountedRef = useRef(true)
   const controllersRef = useRef(new Map<string, AbortController>())
   const setValueRef = useRef(setValue)
   setValueRef.current = setValue
-  const [items, setItems] = useState<FileUploadListItem[]>(() =>
-    initialUrls.map((url) => fileItemFromUrl(url, `external-${externalUidRef.current++}`)),
-  )
+  const [items, setItems] = useState<FileUploadListItem[]>(() => [
+    ...initialUrls.map((url) => fileItemFromUrl(url, `external-${externalUidRef.current++}`)),
+    ...rejectedUrls.map((url) => ({
+      ...fileItemFromUrl(url, `rejected-${externalUidRef.current++}`),
+      status: 'error' as const,
+      error: reviewMessage || '审核不合格，请重新上传',
+    })),
+  ])
   const itemsRef = useRef(items)
   itemsRef.current = items
 
@@ -636,14 +717,15 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
 
   const startUpload = useCallback(
     (file: File & { uid?: string }) => {
-      if (!interactive) return
-      if (hasMaxLimit && itemsRef.current.length >= maxCount) return
+      if (!interactive || sourceMode === 'asset_only') return
+      const activeCount = itemsRef.current.filter((item) => item.status !== 'error').length
+      if (hasMaxLimit && activeCount >= maxCount) return
 
       const uid = `${file.uid ?? 'file'}-${externalUidRef.current++}`
       const controller = new AbortController()
       controllersRef.current.set(uid, controller)
       commitItems(
-        (current) => [...current, { uid, name: file.name, status: 'uploading' }],
+        (current) => [...current.filter((item) => item.status !== 'error'), { uid, name: file.name, status: 'uploading' }],
         false,
       )
       const endUpload = beginUpload()
@@ -677,7 +759,7 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
           endUpload()
         })
     },
-    [beginUpload, commitItems, hasMaxLimit, interactive, maxCount],
+    [beginUpload, commitItems, hasMaxLimit, interactive, maxCount, sourceMode],
   )
 
   const handleRemove = useCallback(
@@ -690,7 +772,7 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
   )
 
   const uploadedCount = items.filter((item) => item.status === 'done').length
-  const atMaxLimit = hasMaxLimit && items.length >= maxCount
+  const atMaxLimit = hasMaxLimit && items.filter((item) => item.status !== 'error').length >= maxCount
   const belowMinCount = uploadedCount < minCount
   const latestError = [...items].reverse().find((item) => item.error)?.error
   const fileList: UploadFile[] = items.map((item) => ({
@@ -700,17 +782,131 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
     url: item.url,
     response: item.error,
   }))
+  const assetPicker = <Modal title={`选择推荐素材 · ${label || '素材位置'}`} open={assetPickerOpen} footer={null} width={860} onCancel={() => setAssetPickerOpen(false)}>
+    {assetOptions.length ? <div className="skopon-asset-picker">
+      {assetOptions.map((asset) => {
+        const isImage = asset.assetType === 'image' || Boolean(asset.previewUrl && asset.previewUrl !== asset.url)
+        const chooseAsset = () => {
+          if (!interactive || reviewStatus === 'passed') return
+          if (hasMaxLimit && maxCount > 1 && atMaxLimit) return
+          if (maxCount === 1) {
+            for (const controller of controllersRef.current.values()) controller.abort()
+            controllersRef.current.clear()
+          }
+          commitItems((current) => {
+            const retained = maxCount === 1 ? [] : current.filter((item) => item.status !== 'error' && item.url !== asset.url)
+            return [...retained, { uid: `asset-${asset.assetId}-${externalUidRef.current++}`, name: asset.label, status: 'done', url: asset.url }]
+          }, true)
+          setAssetPickerOpen(false)
+        }
+        return <article key={asset.assetId} className="skopon-asset-picker__card">
+          <div className="skopon-asset-picker__media">
+            {isImage
+              ? <Image src={asset.previewUrl || asset.url} alt={asset.label} preview={{ mask: '放大预览' }} />
+              : <div className="skopon-asset-picker__placeholder"><FilePlaceholderIcon type={asset.assetType === 'video' ? 'video' : asset.assetType === 'audio' ? 'audio' : 'document'} size={36} /></div>}
+          </div>
+          <Typography.Text className="skopon-asset-picker__name" title={asset.label}>{asset.label}</Typography.Text>
+          <Button type="primary" size="small" block aria-label={`选择素材 ${asset.label}`} disabled={!interactive || reviewStatus === 'passed' || (hasMaxLimit && maxCount > 1 && atMaxLimit)} onClick={chooseAsset}>使用此素材</Button>
+        </article>
+      })}
+    </div> : <Typography.Paragraph type="secondary">此位置暂无可选素材，请先在素材库为该位置打标。</Typography.Paragraph>}
+  </Modal>
+
+  if (compact) {
+    const displayItem = items.find((item) => item.status === 'error') ?? items[0]
+    const displayUrl = displayItem?.url
+    const isImage = fileAcceptTypes?.includes('image/*') ?? placeholderIcon === 'image'
+    const state = reviewStatus === 'passed'
+      ? 'passed'
+      : reviewStatus === 'failed'
+        ? 'failed'
+        : displayItem?.status === 'uploading'
+          ? 'uploading'
+          : displayItem?.status === 'done'
+            ? 'pending'
+            : 'empty'
+    const stateText = state === 'passed'
+      ? '审核通过'
+      : state === 'failed'
+        ? (reviewMessage || '审核不合格，请替换')
+        : state === 'uploading'
+          ? '正在上传…'
+          : state === 'pending'
+            ? '等待审核'
+          : `${acceptSummary ?? '文件'}${maxCount > 1 ? `，最多 ${maxCount} 个` : ''}`
+    const canChoose = interactive && state !== 'passed' && state !== 'uploading'
+
+    return (
+      <><article className={`skopon-compact-upload skopon-compact-upload--${state}`} data-skopon-field={fieldName || undefined}>
+        <div className="skopon-compact-upload__thumb">
+          {displayUrl && isImage ? (
+            <img src={displayUrl} alt={label || '已上传素材'} />
+          ) : (
+            <FilePlaceholderIcon type={placeholderIcon} size={30} />
+          )}
+          {state !== 'empty' ? <span className="skopon-compact-upload__state-mark" aria-hidden>
+            {state === 'passed' ? '✓' : state === 'failed' ? '!' : state === 'uploading' ? '…' : '•'}
+          </span> : null}
+        </div>
+        <div className="skopon-compact-upload__meta">
+          <strong>{label || '上传素材'}</strong>
+          <span className={`skopon-compact-upload__source skopon-compact-upload__source--${sourceMode}`}>{sourceLabel}</span>
+          <span className="skopon-compact-upload__status">{stateText}</span>
+          <div className="skopon-file-source-actions">
+          {canChoose && sourceMode !== 'asset_only' ? (
+            <Upload
+              accept={buildFileAcceptAttribute(fileAcceptTypes, fileAcceptExtensions)}
+              multiple={!hasMaxLimit || maxCount > 1}
+              showUploadList={false}
+              beforeUpload={(file) => {
+                if (displayItem?.status === 'done') handleRemove(displayItem.uid)
+                startUpload(file)
+                return Upload.LIST_IGNORE
+              }}
+            >
+              <Button size="small">上传</Button>
+            </Upload>
+          ) : null}
+          {canChoose && sourceMode !== 'upload_required' ? <Button size="small" onClick={() => setAssetPickerOpen(true)}>选择素材</Button> : null}
+          </div>
+          {latestError && state !== 'failed' ? <span className="skopon-compact-upload__error">{latestError}</span> : null}
+        </div>
+      </article>{assetPicker}</>
+    )
+  }
 
   return (
     <div className="form-block-preview" data-skopon-field={fieldName || undefined}>
       {label ? <div className="form-block-preview-label">{label}</div> : null}
+      {reviewStatus === 'passed' ? (
+        <Typography.Paragraph style={{ color: '#389e0d', marginBottom: 8 }}>✅ 审核通过，已保留，无需重新上传</Typography.Paragraph>
+      ) : null}
+      {reviewStatus === 'failed' ? (
+        <Typography.Paragraph type="danger" style={{ marginBottom: 8 }}>❌ 审核不合格：{reviewMessage || '请重新上传'}</Typography.Paragraph>
+      ) : null}
+      {help ? <Typography.Paragraph type="secondary" style={{ whiteSpace: 'pre-line' }}>{help}</Typography.Paragraph> : null}
+      {reviewCriteria ? <Typography.Paragraph type="secondary" style={{ whiteSpace: 'pre-line' }}>素材要求：{reviewCriteria}</Typography.Paragraph> : null}
+      {exampleUrls.length ? (
+        <div className="form-file-examples">
+          <Typography.Text type="secondary">参考示例（不作为上传素材提交）</Typography.Text>
+          <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', margin: '8px 0' }}>
+            <Image.PreviewGroup>
+              {exampleUrls.map((url, index) => (
+                <Image key={url} src={url} alt={`${label || '素材'}示例 ${index + 1}`} width={120} height={120} style={{ objectFit: 'contain' }} />
+              ))}
+            </Image.PreviewGroup>
+          </div>
+        </div>
+      ) : null}
+      {sourceMode !== 'upload_required' ? <div className="skopon-file-source-actions"><Button disabled={!interactive || reviewStatus === 'passed'} onClick={() => setAssetPickerOpen(true)}>选择素材</Button></div> : null}
+      {sourceMode !== 'asset_only' ?
       <Upload.Dragger
-        disabled={!interactive}
-        openFileDialogOnClick={!atMaxLimit}
+        disabled={!interactive || reviewStatus === 'passed'}
+        openFileDialogOnClick={reviewStatus !== 'passed' && !atMaxLimit}
         accept={buildFileAcceptAttribute(fileAcceptTypes, fileAcceptExtensions)}
         className="form-file-upload-preview"
         multiple={!hasMaxLimit || maxCount > 1}
-        showUploadList={interactive && items.length > 0}
+        showUploadList={interactive && items.length > 0 ? { showRemoveIcon: reviewStatus !== 'passed' } : false}
         fileList={interactive ? fileList : []}
         beforeUpload={(file) => {
           if (!interactive) return Upload.LIST_IGNORE
@@ -718,6 +914,7 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
           return Upload.LIST_IGNORE
         }}
         onRemove={(file) => {
+          if (reviewStatus === 'passed') return false
           handleRemove(file.uid)
           return true
         }}
@@ -727,11 +924,15 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
         </p>
         <p className="form-file-upload-preview-text">点击或拖拽文件到此处上传</p>
       </Upload.Dragger>
+      : <div className="skopon-selected-assets">{items.map((item) => <div key={item.uid} className="skopon-selected-assets__row">
+        {item.url ? <a href={item.url} target="_blank" rel="noreferrer">{item.name}</a> : <span>{item.name}</span>}
+        {interactive && reviewStatus !== 'passed' ? <Button size="small" type="text" onClick={() => handleRemove(item.uid)}>移除</Button> : null}
+      </div>)}</div>}
       <Typography.Text type="secondary" className="form-block-preview-help">
         允许：{acceptSummary ?? '全部类型'}
         {minCount > 0 ? `；至少 ${minCount} 个文件` : ''}
-        {hasMaxLimit ? `；最多 ${maxCount} 个文件` : ''}
-        ；选择后自动上传至 CDN
+        {maxCount > 1 ? `；最多 ${maxCount} 个文件` : ''}
+        {sourceMode === 'asset_only' ? '；从推荐素材中选择' : '；选择文件后自动上传至 CDN'}
         {belowMinCount && interactive ? `（当前 ${uploadedCount} 个，未达下限）` : ''}
       </Typography.Text>
       {latestError ? (
@@ -739,6 +940,7 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
           {latestError}
         </Typography.Text>
       ) : null}
+      {assetPicker}
     </div>
   )
 }
@@ -906,6 +1108,7 @@ export function buildSkoponCatalog(): Catalog<ReactComponentImplementation> {
     ...baseComponents,
     SkoponMediaImpl,
     SkoponSelectImpl,
+    SkoponModulePanelImpl,
     ImageImpl,
     VideoImpl,
     AudioPlayerImpl,

package/src/catalog/fileUploadPreview.test.tsx

@@ -56,6 +56,12 @@ function renderFileSurface(options: {
   defaultValue?: string | string[]
   legacyRawValue?: string
   onUploadingChange?: (uploading: boolean) => void
+  fileExampleUrls?: string[]
+  fileReviewCriteria?: string
+  fileReviewStatus?: 'passed' | 'failed'
+  fileReviewMessage?: string
+  fileRejectedUrls?: string[]
+  help?: string
 } = {}) {
   const doc = blocksToA2ui(
     {
@@ -70,6 +76,12 @@ function renderFileSurface(options: {
           fileMinCount: options.minCount ?? 0,
           fileMaxCount: options.maxCount ?? 1,
           defaultValue: options.defaultValue,
+          fileExampleUrls: options.fileExampleUrls,
+          fileReviewCriteria: options.fileReviewCriteria,
+          fileReviewStatus: options.fileReviewStatus,
+          fileReviewMessage: options.fileReviewMessage,
+          fileRejectedUrls: options.fileRejectedUrls,
+          help: options.help,
         },
       ],
     },
@@ -94,6 +106,39 @@ function renderFileSurface(options: {
 }
 
 describe('FileUploadPreview', () => {
+  it('shows descriptions, criteria and examples without submitting example URLs', () => {
+    const { getByText, getByAltText, ref } = renderFileSurface({
+      help: '请上传一张人物图',
+      fileReviewCriteria: '五官清晰',
+      fileExampleUrls: ['https://cdn.example.com/example.jpg'],
+    })
+    expect(getByText('请上传一张人物图')).toBeTruthy()
+    expect(getByText('素材要求：五官清晰')).toBeTruthy()
+    expect(getByAltText('附件示例 1').getAttribute('src')).toBe('https://cdn.example.com/example.jpg')
+    expect(ref.current?.getValues()).toEqual({ attachments: [] })
+  })
+  it('shows a rejected uploaded file and reason without treating its old URL as a valid answer', () => {
+    const { getByText, container, ref } = renderFileSurface({
+      minCount: 1,
+      fileReviewStatus: 'failed',
+      fileReviewMessage: '场景中检测到人物',
+      fileRejectedUrls: ['https://cdn.example.com/rejected-scene.jpg'],
+    })
+    expect(getByText('❌ 审核不合格：场景中检测到人物')).toBeTruthy()
+    expect(container.textContent).toContain('rejected-scene.jpg')
+    expect(ref.current?.getValues()).toEqual({ attachments: [] })
+  })
+
+  it('shows and locks a retained approved upload', () => {
+    const { getByText, container, ref } = renderFileSurface({
+      defaultValue: ['https://cdn.example.com/approved.jpg'],
+      fileReviewStatus: 'passed',
+    })
+    expect(getByText('✅ 审核通过，已保留，无需重新上传')).toBeTruthy()
+    expect(container.textContent).toContain('approved.jpg')
+    expect(container.querySelector('input[type="file"]')?.hasAttribute('disabled')).toBe(true)
+    expect(ref.current?.getValues()).toEqual({ attachments: ['https://cdn.example.com/approved.jpg'] })
+  })
   it('stores successful CDN URLs in user selection order', async () => {
     const first = deferred<{ url: string }>()
     const second = deferred<{ url: string }>()
@@ -175,3 +220,31 @@ describe('FileUploadPreview', () => {
     expect(getByText('legacy file.pdf')).toBeTruthy()
   })
 })
+
+describe('Footage selection in generic material forms', () => {
+  function renderAssetField(mode: 'asset_only' | 'upload_or_asset') {
+    const ref = createRef<SkoponFormRendererRef>()
+    const doc = blocksToA2ui({ blocks: [{
+      id: 'asset-field', type: 'file', name: 'scene', label: '场景', fileSourceMode: mode,
+      fileMaxCount: 1, fileAssetOptions: [{ assetId: '17', label: '山景', assetType: 'image', url: 'https://cdn.test/scene.jpg' }],
+    }] }, { includeHeader: false })
+    return { ref, ...render(createElement(SkoponFormRenderer, { ref, doc, surfaceId: 'asset-test', fieldNames: ['scene'] })) }
+  }
+
+  it('asset-only fields choose from Footage and submit the URL without uploading', async () => {
+    const view = renderAssetField('asset_only')
+    expect(view.container.querySelector('input[type="file"]')).toBeNull()
+    fireEvent.click(view.getByRole('button', { name: '选择素材' }))
+    fireEvent.click(await view.findByRole('button', { name: '选择素材 山景' }))
+    await waitFor(() => expect(view.ref.current?.getValues().scene).toEqual(['https://cdn.test/scene.jpg']))
+    expect(uploadMock).not.toHaveBeenCalled()
+  })
+
+  it('mixed fields retain both upload and library selection actions', async () => {
+    const view = renderAssetField('upload_or_asset')
+    expect(view.container.querySelector('input[type="file"]')).not.toBeNull()
+    fireEvent.click(view.getByRole('button', { name: '选择素材' }))
+    fireEvent.click(await view.findByRole('button', { name: '选择素材 山景' }))
+    await waitFor(() => expect(view.ref.current?.getValues().scene).toEqual(['https://cdn.test/scene.jpg']))
+  })
+})

package/src/catalog/moduleTabs.test.tsx

@@ -0,0 +1,59 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@a2ui/web_core/v0_9/basic_catalog', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@a2ui/web_core/v0_9/basic_catalog')>()
+  return { ...actual, injectBasicCatalogStyles: vi.fn() }
+})
+vi.mock('@a2ui/react/styles', () => ({ injectStyles: vi.fn(), removeStyles: vi.fn() }))
+
+import { createElement } from 'react'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { blocksToA2ui } from '../adapter/a2uiAdapter'
+import SkoponFormRenderer from '../components/SkoponFormRenderer'
+
+beforeAll(() => {
+  class ResizeObserverMock { observe() {} unobserve() {} disconnect() {} }
+  vi.stubGlobal('ResizeObserver', ResizeObserverMock)
+})
+afterEach(cleanup)
+
+describe('form module tabs', () => {
+  it('renders grouped upload fields and module guidance inside tabs', () => {
+    const doc = blocksToA2ui({
+      title: '',
+      description: '',
+      modules: [
+        { id: 'person', label: '人物', reviewCriteria: '人物五官清晰' },
+        { id: 'scene', label: '场景', reviewCriteria: '场景中不能有人物' },
+      ],
+      blocks: [
+        { id: 'p', type: 'file', name: 'person', label: '人物图', moduleId: 'person', fileSourceMode: 'upload_required', fileReviewCriteria: '人物五官清晰' },
+        { id: 'p2', type: 'file', name: 'person2', label: '人物备选图', moduleId: 'person', fileSourceMode: 'upload_or_asset', fileReviewCriteria: '人物五官清晰' },
+        { id: 's', type: 'file', name: 'scene', label: '场景图', moduleId: 'scene', fileSourceMode: 'asset_only', fileReviewCriteria: '场景中不能有人物' },
+      ],
+    })
+    const view = render(createElement(SkoponFormRenderer, { doc, surfaceId: 'modules-test' }))
+    expect(view.container.querySelector('.skopon-compact-upload')).toBeTruthy()
+    expect(view.container.querySelector('.ant-upload-drag')).toBeNull()
+    expect(view.getByText('人物图')).toBeTruthy()
+    expect(view.getByText('物料 · 仅上传')).toBeTruthy()
+    expect(view.container.querySelectorAll('.skopon-compact-upload__state-mark')).toHaveLength(0)
+    expect(view.container.textContent).not.toContain('最多 1')
+    const cards = view.container.querySelectorAll('.skopon-compact-upload')
+    expect(cards).toHaveLength(2)
+    expect(cards[0].querySelector('button')?.textContent?.replace(/\s/g, '')).toContain('上传')
+    expect(cards[0].textContent).not.toContain('选择素材')
+    expect(cards[1].textContent).toContain('物料或素材')
+    expect(cards[1].textContent?.replace(/\s/g, '')).toContain('上传')
+    expect(cards[1].textContent).toContain('选择素材')
+    expect(view.getByText('人物素材要求')).toBeTruthy()
+    expect(view.getByText('人物五官清晰')).toBeTruthy()
+    fireEvent.click(view.getByRole('button', { name: '场景' }))
+    expect(view.getByText('场景图')).toBeTruthy()
+    expect(view.getByText('素材 · 仅选择')).toBeTruthy()
+    expect(view.queryByRole('button', { name: '上传' })).toBeNull()
+    expect(view.getByRole('button', { name: '选择素材' })).toBeTruthy()
+    expect(view.getByText('场景中不能有人物')).toBeTruthy()
+  })
+})

package/src/components/AskUserFormCard.tsx

@@ -61,6 +61,8 @@ export interface AskUserFormCardProps {
   payload: unknown
   /** 可选；无则跳过拉取 vt_forms，仅用 payload blocks fallback */
   formUniqueId?: string | null
+  /** 开放卡使用 latest；已提交/失效卡使用 snapshot，冻结发卡时外观。 */
+  formDefinitionPolicy?: 'latest' | 'snapshot'
   /**
    * ask_source_unique_id（Flow/QA 业务 id）。
    * 有值且 sessionStorage.auth_user.realtime_ws_url 存在、且渲染出表单控件时按卡建连。
@@ -90,6 +92,7 @@ interface AskUserFormCardBodyProps extends AskUserFormCardProps {
 function AskUserFormCardBody({
   payload,
   formUniqueId,
+  formDefinitionPolicy = 'latest',
   askUserMessageId,
   callbackUrl,
   submitMode = 'curl',
@@ -147,7 +150,7 @@ function AskUserFormCardBody({
 
   useEffect(() => {
     let cancelled = false
-    if (!resolvedFormUniqueId) {
+    if (!resolvedFormUniqueId || formDefinitionPolicy === 'snapshot') {
       setLoading(false)
       setFormDisabled(false)
       setFormDef(null)
@@ -178,18 +181,30 @@ function AskUserFormCardBody({
     return () => {
       cancelled = true
     }
-  }, [resolvedFormUniqueId, fetchFormDetail])
+  }, [resolvedFormUniqueId, fetchFormDetail, formDefinitionPolicy])
 
   const payloadDef = useMemo(() => parsePayloadBlocksJson(payload), [payload])
 
+  // Older hibot servers omitted schema when persisting card_data.payload.
+  // Runtime source mode is unique to the dynamic material collection payload,
+  // so retain its snapshot blocks in that compatibility case as well.
+  const dynamicMaterialForm = payloadDef?.schema === 'skopon.material-form/v2' || Boolean(
+    payloadDef?.rawBlocks?.some((block) =>
+      block.type === 'file' &&
+      ['upload_required', 'upload_or_asset', 'asset_only'].includes(String(block.fileSourceMode)),
+    ),
+  )
+
   const intersection = useMemo(() => {
     if (!payloadDef) return null
-    return intersectPayloadBlocksWithForm(payloadDef, formDef ?? undefined)
-  }, [payloadDef, formDef])
+    return intersectPayloadBlocksWithForm(payloadDef, formDef ?? undefined, {
+      definitionPolicy: formDefinitionPolicy,
+    })
+  }, [payloadDef, formDef, formDefinitionPolicy])
 
   const matchedBlocks = intersection?.matchedBlocks ?? []
   const usePayloadFallback =
-    Boolean(payloadDef && payloadHasInputBlocks(payloadDef) && matchedBlocks.length === 0)
+    Boolean(payloadDef && payloadHasInputBlocks(payloadDef) && (dynamicMaterialForm || matchedBlocks.length === 0))
 
   const renderBlocks = useMemo(() => {
     if (usePayloadFallback && payloadDef) {
@@ -224,16 +239,17 @@ function AskUserFormCardBody({
     [renderBlocks],
   )
 
-  const surfaceTitle = intersection?.title ?? payloadDef?.title ?? ''
-  const surfaceDescription = intersection?.description ?? payloadDef?.description ?? ''
+  const surfaceTitle = dynamicMaterialForm ? payloadDef?.title ?? '' : intersection?.title ?? payloadDef?.title ?? ''
+  const surfaceDescription = dynamicMaterialForm ? payloadDef?.description ?? '' : intersection?.description ?? payloadDef?.description ?? ''
+  const surfaceModules = dynamicMaterialForm ? payloadDef?.modules : intersection?.modules ?? payloadDef?.modules
 
   const surfaceDoc = useMemo(() => {
     if (renderBlocks.length === 0) return null
     return buildAskUserSurface(
-      { title: surfaceTitle, description: surfaceDescription },
+      { title: surfaceTitle, description: surfaceDescription, modules: surfaceModules },
       renderBlocks,
     )
-  }, [surfaceTitle, surfaceDescription, renderBlocks])
+  }, [surfaceTitle, surfaceDescription, surfaceModules, renderBlocks])
 
   const docKey = useMemo(() => {
     if (!surfaceDoc) return ''
@@ -370,8 +386,10 @@ function AskUserFormCardBody({
       const effectiveForm =
         renderBlocks.length > 0
           ? {
+              ...(dynamicMaterialForm ? { schema: 'skopon.material-form/v2' as const } : {}),
               title: surfaceTitle,
               description: surfaceDescription,
+              modules: surfaceModules,
               blocks: renderBlocks,
             }
           : (payloadDef ?? undefined)
@@ -411,6 +429,7 @@ function AskUserFormCardBody({
     renderBlocks,
     surfaceTitle,
     surfaceDescription,
+    surfaceModules,
     extraValues,
     reportSnapshot,
     runtime,