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

package/templates/database-starter/page/src/components/UserSelectorPanel/user-search.ts

@@ -0,0 +1,201 @@
+import { fetch as databaseFetch } from '../../lib/database-runtime'
+import { fetchProjectMeta } from '../floating-button/utils/project-meta'
+
+const RECOMMEND_USERS_API_PATH = '/space/api/mention/recommend.v2/'
+const BITABLE_OBJECT_TYPE = '8'
+const BITABLE_MENTION_SOURCE = '4'
+const USER_MENTION_TYPE = '0'
+const SEARCH_PAGE_SIZE = 20
+
+export interface UserAvatar {
+  avatar_72: string
+  avatar_240: string
+  avatar_640: string
+  avatar_origin: string
+}
+
+export interface User {
+  avatar: UserAvatar
+  department_ids: string[]
+  description?: string
+  is_external?: boolean
+  name: string
+  user_id: string
+  open_id?: string
+}
+
+export interface SearchUsersData {
+  users: User[]
+}
+
+export interface SearchUsersResponse {
+  code: number
+  msg: string
+  data: SearchUsersData
+}
+
+export type SearchUsers = (keyword: string) => Promise<SearchUsersResponse>
+
+export async function requestUsers(
+  keyword: string,
+): Promise<SearchUsersResponse> {
+  const projectMeta = await fetchProjectMeta()
+  const baseToken = projectMeta.baseBindings[0]?.baseToken
+  if (!baseToken) {
+    throw new Error('应用未绑定 Base，无法搜索成员')
+  }
+
+  const body = new URLSearchParams({
+    config_source: '0',
+    obj_type: BITABLE_OBJECT_TYPE,
+    source: BITABLE_MENTION_SOURCE,
+    token: baseToken,
+    type: USER_MENTION_TYPE,
+    user_type: '0',
+    content: keyword.trim().slice(0, 50),
+  }).toString()
+
+  // 与 GetInvokeProject 完全复用同一条 Channel Runtime fetch 链路：
+  // Site iframe -> site.v1.http.request -> BaseApp 宿主同源请求。
+  const response = await databaseFetch(RECOMMEND_USERS_API_PATH, {
+    body,
+    headers: {
+      'content-type': 'application/x-www-form-urlencoded',
+    },
+    method: 'POST',
+  })
+
+  if (!response.ok) {
+    throw new Error(`搜索用户请求失败，HTTP 状态码：${response.status}`)
+  }
+
+  const payload: unknown = await response.json()
+  return {
+    code: 0,
+    msg: 'ok',
+    data: normalizeRecommendUsersResponse(payload),
+  }
+}
+
+export function normalizeRecommendUsersResponse(
+  value: unknown,
+  locale = getLocale(),
+): SearchUsersData {
+  const payload = unwrapRecommendPayload(value)
+  if (!payload) {
+    throw new Error('搜索用户返回结构不正确')
+  }
+
+  const entities = payload.entities
+  const users = isRecord(entities) ? entities.users : undefined
+  if (!isRecord(users) || !Array.isArray(payload.result_list)) {
+    throw new Error('搜索用户返回结构不正确')
+  }
+
+  const result: User[] = []
+  const seenUserIds = new Set<string>()
+  for (const item of payload.result_list) {
+    if (!isRecord(item) || Number(item.type) !== 0) continue
+    const token = readString(item.token)
+    if (!token) continue
+
+    const entity = users[token]
+    if (!isRecord(entity)) continue
+    const userId = readString(entity.user_id) || readString(entity.id) || token
+    const name = readUserName(entity, locale)
+    if (!userId || !name || seenUserIds.has(userId)) continue
+
+    seenUserIds.add(userId)
+    const avatarUrl = readString(entity.avatar_url)
+    const openId = readString(entity.open_id)
+    result.push({
+      avatar: {
+        avatar_72: avatarUrl,
+        avatar_240: avatarUrl,
+        avatar_640: avatarUrl,
+        avatar_origin: avatarUrl,
+      },
+      department_ids: readStringArray(entity.department_ids),
+      description: readUserDescription(entity, locale),
+      is_external: entity.is_external === true,
+      name,
+      user_id: userId,
+      ...(openId ? { open_id: openId } : {}),
+    })
+    if (result.length >= SEARCH_PAGE_SIZE) break
+  }
+
+  return { users: result }
+}
+
+function unwrapRecommendPayload(
+  value: unknown,
+): Record<string, unknown> | undefined {
+  if (!isRecord(value)) return undefined
+
+  if (typeof value.code === 'number' && value.code !== 0) {
+    throw new Error(readString(value.msg) || '搜索成员失败')
+  }
+
+  if ('entities' in value && 'result_list' in value) return value
+  return isRecord(value.data) ? value.data : undefined
+}
+
+function readUserName(entity: Record<string, unknown>, locale: string): string {
+  return (
+    readLocalizedString(entity.display_name, locale) ||
+    (locale.toLowerCase().startsWith('en')
+      ? readString(entity.en_name)
+      : readString(entity.cn_name)) ||
+    readString(entity.name) ||
+    readString(entity.cn_name) ||
+    readString(entity.en_name)
+  )
+}
+
+function readUserDescription(
+  entity: Record<string, unknown>,
+  locale: string,
+): string {
+  const localized =
+    entity.is_external === true ? entity.i18n_tenant : entity.i18n_department
+  return readLocalizedString(localized, locale) || readString(entity.department)
+}
+
+function readLocalizedString(value: unknown, locale: string): string {
+  if (typeof value === 'string') return value.trim()
+  if (!isRecord(value)) return ''
+
+  const normalizedLocale = locale.toLowerCase().replace('-', '_')
+  const language = normalizedLocale.split('_')[0] ?? ''
+  return (
+    readString(value[normalizedLocale]) ||
+    readString(value[language]) ||
+    readString(value.zh_cn) ||
+    readString(value.en_us)
+  )
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function readStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string')
+    : []
+}
+
+function getLocale(): string {
+  if (typeof document !== 'undefined' && document.documentElement.lang) {
+    return document.documentElement.lang
+  }
+  if (typeof navigator !== 'undefined' && navigator.language) {
+    return navigator.language
+  }
+  return 'zh-CN'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/templates/database-starter/page/src/components/database-runtime-ready.tsx

@@ -0,0 +1,21 @@
+import { useEffect } from 'react'
+import { siteRuntime } from '../lib/database-runtime'
+
+/** 在首屏挂载完成后向 BaseApp 宿主上报应用 Runtime 就绪。
+ *
+ * 宿主从 Channel 握手完成起等待该事件，超时（当前 10 秒）会展示加载失败态。
+ * 必须放在应用根节点内、且在首屏内容之后渲染，不要在模块顶层或数据初始化前调用。
+ *
+ * @returns 不渲染任何内容。
+ */
+export function DatabaseRuntimeReady(): null {
+  useEffect(() => {
+    void siteRuntime.ready().catch((error: unknown) => {
+      console.error('Application Runtime ready 上报失败', error)
+    })
+  }, [])
+
+  return null
+}
+
+export default DatabaseRuntimeReady

package/templates/database-starter/page/src/components/database-user-menu/index.tsx

@@ -0,0 +1,238 @@
+import { useEffect, useRef, useState } from 'react'
+import {
+  fetchCurrentUser,
+  type CurrentUser,
+} from '../floating-button/utils/current-user'
+import { fetchProjectMeta } from '../floating-button/utils/project-meta'
+import { logout } from '../../lib/database-runtime'
+
+export type DatabaseUserMenuLanguage = 'en' | 'zh'
+
+/** 应用面向的使用场景。
+ *
+ * 企业级系统会被本人以外的人打开，导航里需要交代当前身份（头像、姓名、组织、退出登录）；
+ * 个人系统只有自己用，这些信息是噪音，整块不渲染。该判定在应用开发时由 AI 一次性给出并
+ * 写死在调用处，运行时不做推断——产物里没有可靠信号（实测应用数据模型普遍不建模
+ * 「用户」这一维），而且忽隐忽现比判错更糟。判错时改这里一行重新部署即可。 */
+export type DatabaseAudience = 'enterprise' | 'personal'
+
+interface DatabaseUserMenuProps {
+  /** 界面语言，默认 en。 */
+  language?: DatabaseUserMenuLanguage
+  /** 默认 enterprise：拿不准时宁可多显示一个头像，也不要让用户找不到退出登录。 */
+  audience?: DatabaseAudience
+  /** 弹层相对触发器的对齐方向，默认 right（触发器在右上角时用）。 */
+  align?: 'left' | 'right'
+  /** 弹层展开方向，默认 down（触发器在顶部时用）；侧边栏底部的入口用 up。 */
+  side?: 'up' | 'down'
+  /** 是否在头像右侧显示姓名。窄侧栏或顶栏空间紧张时传 false。 */
+  showName?: boolean
+  className?: string
+}
+
+interface DatabaseUserMenuI18n {
+  account: string
+  logout: string
+}
+
+const I18N: Record<DatabaseUserMenuLanguage, DatabaseUserMenuI18n> = {
+  en: { account: 'Account', logout: 'Log out' },
+  zh: { account: '账号', logout: '退出登录' },
+}
+
+/** 应用自身导航里的当前用户入口：头像 + 姓名，点开是组织名与退出登录。
+ *
+ * 这块信息原先挂在右下角悬浮「更多」菜单里。悬浮控件是应用之外的一层浮层，
+ * 用户不会去那里找账号；放进应用自己的导航（顶栏右上角、侧边栏左下角等）才符合直觉。
+ * 位置由应用开发时按页面布局决定，组件只负责渲染与对齐。
+ *
+ * 数据自己拉：`function.runtime.getCurrentUser` 拿姓名与头像，组织名来自
+ * GetInvokeProject。两者都拿不到（例如应用被独立访问、无宿主）时整个组件不渲染，
+ * 不占位、不显示空头像。
+ */
+export function DatabaseUserMenu({
+  language = 'en',
+  audience = 'enterprise',
+  align = 'right',
+  side = 'down',
+  showName = true,
+  className = '',
+}: DatabaseUserMenuProps) {
+  const [currentUser, setCurrentUser] = useState<CurrentUser | null>(null)
+  const [organization, setOrganization] = useState('')
+  const [isOpen, setIsOpen] = useState(false)
+  const rootRef = useRef<HTMLDivElement>(null)
+  const i18n = I18N[language]
+
+  useEffect(() => {
+    if (audience !== 'enterprise') {
+      return undefined
+    }
+    let isCurrentRequest = true
+
+    /** 读取当前用户与组织名。 */
+    async function load(): Promise<void> {
+      const [user, meta] = await Promise.all([
+        fetchCurrentUser(),
+        fetchProjectMeta().catch(() => null),
+      ])
+      if (!isCurrentRequest) {
+        return
+      }
+      setCurrentUser(user)
+      setOrganization(user?.tenantName || meta?.organization || '')
+    }
+
+    void load()
+    return () => {
+      isCurrentRequest = false
+    }
+  }, [audience])
+
+  useEffect(() => {
+    if (!isOpen) {
+      return undefined
+    }
+
+    /** 点击组件外部时收起弹层。 */
+    function handlePointerDown(event: PointerEvent): void {
+      const target = event.target
+      if (target instanceof Node && !rootRef.current?.contains(target)) {
+        setIsOpen(false)
+      }
+    }
+
+    /** 按 Escape 收起弹层。 */
+    function handleKeyDown(event: KeyboardEvent): void {
+      if (event.key === 'Escape') {
+        setIsOpen(false)
+      }
+    }
+
+    window.addEventListener('pointerdown', handlePointerDown)
+    window.addEventListener('keydown', handleKeyDown)
+    return () => {
+      window.removeEventListener('pointerdown', handlePointerDown)
+      window.removeEventListener('keydown', handleKeyDown)
+    }
+  }, [isOpen])
+
+  // 个人系统整块不渲染；企业级但拿不到用户（应用被独立访问、无宿主）时同样不占位
+  if (audience !== 'enterprise' || !currentUser) {
+    return null
+  }
+
+  const initial = currentUser.name.slice(0, 1)
+
+  return (
+    <div ref={rootRef} className={`relative ${className}`}>
+      <button
+        type="button"
+        aria-label={i18n.account}
+        aria-expanded={isOpen}
+        aria-haspopup="menu"
+        className="flex max-w-full cursor-pointer items-center gap-2 rounded-full bg-transparent p-1 pr-2 text-sm outline-none transition-colors hover:bg-[#1f2329]/5 focus-visible:ring-2 focus-visible:ring-ring active:bg-[#1f2329]/10"
+        onClick={() => setIsOpen((next) => !next)}
+      >
+        {currentUser.avatarUrl ? (
+          <img
+            alt=""
+            aria-hidden="true"
+            className="size-7 shrink-0 rounded-full object-cover"
+            referrerPolicy="no-referrer"
+            src={currentUser.avatarUrl}
+          />
+        ) : (
+          <span
+            aria-hidden="true"
+            className="flex size-7 shrink-0 items-center justify-center rounded-full bg-[#1f2329]/8 text-xs font-medium"
+          >
+            {initial}
+          </span>
+        )}
+        {showName ? (
+          <span className="min-w-0 truncate font-medium">
+            {currentUser.name}
+          </span>
+        ) : null}
+      </button>
+
+      {isOpen ? (
+        <div
+          role="menu"
+          className={`absolute z-50 w-[240px] rounded-[10px] border border-black/10 bg-white p-1 text-sm text-[#1f2329] shadow-[0_2px_4px_rgba(0,0,0,0.02),0_4px_10px_rgba(0,0,0,0.03),0_4px_16px_rgba(0,0,0,0.03)] ${
+            align === 'right' ? 'right-0' : 'left-0'
+          } ${side === 'up' ? 'bottom-[calc(100%+8px)]' : 'top-[calc(100%+8px)]'}`}
+        >
+          <div className="flex items-center gap-2.5 px-2.5 py-3">
+            {currentUser.avatarUrl ? (
+              <img
+                alt=""
+                aria-hidden="true"
+                className="size-8 shrink-0 rounded-full object-cover"
+                referrerPolicy="no-referrer"
+                src={currentUser.avatarUrl}
+              />
+            ) : null}
+            <div className="min-w-0 flex-1 leading-[22px]">
+              <div className="truncate font-medium">{currentUser.name}</div>
+              {organization ? (
+                <div className="truncate text-xs leading-[18px] text-[#646a73]">
+                  {organization}
+                </div>
+              ) : null}
+            </div>
+          </div>
+          <div
+            className="mx-2.5 my-1 border-t border-black/10"
+            aria-hidden="true"
+          />
+          <button
+            type="button"
+            role="menuitem"
+            className="flex min-h-[38px] w-full cursor-pointer items-center gap-2 rounded-md px-2.5 py-1 text-left outline-none transition-colors hover:bg-[#1f2329]/5 focus-visible:bg-[#1f2329]/5 active:bg-[#1f2329]/10"
+            onClick={logoutDatabase}
+          >
+            <LogoutIcon />
+            <span className="min-w-0 flex-1 truncate">{i18n.logout}</span>
+          </button>
+        </div>
+      ) : null}
+    </div>
+  )
+}
+
+/** 退出登录：优先协议内置 Runtime Function（function.runtime.logout，由宿主执行
+ * 真正的登出）；旧版宿主未实现时回落清应用自身会话 cookie 后重载。 */
+function logoutDatabase(): void {
+  void logout().catch(() => {
+    const expire = 'Thu, 01 Jan 1970 00:00:00 GMT'
+    for (const name of ['base-site-session', 'session', 'sl_session']) {
+      document.cookie = `${name}=; expires=${expire}; path=/`
+    }
+    window.location.reload()
+  })
+}
+
+/** 退出登录图标。 */
+function LogoutIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" />
+      <path d="m16 17 5-5-5-5" />
+      <path d="M21 12H9" />
+    </svg>
+  )
+}
+
+export default DatabaseUserMenu

package/templates/database-starter/page/src/components/feedback/page-state.tsx

@@ -0,0 +1,66 @@
+import { CircleAlert, Inbox, LoaderCircle } from 'lucide-react'
+import { Button } from '../ui/button'
+
+interface PageStateProps {
+  status: 'loading' | 'empty' | 'error'
+  title?: string
+  description?: string
+  onRetry?: () => void
+}
+
+/** 展示页面级加载、空数据或错误状态。 */
+export function PageState({
+  status,
+  title,
+  description,
+  onRetry,
+}: PageStateProps) {
+  if (status === 'loading') {
+    return (
+      <div
+        className="flex min-h-48 flex-col items-center justify-center gap-3 text-center text-muted-foreground"
+        role="status"
+      >
+        <LoaderCircle
+          aria-hidden="true"
+          className="size-6 motion-safe:animate-spin"
+        />
+        <p className="text-sm font-medium">{title ?? '正在加载'}</p>
+      </div>
+    )
+  }
+
+  if (status === 'empty') {
+    return (
+      <div className="flex min-h-48 flex-col items-center justify-center gap-3 text-center">
+        <Inbox aria-hidden="true" className="size-7 text-muted-foreground" />
+        <div>
+          <p className="font-semibold">{title ?? '暂无数据'}</p>
+          {description ? (
+            <p className="mt-1 text-sm text-muted-foreground">{description}</p>
+          ) : null}
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div
+      className="flex min-h-48 flex-col items-center justify-center gap-4 text-center"
+      role="alert"
+    >
+      <CircleAlert aria-hidden="true" className="size-7 text-danger" />
+      <div>
+        <p className="font-semibold">{title ?? '加载失败'}</p>
+        <p className="mt-1 text-sm text-muted-foreground">
+          {description ?? '请稍后重试'}
+        </p>
+      </div>
+      {onRetry ? (
+        <Button variant="secondary" onClick={onRetry}>
+          重试
+        </Button>
+      ) : null}
+    </div>
+  )
+}

package/templates/database-starter/page/src/components/floating-button/chatbot-entry.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { resolveChatbotDisplayName } from './chatbot-entry'
+
+describe('resolveChatbotDisplayName', () => {
+  it.each(['未命名站点', '未命名智能体', 'Untitled site', 'Unnamed chatbot'])(
+    'uses the Site name for placeholder chatbot name %s',
+    (chatbotName) => {
+      expect(
+        resolveChatbotDisplayName(chatbotName, '客户工单与 SLA 系统'),
+      ).toBe('客户工单与 SLA 系统')
+    },
+  )
+
+  it('keeps an explicitly configured chatbot name', () => {
+    expect(resolveChatbotDisplayName('SLA 助手', '客户工单系统')).toBe(
+      'SLA 助手',
+    )
+  })
+
+  it('uses the generic caller fallback when Site metadata is unnamed', () => {
+    expect(resolveChatbotDisplayName('未命名站点', '智能助手')).toBe('智能助手')
+  })
+})