ai-kefu-jc/docs/superpowers/specs/2026-04-23-auto-popup-invite-card-design.md

# 自动弹出邀请卡片设计规范

**日期:** 2026-04-23
**状态:** 已批准
**相关:** 2026-04-22-chat-widget-redesign.md

---

## 概述

为 Widget 模式添加自动弹出邀请卡片，页面加载 1.8 秒后显示。邀请卡片提供快速访问常见话题的入口，提升用户参与度。

### 目标

- 通过主动邀请提升用户参与度
- 提供热门话题的快速访问
- 保持每页独立的状态管理
- 与现有聊天组件无缝集成

---

## 组件设计

### 邀请卡片

**位置**: 右下角，悬浮按钮上方

**尺寸**:
- 宽度: 360px
- 移动端最大宽度: calc(100vw - 24px)

**样式**:
- 圆角: 26px
- 头部: 橙色渐变 `linear-gradient(135deg, #F08A34 0%, #EC8C2F 100%)`
- 阴影: `0 28px 80px rgba(196,91,25,0.22)`
- 动画: 淡入 + 从底部滑入 (300ms)

**结构**:

```
┌──────────────────────────────────────┐
│ 头部 (橙色渐变)                       │
│ 🤖 Get stock list or quotation now   │
│ Chat with us for available vehicles, │
│ delivery timing and distributor...   │
├──────────────────────────────────────┤
│ 话题按钮 (2x1 网格)                   │
│ ┌─────────────┐  ┌─────────────────┐ │
│ │Get Quotation│  │Distributor Coopt│ │
│ └─────────────┘  └─────────────────┘ │
├──────────────────────────────────────┤
│ 操作按钮                              │
│ [Start Chat →]  [   No Thanks   ]   │
└──────────────────────────────────────┘
```

**话题列表**:
1. Get Quotation
2. Distributor Cooperation

---

## 状态管理

### 存储方案

**键名格式**: `widget_invite_dismissed_${pathname}`

**示例**:
- 页面 `/home` → `widget_invite_dismissed_/home`
- 页面 `/products` → `widget_invite_dismissed_/products`

**存储类型**: `sessionStorage`

### 状态流程

```
页面加载
    ↓
启动 1.8 秒定时器
    ↓
检查 sessionStorage
    ↓
┌─────────────┬─────────────┐
│ 未关闭      │  已关闭     │
│     ↓       │     ↓       │
│  显示邀请   │   跳过      │
└─────────────┴─────────────┘
```

### 关闭类型

| 类型 | 触发条件 | 存储行为 | 刷新后行为 |
|------|---------|---------|-----------|
| 暂时关闭 | 点击话题、Start Chat、悬浮按钮 | 设置 dismissed = true | 重置（再次显示） |
| 永久关闭 | 点击 No Thanks | 设置 dismissed = true | 持续（保持隐藏） |

---

## 交互矩阵

| 用户操作 | 邀请卡片 | 聊天面板 | 自动发送消息 |
|---------|---------|---------|-------------|
| 点击 "Get Quotation" | 关闭(暂时) | 打开 | 是 |
| 点击 "Distributor Cooperation" | 关闭(暂时) | 打开 | 是 |
| 点击 "Start Chat" | 关闭(暂时) | 打开 | 否 |
| 点击 "No Thanks" | 关闭(永久) | - | 否 |
| 点击悬浮按钮(邀请可见时) | 关闭(暂时) | 打开 | 否 |
| 点击悬浮按钮(邀请隐藏时) | - | 打开 | 否 |

### 显示逻辑

**互斥关系**:
- 邀请卡片可见 → 聊天面板隐藏
- 聊天面板打开 → 邀请卡片隐藏

**层级 (Z-Index)**:
- 邀请卡片: 99998
- 聊天面板: 99999
- 悬浮按钮: 99997

---

## 聊天面板中的热门话题

### 位置

消息区域，初始消息上方。仅在对话初始阶段显示。

### 样式

```
┌──────────────────────────────────────┐
│ POPULAR TOPICS                       │
│ ┌─────────────┐  ┌─────────────────┐ │
│ │Get Quotation│  │Distributor Coopt│ │
│ └─────────────┘  └─────────────────┘ │
└──────────────────────────────────────┘
```

### 行为

- 点击话题 → 自动发送消息到聊天
- 用户发送第一条消息后隐藏

---

## 每页独立运行

### 规则

1. **独立定时器**: 每个页面加载时启动自己的 1.8 秒定时器
2. **独立存储**: 每个页面单独存储关闭状态
3. **无跨页面通信**: 状态不在页面间同步
4. **会话重置**: 关闭网站清空所有状态

### 示例流程

```
1. 用户打开 /home
   → 1.8 秒 → 显示邀请
   → 用户点击 "Get Quotation"
   → /home 标记为已关闭

2. 用户导航到 /products
   → 1.8 秒 → 显示邀请（独立）
   → 用户点击 "No Thanks"
   → /products 标记为已关闭

3. 用户导航到 /about
   → 1.8 秒 → 显示邀请（独立）
   → 用户没有操作
   → /about 未标记为已关闭

4. 用户回到 /home
   → 检查存储 → 已关闭
   → 不显示邀请

5. 用户回到 /about
   → 检查存储 → 未关闭
   → 邀请保持显示

6. 用户刷新 /about
   → 存储持续 → 邀请保持显示

7. 用户关闭并重新打开网站
   → 所有存储清空
   → 所有页面重新开始
```

---

## 实现文件

### 修改

- `static/widget.js` - 添加邀请卡片组件和逻辑（约 250-300 行）

### 新增代码段

1. **邀请 HTML 生成** - 创建邀请卡片 DOM 结构
2. **邀请 CSS 样式** - 添加到 Shadow DOM 的样式
3. **定时器逻辑** - 1.8 秒延迟机制
4. **存储管理** - 每页状态管理
5. **事件处理** - 话题按钮、操作按钮
6. **自动发送消息** - 注入消息到聊天的函数

---

## 技术考虑

### Shadow DOM

所有邀请卡片样式都在 Shadow DOM 内部作用域，防止与宿主页面样式冲突。

### 性能

- 定时器是简单的 `setTimeout()` - 开销极小
- 存储检查是同步且快速的
- 初始渲染后 DOM 操作最少

### 可访问性

- 邀请卡片可用 Escape 键关闭（未来增强）
- 所有按钮都有正确的 `aria-label` 属性
- 支持键盘导航

### 浏览器兼容性

- `sessionStorage` 在所有现代浏览器中支持
- Shadow DOM 在 Chrome 53+、Firefox 63+、Safari 10+ 中支持

---

## 未来增强

1. **可配置延迟**: 通过 data 属性自定义 1.8 秒延迟
2. **A/B 测试**: 支持不同的邀请变体
3. **分析**: 跟踪邀请关闭和转化率
4. **Escape 键**: 用键盘关闭邀请
5. **智能时机**: 用户主动滚动时延迟邀请

---

## 参考资料

- 父规范: `2026-04-22-chat-widget-redesign.md`
- 参考设计: `livechat_ui_widget (5).jsx` (StrongInvite 组件)