@lark-base-open/base-database-cli 1.0.0

package/templates/database-starter/page/src/components/floating-button/utils/project-meta.ts

@@ -0,0 +1,252 @@
+import {
+  buildDatabaseInvokeGetPath,
+  resolveDatabaseContext,
+  fetch as databaseFetch,
+  type DatabaseContext,
+} from '../../../lib/database-runtime'
+
+interface ProjectChat {
+  id: string
+  name: string
+  iconInfo: string
+}
+
+export interface ProjectBaseBinding {
+  baseToken: string
+  tableIds: string[]
+}
+
+export interface ProjectMeta {
+  baseBindings: ProjectBaseBinding[]
+  chatList: ProjectChat[]
+  name: string
+  description: string
+  isOwner: boolean
+  /** 应用所属组织（企业）名，浮层菜单展示用；服务端未下发时为空串。 */
+  organization: string
+}
+
+const projectMetaCache = new Map<string, Promise<ProjectMeta>>()
+
+/** 判断输入是否为普通对象。
+ * @param value 待判断的数据。
+ * @returns 是普通对象时返回 true。
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** 读取可选字符串字段。
+ * @param record 数据对象。
+ * @param key 字段名。
+ * @returns 字段字符串值；缺失或类型不匹配时返回空字符串。
+ */
+function readOptionalString(
+  record: Record<string, unknown>,
+  key: string,
+): string {
+  const value = record[key]
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+/** 读取字符串数组字段。
+ * @param value 待解析的数据。
+ * @returns 仅包含字符串项的数组。
+ */
+function readStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string')
+    : []
+}
+
+/** 构造空项目 meta。
+ * @returns chatList 为空的项目 meta。
+ */
+function createEmptyProjectMeta(): ProjectMeta {
+  return {
+    baseBindings: [],
+    chatList: [],
+    name: '',
+    description: '',
+    isOwner: false,
+    organization: '',
+  }
+}
+
+/** 获取已有网页描述 meta 标签。
+ * @returns 已存在的 description meta 标签；不存在时返回 null。
+ */
+function getExistingDescriptionMeta(): HTMLMetaElement | null {
+  const existingMeta = document.querySelector('meta[name="description"]')
+  if (existingMeta instanceof HTMLMetaElement) {
+    return existingMeta
+  }
+
+  return null
+}
+
+/** 将项目元信息同步到网页标题和描述。
+ * @param meta 项目元信息。
+ */
+function applyDocumentMeta(meta: ProjectMeta): void {
+  if (meta.name) {
+    document.title = meta.name
+  }
+
+  if (meta.description) {
+    const descriptionMeta = getExistingDescriptionMeta()
+    if (descriptionMeta) {
+      descriptionMeta.content = meta.description
+    }
+  }
+}
+
+/** 解析 Site 绑定的 Base 列表。
+ * @param rawBaseBindings 接口返回的 baseBindings 字段。
+ * @returns 可用于页面跳转的 Base 绑定列表。
+ */
+function parseProjectBaseBindings(
+  rawBaseBindings: unknown,
+): ProjectBaseBinding[] {
+  if (!Array.isArray(rawBaseBindings)) {
+    return []
+  }
+
+  return rawBaseBindings.reduce<ProjectBaseBinding[]>((bindings, binding) => {
+    if (!isRecord(binding)) {
+      return bindings
+    }
+
+    const baseToken = readOptionalString(binding, 'baseToken')
+    if (!baseToken) {
+      return bindings
+    }
+
+    bindings.push({
+      baseToken,
+      tableIds: readStringArray(binding.tableIds),
+    })
+    return bindings
+  }, [])
+}
+
+/** 解析 Site 绑定的 chatbot 列表。
+ *
+ * 接口的 chatbot 字段全部可选：缺 id 的条目无法跳转，直接丢弃；名称与图标缺失时
+ * 留空交由展示层兜底。单个 chatbot 字段不全不能影响整个项目 meta 的解析。
+ *
+ * @param rawChatbots 接口返回的 chatbots 字段。
+ * @returns 可用于展示的 chatbot 列表。
+ */
+function parseProjectChats(rawChatbots: unknown): ProjectChat[] {
+  if (!Array.isArray(rawChatbots)) {
+    return []
+  }
+
+  return rawChatbots.reduce<ProjectChat[]>((chats, chatbot) => {
+    if (!isRecord(chatbot)) {
+      return chats
+    }
+
+    const id = readOptionalString(chatbot, 'id')
+    if (!id) {
+      return chats
+    }
+
+    chats.push({
+      id,
+      name: readOptionalString(chatbot, 'name'),
+      iconInfo: readOptionalString(chatbot, 'iconInfo'),
+    })
+    return chats
+  }, [])
+}
+
+/** 将资源接口响应转换为页面需要的项目 meta。
+ * @param rawResponse 接口原始响应。
+ * @returns 提取后的应用名称、描述和 chatbot 列表；接口或结构异常时返回空数据。
+ */
+export function parseProjectMetaResponse(rawResponse: unknown): ProjectMeta {
+  if (!isRecord(rawResponse)) {
+    return createEmptyProjectMeta()
+  }
+
+  if (rawResponse.code !== 0) {
+    return createEmptyProjectMeta()
+  }
+
+  const data = rawResponse.data
+  if (!isRecord(data)) {
+    return createEmptyProjectMeta()
+  }
+
+  const site = data.site
+  if (!isRecord(site)) {
+    return createEmptyProjectMeta()
+  }
+
+  return {
+    baseBindings: parseProjectBaseBindings(site.baseBindings),
+    chatList: parseProjectChats(site.chatbots),
+    description: readOptionalString(site, 'description'),
+    name: readOptionalString(site, 'name'),
+    isOwner: data.isOwner === true,
+    organization: readOptionalString(site, 'organization'),
+  }
+}
+
+/** 请求项目资源元信息。
+ *
+ * 走统一网关的 GetInvokeProject，由父页面以同源身份代发；子页面不直连业务域名。
+ *
+ * @param context 当前应用上下文。
+ * @returns 解析后的项目 meta。
+ */
+async function requestProjectMeta(
+  context: DatabaseContext,
+): Promise<ProjectMeta> {
+  try {
+    const response = await databaseFetch(
+      buildDatabaseInvokeGetPath(context, true),
+      {
+        method: 'GET',
+      },
+    )
+
+    if (!response.ok) {
+      return createEmptyProjectMeta()
+    }
+
+    const rawResponse: unknown = await response.json()
+    const projectMeta = parseProjectMetaResponse(rawResponse)
+    applyDocumentMeta(projectMeta)
+    return projectMeta
+  } catch {
+    return createEmptyProjectMeta()
+  }
+}
+
+/** 获取当前项目资源元信息，按应用 token 与环境复用缓存。
+ * @returns 结构化项目 meta。
+ */
+export async function fetchProjectMeta(): Promise<ProjectMeta> {
+  const context = await resolveDatabaseContext()
+
+  if (!context.token) {
+    return createEmptyProjectMeta()
+  }
+
+  const cacheKey = `${context.env}:${context.token}`
+  const cachedMeta = projectMetaCache.get(cacheKey)
+  if (cachedMeta) {
+    return cachedMeta
+  }
+
+  const metaRequest = requestProjectMeta(context).catch((error) => {
+    projectMetaCache.delete(cacheKey)
+    throw error
+  })
+
+  projectMetaCache.set(cacheKey, metaRequest)
+  return metaRequest
+}

package/templates/database-starter/page/src/components/ui/button.tsx

@@ -0,0 +1,56 @@
+import { Slot } from '@radix-ui/react-slot'
+import { cva, type VariantProps } from 'class-variance-authority'
+import type { ButtonHTMLAttributes } from 'react'
+import { cn } from '../../lib/cn'
+
+const buttonVariants = cva(
+  'inline-flex min-h-10 items-center justify-center gap-2 rounded-lg px-4 text-sm font-semibold transition-colors outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        primary:
+          'bg-primary text-primary-foreground hover:bg-primary/90 active:bg-primary/80',
+        secondary:
+          'bg-secondary text-secondary-foreground hover:bg-secondary/75 active:bg-secondary/60',
+        danger:
+          'bg-danger text-danger-foreground hover:bg-danger/90 active:bg-danger/80',
+        ghost: 'hover:bg-secondary active:bg-secondary/75',
+      },
+      size: {
+        sm: 'min-h-9 px-3',
+        md: 'min-h-10 px-4',
+        lg: 'min-h-11 px-5 text-base',
+        icon: 'size-10 px-0',
+      },
+    },
+    defaultVariants: {
+      variant: 'primary',
+      size: 'md',
+    },
+  },
+)
+
+interface ButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+}
+
+export function Button({
+  asChild = false,
+  className,
+  size,
+  type,
+  variant,
+  ...props
+}: ButtonProps) {
+  const Component = asChild ? Slot : 'button'
+
+  return (
+    <Component
+      className={cn(buttonVariants({ size, variant }), className)}
+      type={asChild ? undefined : (type ?? 'button')}
+      {...props}
+    />
+  )
+}

package/templates/database-starter/page/src/index.css

@@ -0,0 +1,67 @@
+@import 'tailwindcss';
+
+:root {
+  color-scheme: light;
+  --background: #f6f7f9;
+  --foreground: #172033;
+  --card: #ffffff;
+  --card-foreground: #172033;
+  --primary: #245bdb;
+  --primary-foreground: #ffffff;
+  --secondary: #eef2f8;
+  --secondary-foreground: #25324a;
+  --muted: #eef1f5;
+  --muted-foreground: #667085;
+  --border: #dfe3ea;
+  --danger: #c9362b;
+  --danger-foreground: #ffffff;
+  --ring: #4c7ff0;
+  font-family:
+    -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica,
+    Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji';
+  line-height: 1.5;
+  font-weight: 400;
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-border: var(--border);
+  --color-danger: var(--danger);
+  --color-danger-foreground: var(--danger-foreground);
+  --color-ring: var(--ring);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  min-width: 320px;
+  margin: 0;
+  background: var(--background);
+  color: var(--foreground);
+}
+
+button,
+input,
+textarea,
+select {
+  font: inherit;
+}
+
+::selection {
+  background: color-mix(in srgb, var(--primary) 20%, transparent);
+}

package/templates/database-starter/page/src/lib/cn.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest'
+
+import { cn } from './cn'
+
+describe('cn', () => {
+  it('merges conditional classes and resolves Tailwind conflicts', () => {
+    expect(cn('px-2', { hidden: false }, 'px-4')).toBe('px-4')
+  })
+})

package/templates/database-starter/page/src/lib/cn.ts

@@ -0,0 +1,7 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/** 合并条件 class，并解决 Tailwind utility 冲突。 */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/templates/database-starter/page/src/lib/database-runtime-attachment.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const getRuntimeContext = vi.fn()
+const siteRuntimeFetch = vi.fn()
+
+vi.mock('@lark-base-open/base-site-channel/runtime', () => ({
+  fetch: siteRuntimeFetch,
+  invokeHttp: vi.fn(),
+  siteRuntime: { getRuntimeContext },
+}))
+
+const attachmentRef = {
+  fieldId: 'fldPhotos',
+  fileToken: 'boxcnFileToken',
+  recordId: 'recTicket',
+  tableId: 'tblTickets',
+}
+
+/** 重新加载模块，清掉 resolveDatabaseContext 的会话级缓存。 */
+async function loadDatabaseRuntime() {
+  vi.resetModules()
+  return import('./database-runtime')
+}
+
+beforeEach(() => {
+  getRuntimeContext.mockReset()
+  siteRuntimeFetch.mockReset()
+  vi.stubGlobal('location', {
+    ancestorOrigins: ['https://ancestor.example'],
+    pathname: '/app/pathToken/',
+  })
+  vi.stubGlobal('document', {
+    referrer: 'https://referrer.example/parent/path',
+  })
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('buildAttachmentCoverUrl', () => {
+  it('uses the ancestor origin before the referrer', async () => {
+    getRuntimeContext.mockResolvedValue({ siteToken: 'hostToken' })
+
+    const { buildAttachmentCoverUrl, resolveDatabaseContext } =
+      await loadDatabaseRuntime()
+    const context = await resolveDatabaseContext()
+
+    expect(buildAttachmentCoverUrl(context, attachmentRef)).toMatch(
+      /^https:\/\/ancestor\.example\/space\/api\/box\/stream\/download\/v2\/cover\//,
+    )
+  })
+
+  it('falls back to the referrer origin when ancestorOrigins is unavailable', async () => {
+    vi.stubGlobal('location', { pathname: '/app/pathToken/' })
+    getRuntimeContext.mockResolvedValue({ siteToken: 'hostToken' })
+
+    const { buildAttachmentCoverUrl, resolveDatabaseContext } =
+      await loadDatabaseRuntime()
+    const context = await resolveDatabaseContext()
+
+    expect(buildAttachmentCoverUrl(context, attachmentRef)).toMatch(
+      /^https:\/\/referrer\.example\/space\/api\/box\/stream\/download\/v2\/cover\//,
+    )
+  })
+
+  it('snaps the requested size up and defaults to 360', async () => {
+    getRuntimeContext.mockResolvedValue({})
+    const { buildAttachmentCoverUrl } = await loadDatabaseRuntime()
+    const context = {
+      env: 'prod',
+      gatewayOrigin: 'https://gateway.example',
+      token: 'siteToken',
+    } as const
+
+    const requested = new URL(
+      buildAttachmentCoverUrl(context, attachmentRef, 480),
+    )
+    const defaulted = new URL(buildAttachmentCoverUrl(context, attachmentRef))
+
+    expect(requested.searchParams.get('width')).toBe('720')
+    expect(requested.searchParams.get('height')).toBe('720')
+    expect(defaulted.searchParams.get('width')).toBe('360')
+    expect(defaulted.searchParams.get('height')).toBe('360')
+  })
+
+  it('returns an empty string when the gateway origin is missing', async () => {
+    getRuntimeContext.mockResolvedValue({})
+    const { buildAttachmentCoverUrl } = await loadDatabaseRuntime()
+
+    expect(
+      buildAttachmentCoverUrl(
+        { env: 'prod', gatewayOrigin: '', token: 'siteToken' },
+        attachmentRef,
+      ),
+    ).toBe('')
+  })
+
+  it('puts the complete attachment location and site token in extra', async () => {
+    getRuntimeContext.mockResolvedValue({})
+    const { buildAttachmentCoverUrl } = await loadDatabaseRuntime()
+    const url = new URL(
+      buildAttachmentCoverUrl(
+        {
+          env: 'prod',
+          gatewayOrigin: 'https://gateway.example',
+          token: 'siteToken',
+        },
+        attachmentRef,
+      ),
+    )
+    const extra = JSON.parse(String(url.searchParams.get('extra'))) as unknown
+
+    expect(extra).toEqual({
+      bitablePerm: {
+        tableId: 'tblTickets',
+        attachments: {
+          fldPhotos: { recTicket: ['boxcnFileToken'] },
+        },
+        baseAppToken: 'siteToken',
+      },
+    })
+  })
+})
+
+describe('fetchAttachmentDownloadUrl', () => {
+  it('uses the bridge path and returns the plaintext self-authenticating URL', async () => {
+    siteRuntimeFetch.mockResolvedValue({
+      json: () =>
+        Promise.resolve({
+          data: { url: 'https://download.example/authcode/?code=signed' },
+        }),
+      ok: true,
+    })
+    const { fetchAttachmentDownloadUrl } = await loadDatabaseRuntime()
+    const context = {
+      env: 'prod',
+      gatewayOrigin: 'https://gateway.example',
+      token: 'siteToken',
+    } as const
+
+    await expect(
+      fetchAttachmentDownloadUrl(context, attachmentRef),
+    ).resolves.toBe('https://download.example/authcode/?code=signed')
+    expect(siteRuntimeFetch).toHaveBeenCalledWith(
+      '/space/api/box/file/temporary_download_url',
+      {
+        body: expect.any(String),
+        headers: { 'content-type': 'application/json' },
+        method: 'POST',
+      },
+    )
+
+    const request = siteRuntimeFetch.mock.calls[0]?.[1] as { body: string }
+    expect(JSON.parse(request.body)).toEqual({
+      extra: JSON.stringify({
+        bitablePerm: {
+          tableId: 'tblTickets',
+          attachments: {
+            fldPhotos: { recTicket: ['boxcnFileToken'] },
+          },
+          baseAppToken: 'siteToken',
+        },
+      }),
+      file_token: 'boxcnFileToken',
+    })
+  })
+})

package/templates/database-starter/page/src/lib/database-runtime-context.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const getRuntimeContext = vi.fn()
+
+vi.mock('@lark-base-open/base-site-channel/runtime', () => ({
+  fetch: vi.fn(),
+  invokeHttp: vi.fn(),
+  siteRuntime: { getRuntimeContext },
+}))
+
+/** 重新加载模块，清掉 resolveDatabaseContext 的会话级缓存。 */
+async function loadDatabaseRuntime() {
+  vi.resetModules()
+  return import('./database-runtime')
+}
+
+beforeEach(() => {
+  getRuntimeContext.mockReset()
+  vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+  vi.spyOn(console, 'error').mockImplementation(() => undefined)
+  vi.stubGlobal('location', { pathname: '/app/pathToken/' })
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+describe('resolveDatabaseContext', () => {
+  it('prefers the host provided token and env over the artifact path', async () => {
+    getRuntimeContext.mockResolvedValue({
+      colorScheme: 'light',
+      env: 'preview',
+      locale: 'zh-CN',
+      mode: 'reading',
+      protocolVersion: 'site.v1',
+      siteToken: 'hostToken',
+    })
+
+    const { resolveDatabaseContext } = await loadDatabaseRuntime()
+    expect(await resolveDatabaseContext()).toEqual({
+      env: 'preview',
+      gatewayOrigin: '',
+      token: 'hostToken',
+    })
+  })
+
+  it('falls back to the artifact path when the host omits the fields', async () => {
+    getRuntimeContext.mockResolvedValue({
+      colorScheme: 'light',
+      locale: 'zh-CN',
+      mode: 'reading',
+      protocolVersion: 'site.v1',
+    })
+
+    const { resolveDatabaseContext } = await loadDatabaseRuntime()
+    expect(await resolveDatabaseContext()).toEqual({
+      env: 'prod',
+      gatewayOrigin: '',
+      token: 'pathToken',
+    })
+  })
+
+  it('falls back to the artifact path when the host call fails', async () => {
+    getRuntimeContext.mockRejectedValue(new Error('no host'))
+
+    const { resolveDatabaseContext } = await loadDatabaseRuntime()
+    expect(await resolveDatabaseContext()).toEqual({
+      env: 'prod',
+      gatewayOrigin: '',
+      token: 'pathToken',
+    })
+    expect(console.warn).toHaveBeenCalled()
+  })
+
+  it('ignores an unrecognised env but keeps the host token', async () => {
+    getRuntimeContext.mockResolvedValue({
+      env: 'staging',
+      siteToken: 'hostToken',
+    })
+
+    const { resolveDatabaseContext } = await loadDatabaseRuntime()
+    expect(await resolveDatabaseContext()).toEqual({
+      env: 'prod',
+      gatewayOrigin: '',
+      token: 'hostToken',
+    })
+  })
+
+  it('reports loudly when neither source yields a token', async () => {
+    vi.stubGlobal('location', { pathname: '/' })
+    getRuntimeContext.mockResolvedValue({})
+
+    const { resolveDatabaseContext } = await loadDatabaseRuntime()
+    expect(await resolveDatabaseContext()).toEqual({
+      env: 'prod',
+      gatewayOrigin: '',
+      token: '',
+    })
+    expect(console.error).toHaveBeenCalled()
+  })
+
+  it('caches the resolved context within a session', async () => {
+    getRuntimeContext.mockResolvedValue({ siteToken: 'hostToken' })
+
+    const { resolveDatabaseContext } = await loadDatabaseRuntime()
+    await resolveDatabaseContext()
+    await resolveDatabaseContext()
+    expect(getRuntimeContext).toHaveBeenCalledTimes(1)
+  })
+})