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

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

@@ -0,0 +1,103 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  buildDatabaseInvokeFunctionPath,
+  buildDatabaseInvokeGetPath,
+  getDatabaseContext,
+} from './database-runtime'
+
+function stubPathname(pathname: string): void {
+  vi.stubGlobal('location', { pathname })
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('getDatabaseContext', () => {
+  it('reads token and prod env from the online artifact path', () => {
+    stubPathname('/app/bascnDemo/index.html')
+    expect(getDatabaseContext()).toEqual({
+      env: 'prod',
+      gatewayOrigin: '',
+      token: 'bascnDemo',
+    })
+  })
+
+  it('reads preview env from the preview artifact path', () => {
+    stubPathname('/preview/app/bascnDemo/')
+    expect(getDatabaseContext()).toEqual({
+      env: 'preview',
+      gatewayOrigin: '',
+      token: 'bascnDemo',
+    })
+  })
+
+  it('returns an empty token when the path is not an artifact path', () => {
+    stubPathname('/')
+    expect(getDatabaseContext()).toEqual({
+      env: 'prod',
+      gatewayOrigin: '',
+      token: '',
+    })
+  })
+})
+
+describe('buildDatabaseInvokeGetPath', () => {
+  it('builds the prod path with the chatbot flag', () => {
+    expect(
+      buildDatabaseInvokeGetPath(
+        { env: 'prod', gatewayOrigin: '', token: 'bascnDemo' },
+        true,
+      ),
+    ).toBe('/space/api/bitable/site/v1/bascnDemo/invoke_get?withChatbot=true')
+  })
+
+  it('adds the preview env for draft artifacts', () => {
+    expect(
+      buildDatabaseInvokeGetPath(
+        { env: 'preview', gatewayOrigin: '', token: 'bascnDemo' },
+        false,
+      ),
+    ).toBe('/space/api/bitable/site/v1/bascnDemo/invoke_get?env=preview')
+  })
+})
+
+describe('buildDatabaseInvokeFunctionPath', () => {
+  // token 与 function_id 是 path 参数，env 走 query，prod 依赖服务端缺省。
+  it('puts token and functionId in the path and omits env for prod', () => {
+    expect(
+      buildDatabaseInvokeFunctionPath(
+        { env: 'prod', gatewayOrigin: '', token: 'bascnDemo' },
+        'list_tasks',
+      ),
+    ).toBe('/space/api/bitable/site/v1/bascnDemo/invoke_function/list_tasks')
+  })
+
+  it('adds the preview env query for draft artifacts', () => {
+    expect(
+      buildDatabaseInvokeFunctionPath(
+        { env: 'preview', gatewayOrigin: '', token: 'bascnDemo' },
+        'list-tasks',
+      ),
+    ).toBe(
+      '/space/api/bitable/site/v1/bascnDemo/invoke_function/list-tasks?env=preview',
+    )
+  })
+
+  it('rejects functionIds that cannot be a safe path segment', () => {
+    const context = {
+      env: 'prod',
+      gatewayOrigin: '',
+      token: 'bascnDemo',
+    } as const
+    expect(() => buildDatabaseInvokeFunctionPath(context, 'a/b')).toThrow(
+      TypeError,
+    )
+    expect(() => buildDatabaseInvokeFunctionPath(context, '../x')).toThrow(
+      TypeError,
+    )
+    expect(() => buildDatabaseInvokeFunctionPath(context, '')).toThrow(
+      TypeError,
+    )
+  })
+})

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

@@ -0,0 +1,389 @@
+import {
+  invokeHttp,
+  siteRuntime,
+  fetch as siteRuntimeFetch,
+  type SiteProjectEnv,
+} from '@lark-base-open/base-site-channel/runtime'
+
+/** 内置 Runtime Function（function.runtime.*，由宿主固定分发）。
+ * 随 channel 包发布，直接透传官方实现，不在 starter 侧包装。 */
+export {
+  getCurrentUser,
+  logout,
+  requestEdit,
+} from '@lark-base-open/base-site-channel/runtime'
+export type { SiteRuntimeUserInfo } from '@lark-base-open/base-site-channel/runtime'
+
+/** 应用产物在 BaseApp 页面 iframe 中的运行上下文。 */
+export interface DatabaseContext {
+  env: DatabaseEnv
+  gatewayOrigin: string
+  token: string
+}
+
+/** 附件在底表里的位置。四个值都来自 catalog.json 与 SQL 结果。 */
+export interface DatabaseAttachmentRef {
+  tableId: string
+  fieldId: string
+  recordId: string
+  fileToken: string
+}
+
+/** 产物环境沿用 site.v1 协议的规范类型，避免两侧各自声明后漂移。 */
+export type DatabaseEnv = SiteProjectEnv
+
+/** Function 调用的统一响应包裹结构，与运行态接口一致。 */
+export interface DatabaseFunctionResponse<Data = unknown> {
+  code: number
+  data?: Data
+  msg?: string
+}
+
+/** 产物托管路径：线上为 /app/{token}/，预览为 /preview/app/{token}/。 */
+const ARTIFACT_PATH_PATTERN = /^\/?(preview\/)?app\/([^/]+)(\/|$)/
+
+/** functionId 会进入 URL 路径段，收口到 Base Database 的既有命名约束。 */
+const FUNCTION_ID_PATTERN = /^[A-Za-z0-9_-]+$/
+
+const DATABASE_RUNTIME_GATEWAY_PREFIX = '/space/api/bitable/site/v1'
+const ATTACHMENT_COVER_PATH = '/space/api/box/stream/download/v2/cover/'
+const ATTACHMENT_DOWNLOAD_URL_PATH =
+  '/space/api/box/file/temporary_download_url'
+const ATTACHMENT_COVER_SIZES = [120, 360, 720, 1280] as const
+const PREVIEW_ENV: DatabaseEnv = 'preview'
+
+let databaseContextPromise: Promise<DatabaseContext> | null = null
+
+export {
+  invokeHttp,
+  siteRuntime,
+  /** 兼容原生 fetch 签名的父页面代理请求方法。 */
+  siteRuntimeFetch as fetch,
+}
+
+/** 资源请求不能用会落到产物域的相对地址；无法从 iframe 关系确定网关时返回空串。 */
+function inferGatewayOrigin(): string {
+  const location =
+    typeof globalThis.location === 'undefined' ? undefined : globalThis.location
+  const ancestorOrigin = location?.ancestorOrigins?.[0]
+
+  if (ancestorOrigin) {
+    return ancestorOrigin
+  }
+
+  const referrer =
+    typeof globalThis.document === 'undefined'
+      ? ''
+      : globalThis.document.referrer
+
+  if (!referrer) {
+    return ''
+  }
+
+  try {
+    return new URL(referrer).origin
+  } catch {
+    return ''
+  }
+}
+
+/** 从产物托管路径推断当前应用 token 与运行环境。
+ *
+ * 这是宿主未下发上下文时的兜底：BaseApp 形态下 site 与 BaseApp 共用同一个 token，
+ * 线上产物挂在 /app/{token}/、预览产物挂在 /preview/app/{token}/。
+ * 该推断依赖部署侧的 CDN 路径约定，优先级低于宿主下发值。
+ *
+ * @returns 应用 token、运行环境与业务网关 origin；无法推断的值为空字符串。
+ */
+export function getDatabaseContext(): DatabaseContext {
+  const pathname =
+    typeof globalThis.location === 'undefined'
+      ? ''
+      : globalThis.location.pathname
+  const matched = ARTIFACT_PATH_PATTERN.exec(pathname)
+  const gatewayOrigin = inferGatewayOrigin()
+
+  if (!matched) {
+    return { env: 'prod', gatewayOrigin, token: '' }
+  }
+
+  return {
+    env: matched[1] ? PREVIEW_ENV : 'prod',
+    gatewayOrigin,
+    token: decodeURIComponent(matched[2] ?? ''),
+  }
+}
+
+/** 判断输入是否为普通对象。
+ * @param value 待判断的数据。
+ * @returns 是普通对象时返回 true。
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** 判断输入是否为受支持的产物环境。
+ * @param value 待判断的数据。
+ * @returns 是 preview 或 prod 时返回 true。
+ */
+function isDatabaseEnv(value: unknown): value is DatabaseEnv {
+  return value === PREVIEW_ENV || value === 'prod'
+}
+
+/** 从宿主下发的 Runtime 上下文中提取应用定位信息。
+ *
+ * 协议把 siteToken 与 env 声明为可选，但这里刻意按 unknown 处理并逐项校验：
+ * 取值跨 iframe 边界、来自另一个 origin，声明类型不构成运行时保证；
+ * 旧版本宿主也可能完全不返回这两个字段（宿主实现见 base-app 的 SiteRuntimeHost）。
+ *
+ * @param context 宿主返回的 Runtime 上下文。
+ * @returns 宿主提供的 token 与环境；缺失或非法时对应项为 undefined。
+ */
+function readHostDatabaseContext(context: unknown): Partial<DatabaseContext> {
+  if (!isRecord(context)) {
+    return {}
+  }
+
+  const token =
+    typeof context.siteToken === 'string' ? context.siteToken.trim() : ''
+
+  return {
+    ...(token ? { token } : {}),
+    ...(isDatabaseEnv(context.env) ? { env: context.env } : {}),
+  }
+}
+
+/** 解析当前应用上下文，宿主下发值优先、产物路径推断兜底。
+ *
+ * 结果按会话缓存；解析失败时清空缓存，允许后续调用重试。
+ *
+ * @returns 应用 token、运行环境与业务网关 origin。
+ */
+export async function resolveDatabaseContext(): Promise<DatabaseContext> {
+  if (databaseContextPromise) {
+    return databaseContextPromise
+  }
+
+  databaseContextPromise = (async (): Promise<DatabaseContext> => {
+    const fallback = getDatabaseContext()
+    let host: Partial<DatabaseContext> = {}
+
+    try {
+      host = readHostDatabaseContext(await siteRuntime.getRuntimeContext())
+    } catch (error) {
+      // 宿主未实现或握手尚未完成时退回路径推断，不阻断业务。
+      console.warn('读取宿主 Runtime 上下文失败，回退产物路径推断', error)
+    }
+
+    const context: DatabaseContext = {
+      env: host.env ?? fallback.env,
+      gatewayOrigin: fallback.gatewayOrigin,
+      token: host.token ?? fallback.token,
+    }
+
+    if (!context.token) {
+      console.error(
+        '未能确定应用 token：宿主未下发 siteToken，且当前路径不符合产物托管规则',
+      )
+    }
+
+    return context
+  })().catch((error: unknown) => {
+    databaseContextPromise = null
+    throw error
+  })
+
+  return databaseContextPromise
+}
+
+/** 位置声明的四个值缺一不可，缺任意一个服务端都无法核验归属。 */
+function hasCompleteRef(ref: DatabaseAttachmentRef): boolean {
+  return Boolean(
+    ref.tableId.trim() &&
+      ref.fieldId.trim() &&
+      ref.recordId.trim() &&
+      ref.fileToken.trim(),
+  )
+}
+
+/** baseAppToken 把附件鉴权绑定到应用；省略会退回底表权限判定并导致访客被拒。 */
+function buildAttachmentExtra(
+  context: DatabaseContext,
+  ref: DatabaseAttachmentRef,
+): string {
+  return JSON.stringify({
+    bitablePerm: {
+      tableId: ref.tableId,
+      attachments: {
+        [ref.fieldId]: { [ref.recordId]: [ref.fileToken] },
+      },
+      baseAppToken: context.token,
+    },
+  })
+}
+
+/** 封面由浏览器直连网关获取，必须是绝对 URL；尺寸向上匹配服务端档位。
+ * 构造 URL 不会检查附件是否挂载成功，不能用于确认写入结果。
+ *
+ * @returns 可直接交给 img.src 的地址；上下文或附件位置不完整时返回空字符串。
+ */
+export function buildAttachmentCoverUrl(
+  context: DatabaseContext,
+  ref: DatabaseAttachmentRef,
+  size = 360,
+): string {
+  if (!context.gatewayOrigin || !context.token || !hasCompleteRef(ref)) {
+    return ''
+  }
+
+  const coverSize =
+    ATTACHMENT_COVER_SIZES.find((candidate) => candidate >= size) ??
+    ATTACHMENT_COVER_SIZES[ATTACHMENT_COVER_SIZES.length - 1]
+  const searchParams = new URLSearchParams({
+    extra: buildAttachmentExtra(context, ref),
+    width: String(coverSize),
+    height: String(coverSize),
+    policy: 'allow_up',
+    fallback_source: '1',
+  })
+
+  return (
+    `${context.gatewayOrigin}${ATTACHMENT_COVER_PATH}` +
+    `${encodeURIComponent(ref.fileToken)}?${searchParams.toString()}`
+  )
+}
+
+/** 经父页面 bridge 取短时效自证链接；原文件由浏览器下载，不进入页面 JavaScript。
+ * 下载链接不代表附件增删已完成，也不提供并发或重试保证。
+ *
+ * @returns 可直接交给 a.href 的下载链接。
+ */
+export async function fetchAttachmentDownloadUrl(
+  context: DatabaseContext,
+  ref: DatabaseAttachmentRef,
+): Promise<string> {
+  if (!context.token) {
+    throw new Error('应用 token 未确定，无法获取附件下载链接')
+  }
+
+  if (!hasCompleteRef(ref)) {
+    throw new Error('附件位置不完整，无法获取下载链接')
+  }
+
+  const response = await siteRuntimeFetch(ATTACHMENT_DOWNLOAD_URL_PATH, {
+    body: JSON.stringify({
+      extra: buildAttachmentExtra(context, ref),
+      file_token: ref.fileToken,
+    }),
+    headers: { 'content-type': 'application/json' },
+    method: 'POST',
+  })
+
+  if (!response.ok) {
+    throw new Error(`附件下载链接获取失败：HTTP ${response.status}`)
+  }
+
+  const body: unknown = await response.json()
+  const url =
+    isRecord(body) && isRecord(body.data) && typeof body.data.url === 'string'
+      ? body.data.url.trim()
+      : ''
+
+  if (!url) {
+    throw new Error('附件下载链接获取失败：响应缺少 data.url')
+  }
+
+  return url
+}
+
+/** 构造运行态读取应用信息的统一网关地址。
+ *
+ * @param context 当前应用上下文。
+ * @param withChatbot 是否附带项目绑定的 chatbot 列表。
+ * @returns GetInvokeProject 的同源相对路径。
+ */
+export function buildDatabaseInvokeGetPath(
+  context: DatabaseContext,
+  withChatbot: boolean,
+): string {
+  const searchParams = new URLSearchParams()
+
+  if (withChatbot) {
+    searchParams.set('withChatbot', 'true')
+  }
+
+  if (context.env === PREVIEW_ENV) {
+    searchParams.set('env', PREVIEW_ENV)
+  }
+
+  const query = searchParams.toString()
+  const path = `${DATABASE_RUNTIME_GATEWAY_PREFIX}/${encodeURIComponent(context.token)}/invoke_get`
+
+  return query ? `${path}?${query}` : path
+}
+
+/** 构造运行态调用函数的统一网关地址。
+ *
+ * token 与 function_id 是 path 参数，env 走 query（prod 为服务端缺省，不显式下传）。
+ *
+ * @param context 当前应用上下文。
+ * @param functionId Base Database Function ID。
+ * @returns InvokeFunction 的同源相对路径。
+ * @throws functionId 不满足命名约束时抛出 TypeError。
+ */
+export function buildDatabaseInvokeFunctionPath(
+  context: DatabaseContext,
+  functionId: string,
+): string {
+  if (!FUNCTION_ID_PATTERN.test(functionId)) {
+    throw new TypeError(
+      `functionId ${functionId} 不满足命名约束 ${String(FUNCTION_ID_PATTERN)}`,
+    )
+  }
+
+  const path =
+    `${DATABASE_RUNTIME_GATEWAY_PREFIX}/${encodeURIComponent(context.token)}` +
+    `/invoke_function/${encodeURIComponent(functionId)}`
+
+  return context.env === PREVIEW_ENV
+    ? `${path}?env=${encodeURIComponent(PREVIEW_ENV)}`
+    : path
+}
+
+/** 调用应用 Function。
+ *
+ * 请求经父页面同源代理发往统一网关；整个请求体即 payload，业务参数包在 params 下。
+ * 目标环境只走 query 参数 env：服务端 resolveProjectEnv 显式入参优先，且
+ * cloneBaseAppHeaders 会剥掉入站的 x-project-env 后按归一化 env 重写，
+ * 再带同名 Header 属于重复下发。
+ * 4xx/5xx 直接抛错，业务码由调用方按 operation 契约校验一次顶层 code。
+ *
+ * @param functionId Base Database Function ID。
+ * @param params 函数入参：SQL Function 用数组，FaaS 用业务对象。
+ * @returns 统一包裹的函数响应。
+ */
+export async function invokeDatabaseFunction<Data = unknown>(
+  functionId: string,
+  params?: unknown,
+): Promise<DatabaseFunctionResponse<Data>> {
+  const context = await resolveDatabaseContext()
+
+  if (!context.token) {
+    throw new Error(`应用 token 未确定，无法调用 Function ${functionId}`)
+  }
+
+  const response = await invokeHttp({
+    url: buildDatabaseInvokeFunctionPath(context, functionId),
+    init: {
+      body: JSON.stringify({ params }),
+      headers: { 'content-type': 'application/json' },
+      method: 'POST',
+    },
+  })
+
+  if (!response.ok) {
+    throw new Error(`Function ${functionId} 调用失败：HTTP ${response.status}`)
+  }
+
+  return (await response.json()) as DatabaseFunctionResponse<Data>
+}

package/templates/database-starter/page/src/main.tsx

@@ -0,0 +1,34 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+import { DatabaseRuntimeReady } from './components/database-runtime-ready'
+import { siteRuntime } from './lib/database-runtime'
+import './index.css'
+
+const APP_BOOT_FAILED_CODE = 'APP_BOOT_FAILED'
+
+/** 挂载应用。 */
+function bootstrapDatabaseApp(): void {
+  const rootElement = document.getElementById('root')
+
+  if (!rootElement) {
+    throw new Error('未找到应用挂载节点 #root')
+  }
+
+  createRoot(rootElement).render(
+    <StrictMode>
+      <App />
+      <DatabaseRuntimeReady />
+    </StrictMode>,
+  )
+}
+
+try {
+  bootstrapDatabaseApp()
+} catch (error) {
+  // ready 之前的启动失败必须显式上报，否则宿主只能等到 ready 超时才展示错误态。
+  void siteRuntime.reportLoadFailed(APP_BOOT_FAILED_CODE).catch(() => {
+    // 上报本身失败时不掩盖原始启动错误。
+  })
+  throw error
+}

package/templates/database-starter/page/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/database-starter/page/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": false,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}

package/templates/database-starter/page/vite.config.ts

@@ -0,0 +1,13 @@
+import { createArgusCsrfPlugin } from '@lark-base-open/base-site-js/vite'
+import tailwindcss from '@tailwindcss/vite'
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+// https://vite.dev/config/
+export default defineConfig({
+  base: './',
+  build: {
+    sourcemap: false,
+  },
+  plugins: [createArgusCsrfPlugin(), react(), tailwindcss()],
+})

package/templates/database-starter/prettierignore

@@ -0,0 +1 @@
+sql/

package/templates/database-starter/server-functions/.prettierignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+package-lock.json

package/templates/database-starter/server-functions/.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "embeddedLanguageFormatting": "off",
+  "proseWrap": "preserve",
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all"
+}

package/templates/database-starter/server-functions/README.md

@@ -0,0 +1,11 @@
+# Server Functions
+
+每个业务写入 operation 放在：
+
+```text
+functions/<functionId>/
+├── index.ts
+└── meta.json
+```
+
+本目录是服务端 FaaS Functions 的源码与构建工作区，不是一个长期运行的服务。依赖与脚本以本目录 `package.json` 为准。Function ID、handler、`rawParams`、`context`、读写路径和返回结构见 `lark-base-database` Skill 的 `development.md`。