@anker-in/campaign-ui 0.2.11-beta.3 → 0.2.11-beta.31

package/src/components/LiveChatWidget/LiveChatWidget.tsx

@@ -0,0 +1,732 @@
+/**
+ * LiveChat 主组件
+ * 集成所有子组件，提供完整的聊天功能
+ * 基于 specs/livechat-widget/plan.md 的三层架构设计
+ */
+
+import React, { useEffect, useCallback } from 'react'
+import * as Dialog from '@radix-ui/react-dialog'
+import type {
+  LiveChatWidgetProps,
+  QuickReply,
+  Message,
+  MessageContent,
+  ChatStreamRequest,
+  BackendCartData,
+  CommonText,
+} from './types'
+import { DEFAULT_COMMON_TEXT } from './constants'
+import { ChatBubble } from './components/ChatBubble'
+import { ChatWindow } from './components/ChatWindow'
+import { useChatState } from './hooks/useChatState'
+import { useChatAPI } from './hooks/useChatAPI'
+import { MessageRendererRegistry } from './utils/messageRenderers'
+import { sanitizeInput } from './utils/validation'
+import { transformProducts } from './utils/productTransformers.js'
+import { transformCartData } from './utils/cartTransformers.js'
+import {
+  TextBlock,
+  ProductCard,
+  ProductList,
+  ProductComparisonRenderer,
+  PolicyBlock,
+  createQuickRepliesRenderer,
+  ThinkingBlock,
+  ErrorBlock,
+  FAQListRenderer,
+  PromotionListRenderer,
+  CartCard,
+} from './components/MessageContent/index.js'
+
+/**
+ * LiveChat 聊天组件
+ *
+ * 功能：
+ * - 气泡弹窗聊天界面
+ * - SSE 流式消息接收
+ * - 会话管理（userId, sessionId）
+ * - 历史消息加载
+ * - 多种消息类型渲染
+ * - 自定义扩展机制
+ * - reCAPTCHA v3 安全防护
+ *
+ * 架构：
+ * - UI Layer: ChatBubble, ChatWindow, MessageList, etc.
+ * - Logic Layer: useChatState, useChatAPI, useSession
+ * - Core Layer: MessageRendererRegistry, 自定义渲染器
+ *
+ * @example
+ * ```tsx
+ * // 基础使用（使用默认位置）
+ * <LiveChatWidget
+ *   apiBaseUrl="https://beta-api-livechat.anker.com"
+ *   site="www.eufy.com"
+ *   welcomeMessage="你好！我是 AI 助手"
+ *   onMessageSend={(msg) => console.log('Sent:', msg)}
+ * />
+ *
+ * // 使用自定义位置
+ * <LiveChatWidget
+ *   apiBaseUrl="https://beta-api-livechat.anker.com"
+ *   site="www.eufy.com"
+ *   position={{ bottom: "20px", right: "30px" }}
+ *   onMessageSend={(msg) => console.log('Sent:', msg)}
+ * />
+ *
+ * // 启用 reCAPTCHA v3 安全防护（提供 sitekey 即自动启用）
+ * <LiveChatWidget
+ *   apiBaseUrl="https://beta-api-livechat.anker.com"
+ *   site="www.eufy.com"
+ *   recaptchaSitekey="6LfS4J4pAAAAACX1e_WrxutmxxzCK7FU4WzVqL14"
+ *   recaptchaAction="livechat"
+ * />
+ *
+ * // 使用自定义 headers 和 reCAPTCHA
+ * <LiveChatWidget
+ *   apiBaseUrl="https://beta-api-livechat.anker.com"
+ *   site="www.eufy.com"
+ *   headers={{
+ *     "Authorization": "Bearer your-token",
+ *     "X-Custom-Header": "value"
+ *   }}
+ *   recaptchaSitekey="your-site-key"
+ * />
+ * ```
+ */
+export const LiveChatWidget: React.FC<LiveChatWidgetProps> = ({
+  apiBaseUrl,
+  headers,
+  recaptchaSitekey,
+  recaptchaAction,
+  site,
+  channelCode,
+  loginUserId,
+  cartId,
+  accessToken,
+  position,
+  welcomeMessage,
+  quickReplies,
+  customRenderers,
+  logoUrl,
+  title,
+  chatBubbleIcon,
+  open,
+  onOpenChange,
+  onOpen,
+  onClose,
+  onMessageSend,
+  onError,
+  onTextMessage,
+  onProductList,
+  onPromotionList,
+  onAddToCart,
+  onCart,
+  showNewSessionButton,
+  commonText,
+  productCardRender,
+}) => {
+  // 合并默认文案和自定义文案
+  const mergedText: Required<CommonText> = React.useMemo(
+    () => ({
+      ...DEFAULT_COMMON_TEXT,
+      ...commonText,
+    }),
+    [commonText]
+  )
+
+  // 状态管理
+  const chatState = useChatState({
+    welcomeMessage,
+    site,
+    open,
+    onOpenChange,
+    onOpen,
+    onClose,
+    onMessageSend,
+    onError,
+    onTextMessage,
+    onProductList,
+    onPromotionList,
+    onAddToCart,
+    onCart,
+    productCardRender,
+  })
+
+  const {
+    messages,
+    isOpen,
+    userId,
+    sessionId,
+    inputValue,
+    isStreaming,
+    openChat,
+    closeChat,
+    setInputValue,
+    addMessage,
+    setMessages,
+    clearMessages,
+    handleSSEEvent,
+    saveSession,
+    clearSession,
+  } = chatState
+
+  // API 调用
+  const { sendMessageStream, createSession } = useChatAPI({
+    apiBaseUrl,
+    headers,
+    recaptchaConfig: {
+      needRecaptcha: !!recaptchaSitekey, // 根据 sitekey 自动判断是否启用
+      recaptchaSitekey,
+      recaptchaAction,
+    },
+    onError,
+  })
+
+  // 使用 ref 存储最新的 handleSendMessage，避免循环依赖
+  const handleSendMessageRef = React.useRef<(_message?: string) => Promise<void>>(async (_message?: string) => {})
+
+  // 消息渲染器注册表
+  const rendererRegistry = React.useMemo(() => {
+    const registry = new MessageRendererRegistry()
+
+    // 注册默认渲染器
+    registry.register('text', TextBlock)
+    registry.register('product_card', ProductCard)
+    registry.register('product_list', ProductList)
+    registry.register('product_comparison', ProductComparisonRenderer)
+    registry.register('policy', PolicyBlock)
+    registry.register('thinking', ThinkingBlock)
+    registry.register('error', ErrorBlock)
+    registry.register('faq_list', FAQListRenderer)
+    registry.register('promotion_list', PromotionListRenderer)
+    registry.register('cart', CartCard)
+
+    // 注册快捷回复渲染器（带回调）
+    const quickRepliesRenderer = createQuickRepliesRenderer((reply: QuickReply) => {
+      // 使用 ref 调用最新的 handleSendMessage
+      handleSendMessageRef.current(reply.value)
+    })
+    registry.register('quick_replies', quickRepliesRenderer)
+
+    // 注册自定义渲染器
+    if (customRenderers) {
+      registry.registerMany(customRenderers)
+    }
+
+    return registry
+  }, [customRenderers])
+
+  /**
+   * T043: 打开聊天窗口时初始化会话
+   * 使用 API v2.0.0 的统一接口：
+   * - 如果没有 sessionId，创建新会话
+   * - 如果有 sessionId，恢复会话并加载历史消息
+   */
+  useEffect(() => {
+    if (!isOpen || !userId) return
+
+    const currentSessionId = sessionId
+
+    if (!currentSessionId) {
+      // 没有会话，创建新会话
+      handleCreateNewSession()
+    } else {
+      // 有会话，尝试恢复会话和历史消息
+      handleResumeSession(currentSessionId)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isOpen, userId])
+
+  /**
+   * 规范化消息格式（确保 content 是数组）
+   * 后端返回格式：
+   * - content: 字符串（文本内容）
+   * - structuredContent: 数组（结构化内容，如产品列表、政策等）
+   * 需要合并为统一的 content 数组格式
+   */
+  const normalizeMessage = useCallback(
+    (message: any): Message => {
+      // 如果 content 已经是数组，直接返回
+      if (Array.isArray(message.content)) {
+        return message as Message
+      }
+
+      const contentBlocks: MessageContent[] = []
+
+      // 处理文本内容
+      if (typeof message.content === 'string' && message.content.trim()) {
+        contentBlocks.push({
+          type: 'text',
+          text: message.content,
+        })
+      }
+
+      // 处理结构化内容
+      // 历史消息格式: structured_content: [{type, data}]
+      const structuredData = message.structuredContent || message.structured_content
+
+      if (Array.isArray(structuredData)) {
+        structuredData.forEach((block: any) => {
+          if (block.type === 'product_list' && Array.isArray(block.data)) {
+            // 转换产品列表数据结构 - data 直接是产品数组
+            contentBlocks.push({
+              type: 'product_list',
+              data: {
+                products: transformProducts(block.data, site),
+                title: undefined, // 历史消息不包含 title
+                commonText: mergedText,
+              },
+            })
+          } else if (block.type === 'quick_replies' && block.data?.replies) {
+            contentBlocks.push({
+              type: 'quick_replies',
+              data: {
+                replies: block.data.replies,
+              },
+            })
+          } else if (block.type === 'policy' && block.data?.title && block.data?.content) {
+            contentBlocks.push({
+              type: 'policy',
+              data: {
+                title: block.data.title,
+                content: block.data.content,
+              },
+            })
+          } else if (block.type === 'product_comparison' && block.data?.products && block.data?.dimensions) {
+            // 转换产品对比数据结构并注入 onAddToCart 回调
+            contentBlocks.push({
+              type: 'product_comparison',
+              data: {
+                products: transformProducts(block.data.products, site),
+                dimensions: block.data.dimensions,
+                onAddToCart: onAddToCart,
+                commonText: mergedText,
+              },
+            })
+          } else if (block.type === 'faq_list' && block.data?.found !== undefined) {
+            // FAQ 列表卡片 - 直接使用后端数据
+            contentBlocks.push({
+              type: 'faq_list',
+              data: block.data,
+            })
+          } else if (block.type === 'promotion_list' && block.data?.found !== undefined) {
+            // 促销活动列表卡片 - 直接使用后端数据
+            contentBlocks.push({
+              type: 'promotion_list',
+              data: {
+                ...block.data,
+                commonText: mergedText,
+              },
+            })
+          } else if (block.type === 'cart' && block.data?.id !== undefined) {
+            // 购物车卡片 - 转换后端数据格式并注入 onCart 回调
+            const transformedData = transformCartData(block.data as BackendCartData)
+            contentBlocks.push({
+              type: 'cart',
+              data: {
+                ...transformedData,
+                onCart: onCart,
+                commonText: mergedText,
+              },
+            })
+          } else {
+            // 其他类型直接添加
+            contentBlocks.push(block)
+          }
+        })
+      }
+
+      // 如果没有任何内容块，返回空文本块
+      if (contentBlocks.length === 0) {
+        contentBlocks.push({
+          type: 'text',
+          text: '',
+        })
+      }
+
+      return {
+        ...message,
+        content: contentBlocks,
+      } as Message
+    },
+    [site, onCart, onAddToCart, mergedText]
+  )
+
+  /**
+   * 创建新会话
+   */
+  const handleCreateNewSession = useCallback(async () => {
+    if (!userId) return
+
+    try {
+      const response = await createSession({
+        user_id: userId,
+        site: site,
+        channel_code: channelCode,
+        real_user_id: loginUserId,
+      })
+
+      if (response.success) {
+        // 保存新会话 ID
+        saveSession(response.sessionId)
+
+        // 清空消息列表
+        clearMessages()
+
+        // 使用后端返回的欢迎消息，如果没有则使用 props 中的默认值
+        const messageText = response.welcomeMessage || welcomeMessage
+
+        if (messageText) {
+          const welcomeContent: MessageContent[] = [{ type: 'text', text: messageText }]
+
+          // 使用后端返回的快捷问题，如果没有则使用 props 中的快捷回复
+          const questions = response.quickQuestions
+          if (questions && questions.length > 0) {
+            // 将后端的 quickQuestions (字符串数组) 转换为 QuickReply 格式
+            const quickRepliesFromBackend = questions.map((question, index) => ({
+              id: `quick-${index}`,
+              label: question,
+              value: question,
+            }))
+
+            welcomeContent.push({
+              type: 'quick_replies',
+              data: {
+                replies: quickRepliesFromBackend,
+              },
+            })
+          } else if (quickReplies && quickReplies.length > 0) {
+            // 如果后端没有返回，使用 props 中的快捷回复
+            welcomeContent.push({
+              type: 'quick_replies',
+              data: {
+                replies: quickReplies,
+              },
+            })
+          }
+
+          addMessage({
+            id: `welcome-${Date.now()}`,
+            role: 'assistant',
+            content: welcomeContent,
+            timestamp: Date.now(),
+          })
+        }
+      }
+    } catch (error) {
+      console.error('[LiveChatWidget] Failed to create new session:', error)
+      onError?.(error as Error)
+
+      // 添加错误消息到界面
+      addMessage({
+        id: `error-${Date.now()}`,
+        role: 'system',
+        content: [
+          {
+            type: 'error',
+            data: {
+              message: 'Failed to create session. Please refresh the page and try again.',
+              code: 'SESSION_CREATE_ERROR',
+            },
+          },
+        ],
+        timestamp: Date.now(),
+      })
+    }
+  }, [
+    userId,
+    site,
+    channelCode,
+    loginUserId,
+    createSession,
+    saveSession,
+    clearMessages,
+    welcomeMessage,
+    quickReplies,
+    addMessage,
+    onError,
+  ])
+
+  /**
+   * 恢复会话和历史消息（使用新的 API v2.0.0）
+   */
+  const handleResumeSession = useCallback(
+    async (existingSessionId: string) => {
+      try {
+        const response = await createSession({
+          user_id: userId,
+          session_id: existingSessionId,
+          site: site,
+          channel_code: channelCode,
+          real_user_id: loginUserId,
+        })
+
+        if (response.success && response.resumed) {
+          // 会话恢复成功
+          if (response.messages && response.messages.length > 0) {
+            // 有历史消息，规范化并加载（过滤掉 null/undefined 值和空内容消息）
+            const normalizedMessages = response.messages
+              .filter((msg: any) => msg != null)
+              .map(normalizeMessage)
+              .filter((msg: Message) => msg.content && msg.content.length > 0 && !(msg.content.length === 1 && msg.content[0].type === 'text' && !msg.content[0].text))
+            setMessages(normalizedMessages)
+          } else {
+            // 没有历史消息，显示欢迎消息
+            clearMessages()
+
+            // 使用后端返回的欢迎消息，如果没有则使用 props 中的默认值
+            const messageText = response.welcomeMessage || welcomeMessage
+
+            if (messageText) {
+              const welcomeContent: MessageContent[] = [{ type: 'text', text: messageText }]
+
+              // 使用后端返回的快捷问题
+              const questions = response.quickQuestions
+              if (questions && questions.length > 0) {
+                const quickRepliesFromBackend = questions.map((question, index) => ({
+                  id: `quick-${index}`,
+                  label: question,
+                  value: question,
+                }))
+
+                welcomeContent.push({
+                  type: 'quick_replies',
+                  data: {
+                    replies: quickRepliesFromBackend,
+                  },
+                })
+              } else if (quickReplies && quickReplies.length > 0) {
+                welcomeContent.push({
+                  type: 'quick_replies',
+                  data: {
+                    replies: quickReplies,
+                  },
+                })
+              }
+
+              addMessage({
+                id: `welcome-${Date.now()}`,
+                role: 'assistant',
+                content: welcomeContent,
+                timestamp: Date.now(),
+              })
+            }
+          }
+        } else if (!response.resumed) {
+          // 会话无效或过期，创建新会话
+          clearSession()
+          handleCreateNewSession()
+        }
+      } catch (error) {
+        console.error('[LiveChatWidget] Failed to resume session:', error)
+
+        // 添加错误消息到界面
+        addMessage({
+          id: `error-${Date.now()}`,
+          role: 'system',
+          content: [
+            {
+              type: 'error',
+              data: {
+                message: 'Failed to resume session. Creating a new session...',
+                code: 'SESSION_RESUME_ERROR',
+              },
+            },
+          ],
+          timestamp: Date.now(),
+        })
+
+        // 恢复失败，清空会话并创建新的
+        clearSession()
+        handleCreateNewSession()
+      }
+    },
+    [
+      userId,
+      site,
+      channelCode,
+      loginUserId,
+      createSession,
+      setMessages,
+      clearSession,
+      clearMessages,
+      normalizeMessage,
+      handleCreateNewSession,
+      welcomeMessage,
+      quickReplies,
+      addMessage,
+    ]
+  )
+
+  /**
+   * 发送消息
+   */
+  const handleSendMessage = useCallback(
+    async (message?: string) => {
+      const textToSend = message || inputValue.trim()
+
+      if (!textToSend) return
+
+      // 清空输入框
+      if (!message) {
+        setInputValue('')
+      }
+
+      // 输入验证
+      const sanitized = sanitizeInput(textToSend)
+      if (!sanitized) {
+        onError?.(new Error('Invalid message'))
+        return
+      }
+
+      // 添加用户消息到界面
+      const userMessage = {
+        id: `user-${Date.now()}`,
+        role: 'user' as const,
+        content: [{ type: 'text' as const, text: sanitized }],
+        timestamp: Date.now(),
+      }
+      addMessage(userMessage)
+
+      // 立即添加思考状态消息，提升用户体验
+      const thinkingMessage = {
+        id: `thinking-${Date.now()}`,
+        role: 'assistant' as const,
+        content: [{ type: 'thinking' as const, data: { status: 'thinking' } }],
+        timestamp: Date.now(),
+      }
+      addMessage(thinkingMessage)
+
+      // 触发消息发送回调
+      onMessageSend?.(sanitized)
+
+      try {
+        // 确保有 sessionId，如果没有则先创建会话
+        let currentSessionId = sessionId
+        if (!currentSessionId) {
+          // 没有会话，创建新会话
+          const response = await createSession({
+            user_id: userId,
+            site: site,
+            channel_code: channelCode,
+            real_user_id: loginUserId,
+          })
+          if (response.success) {
+            currentSessionId = response.sessionId
+            saveSession(currentSessionId)
+          } else {
+            throw new Error('Failed to create session')
+          }
+        }
+
+        // 构建请求参数（session_id 现在是必填的）
+        const requestPayload: ChatStreamRequest = {
+          message: sanitized,
+          user_id: userId,
+          session_id: currentSessionId,
+          context: {
+            cartId: cartId,
+            accessToken: accessToken,
+            real_user_id: loginUserId,
+          },
+        }
+
+        // 发送消息到后端
+        await sendMessageStream(requestPayload, event => {
+          // 处理 SSE 事件
+          handleSSEEvent(event)
+
+          // 特殊处理：会话过期
+          if (event.event === 'status' && event.data.type === 'session_expired') {
+            clearSession()
+          }
+        })
+      } catch (error) {
+        console.error('[LiveChatWidget] Failed to send message:', error)
+        onError?.(error as Error)
+
+        // 移除刚才添加的 thinking 消息，并添加错误消息
+        const messagesWithoutThinking = messages.filter(msg => msg.id !== thinkingMessage.id)
+        setMessages([
+          ...messagesWithoutThinking,
+          {
+            id: `error-${Date.now()}`,
+            role: 'system',
+            content: [
+              {
+                type: 'error',
+                data: {
+                  message: 'Failed to send message. Please check your network connection and try again.',
+                  code: 'NETWORK_ERROR',
+                },
+              },
+            ],
+            timestamp: Date.now(),
+          },
+        ])
+      }
+    },
+    [
+      inputValue,
+      userId,
+      sessionId,
+      site,
+      channelCode,
+      loginUserId,
+      cartId,
+      accessToken,
+      messages,
+      setInputValue,
+      addMessage,
+      setMessages,
+      createSession,
+      sendMessageStream,
+      handleSSEEvent,
+      saveSession,
+      clearSession,
+      onMessageSend,
+      onError,
+    ]
+  )
+
+  // 更新 ref 以保持最新的 handleSendMessage
+  React.useEffect(() => {
+    handleSendMessageRef.current = handleSendMessage
+  }, [handleSendMessage])
+
+  return (
+    <>
+      {/* 气泡按钮 */}
+      <ChatBubble position={position} onClick={openChat} visible={!isOpen} iconImageUrl={chatBubbleIcon} />
+
+      {/* 聊天窗口（使用 Radix UI Dialog） */}
+      <Dialog.Root open={isOpen} onOpenChange={open => (open ? openChat() : closeChat())}>
+        <Dialog.Portal>
+          <Dialog.Content
+            className="livechat-window-enter"
+            style={{
+              position: 'fixed',
+              zIndex: 9998,
+            }}
+          >
+            <ChatWindow
+              messages={messages}
+              inputValue={inputValue}
+              onInputChange={setInputValue}
+              onSend={() => handleSendMessage()}
+              onClose={closeChat}
+              onNewSession={handleCreateNewSession}
+              title={title}
+              logoUrl={logoUrl}
+              isSending={isStreaming}
+              rendererRegistry={rendererRegistry}
+              inputPlaceholder=""
+              onAddToCart={onAddToCart}
+              showNewSessionButton={showNewSessionButton}
+            />
+          </Dialog.Content>
+        </Dialog.Portal>
+      </Dialog.Root>
+    </>
+  )
+}