@anker-in/campaign-ui 0.3.2 → 0.3.4

package/src/components/LiveChatWidget/hooks/useChatState.ts

@@ -0,0 +1,1090 @@
+/**
+ * 聊天状态管理 Hook
+ * 管理消息列表、窗口状态、输入框状态、流式消息累积
+ * 基于 specs/livechat-widget/plan.md 的状态管理策略
+ */
+
+import { useState, useCallback, useRef, useEffect } from 'react'
+import type { Message, MessageContent, SSEEvent, StatusData, ErrorData, MessageStartData, BackendCartData, Product, TextContent, ProductCardContent, ProductListContent } from '../types'
+import { getUserId } from '../utils/userId'
+import { useSession } from './useSession'
+import { transformProducts } from '../utils/productTransformers'
+import { transformCartData } from '../utils/cartTransformers'
+
+// ============================================================================
+// 辅助函数：文本解析和消息重组
+// ============================================================================
+
+/**
+ * 实时解析流式文本中的产品占位符
+ * 处理缓冲区中的文本，检测完整的 {{product:xxx}} 占位符
+ *
+ * @param buffer 当前缓冲区内容（包含新接收的文本）
+ * @param productMap handle → Product 的映射表
+ * @param rawProductMap handle → raw backend product 的映射表
+ * @param onAddToCart 添加到购物车回调
+ * @param productCardRender 自定义产品卡片渲染函数
+ * @returns { contents: 需要添加的内容数组, remainingBuffer: 剩余缓冲区内容 }
+ */
+function parseStreamingText(
+  buffer: string,
+  productMap: Map<string, Product>,
+  rawProductMap: Map<string, any>,
+  onAddToCart?: (product: Product) => void,
+  productCardRender?: (product: any, productHandle: string) => React.ReactNode
+): { contents: MessageContent[]; remainingBuffer: string } {
+  const contents: MessageContent[] = []
+  const regex = /\{\{(?:product:)?([^}]+)\}\}/g
+
+  let lastIndex = 0
+  let match: RegExpExecArray | null
+  let foundMatch = false
+
+  // 查找所有完整的占位符
+  while ((match = regex.exec(buffer)) !== null) {
+    foundMatch = true
+
+    // 提取占位符前的文本
+    const beforeText = buffer.slice(lastIndex, match.index)
+    if (beforeText) {
+      contents.push({ type: 'text', text: beforeText } as TextContent)
+    }
+
+    // 提取产品 ID 并创建产品卡片
+    const productId = match[1].trim()
+    const product = productMap.get(productId)
+    const rawProduct = rawProductMap.get(productId)
+
+    // 无论是否找到产品数据，都渲染 product_card，应用层可通过 productHandle 查询产品
+    if (product) {
+      console.log('[useChatState] 🎯 实时检测到产品:', productId, '→', product.title)
+    } else {
+      console.log('[useChatState] 📦 实时检测到产品占位符，产品数据待应用层查询:', productId)
+    }
+
+    contents.push({
+      type: 'product_card',
+      data: {
+        product: product,
+        rawProduct: rawProduct,
+        productHandle: productId,
+        onAddToCart: onAddToCart,
+        productCardRender: productCardRender
+      }
+    } as ProductCardContent)
+
+    lastIndex = regex.lastIndex
+  }
+
+  // 如果找到了至少一个完整占位符
+  if (foundMatch) {
+    // 返回剩余的文本作为缓冲区（可能包含不完整的占位符）
+    const remainingBuffer = buffer.slice(lastIndex)
+    return { contents, remainingBuffer }
+  } else {
+    // 没有找到完整占位符，检查是否有不完整的占位符开头
+    // 例如：缓冲区是 "some text {{prod"，我们需要保留 "{{prod" 等待更多文本
+    const incompleteMatch = buffer.match(/\{\{[^}]*$/)
+
+    if (incompleteMatch) {
+      // 有不完整的占位符开头
+      const completeText = buffer.slice(0, incompleteMatch.index)
+      if (completeText) {
+        contents.push({ type: 'text', text: completeText } as TextContent)
+      }
+      return { contents, remainingBuffer: incompleteMatch[0] }
+    } else {
+      // 没有不完整的占位符，整个缓冲区都是普通文本
+      if (buffer) {
+        contents.push({ type: 'text', text: buffer } as TextContent)
+      }
+      return { contents, remainingBuffer: '' }
+    }
+  }
+}
+
+/**
+ * 解析文本中的 {{handle}}，返回 [text, product_card, text, ...] 数组（用于历史消息重组）
+ *
+ * @param text 包含 {{handle}} 标记的文本
+ * @param productMap handle → Product 的映射表
+ * @param rawProductMap handle → raw backend product 的映射表
+ * @param onAddToCart 添加到购物车回调
+ * @param productCardRender 自定义产品卡片渲染函数
+ * @returns MessageContent 数组
+ *
+ * @example
+ * 输入：
+ *   text: "我推荐以下产品：\n{{product-handle}}\n这款产品性价比很高。"
+ *   productMap: Map { 'product-handle' => Product {...} }
+ * 输出：
+ *   [
+ *     { type: 'text', text: '我推荐以下产品：' },
+ *     { type: 'product_card', data: { product: {...}, onAddToCart } },
+ *     { type: 'text', text: '这款产品性价比很高。' }
+ *   ]
+ */
+function parseTextWithProductIds(
+  text: string,
+  productMap: Map<string, Product>,
+  rawProductMap: Map<string, any>,
+  onAddToCart?: (product: Product) => void,
+  productCardRender?: (product: any, productHandle: string) => React.ReactNode
+): MessageContent[] {
+  const result: MessageContent[] = []
+  // 修改正则表达式以匹配 {{product:ID}} 格式
+  // 匹配 {{product:xxx}} 或 {{xxx}}（兼容两种格式）
+  const regex = /\{\{(?:product:)?([^}]+)\}\}/g
+
+  let lastIndex = 0
+  let match: RegExpExecArray | null
+
+  while ((match = regex.exec(text)) !== null) {
+    const beforeText = text.slice(lastIndex, match.index).trim()
+    // match[1] 是捕获组中的内容，即 product: 后面的 ID
+    const productId = match[1].trim()
+
+    // 添加前面的文本（如果有）
+    if (beforeText) {
+      result.push({
+        type: 'text',
+        text: beforeText,
+      } as TextContent)
+    }
+
+    // 添加产品卡片（无论是否找到产品数据，都渲染 product_card）
+    const product = productMap.get(productId)
+    const rawProduct = rawProductMap.get(productId)
+    if (product) {
+      console.log(`[useChatState] ✅ 找到产品匹配: ${productId} → ${product.title}`)
+    } else {
+      console.log(`[useChatState] 📦 产品占位符，产品数据待应用层查询: ${productId}`)
+    }
+
+    result.push({
+      type: 'product_card',
+      data: {
+        product: product,
+        rawProduct: rawProduct,
+        productHandle: productId,
+        onAddToCart: onAddToCart,
+        productCardRender: productCardRender,
+      },
+    } as ProductCardContent)
+
+    lastIndex = regex.lastIndex
+  }
+
+  // 添加最后剩余的文本
+  const remainingText = text.slice(lastIndex).trim()
+  if (remainingText) {
+    result.push({
+      type: 'text',
+      text: remainingText,
+    } as TextContent)
+  }
+
+  return result
+}
+
+/**
+ * 重组消息内容：解析文本中的 {{handle}}，替换为产品卡片
+ *
+ * 处理逻辑：
+ * 1. 遍历消息的所有 content blocks
+ * 2. 对于 text 类型，解析其中的 {{handle}} 并拆分为多个 content
+ * 3. 跳过 product_list 类型（已经被拆分到文本中）
+ * 4. 其他类型直接保留
+ *
+ * @param contents 原始消息内容数组
+ * @param productMap handle → Product 的映射表
+ * @param rawProductMap handle → raw backend product 的映射表
+ * @param onAddToCart 添加到购物车回调
+ * @param productCardRender 自定义产品卡片渲染函数
+ * @returns 重组后的消息内容数组
+ */
+function reorganizeMessageContent(
+  contents: MessageContent[],
+  productMap: Map<string, Product>,
+  rawProductMap: Map<string, any>,
+  onAddToCart?: (product: Product) => void,
+  productCardRender?: (product: any, productHandle: string) => React.ReactNode
+): MessageContent[] {
+  const result: MessageContent[] = []
+
+  for (const content of contents) {
+    // 只处理文本类型
+    if (content.type === 'text') {
+      const textContent = content as TextContent
+      const segments = parseTextWithProductIds(textContent.text, productMap, rawProductMap, onAddToCart, productCardRender)
+      result.push(...segments)
+    }
+    // 跳过 product_list（已经被拆分到文本中）
+    else if (content.type === 'product_list') {
+      continue
+    }
+    // 其他类型直接保留
+    else {
+      result.push(content)
+    }
+  }
+
+  return result
+}
+
+/**
+ * 处理单条消息的重组（用于历史消息加载）
+ * 如果消息包含带有 {{}} 的文本，则进行重组
+ *
+ * @param message 原始消息
+ * @param onAddToCart 添加到购物车回调
+ * @param productCardRender 自定义产品卡片渲染函数
+ * @returns 重组后的消息（如果需要重组），否则返回原消息
+ */
+function maybeReorganizeHistoricalMessage(
+  message: Message,
+  onAddToCart?: (product: Product) => void,
+  productCardRender?: (product: any, productHandle: string) => React.ReactNode
+): Message {
+  // 检查消息是否包含带有 {{}} 的文本
+  const hasPlaceholder = message.content.some(
+    c => c.type === 'text' && /\{\{(?:product:)?[^}]+\}\}/.test((c as TextContent).text)
+  )
+  if (!hasPlaceholder) {
+    return message // 没有占位符，不需要重组
+  }
+
+  console.log('[useChatState] 检测到历史消息需要重组, 消息ID:', message.id)
+
+  // 构建产品映射 (handle → Product)
+  const productMap = new Map<string, Product>()
+  // 从 structured_content 中提取原始后端产品数据 (handle → rawProduct)
+  const rawProductMap = new Map<string, any>()
+
+  // 优先从 structured_content 获取原始产品数据（如果存在）
+  if (message.structured_content) {
+    message.structured_content.forEach(structuredContent => {
+      if (structuredContent.type === 'product_list' && Array.isArray(structuredContent.data)) {
+        structuredContent.data.forEach((rawProduct: any) => {
+          if (rawProduct && rawProduct.handle) {
+            rawProductMap.set(rawProduct.handle, rawProduct)
+            console.log('[useChatState] 从 structured_content 提取原始产品数据, handle:', rawProduct.handle)
+          }
+        })
+      }
+    })
+  }
+
+  // 构建转换后的产品映射（用于默认渲染）
+  message.content.forEach(content => {
+    if (content.type === 'product_list') {
+      const productListContent = content as ProductListContent
+      productListContent.data.products.forEach(product => {
+        if (product && product.handle) {
+          productMap.set(product.handle, product)
+        }
+      })
+    }
+  })
+
+  // 重组消息内容
+  const reorganizedContent = reorganizeMessageContent(message.content, productMap, rawProductMap, onAddToCart, productCardRender)
+
+  // 返回新消息对象
+  return {
+    ...message,
+    content: reorganizedContent,
+  }
+}
+
+export interface UseChatStateOptions {
+  /**
+   * 初始欢迎消息
+   */
+  welcomeMessage?: string
+
+  /**
+   * Shopify 店铺域名
+   */
+  site?: string
+
+  /**
+   * 受控模式：是否打开聊天窗口
+   * 提供此参数时，组件处于受控模式
+   */
+  open?: boolean
+
+  /**
+   * 受控模式：状态变化回调（必需）
+   * 用于同步状态到父组件
+   */
+  onOpenChange?: (open: boolean) => void
+
+  /**
+   * 窗口打开事件监听（可选）
+   * 用于埋点、日志等副作用
+   */
+  onOpen?: () => void
+
+  /**
+   * 窗口关闭事件监听（可选）
+   * 用于埋点、日志等副作用
+   */
+  onClose?: () => void
+
+  /**
+   * 消息发送回调
+   */
+  onMessageSend?: (message: string) => void
+
+  /**
+   * 错误处理回调
+   */
+  onError?: (error: Error) => void
+
+  /**
+   * AI 消息回调
+   */
+  /**
+   * AI 回复文本消息时触发
+   */
+  onTextMessage?: () => void
+
+  /**
+   * AI 回复商品列表卡片时触发
+   */
+  onProductList?: () => void
+
+  /**
+   * AI 回复促销卡片时触发
+   */
+  onPromotionList?: () => void
+
+  /**
+   * 商品添加到购物车回调
+   */
+  onAddToCart?: (product: any) => void
+
+  /**
+   * 购物车按钮点击回调
+   */
+  onCart?: (cartId: string, checkoutUrl?: string) => void
+
+  /**
+   * 自定义产品卡片渲染函数
+   * @param product 产品数据（如果在 product_list 中找到），否则为 undefined
+   * @param productHandle 文本占位符中的产品 ID，可用于应用层查询产品数据
+   */
+  productCardRender?: (product: any, productHandle: string) => React.ReactNode
+}
+
+export interface UseChatStateReturn {
+  /**
+   * 消息列表
+   */
+  messages: Message[]
+
+  /**
+   * 聊天窗口是否打开
+   */
+  isOpen: boolean
+
+  /**
+   * 用户 ID
+   */
+  userId: string
+
+  /**
+   * 会话 ID
+   */
+  sessionId: string | null
+
+  /**
+   * 输入框内容
+   */
+  inputValue: string
+
+  /**
+   * 是否正在接收流式消息
+   */
+  isStreaming: boolean
+
+  /**
+   * 打开聊天窗口
+   */
+  openChat: () => void
+
+  /**
+   * 关闭聊天窗口
+   */
+  closeChat: () => void
+
+  /**
+   * 切换聊天窗口状态
+   */
+  toggleChat: () => void
+
+  /**
+   * 设置输入框内容
+   */
+  setInputValue: (value: string) => void
+
+  /**
+   * 添加消息到列表
+   */
+  addMessage: (message: Message) => void
+
+  /**
+   * 批量设置消息列表（用于加载历史）
+   */
+  setMessages: (messages: Message[]) => void
+
+  /**
+   * 清空消息列表
+   */
+  clearMessages: () => void
+
+  /**
+   * 处理 SSE 事件
+   */
+  handleSSEEvent: (event: SSEEvent) => void
+
+  /**
+   * 保存会话 ID
+   */
+  saveSession: (id: string) => void
+
+  /**
+   * 清空会话
+   */
+  clearSession: () => void
+}
+
+/**
+ * 聊天状态管理 Hook
+ *
+ * 功能：
+ * 1. 管理消息列表（添加、清空、批量设置）
+ * 2. 管理窗口状态（打开、关闭、切换）
+ * 3. 管理输入框状态
+ * 4. 处理 SSE 流式消息事件
+ * 5. 累积流式文本内容
+ *
+ * @param options Hook 配置选项
+ * @returns 状态管理工具对象
+ */
+export function useChatState(options: UseChatStateOptions = {}): UseChatStateReturn {
+  const {
+    welcomeMessage,
+    site,
+    open: controlledOpen,
+    onOpenChange,
+    onOpen,
+    onClose,
+    onMessageSend,
+    onError,
+    onTextMessage,
+    onProductList,
+    onPromotionList,
+    onAddToCart,
+    onCart,
+    productCardRender,
+  } = options
+
+  // 会话管理
+  const { sessionId, saveSession, clearSession } = useSession()
+
+  // 用户 ID (初始化时异步生成)
+  const [userId, setUserId] = useState<string>('')
+
+  // 初始化 userId
+  useEffect(() => {
+    getUserId().then(id => setUserId(id))
+  }, [])
+
+  // 消息列表
+  const [messages, setMessagesState] = useState<Message[]>(() => {
+    // 如果有欢迎消息，初始化时添加
+    if (welcomeMessage) {
+      return [
+        {
+          id: `welcome-${Date.now()}`,
+          role: 'assistant',
+          content: [{ type: 'text', text: welcomeMessage }],
+          timestamp: Date.now(),
+        },
+      ]
+    }
+    return []
+  })
+
+  // 聊天窗口是否打开（支持受控和非受控两种模式）
+  const [internalOpen, setInternalOpen] = useState(false)
+  const isControlled = controlledOpen !== undefined
+  const isOpen = isControlled ? controlledOpen : internalOpen
+
+  // 输入框内容
+  const [inputValue, setInputValue] = useState('')
+
+  // 是否正在接收流式消息
+  const [isStreaming, setIsStreaming] = useState(false)
+
+  // 当前正在累积的流式消息 (临时存储)
+  const currentMessageRef = useRef<Message | null>(null)
+
+  // 标记当前消息是否已触发 onTextMessage 回调（避免重复触发）
+  const textMessageCallbackTriggeredRef = useRef<boolean>(false)
+
+  // 产品映射缓存 (handle → Product)，用于实时解析占位符
+  const productMapRef = useRef<Map<string, Product>>(new Map())
+
+  // 原始产品数据缓存 (handle → raw backend product)，用于 productCardRender
+  const rawProductMapRef = useRef<Map<string, any>>(new Map())
+
+  // 文本缓冲区，用于存储未完成的文本（处理占位符跨越多个 delta 的情况）
+  const textBufferRef = useRef<string>('')
+
+  // 卡片缓存队列，用于存储需要延迟显示的卡片（在文本完成后显示）
+  const pendingCardsRef = useRef<MessageContent[]>([])
+
+  /**
+   * 打开聊天窗口
+   */
+  const openChat = useCallback(() => {
+    if (!isControlled) {
+      setInternalOpen(true)
+    }
+    onOpenChange?.(true)
+    onOpen?.()
+  }, [isControlled, onOpenChange, onOpen])
+
+  /**
+   * 关闭聊天窗口
+   */
+  const closeChat = useCallback(() => {
+    if (!isControlled) {
+      setInternalOpen(false)
+    }
+    onOpenChange?.(false)
+    onClose?.()
+  }, [isControlled, onOpenChange, onClose])
+
+  /**
+   * 切换聊天窗口状态
+   */
+  const toggleChat = useCallback(() => {
+    const newState = !isOpen
+    if (!isControlled) {
+      setInternalOpen(newState)
+    }
+    onOpenChange?.(newState)
+    if (newState) {
+      onOpen?.()
+    } else {
+      onClose?.()
+    }
+  }, [isControlled, isOpen, onOpenChange, onOpen, onClose])
+
+  /**
+   * 添加消息到列表
+   */
+  const addMessage = useCallback((message: Message) => {
+    // 防护：如果消息为 null 或 undefined，不添加
+    if (!message) {
+      console.warn('[useChatState] Attempted to add null/undefined message')
+      return
+    }
+    setMessagesState(prev => [...prev, message])
+  }, [])
+
+  /**
+   * 批量设置消息列表（用于加载历史）
+   */
+  const setMessages = useCallback(
+    (newMessages: Message[]) => {
+      // 防护：过滤掉 null/undefined 消息
+      const validMessages = newMessages.filter(msg => msg != null)
+      if (validMessages.length !== newMessages.length) {
+        console.warn('[useChatState] Filtered out null/undefined messages from batch set')
+      }
+
+      // 对每条历史消息进行重组（如果需要）
+      const reorganizedMessages = validMessages.map(msg => maybeReorganizeHistoricalMessage(msg, onAddToCart, productCardRender))
+
+      setMessagesState(reorganizedMessages)
+    },
+    [onAddToCart, productCardRender]
+  )
+
+  /**
+   * 清空消息列表
+   */
+  const clearMessages = useCallback(() => {
+    setMessagesState([])
+  }, [])
+
+  /**
+   * 处理 SSE 事件
+   * 根据事件类型进行不同的处理
+   */
+  const handleSSEEvent = useCallback(
+    (event: SSEEvent) => {
+      const { event: eventType, data } = event
+
+      switch (eventType) {
+        case 'message_start': {
+          // 开始接收新消息
+          setIsStreaming(true)
+
+          // 重置文本消息回调标记
+          textMessageCallbackTriggeredRef.current = false
+
+          // 重置文本缓冲区
+          textBufferRef.current = ''
+
+          // 重置卡片缓存队列
+          pendingCardsRef.current = []
+
+          // T039: 保存 sessionId（如果后端返回）
+          const messageStartData = data as MessageStartData
+          if (messageStartData.sessionId && messageStartData.sessionId !== sessionId) {
+            saveSession(messageStartData.sessionId)
+          }
+
+          // 检查最后一条消息是否是 thinking 消息（用户发送消息时已添加）
+          setMessagesState(prev => {
+            const lastMessage = prev[prev.length - 1]
+            const hasThinking =
+              lastMessage &&
+              lastMessage.role === 'assistant' &&
+              lastMessage.content.length === 1 &&
+              lastMessage.content[0].type === 'thinking'
+
+            if (hasThinking) {
+              // 复用已存在的 thinking 消息
+              currentMessageRef.current = lastMessage
+              return prev // 不需要添加新消息
+            } else {
+              // 没有 thinking 消息，创建新的（兼容其他场景）
+              const messageId = `msg-${Date.now()}`
+              currentMessageRef.current = {
+                id: messageId,
+                role: 'assistant',
+                content: [{ type: 'thinking', data: { status: 'thinking' } }],
+                timestamp: Date.now(),
+              }
+              return [...prev, currentMessageRef.current!]
+            }
+          })
+          break
+        }
+
+        case 'content_delta': {
+          // 累积流式文本内容，并实时检测产品占位符
+          const deltaData = data as any
+          const deltaText = deltaData.delta || deltaData.text || ''
+
+          if (currentMessageRef.current && deltaText) {
+            // 触发文本消息回调（仅触发一次）
+            if (!textMessageCallbackTriggeredRef.current) {
+              textMessageCallbackTriggeredRef.current = true
+              onTextMessage?.()
+            }
+
+            // 移除思考气泡（如果存在）
+            const hasThinking = currentMessageRef.current.content.some(c => c.type === 'thinking')
+            if (hasThinking) {
+              currentMessageRef.current.content = currentMessageRef.current.content.filter(c => c.type !== 'thinking')
+            }
+
+            // 将新文本添加到缓冲区
+            textBufferRef.current += deltaText
+
+            // 实时解析缓冲区中的占位符
+            const { contents, remainingBuffer } = parseStreamingText(
+              textBufferRef.current,
+              productMapRef.current,
+              rawProductMapRef.current,
+              onAddToCart,
+              productCardRender
+            )
+
+            // 更新缓冲区为剩余内容
+            textBufferRef.current = remainingBuffer
+
+            // 将解析出的内容添加到消息中
+            if (contents.length > 0) {
+              contents.forEach(content => {
+                const lastContent = currentMessageRef.current!.content[
+                  currentMessageRef.current!.content.length - 1
+                ] as MessageContent | undefined
+
+                // 如果是文本内容且最后一个也是文本，则合并
+                if (content.type === 'text' && lastContent && lastContent.type === 'text') {
+                  lastContent.text += content.text
+                } else {
+                  // 否则添加新内容
+                  currentMessageRef.current!.content.push(content)
+                }
+              })
+
+              // 更新消息列表以触发渲染
+              setMessagesState(prev => {
+                if (!currentMessageRef.current) return prev
+
+                const updated = [...prev]
+                const existingIndex = updated.findIndex(m => m && m.id === currentMessageRef.current!.id)
+
+                if (existingIndex >= 0) {
+                  updated[existingIndex] = { ...currentMessageRef.current! }
+                } else {
+                  updated.push({ ...currentMessageRef.current! })
+                }
+
+                return updated
+              })
+            }
+          }
+          break
+        }
+
+        case 'content_block': {
+          // 接收结构化内容块（商品、政策等）
+          // API 返回格式变更:
+          // 新格式: {index: number, type: string, data: {...}}  <- type 在外层
+          // 旧格式: {index: number, data: {type: string, ...}}  <- type 在 data 内
+          const blockData = data as any
+          if (currentMessageRef.current) {
+            // 获取 type 和 data
+            // 优先从外层获取 type，兼容旧格式从 data 内获取
+            const contentType = blockData.type || blockData.data?.type
+            const contentData = blockData.data
+
+            if (!contentType || !contentData) {
+              console.warn('[useChatState] Invalid content_block:', blockData)
+              break
+            }
+
+            // ============================================================
+            // 转换数据结构以匹配类型定义
+            // 根据后端数据结构规范（飞书文档）进行转换
+            // ============================================================
+            let messageContent: MessageContent
+
+            // ========== 1. 产品列表卡片 (Product List) ==========
+            // 后端格式: {type: "product_list", data: [product1, product2, ...]}
+            // data 直接是产品数组，不是 {products: [...]}
+            if (contentType === 'product_list' && Array.isArray(contentData)) {
+              // 触发商品列表回调
+              onProductList?.()
+
+              // 缓存原始后端产品数据（用于 productCardRender）
+              // 使用 handle 作为 key 进行匹配
+              contentData.forEach((rawProduct: any) => {
+                if (rawProduct && rawProduct.handle) {
+                  rawProductMapRef.current.set(rawProduct.handle, rawProduct)
+                  console.log('[useChatState] 缓存原始产品数据, handle:', rawProduct.handle)
+                }
+              })
+
+              // 使用统一的产品转换工具函数
+              const transformedProducts = transformProducts(contentData, site)
+
+              // 建立产品映射缓存 (handle → Product)
+              // 用于后续在 message_end 时解析文本中的 {{handle}}
+              transformedProducts.forEach(product => {
+                if (product && product.handle) {
+                  productMapRef.current.set(product.handle, product)
+
+                  console.log('[useChatState] 建立产品映射:', {
+                    handle: product.handle,
+                    title: product.title,
+                  })
+                }
+              })
+
+              // ⚠️ 不要把 product_list 添加到消息中，避免闪烁
+              // 等到 message_end 时，通过文本解析创建 product_card，直接显示最终的交替格式
+              console.log('[useChatState] ✅ 产品列表已缓存，不添加到消息中（避免闪烁）')
+              break // 直接跳出，不执行后续的 push 操作
+            }
+            // ========== 2. 产品对比卡片 (Product Comparison) ==========
+            // 后端格式: {type: "product_comparison", data: {products: [...], dimensions: {...}}}
+            else if (contentType === 'product_comparison' && contentData.products) {
+              // 使用统一的产品转换工具函数
+              const transformedProducts = transformProducts(contentData.products, site)
+
+              messageContent = {
+                type: 'product_comparison',
+                data: {
+                  products: transformedProducts,
+                  dimensions: contentData.dimensions || {},
+                },
+              } as MessageContent
+            }
+            // ========== 3. FAQ 列表卡片 (FAQ List) ==========
+            // 后端格式: {type: "faq_list", data: {found, count, total, results: [...]}}
+            else if (contentType === 'faq_list' && contentData.found !== undefined) {
+              messageContent = {
+                type: 'faq_list',
+                data: contentData, // 直接使用，结构已匹配
+              } as MessageContent
+            }
+            // ========== 4. 快捷回复 (Quick Replies) ==========
+            else if (contentType === 'quick_replies' && contentData.replies) {
+              messageContent = {
+                type: 'quick_replies',
+                data: {
+                  replies: contentData.replies,
+                },
+              } as MessageContent
+            }
+            // ========== 5. 政策内容 (Policy) ==========
+            else if (contentType === 'policy' && contentData.title && contentData.content) {
+              messageContent = {
+                type: 'policy',
+                data: {
+                  title: contentData.title,
+                  content: contentData.content,
+                },
+              } as MessageContent
+            }
+            // ========== 6. 促销活动列表 (Promotion List) ==========
+            // 后端格式: {type: "promotion_list", data: {found, count, total, results: [...]}}
+            else if (contentType === 'promotion_list' && contentData.found !== undefined) {
+              // 触发促销卡片回调
+              onPromotionList?.()
+
+              messageContent = {
+                type: 'promotion_list',
+                data: contentData, // 直接使用，结构已匹配
+              } as MessageContent
+            }
+            // ========== 7. 购物车 (Cart) ==========
+            // 后端格式: {type: "cart", data: {id, lines: {edges: [...]}, cost, ...}} (Shopify GraphQL)
+            // 需要转换为前端格式: {cartId, lines: [...], cost, ...}
+            else if (contentType === 'cart' && contentData.id !== undefined) {
+              // 转换后端 Shopify GraphQL 格式为前端标准格式
+              const transformedData = transformCartData(contentData as BackendCartData)
+              messageContent = {
+                type: 'cart',
+                data: {
+                  ...transformedData,
+                  onCart: onCart, // 注入购物车按钮回调
+                },
+              } as MessageContent
+            }
+            // ========== 8. 其他类型（通用处理） ==========
+            else {
+              messageContent = {
+                type: contentType,
+                data: contentData,
+              } as MessageContent
+            }
+
+            // ⚠️ 重要修改：将卡片缓存起来，不立即添加到消息中
+            // 等待 message_end 时，在文本完成后再统一添加卡片
+            console.log('[useChatState] ✅ 卡片已缓存，等待文本完成后显示:', contentType)
+            pendingCardsRef.current.push(messageContent)
+
+            // 不再立即更新消息列表，避免卡片在文本之前显示
+            // 原来的代码：
+            // currentMessageRef.current.content.push(messageContent)
+            // setMessagesState(prev => { ... })
+          }
+          break
+        }
+
+        case 'tool_start':
+        case 'tool_end': {
+          // 工具调用事件，暂时忽略
+          // 可以在未来用于显示工具调用状态
+          break
+        }
+
+        case 'message_end': {
+          // 消息接收完成
+          setIsStreaming(false)
+
+          // 处理缓冲区中剩余的文本（如果有）
+          if (currentMessageRef.current && textBufferRef.current) {
+            console.log('[useChatState] 处理剩余缓冲区:', textBufferRef.current)
+
+            const lastContent = currentMessageRef.current.content[
+              currentMessageRef.current.content.length - 1
+            ] as MessageContent | undefined
+
+            // 如果最后一个内容是文本，则合并
+            if (lastContent && lastContent.type === 'text') {
+              lastContent.text += textBufferRef.current
+            } else {
+              // 否则添加为新的文本块
+              currentMessageRef.current.content.push({
+                type: 'text',
+                text: textBufferRef.current,
+              })
+            }
+          }
+
+          // ⚠️ 重要修改：在文本完成后，添加所有缓存的卡片
+          if (currentMessageRef.current && pendingCardsRef.current.length > 0) {
+            console.log('[useChatState] 📋 文本已完成，现在添加', pendingCardsRef.current.length, '个缓存的卡片')
+
+            // 将所有缓存的卡片添加到消息内容中
+            currentMessageRef.current.content.push(...pendingCardsRef.current)
+          }
+
+          // ⚠️ 超时检测：如果 message_end 时仍存在 thinking block，视为超时/异常
+          // 注意：在添加卡片之后检测，这样如果有卡片就不会添加超时提示
+          if (currentMessageRef.current) {
+            const hasThinking = currentMessageRef.current.content.some(c => c.type === 'thinking')
+
+            if (hasThinking) {
+              console.log('[useChatState] ⚠️ message_end 时仍存在 thinking block，立即移除（视为超时）')
+
+              // 移除 thinking block
+              currentMessageRef.current.content = currentMessageRef.current.content.filter(c => c.type !== 'thinking')
+
+              // 如果没有其他内容（包括缓存的卡片），添加超时提示
+              if (currentMessageRef.current.content.length === 0) {
+                currentMessageRef.current.content.push({
+                  type: 'text',
+                  text: 'Response timed out, please try again.',
+                } as TextContent)
+              }
+            }
+          }
+
+          // 更新消息列表（统一更新，包含文本和卡片）
+          if (currentMessageRef.current) {
+            setMessagesState(prev => {
+              if (!currentMessageRef.current) return prev
+
+              const updated = [...prev]
+              const existingIndex = updated.findIndex(m => m && m.id === currentMessageRef.current!.id)
+
+              if (existingIndex >= 0) {
+                updated[existingIndex] = { ...currentMessageRef.current! }
+              }
+
+              return updated
+            })
+          }
+
+          // 清空缓冲区、产品映射和卡片缓存
+          textBufferRef.current = ''
+          pendingCardsRef.current = []
+          productMapRef.current.clear()
+          rawProductMapRef.current.clear()
+          currentMessageRef.current = null
+          break
+        }
+
+        case 'status': {
+          // T040: 状态更新（如会话过期）
+          const statusData = data as StatusData
+          if (statusData.type === 'session_expired') {
+            // 会话过期，清空消息列表和会话
+            clearMessages()
+            clearSession()
+            if (welcomeMessage) {
+              addMessage({
+                id: `welcome-${Date.now()}`,
+                role: 'assistant',
+                content: [{ type: 'text', text: welcomeMessage }],
+                timestamp: Date.now(),
+              })
+            }
+          }
+          break
+        }
+
+        case 'error': {
+          // 错误处理
+          const errorData = data as ErrorData
+          setIsStreaming(false)
+
+          // 清理缓存（防止泄漏到下次消息）
+          textBufferRef.current = ''
+          pendingCardsRef.current = []
+          productMapRef.current.clear()
+          rawProductMapRef.current.clear()
+          currentMessageRef.current = null
+
+          // 添加错误消息到界面
+          addMessage({
+            id: `error-${Date.now()}`,
+            role: 'system',
+            content: [
+              {
+                type: 'error',
+                data: {
+                  message: errorData.message,
+                  code: errorData.code,
+                },
+              },
+            ],
+            timestamp: Date.now(),
+          })
+
+          onError?.(new Error(errorData.message))
+          break
+        }
+
+        case 'done': {
+          // 流结束
+          setIsStreaming(false)
+
+          // 清理缓存（防止泄漏到下次消息）
+          textBufferRef.current = ''
+          pendingCardsRef.current = []
+          productMapRef.current.clear()
+          rawProductMapRef.current.clear()
+
+          // 清理当前消息引用
+          currentMessageRef.current = null
+          break
+        }
+
+        default:
+          // 其他事件类型（tool_start, tool_end 等）
+          break
+      }
+    },
+    [
+      welcomeMessage,
+      site,
+      addMessage,
+      clearMessages,
+      clearSession,
+      saveSession,
+      sessionId,
+      onError,
+      onTextMessage,
+      onProductList,
+      onPromotionList,
+      onAddToCart,
+      onCart,
+    ]
+  )
+
+
+  return {
+    messages,
+    isOpen,
+    userId,
+    sessionId,
+    inputValue,
+    isStreaming,
+    openChat,
+    closeChat,
+    toggleChat,
+    setInputValue,
+    addMessage,
+    setMessages,
+    clearMessages,
+    handleSSEEvent,
+    saveSession,
+    clearSession,
+  }
+}