@anker-in/campaign-ui 0.2.11-beta.2 → 0.2.11-beta.21

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

@@ -0,0 +1,542 @@
+/**
+ * 聊天状态管理 Hook
+ * 管理消息列表、窗口状态、输入框状态、流式消息累积
+ * 基于 specs/livechat-widget/plan.md 的状态管理策略
+ */
+
+import { useState, useCallback, useRef, useEffect } from 'react'
+import type { Message, MessageContent, SSEEvent, StatusData, ErrorData, MessageStartData, BackendCartData } from '../types'
+import { getUserId } from '../utils/userId'
+import { useSession } from './useSession'
+import { transformProducts } from '../utils/productTransformers'
+import { transformCartData } from '../utils/cartTransformers'
+
+export interface UseChatStateOptions {
+  /**
+   * 初始欢迎消息
+   */
+  welcomeMessage?: string
+
+  /**
+   * Shopify 店铺域名
+   */
+  site?: string
+
+  /**
+   * 窗口打开回调
+   */
+  onOpen?: () => void
+
+  /**
+   * 窗口关闭回调
+   */
+  onClose?: () => void
+
+  /**
+   * 消息发送回调
+   */
+  onMessageSend?: (message: string) => void
+
+  /**
+   * 错误处理回调
+   */
+  onError?: (error: Error) => void
+
+  /**
+   * 商品添加到购物车回调
+   */
+  onAddToCart?: (product: any) => void
+
+  /**
+   * 购物车按钮点击回调
+   */
+  onCart?: (cartId: string, checkoutUrl?: string) => void
+}
+
+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, onOpen, onClose, onMessageSend, onError, onAddToCart, onCart } = 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 [isOpen, setIsOpen] = useState(false)
+
+  // 输入框内容
+  const [inputValue, setInputValue] = useState('')
+
+  // 是否正在接收流式消息
+  const [isStreaming, setIsStreaming] = useState(false)
+
+  // 当前正在累积的流式消息 (临时存储)
+  const currentMessageRef = useRef<Message | null>(null)
+
+  /**
+   * 打开聊天窗口
+   */
+  const openChat = useCallback(() => {
+    setIsOpen(true)
+    onOpen?.()
+  }, [onOpen])
+
+  /**
+   * 关闭聊天窗口
+   */
+  const closeChat = useCallback(() => {
+    setIsOpen(false)
+    onClose?.()
+  }, [onClose])
+
+  /**
+   * 切换聊天窗口状态
+   */
+  const toggleChat = useCallback(() => {
+    setIsOpen(prev => {
+      const newState = !prev
+      if (newState) {
+        onOpen?.()
+      } else {
+        onClose?.()
+      }
+      return newState
+    })
+  }, [onOpen, onClose])
+
+  /**
+   * 添加消息到列表
+   */
+  const addMessage = useCallback((message: Message) => {
+    setMessagesState(prev => [...prev, message])
+  }, [])
+
+  /**
+   * 批量设置消息列表（用于加载历史）
+   */
+  const setMessages = useCallback((newMessages: Message[]) => {
+    setMessagesState(newMessages)
+  }, [])
+
+  /**
+   * 清空消息列表
+   */
+  const clearMessages = useCallback(() => {
+    setMessagesState([])
+  }, [])
+
+  /**
+   * 处理 SSE 事件
+   * 根据事件类型进行不同的处理
+   */
+  const handleSSEEvent = useCallback(
+    (event: SSEEvent) => {
+      const { event: eventType, data } = event
+
+      switch (eventType) {
+        case 'message_start': {
+          // 开始接收新消息，显示思考气泡
+          setIsStreaming(true)
+
+          // T039: 保存 sessionId（如果后端返回）
+          const messageStartData = data as MessageStartData
+          if (messageStartData.sessionId && messageStartData.sessionId !== sessionId) {
+            saveSession(messageStartData.sessionId)
+          }
+
+          const messageId = `msg-${Date.now()}`
+          currentMessageRef.current = {
+            id: messageId,
+            role: 'assistant',
+            content: [{ type: 'thinking', data: { status: 'thinking' } }], // 添加思考状态
+            timestamp: Date.now(),
+          }
+
+          // 立即添加到消息列表以显示思考动画
+          setMessagesState(prev => [...prev, currentMessageRef.current!])
+          break
+        }
+
+        case 'content_delta': {
+          // 累积流式文本内容
+          // 实际 API 返回的是 {index: 0, delta: "文本"} 而不是 {text: "文本"}
+          const deltaData = data as any
+          const deltaText = deltaData.delta || deltaData.text || ''
+
+          if (currentMessageRef.current && deltaText) {
+            // 移除思考气泡（如果存在）
+            const hasThinking = currentMessageRef.current.content.some(c => c.type === 'thinking')
+            if (hasThinking) {
+              currentMessageRef.current.content = currentMessageRef.current.content.filter(c => c.type !== 'thinking')
+            }
+
+            const lastContent = currentMessageRef.current.content[currentMessageRef.current.content.length - 1] as
+              | MessageContent
+              | undefined
+
+            if (lastContent && lastContent.type === 'text') {
+              // 追加到现有文本块
+              lastContent.text += deltaText
+            } else {
+              // 创建新文本块
+              currentMessageRef.current.content.push({
+                type: 'text',
+                text: deltaText,
+              })
+            }
+
+            // 更新消息列表以触发渲染
+            setMessagesState(prev => {
+              const updated = [...prev]
+              const existingIndex = updated.findIndex(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)) {
+              // 使用统一的产品转换工具函数
+              const transformedProducts = transformProducts(contentData, site)
+
+              messageContent = {
+                type: 'product_list',
+                data: {
+                  products: transformedProducts,
+                  title: undefined, // 后端新规范不返回 title
+                  onAddToCart: onAddToCart, // 注入购物车回调
+                },
+              } as MessageContent
+            }
+            // ========== 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) {
+              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
+            }
+
+            currentMessageRef.current.content.push(messageContent)
+
+            setMessagesState(prev => {
+              const updated = [...prev]
+              const existingIndex = updated.findIndex(m => m.id === currentMessageRef.current!.id)
+
+              if (existingIndex >= 0) {
+                updated[existingIndex] = { ...currentMessageRef.current! }
+              } else {
+                updated.push({ ...currentMessageRef.current! })
+              }
+
+              return updated
+            })
+          }
+          break
+        }
+
+        case 'tool_start':
+        case 'tool_end': {
+          // 工具调用事件，暂时忽略
+          // 可以在未来用于显示工具调用状态
+          break
+        }
+
+        case 'message_end': {
+          // 消息接收完成
+          setIsStreaming(false)
+          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)
+          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)
+          currentMessageRef.current = null
+          break
+        }
+
+        default:
+          // 其他事件类型（tool_start, tool_end 等）
+          break
+      }
+    },
+    [welcomeMessage, site, addMessage, clearMessages, clearSession, saveSession, sessionId, onError, onAddToCart, onCart]
+  )
+
+  return {
+    messages,
+    isOpen,
+    userId,
+    sessionId,
+    inputValue,
+    isStreaming,
+    openChat,
+    closeChat,
+    toggleChat,
+    setInputValue,
+    addMessage,
+    setMessages,
+    clearMessages,
+    handleSSEEvent,
+    saveSession,
+    clearSession,
+  }
+}

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

@@ -0,0 +1,123 @@
+/**
+ * 会话管理 Hook
+ * 负责 sessionId 的持久化和生命周期管理
+ * 基于 specs/livechat-widget/plan.md 的会话管理策略
+ */
+
+import { useState, useCallback, useEffect } from 'react'
+
+const SESSION_KEY = 'livechat_session_id'
+
+export interface UseSessionReturn {
+  /**
+   * 当前会话 ID
+   */
+  sessionId: string | null
+
+  /**
+   * 保存会话 ID 到 localStorage 和状态
+   * @param id 会话 ID (UUID 格式)
+   */
+  saveSession: (id: string) => void
+
+  /**
+   * 清空会话 ID (会话过期或新会话)
+   */
+  clearSession: () => void
+
+  /**
+   * 检查是否有活动会话
+   */
+  hasSession: boolean
+}
+
+/**
+ * 会话管理 Hook
+ *
+ * 会话管理策略：
+ * 1. 首次对话: 不传 session_id,后端从 message_start 事件返回
+ * 2. 存储位置: localStorage.livechat_session_id
+ * 3. 会话恢复: 打开聊天窗口时自动加载历史消息
+ * 4. 会话过期: 监听 status 事件 (type: "session_expired"),清空消息列表和 sessionId
+ * 5. 新会话按钮: 调用 POST /api/chat/new-session,更新 sessionId
+ *
+ * @returns 会话管理工具对象
+ */
+export function useSession(): UseSessionReturn {
+  // 从 localStorage 初始化会话 ID
+  const [sessionId, setSessionId] = useState<string | null>(() => {
+    if (typeof window === 'undefined') return null
+
+    try {
+      return localStorage.getItem(SESSION_KEY)
+    } catch (error) {
+      console.error('[useSession] Failed to read from localStorage:', error)
+      return null
+    }
+  })
+
+  /**
+   * 保存会话 ID
+   * 同时更新状态和 localStorage
+   */
+  const saveSession = useCallback((id: string) => {
+    if (!id || typeof id !== 'string') {
+      console.warn('[useSession] Invalid session ID:', id)
+      return
+    }
+
+    setSessionId(id)
+
+    if (typeof window !== 'undefined') {
+      try {
+        localStorage.setItem(SESSION_KEY, id)
+      } catch (error) {
+        console.error('[useSession] Failed to save to localStorage:', error)
+      }
+    }
+  }, [])
+
+  /**
+   * 清空会话 ID
+   * 用于会话过期或开始新会话
+   */
+  const clearSession = useCallback(() => {
+    setSessionId(null)
+
+    if (typeof window !== 'undefined') {
+      try {
+        localStorage.removeItem(SESSION_KEY)
+      } catch (error) {
+        console.error('[useSession] Failed to remove from localStorage:', error)
+      }
+    }
+  }, [])
+
+  /**
+   * 监听 localStorage 变化（跨标签页同步）
+   * 注意：根据计划文档，多标签页不支持实时同步
+   * 这里仅监听是为了防止同一浏览器多标签页导致的状态不一致
+   */
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+
+    const handleStorageChange = (event: StorageEvent) => {
+      if (event.key === SESSION_KEY) {
+        setSessionId(event.newValue)
+      }
+    }
+
+    window.addEventListener('storage', handleStorageChange)
+
+    return () => {
+      window.removeEventListener('storage', handleStorageChange)
+    }
+  }, [])
+
+  return {
+    sessionId,
+    saveSession,
+    clearSession,
+    hasSession: sessionId !== null,
+  }
+}