@lark-base-open/base-database-cli 1.1.1 → 1.3.8

package/templates/database-starter/page/src/examples/ai-function/ai-media-panel.tsx

@@ -0,0 +1,382 @@
+import { useEffect, useRef, useState } from 'react'
+import { Button } from '../../components/ui/button'
+import {
+  createSiteAIFunctionTask,
+  getSiteAIFunctionTask,
+  hasRunnableMediaTask,
+  type SiteAIMediaTask,
+} from '../../lib/database-runtime'
+import { useUiLanguage } from '../../lib/ui-language'
+import { AI_FUNCTION_COPY, formatAiTaskStatus } from './ai-copy'
+
+// AI Function 媒体示例：文生图和文生视频统一使用任务提交 + 轮询。
+// functionKey 指向对应能力 AI Function；页面提交 prompt，model/尺寸/时长由配置声明。
+
+export interface AIImagePanelProps {
+  functionKey: string
+  referenceImages?: string[]
+  title?: string
+  pollIntervalMs?: number
+  pollDeadlineMs?: number
+}
+
+export interface AIVideoPanelProps {
+  functionKey: string
+  title?: string
+  // pollIntervalMs 轮询节奏，默认 3s；服务端也有轮询上限。
+  pollIntervalMs?: number
+  // pollDeadlineMs 单次任务总轮询时限，超过后放弃并结束 loading。默认 5 分钟。
+  pollDeadlineMs?: number
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 3000
+const DEFAULT_POLL_DEADLINE_MS = 5 * 60 * 1000
+
+export interface MediaTaskRequestTracker {
+  activate: () => void
+  begin: () => number
+  deactivate: () => void
+  isCurrent: (requestId: number) => boolean
+}
+
+export function createMediaTaskRequestTracker(): MediaTaskRequestTracker {
+  let active = false
+  let sequence = 0
+  return {
+    activate: () => {
+      active = true
+    },
+    begin: () => {
+      sequence += 1
+      return sequence
+    },
+    deactivate: () => {
+      active = false
+      sequence += 1
+    },
+    isCurrent: (requestId) => active && requestId === sequence,
+  }
+}
+
+export function activateMediaTaskRequestTracker(
+  tracker: MediaTaskRequestTracker,
+): () => void {
+  tracker.activate()
+  return () => tracker.deactivate()
+}
+
+export interface MediaTaskPollUpdate {
+  error?: string
+  finished: boolean
+  task?: SiteAIMediaTask
+}
+
+/** pollMediaTaskUntilTerminal 是可复用的轮询循环：
+ *  - `isCurrent()` 返回 false 时立即中止（旧任务），不 emit 更新；
+ *  - `now()` 超过 `deadline` 时按超时结束；
+ *  - 收到 succeeded/failed/cancelled 时结束；否则继续下一轮。
+ * 参数 <= 3 个：通过 config 传入，便于测试与复用。 */
+export async function pollMediaTaskUntilTerminal(config: {
+  fetchTask: () => Promise<SiteAIMediaTask>
+  isCurrent: () => boolean
+  timing: {
+    deadline: number
+    intervalMs: number
+    now: () => number
+    sleep: (ms: number) => Promise<void>
+  }
+  onUpdate: (update: MediaTaskPollUpdate) => void
+  timeoutMessage: string
+  failureMessage: string
+}): Promise<void> {
+  const { fetchTask, isCurrent, timing, onUpdate } = config
+  const { deadline, intervalMs, now, sleep } = timing
+  while (isCurrent()) {
+    await sleep(intervalMs)
+    if (!isCurrent()) return
+    if (now() >= deadline) {
+      onUpdate({ error: config.timeoutMessage, finished: true })
+      return
+    }
+    try {
+      const next = await fetchTask()
+      if (!isCurrent()) return
+      if (next.status === 'succeeded') {
+        onUpdate({ finished: true, task: next })
+        return
+      }
+      if (next.status === 'failed' || next.status === 'cancelled') {
+        onUpdate({
+          error: next.errMessage ?? config.failureMessage,
+          finished: true,
+          task: next,
+        })
+        return
+      }
+      onUpdate({ finished: false, task: next })
+    } catch (cause) {
+      if (!isCurrent()) return
+      onUpdate({
+        error: cause instanceof Error ? cause.message : config.failureMessage,
+        finished: true,
+      })
+      return
+    }
+  }
+}
+
+interface MediaTaskState {
+  error: string
+  loading: boolean
+  task: SiteAIMediaTask | null
+}
+
+const INITIAL_STATE: MediaTaskState = { error: '', loading: false, task: null }
+
+interface MediaTaskOptions {
+  capability: 'image' | 'video'
+  failureMessage: string
+  functionKey: string
+  pollDeadlineMs?: number
+  pollIntervalMs?: number
+  referenceImages?: string[]
+  timeoutMessage: string
+}
+
+interface SubmitMediaTaskOptions
+  extends Required<
+    Pick<MediaTaskOptions, 'pollDeadlineMs' | 'pollIntervalMs'>
+  > {
+  capability: MediaTaskOptions['capability']
+  failureMessage: string
+  functionKey: string
+  isCurrent: () => boolean
+  onCreated: (task: SiteAIMediaTask) => void
+  onUpdate: (update: MediaTaskPollUpdate) => void
+  prompt: string
+  referenceImages: string[]
+  timeoutMessage: string
+}
+
+function useMediaTaskRequestTracker(scope: string): MediaTaskRequestTracker {
+  const trackerRef = useRef<MediaTaskRequestTracker | null>(null)
+  if (!trackerRef.current) trackerRef.current = createMediaTaskRequestTracker()
+  const tracker = trackerRef.current
+  useEffect(() => activateMediaTaskRequestTracker(tracker), [scope, tracker])
+  return tracker
+}
+
+function applyPollUpdate(
+  current: MediaTaskState,
+  update: MediaTaskPollUpdate,
+): MediaTaskState {
+  return {
+    ...current,
+    ...(update.task ? { task: update.task } : {}),
+    ...(update.error ? { error: update.error } : {}),
+    ...(update.finished ? { loading: false } : {}),
+  }
+}
+
+async function submitMediaTask(options: SubmitMediaTaskOptions): Promise<void> {
+  const created = await createSiteAIFunctionTask({
+    functionKey: options.functionKey,
+    capability: options.capability,
+    input: {
+      prompt: options.prompt,
+      ...(options.capability === 'image' && options.referenceImages.length
+        ? { image: options.referenceImages }
+        : {}),
+    },
+  })
+  if (!options.isCurrent()) return
+  options.onCreated(created)
+  if (!hasRunnableMediaTask(created)) {
+    options.onUpdate({ finished: true })
+    return
+  }
+  await pollMediaTaskUntilTerminal({
+    fetchTask: () => getSiteAIFunctionTask(options.functionKey, created.taskId),
+    isCurrent: options.isCurrent,
+    timing: {
+      deadline: Date.now() + options.pollDeadlineMs,
+      intervalMs: options.pollIntervalMs,
+      now: () => Date.now(),
+      sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    },
+    onUpdate: options.onUpdate,
+    timeoutMessage: options.timeoutMessage,
+    failureMessage: options.failureMessage,
+  })
+}
+
+function useMediaTask(options: MediaTaskOptions) {
+  const {
+    capability,
+    failureMessage,
+    functionKey,
+    pollDeadlineMs = DEFAULT_POLL_DEADLINE_MS,
+    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    referenceImages = [],
+    timeoutMessage,
+  } = options
+  const [state, setState] = useState<MediaTaskState>(INITIAL_STATE)
+  const tracker = useMediaTaskRequestTracker(`${capability}:${functionKey}`)
+
+  const submit = async (prompt: string) => {
+    const value = prompt.trim()
+    if (!value) return
+    const requestId = tracker.begin()
+    const isCurrent = () => tracker.isCurrent(requestId)
+    setState({ ...INITIAL_STATE, loading: true })
+    try {
+      await submitMediaTask({
+        capability,
+        failureMessage,
+        functionKey,
+        isCurrent,
+        onCreated: (task) => setState((current) => ({ ...current, task })),
+        onUpdate: (update) =>
+          setState((current) => applyPollUpdate(current, update)),
+        pollDeadlineMs,
+        pollIntervalMs,
+        prompt: value,
+        referenceImages,
+        timeoutMessage,
+      })
+    } catch (cause) {
+      if (!isCurrent()) return
+      setState((current) => ({
+        ...current,
+        error: cause instanceof Error ? cause.message : failureMessage,
+        loading: false,
+      }))
+    }
+  }
+  return {
+    error: state.error,
+    loading: state.loading,
+    submit,
+    task: state.task,
+  }
+}
+
+/** 图片生成示例：支持纯文本、单参考图、多参考图，提交任务后轮询并展示图片资源。 */
+export function AIImagePanel({
+  functionKey,
+  pollDeadlineMs,
+  pollIntervalMs,
+  referenceImages = [],
+  title,
+}: AIImagePanelProps) {
+  const i18n = AI_FUNCTION_COPY[useUiLanguage()].image
+  const [prompt, setPrompt] = useState('')
+  const { error, loading, submit, task } = useMediaTask({
+    capability: 'image',
+    failureMessage: i18n.unavailable,
+    functionKey,
+    pollDeadlineMs,
+    pollIntervalMs,
+    referenceImages,
+    timeoutMessage: i18n.timeout,
+  })
+
+  const generate = async () => {
+    const value = prompt.trim()
+    if (!value || loading) return
+    await submit(value)
+  }
+
+  return (
+    <section className="flex flex-col gap-3 rounded-2xl border border-border bg-card p-5">
+      <h2 className="font-semibold text-card-foreground">
+        {title ?? i18n.title}
+      </h2>
+      <textarea
+        aria-label={i18n.description}
+        className="min-h-20 rounded-lg border border-border bg-background p-3 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        onChange={(event) => setPrompt(event.target.value)}
+        placeholder={i18n.descriptionPlaceholder}
+        value={prompt}
+      />
+      <Button disabled={loading || !prompt.trim()} onClick={generate}>
+        {loading ? i18n.generating : i18n.generate}
+      </Button>
+      {error ? <p className="text-sm text-danger">{error}</p> : null}
+      <div className="grid grid-cols-2 gap-3">
+        {(task?.type === 'image_task' ? (task.imageAssets ?? []) : [])
+          .filter((asset): asset is typeof asset & { url: string } =>
+            Boolean(asset.url),
+          )
+          .map((asset) => (
+            <img
+              alt={i18n.generatedImage}
+              className="w-full rounded-lg border border-border"
+              key={asset.url}
+              src={asset.url}
+            />
+          ))}
+      </div>
+    </section>
+  )
+}
+
+/** 文生视频示例：提交任务后按节奏轮询，成功后展示视频。 */
+export function AIVideoPanel({
+  functionKey,
+  pollDeadlineMs,
+  pollIntervalMs,
+  title,
+}: AIVideoPanelProps) {
+  const language = useUiLanguage()
+  const i18n = AI_FUNCTION_COPY[language].video
+  const [prompt, setPrompt] = useState('')
+  const { error, loading, submit, task } = useMediaTask({
+    capability: 'video',
+    failureMessage: i18n.unavailable,
+    functionKey,
+    pollDeadlineMs,
+    pollIntervalMs,
+    timeoutMessage: i18n.timeout,
+  })
+
+  const generate = async () => {
+    const value = prompt.trim()
+    if (!value || loading) return
+    await submit(value)
+  }
+
+  return (
+    <section className="flex flex-col gap-3 rounded-2xl border border-border bg-card p-5">
+      <h2 className="font-semibold text-card-foreground">
+        {title ?? i18n.title}
+      </h2>
+      <textarea
+        aria-label={i18n.description}
+        className="min-h-20 rounded-lg border border-border bg-background p-3 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        onChange={(event) => setPrompt(event.target.value)}
+        placeholder={i18n.descriptionPlaceholder}
+        value={prompt}
+      />
+      <Button disabled={loading || !prompt.trim()} onClick={generate}>
+        {loading ? i18n.processing : i18n.generate}
+      </Button>
+      {task ? (
+        <p className="text-sm text-muted-foreground">
+          {formatAiTaskStatus(task.status, task.progress, language)}
+        </p>
+      ) : null}
+      {error ? <p className="text-sm text-danger">{error}</p> : null}
+      {task?.type === 'video_task' &&
+      task.status === 'succeeded' &&
+      task.videoAsset?.url ? (
+        <video
+          aria-label={i18n.generatedVideo}
+          className="w-full rounded-lg border border-border"
+          controls
+          src={task.videoAsset.url}
+        />
+      ) : null}
+    </section>
+  )
+}

package/templates/database-starter/page/src/lib/attachment-image.tsx

@@ -0,0 +1,144 @@
+import { useEffect, useRef, useState } from 'react'
+import {
+  fetchAttachmentCover,
+  type DatabaseAttachmentRef,
+} from './database-runtime'
+import { useUiLanguage, type UiLanguage } from './ui-language'
+
+const ATTACHMENT_IMAGE_COPY = {
+  en: {
+    decodeFailed: 'Image could not be decoded',
+    loadFailed: 'Failed to load image',
+    loading: 'Loading image',
+    retry: 'Retry image',
+  },
+  zh: {
+    decodeFailed: '图片无法解码',
+    loadFailed: '图片加载失败',
+    loading: '图片加载中',
+    retry: '重试图片',
+  },
+  ja: {
+    decodeFailed: '画像を表示できませんでした',
+    loadFailed: '画像を読み込めませんでした',
+    loading: '画像を読み込み中',
+    retry: '画像を再読み込み',
+  },
+} satisfies Record<
+  UiLanguage,
+  {
+    decodeFailed: string
+    loadFailed: string
+    loading: string
+    retry: string
+  }
+>
+
+/** 缩略图与大图共用；只在靠近可见区域时加载，组件持有并释放本地图片 URL。 */
+export function AttachmentImage({
+  attachment,
+  size = 360,
+  alt,
+  className,
+}: {
+  attachment: DatabaseAttachmentRef
+  size?: number
+  alt: string
+  className?: string
+}) {
+  const uiLanguage = useUiLanguage()
+  const i18n = ATTACHMENT_IMAGE_COPY[uiLanguage]
+  const container = useRef<HTMLSpanElement>(null)
+  const [visible, setVisible] = useState(false)
+  const [attempt, setAttempt] = useState(0)
+  const [image, setImage] = useState<{
+    key: string
+    url: string
+    error: string
+    localError?: 'loadFailed' | 'decodeFailed'
+  }>({ key: '', url: '', error: '' })
+  const { tableId, fieldId, recordId, fileToken } = attachment
+  const key = JSON.stringify([
+    tableId,
+    fieldId,
+    recordId,
+    fileToken,
+    size,
+    attempt,
+  ])
+
+  useEffect(() => {
+    if (typeof IntersectionObserver === 'undefined') {
+      setVisible(true)
+      return
+    }
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) {
+          setVisible(true)
+          observer.disconnect()
+        }
+      },
+      { rootMargin: '200px' },
+    )
+    if (container.current) observer.observe(container.current)
+    return () => observer.disconnect()
+  }, [])
+
+  useEffect(() => {
+    if (!visible) return
+    const controller = new AbortController()
+    let url = ''
+    fetchAttachmentCover({ tableId, fieldId, recordId, fileToken }, size, {
+      signal: controller.signal,
+    })
+      .then((blob) => {
+        if (controller.signal.aborted) return
+        url = URL.createObjectURL(blob)
+        setImage({ key, url, error: '' })
+      })
+      .catch((cause: unknown) => {
+        if (!controller.signal.aborted) {
+          setImage({
+            key,
+            url: '',
+            error: cause instanceof Error ? cause.message : '',
+            localError: cause instanceof Error ? undefined : 'loadFailed',
+          })
+        }
+      })
+    return () => {
+      controller.abort()
+      if (url) URL.revokeObjectURL(url)
+    }
+  }, [visible, key, tableId, fieldId, recordId, fileToken, size])
+
+  const current = image.key === key ? image : undefined
+  return (
+    <span ref={container} className={className} aria-busy={!current}>
+      {current?.url ? (
+        <img
+          src={current.url}
+          alt={alt}
+          onError={() =>
+            setImage({ key, url: '', error: '', localError: 'decodeFailed' })
+          }
+        />
+      ) : current?.error || current?.localError ? (
+        <span>
+          <span role="status">
+            {current.localError ? i18n[current.localError] : current.error}
+          </span>
+          <button
+            type="button"
+            onClick={() => setAttempt((value) => value + 1)}
+          >
+            {i18n.retry}
+          </button>
+        </span>
+      ) : (
+        <span role="status">{i18n.loading}</span>
+      )}
+    </span>
+  )
+}

package/templates/database-starter/page/src/lib/database-function-inputs.generated.ts

@@ -0,0 +1,4 @@
+/* Generated by base-database-cli from Function metadata. Do not edit. */
+// prettier-ignore
+export type DatabaseFunctionInputMap = {
+}