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

package/src/stories/LiveChatWidget.stories.tsx

@@ -0,0 +1,754 @@
+/**
+ * LiveChatWidget Storybook Stories
+ * 展示 LiveChat 组件的各种使用场景和配置
+ */
+
+import type { Meta, StoryObj } from '@storybook/react'
+import { LiveChatWidget } from '../components/LiveChatWidget'
+import type { MessageRenderer, MessageContent } from '../components/LiveChatWidget'
+import '../styles/livechat.css'
+
+const meta: Meta<typeof LiveChatWidget> = {
+  title: 'Campaign/LiveChatWidget',
+  component: LiveChatWidget,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      story: {
+        inline: false,
+        iframeHeight: 500,
+      },
+      description: {
+        component: `
+# LiveChat 聊天组件
+
+可复用的气泡弹窗聊天组件，支持 SSE 流式消息、自定义渲染器和多种消息类型。
+
+## 功能特性
+
+- 🎈 **气泡弹窗**: 可自定义位置的悬浮气泡按钮
+- 💬 **流式消息**: 基于 SSE 的实时流式响应
+- 📦 **多种消息类型**: 文本、商品卡片、商品列表、政策、快捷回复等
+- 🎨 **可定制**: 支持自定义品牌颜色、Logo、渲染器
+- 📱 **响应式**: 移动端全屏，桌面端固定尺寸
+- 💾 **会话管理**: 自动管理 userId 和 sessionId
+- 🔒 **安全防护**: 内置 XSS 防护和输入验证
+
+## 基础用法
+
+\`\`\`tsx
+import { LiveChatWidget } from '@anker-in/campaign-ui'
+import '@anker-in/campaign-ui/livechat.css'
+
+function App() {
+  return (
+    <LiveChatWidget
+      apiBaseUrl="https://beta-api-livechat.anker.com"
+      site="www.eufy.com"
+      channel_code="web_homepage"
+      welcomeMessage="你好！我是 AI 助手"
+    />
+  )
+}
+\`\`\`
+
+## 自定义渲染器
+
+\`\`\`tsx
+const customRenderers = {
+  video: {
+    render: (content) => (
+      <video src={content.url} controls className="w-full rounded" />
+    )
+  }
+}
+
+<LiveChatWidget
+  apiBaseUrl="..."
+  site="..."
+  customRenderers={customRenderers}
+/>
+\`\`\`
+        `,
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    apiBaseUrl: {
+      control: 'text',
+      description: 'API 基础 URL',
+    },
+    headers: {
+      control: 'object',
+      description: '自定义请求头，将在所有 API 请求中添加',
+      table: {
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    recaptchaSitekey: {
+      control: 'text',
+      description: 'Google reCAPTCHA v3 site key，提供此参数将自动启用 reCAPTCHA v3 验证',
+      table: {
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    recaptchaAction: {
+      control: 'text',
+      description: 'reCAPTCHA action 名称，用于区分不同的验证场景',
+      table: {
+        defaultValue: { summary: '"activity"' },
+      },
+    },
+    site: {
+      control: 'text',
+      description: 'Shopify 店铺 URL',
+    },
+    channelCode: {
+      control: 'text',
+      description: '渠道编码，用于标识来源渠道',
+      table: {
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    welcomeMessage: {
+      control: 'text',
+      description: '欢迎消息',
+      table: {
+        defaultValue: { summary: '你好！我是 AI 助手，有什么可以帮助你的吗？' },
+      },
+    },
+    logoUrl: {
+      control: 'text',
+      description: 'Logo URL',
+    },
+    position: {
+      control: 'object',
+      description: '气泡按钮位置对象',
+      table: {
+        defaultValue: { summary: '{ bottom: "1.5rem", right: "1.5rem" }' },
+      },
+    },
+  },
+  args: {
+    apiBaseUrl: 'http://172.16.38.183:3003',
+    site: 'www.eufy.com',
+    loginUserId: 'test_test',
+    welcomeMessage: '你好！我是 AI 助手，有什么可以帮助你的吗？',
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof LiveChatWidget>
+
+/**
+ * 默认配置
+ *
+ * 最简单的使用方式，使用默认配置。
+ */
+export const Default: Story = {
+  args: {
+    loginUserId: 'test_test',
+    apiBaseUrl: 'http://172.16.38.183:3003',
+    cartId: 'gid://shopify/Cart/hWN7wB3Pa12gh78d8hPOAUBI?key=0e73db1d3fb5ac21da19099c45033253',
+    accessToken: '47b1aa2c0797043f9baba39388029d70',
+    title: 'eufy',
+
+    commonText: {
+      learnMore: 'Learn More',
+      total: 'Total',
+    },
+
+    site: 'beta.eufy.com',
+    channelCode: 'dtc',
+
+    // reCAPTCHA 配置（提供 sitekey 即自动启用）
+    // recaptchaSitekey: '6LfS4J4pAAAAACX1e_WrxutmxxzCK7FU4WzVqL14',
+    recaptchaAction: 'chat',
+  },
+}
+
+/**
+ * 自定义位置
+ *
+ * 使用自定义位置对象来控制气泡按钮的位置。
+ */
+export const CustomPosition: Story = {
+  args: {
+    position: { bottom: '1.5rem', left: '1.5rem' },
+  },
+}
+
+/**
+ * 自定义品牌样式
+ *
+ * 自定义 Logo 和欢迎消息。
+ */
+export const CustomBranding: Story = {
+  args: {
+    logoUrl: 'https://images.unsplash.com/photo-1599305445671-ac291c95aaa9?w=100&h=100&fit=crop',
+    welcomeMessage: '欢迎来到 Soundcore！我是您的专属 AI 助手 🎧',
+  },
+}
+
+/**
+ * 带快捷回复
+ *
+ * 在欢迎消息后显示快捷回复按钮。
+ */
+export const WithQuickReplies: Story = {
+  args: {
+    quickReplies: [
+      {
+        id: '1',
+        label: '查询价格',
+        value: '我想了解产品价格',
+        icon: '💰',
+      },
+      {
+        id: '2',
+        label: '查询物流',
+        value: '我想查询订单物流',
+        icon: '📦',
+      },
+      {
+        id: '3',
+        label: '售后服务',
+        value: '我需要售后帮助',
+        icon: '🔧',
+      },
+      {
+        id: '4',
+        label: '产品推荐',
+        value: '请推荐适合我的产品',
+        icon: '⭐',
+      },
+    ],
+  },
+}
+
+/**
+ * 自定义欢迎消息
+ *
+ * 自定义首次打开聊天窗口时的欢迎消息。
+ */
+export const CustomWelcomeMessage: Story = {
+  args: {
+    welcomeMessage: `
+👋 您好！欢迎来到 Soundcore 官方商城。
+
+我是您的 AI 购物助手，可以帮您：
+- 🔍 查找产品
+- 💰 比较价格
+- 📦 跟踪订单
+- 💬 解答疑问
+
+有什么我可以帮助您的吗？
+    `.trim(),
+  },
+}
+
+/**
+ * 事件回调
+ *
+ * 监听组件事件进行自定义处理。
+ */
+export const WithEventCallbacks: Story = {
+  args: {
+    title: '',
+    showNewSessionButton: true,
+
+    position: {
+      bottom: '24px',
+      right: '30px',
+    },
+
+    chatBubbleIcon: 'https://cdn.shopify.com/s/files/1/0504/7094/4954/files/Rectangle_400770314.png?v=1768894153',
+
+    // 自定义请求头示例
+    headers: undefined,
+
+    site: 'beta.eufy.com',
+  },
+
+  render: args => (
+    <LiveChatWidget
+      {...args}
+      onOpen={() => {
+        console.log('[Story] Chat opened')
+      }}
+      onClose={() => {
+        console.log('[Story] Chat closed')
+      }}
+      onMessageSend={(message: string) => {
+        console.log('[Story] Message sent:', message)
+      }}
+      onError={(error: Error) => {
+        console.error('[Story] Error occurred:', error)
+      }}
+      onTextMessage={() => {
+        console.log('📝 [Story] AI started replying with text message')
+      }}
+      onProductList={() => {
+        console.log('📦 [Story] AI replied with product list card')
+      }}
+      onPromotionList={() => {
+        console.log('🎉 [Story] AI replied with promotion list card')
+      }}
+      onAddToCart={(product: any) => {
+        console.log('🛒 [Story] Add to Cart clicked!')
+        console.log('📦 Product Info:', {
+          id: product.shopifyId,
+          title: product.title,
+          price: product.price,
+          imageUrl: product.imageUrl,
+          productUrl: product.productUrl,
+        })
+        console.log('📋 Full Product Object:', product)
+
+        // 模拟添加到购物车成功
+        alert(`✅ "${product.title}" 已添加到购物车！\n\n价格: ${product.price.currency} ${product.price.amount}`)
+      }}
+      onCart={(cartId: string, checkoutUrl?: string) => {
+        console.log('🛒 [Story] Cart button clicked!')
+        console.log('📋 Cart ID:', cartId)
+        console.log('🔗 Checkout URL:', checkoutUrl)
+
+        // 模拟购物车按钮点击成功
+        alert(`购物车按钮被点击！\n\nCart ID: ${cartId}\nCheckout URL: ${checkoutUrl || '无'}`)
+      }}
+    />
+  ),
+}
+
+/**
+ * 自定义视频消息渲染器
+ *
+ * 扩展消息类型，添加视频消息支持。
+ */
+export const CustomVideoRenderer: Story = {
+  args: {
+    customRenderers: {
+      video: {
+        render: (content: MessageContent) => {
+          const videoContent = content as any
+          return (
+            <div className="w-full">
+              <video src={videoContent.url} controls className="w-full rounded-lg" poster={videoContent.poster}>
+                您的浏览器不支持视频播放
+              </video>
+              {videoContent.title && <p className="mt-2 text-sm text-gray-600">{videoContent.title}</p>}
+            </div>
+          )
+        },
+      } as MessageRenderer,
+    },
+  },
+}
+
+/**
+ * 自定义图片画廊渲染器
+ *
+ * 扩展消息类型，添加图片画廊支持。
+ */
+export const CustomImageGalleryRenderer: Story = {
+  args: {
+    customRenderers: {
+      image_gallery: {
+        render: (content: MessageContent) => {
+          const galleryContent = content as any
+          const images = galleryContent.images || []
+
+          return (
+            <div className="grid grid-cols-2 gap-2">
+              {images.map((image: any, index: number) => (
+                <div key={index} className="relative aspect-square">
+                  <img
+                    src={image.url}
+                    alt={image.alt || `Image ${index + 1}`}
+                    className="size-full rounded-lg object-cover"
+                  />
+                </div>
+              ))}
+            </div>
+          )
+        },
+      } as MessageRenderer,
+    },
+  },
+}
+
+/**
+ * 移动端预览
+ *
+ * 在移动端尺寸下查看效果（全屏显示）。
+ */
+export const MobileView: Story = {
+  parameters: {
+    viewport: {
+      defaultViewport: 'mobile1',
+    },
+  },
+  args: {},
+}
+
+/**
+ * 平板端预览
+ *
+ * 在平板端尺寸下查看效果。
+ */
+export const TabletView: Story = {
+  parameters: {
+    viewport: {
+      defaultViewport: 'tablet',
+    },
+  },
+  args: {},
+}
+
+/**
+ * 默认位置展示
+ *
+ * 展示气泡按钮的默认位置（右下角）。
+ */
+export const DefaultPositionDemo: Story = {
+  render: () => (
+    <div className="relative h-screen w-full bg-gray-50">
+      <div className="absolute inset-0 flex items-center justify-center">
+        <p className="text-gray-500">页面内容区域</p>
+      </div>
+
+      {/* 演示默认位置 */}
+      <div className="absolute bottom-4 right-4 text-xs text-gray-400">默认位置 (右下角)</div>
+
+      <LiveChatWidget apiBaseUrl="https://beta-api-livechat.anker.com" site="www.eufy.com" />
+    </div>
+  ),
+}
+
+/**
+ * 产品对比消息
+ *
+ * 展示产品对比类型的消息渲染效果，包括价格、会员价、变体数量、折扣等多个维度的对比。
+ *
+ * 产品对比组件会以网格布局展示多个产品的基本信息，并在下方显示各维度的对比数据。
+ */
+export const ProductComparisonMessage: Story = {
+  render: args => (
+    <LiveChatWidget
+      {...args}
+      onAddToCart={(product: any) => {
+        console.log('🛒 [ProductComparison Story] Add to Cart clicked!')
+        console.log('📦 Product Info:', {
+          id: product.shopifyId,
+          title: product.title,
+          price: product.price,
+          imageUrl: product.imageUrl,
+          productUrl: product.productUrl,
+        })
+        console.log('📋 Full Product Object:', product)
+
+        // 模拟添加到购物车成功
+        alert(`✅ "${product.title}" 已添加到购物车！\n\n价格: ${product.price.currency} ${product.price.amount}`)
+      }}
+    />
+  ),
+  args: {
+    welcomeMessage: '以下是您关注的产品对比信息：',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `
+产品对比消息支持以下维度：
+
+- **价格对比**: 显示产品的价格区间和促销标签
+- **会员价对比**: 显示会员专享价格（如果可用）
+- **变体数量对比**: 显示产品的可选变体数量
+- **折扣对比**: 显示产品是否有折扣活动
+
+组件会自动处理从后端返回的产品对比数据，包括：
+- 产品基本信息（图片、标题、价格等）
+- 多维度对比数据（价格、会员价、变体、折扣）
+- 响应式布局（移动端可横向滚动）
+
+**测试 Add to Cart 功能：**
+- 点击产品对比卡片中的 "Add to Cart" 按钮
+- 查看控制台输出的产品信息
+- 会弹出确认提示框显示已添加到购物车
+        `,
+      },
+    },
+  },
+}
+
+/**
+ * FAQ 列表消息
+ *
+ * 展示常见问题列表，支持折叠/展开。
+ *
+ * FAQ 组件会显示搜索结果的常见问题，每个问题可以点击展开查看答案。
+ */
+export const FAQListMessage: Story = {
+  args: {
+    welcomeMessage: '以下是与您的问题相关的常见解答：',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `
+FAQ 列表消息支持：
+
+- **可折叠问题**: 点击问题标题展开/折叠答案
+- **Markdown 答案**: 答案支持 Markdown 格式，可显示富文本
+- **相关问题**: 展开答案后显示相关问题，点击可触发新搜索
+- **分类标记**: 根据问题分类显示（配送、退货、产品、支付、通用）
+- **搜索结果统计**: 显示找到的问题数量
+
+使用场景：
+- 用户询问常见问题时返回 FAQ 列表
+- 产品专属问题查询
+- 按分类查询 FAQ
+        `,
+      },
+    },
+  },
+}
+
+/**
+ * 带 reCAPTCHA 配置
+ *
+ * 展示如何配置 Google reCAPTCHA v3 验证，保护 API 请求免受滥用。
+ *
+ * reCAPTCHA 会在后台自动验证用户行为，无需用户手动操作。
+ */
+export const WithRecaptcha: Story = {
+  args: {
+    // 配置你的 reCAPTCHA site key（提供即自动启用）
+    recaptchaSitekey: '6LfS4J4pAAAAACX1e_WrxutmxxzCK7FU4WzVqL14',
+    // 可选：自定义 action 名称
+    recaptchaAction: 'livechat',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `
+### reCAPTCHA v3 配置
+
+启用 reCAPTCHA v3 可以保护你的 API 免受机器人和滥用行为的攻击。
+
+**配置步骤：**
+
+1. 在 [Google reCAPTCHA](https://www.google.com/recaptcha/admin) 创建 v3 密钥
+2. 在页面中加载 reCAPTCHA 脚本：
+   \`\`\`html
+   <script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
+   \`\`\`
+3. 配置 LiveChatWidget 组件（提供 sitekey 即自动启用）：
+   \`\`\`tsx
+   <LiveChatWidget
+     recaptchaSitekey="YOUR_SITE_KEY"
+     recaptchaAction="livechat"
+   />
+   \`\`\`
+
+**工作原理：**
+
+- 提供 recaptchaSitekey 参数即自动启用 reCAPTCHA 验证
+- 每次发送消息或创建会话时，会自动获取 reCAPTCHA token
+- token 会通过 \`X-Recaptcha-Token\` header 发送到后端
+- 后端需要验证 token 的有效性
+
+**注意事项：**
+
+- reCAPTCHA v3 在后台运行，不会打断用户体验
+- 建议为不同的操作使用不同的 \`recaptchaAction\` 以便分析
+- 确保后端正确验证 reCAPTCHA token
+- 不提供 recaptchaSitekey 则不启用验证（仅用于开发环境）
+        `,
+      },
+    },
+  },
+}
+
+/**
+ * 自定义产品卡片渲染
+ *
+ * 演示如何使用 productCardRender 自定义产品卡片的渲染样式。
+ *
+ * 当后端返回产品占位符 {{product:xxx}} 时，会使用自定义渲染函数来展示产品卡片。
+ */
+export const CustomProductCardRender: Story = {
+  args: {
+    loginUserId: 'test_test',
+    apiBaseUrl: 'http://172.16.38.183:3003',
+    cartId: 'gid://shopify/Cart/hWN7wB3Pa12gh78d8hPOAUBI?key=0e73db1d3fb5ac21da19099c45033253',
+    accessToken: '47b1aa2c0797043f9baba39388029d70',
+    title: 'eufy',
+    site: 'beta.eufy.com',
+    channelCode: 'dtc',
+    welcomeMessage: '你好！我可以为你推荐产品，试试发送 "推荐产品" 来查看自定义产品卡片效果。',
+
+    // 自定义产品卡片渲染函数
+    // 注意：product 参数是原始后端数据（未经转换）
+    productCardRender: (product) => {
+      // 原始后端数据使用 snake_case 字段名
+      const imageUrl = product.featured_image || ''
+      const title = product.title || ''
+      const description = product.description || ''
+      const price = product.price_range?.min || product.variants?.[0]?.price || 0
+      const currency = product.price_range?.currency || product.variants?.[0]?.currency || 'USD'
+      const averageRating = product.average_rating
+
+      return (
+        <div
+          style={{
+            border: '2px solid #4CAF50',
+            borderRadius: '16px',
+            padding: '20px',
+            margin: '12px 0',
+            backgroundColor: '#f0f9ff',
+            boxShadow: '0 4px 12px rgba(76, 175, 80, 0.15)',
+            transition: 'transform 0.2s',
+          }}
+          onMouseEnter={(e) => {
+            e.currentTarget.style.transform = 'scale(1.02)'
+          }}
+          onMouseLeave={(e) => {
+            e.currentTarget.style.transform = 'scale(1)'
+          }}
+        >
+          <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
+            <div
+              style={{
+                width: '70px',
+                height: 'auto',
+                flexShrink: 0,
+                borderRadius: '12px',
+                overflow: 'hidden',
+                border: '2px solid #e0e0e0',
+              }}
+            >
+              <img
+                src={imageUrl}
+                alt={title}
+                style={{
+                  width: '100%',
+                  height: '100%',
+                  objectFit: 'cover',
+                }}
+              />
+            </div>
+
+            <div style={{ flex: 1 }}>
+              <h3
+                style={{
+                  margin: '0 0 8px 0',
+                  fontSize: '18px',
+                  fontWeight: 'bold',
+                  color: '#1a1a1a',
+                  lineHeight: '1.4',
+                }}
+              >
+                {title}
+              </h3>
+
+              {description && (
+                <p
+                  style={{
+                    margin: '0 0 12px 0',
+                    fontSize: '14px',
+                    color: '#666',
+                    lineHeight: '1.5',
+                    display: '-webkit-box',
+                    WebkitLineClamp: 2,
+                    WebkitBoxOrient: 'vertical',
+                    overflow: 'hidden',
+                  }}
+                >
+                  {description}
+                </p>
+              )}
+
+              <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+                <div
+                  style={{
+                    fontSize: '24px',
+                    fontWeight: 'bold',
+                    color: '#4CAF50',
+                  }}
+                >
+                  'test price'
+                </div>
+
+                {averageRating !== undefined && (
+                  <div
+                    style={{
+                      display: 'flex',
+                      alignItems: 'center',
+                      gap: '4px',
+                      fontSize: '14px',
+                      color: '#666',
+                    }}
+                  >
+                    <span style={{ color: '#FFB800' }}>⭐</span>
+                    <span>{averageRating.toFixed(1)}</span>
+                  </div>
+                )}
+
+                <button
+      
+                  style={{
+                    marginLeft: 'auto',
+                    padding: '8px 20px',
+                    backgroundColor: '#4CAF50',
+                    color: 'white',
+                    borderRadius: '8px',
+                    textDecoration: 'none',
+                    fontSize: '14px',
+                    fontWeight: 'bold',
+                    transition: 'background-color 0.2s',
+                  }}
+                   onClick={() => {
+                    console.log('View Details', product)
+                  }}
+                >
+                  View Details
+                </button>
+              </div>
+            </div>
+          </div>
+        </div>
+      )
+    },
+
+    onAddToCart: (product) => {
+      console.log('Add to cart:', product)
+      alert(`Added ${product.title} to cart!`)
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `
+### 自定义产品卡片渲染
+
+使用 \`productCardRender\` 属性可以完全自定义产品卡片的展示样式。
+
+**功能说明：**
+
+- 当后端返回带有产品占位符 \`{{product:xxx}}\` 的文本流时，会使用自定义渲染函数
+- 自定义函数接收完整的产品对象作为参数
+- 返回 React 节点，可以是任何合法的 JSX
+- 如果不提供 \`productCardRender\`，则使用默认的产品卡片样式
+
+**测试步骤：**
+
+1. 打开聊天窗口
+2. 发送 "推荐产品" 或任何会触发产品推荐的消息
+3. 观察返回的产品卡片使用的是自定义样式（绿色边框、悬停放大效果）
+        `,
+      },
+    },
+  },
+}