聊天浮窗组件 (ChatBox Widget)

一个现代化的、可嵌入的聊天浮窗组件，支持第三方网站一行代码集成，具有精美的UI设计和流畅的动画效果。

✨ 特性

• 🚀 一行代码集成 - 第三方网站只需一个script标签即可嵌入
• 🎨 精美UI设计 - 现代化界面，支持明暗主题切换
• 📱 响应式设计 - 完美适配桌面端和移动端
• 🔒 安全可靠 - 内置CORS、CSP、限流等安全策略
• 🌐 多语言支持 - 支持中英文等多种语言
• 📁 文件上传 - 支持图片、文档等文件上传功能
• ⚡ 高性能 - 优化的加载速度和流畅的动画效果
• 🎯 可定制 - 支持主题、颜色、位置等多种自定义选项

🏗️ 项目结构

.
├── loader.js                 # 主加载脚本（客户端集成）
├── embed/                     # 聊天界面应用
│   ├── index.html            # 主HTML文件
│   ├── main.js               # 核心JavaScript逻辑
│   ├── main.css              # 主样式文件
│   ├── themes.css            # 主题样式
│   ├── animations.css        # 动画效果
│   ├── package.json          # 依赖配置
│   └── vite.config.js        # 构建配置
├── api/                       # 中间层API服务
│   ├── chat.js               # 聊天API端点
│   ├── upload.js             # 文件上传端点
│   ├── package.json          # 依赖配置
│   ├── vercel.json           # 部署配置
│   └── .env.example          # 环境变量模板
├── demo/                      # 演示页面
│   ├── index.html            # 演示页面
│   ├── styles.css            # 演示页面样式
│   ├── demo.js               # 演示页面脚本
│   └── package.json          # 依赖配置
└── loader/                    # 构建工具
    ├── webpack.config.js     # Webpack配置
    └── package.json          # 依赖配置

🚀 快速开始

开发环境

# 安装依赖
npm install

# 启动开发服务器
npm run dev

1. 客户端集成

在您的网站中添加一行代码即可集成聊天浮窗：

<script src="https://cdn.yourdomain.com/loader.js" 
        data-project="your-project-id" 
        data-theme="light" 
        data-primary="#0D47A1"
        data-position="bottom-right"
        data-api-url="https://your-api.vercel.app"
        data-language="zh-CN"></script>

🔧 配置选项

2. 配置参数

参数	说明	默认值	可选值
data-project	项目标识符	-	任意字符串
data-theme	主题模式	light	light, dark, auto
data-primary	主色调	#0D47A1	任意有效的CSS颜色值
data-position	浮窗位置	bottom-right	bottom-right, bottom-left, top-right, top-left
data-api-url	API服务地址	-	完整的API URL
data-language	界面语言	zh-CN	zh-CN, en-US

3. JavaScript API

集成后，您可以通过JavaScript API控制聊天浮窗：

// 打开聊天浮窗
ChatboxWidget.open();

// 关闭聊天浮窗
ChatboxWidget.close();

// 发送消息
ChatboxWidget.sendMessage('Hello!');

// 更新配置
ChatboxWidget.updateConfig({
  theme: 'dark',
  primary: '#FF5722'
});

// 监听事件
window.addEventListener('message', (event) => {
  const { type, payload } = event.data;
  
  switch (type) {
    case 'widget:ready':
      console.log('聊天浮窗已准备就绪');
      break;
    case 'widget:userMessage':
      console.log('用户发送消息:', payload);
      break;
    case 'widget:botMessage':
      console.log('机器人回复:', payload);
      break;
  }
});

🔒 安全特性

• ✅ API密钥完全隔离在中间层
• ✅ CORS和CSP安全策略
• ✅ 请求来源验证
• ✅ 按项目和IP的访问限流
• ✅ 数据传输加密

📱 支持特性

• ✅ 响应式设计
• ✅ 深浅主题切换
• ✅ 文件上传支持
• ✅ 打字指示器
• ✅ 消息引用
• ✅ 无障碍访问
• ✅ 动画效果

🛠️ 技术栈

• 前端: Vanilla JavaScript, CSS3
• 中间层: Vercel Functions / Supabase Edge Functions
• 数据库: Supabase PostgreSQL
• 存储: Supabase Storage
• API: MarsMind API

📖 API文档

全局API

// 打开聊天窗口
window.Chatbox.open()

// 关闭聊天窗口
window.Chatbox.close()

// 发送消息
window.Chatbox.send(message)

// 切换主题
window.Chatbox.setTheme('dark')

中间层API

• POST /api/chat - 发送聊天消息
• POST /api/upload - 上传文件

🧪 测试

# 运行所有测试
npm test

# 单独测试组件
npm run test:loader
npm run test:embed

🛠️ 开发部署

环境要求

• Node.js 16+
• npm 或 yarn
• 现代浏览器支持

本地开发

1. 克隆项目

git clone <repository-url>
cd chatbox-widget

2. 安装依赖

# 安装embed应用依赖
cd embed
npm install

# 安装API服务依赖
cd ../api
npm install

# 安装演示页面依赖
cd ../demo
npm install

# 安装构建工具依赖
cd ../loader
npm install

3. 配置环境变量

cd api
cp .env.example .env
# 编辑.env文件，填入您的配置

4. 启动开发服务器

# 启动embed应用开发服务器
cd embed
npm run dev

# 启动API服务（新终端）
cd api
npm run dev

# 启动演示页面（新终端）
cd demo
npm run dev

生产构建

1. 构建embed应用

cd embed
npm run build

2. 构建loader脚本

cd loader
npm run build

3. 部署API服务

cd api
# 部署到Vercel
vercel --prod

# 或部署到其他平台
npm run deploy

部署到CDN

将构建后的文件上传到CDN：

• loader/dist/loader.js → CDN根目录
• embed/dist/ → CDN的embed目录

🔧 配置说明

API服务配置

在 api/.env 文件中配置：

# MarsMind API配置
MARSMIND_API_URL=https://api.marsmind.com
MARSMIND_API_KEY=your_api_key

# Supabase配置（文件上传）
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_key

# 安全配置
JWT_SECRET=your_jwt_secret
ENCRYPTION_KEY=your_encryption_key

# 其他配置
ENVIRONMENT=production
MAX_FILE_SIZE=10485760
RATE_LIMIT_WINDOW=900000
RATE_LIMIT_MAX=100

主题自定义

您可以通过CSS变量自定义主题：

:root {
  --primary-color: #0D47A1;
  --primary-light: #5472D3;
  --primary-dark: #002171;
  --background-color: #FFFFFF;
  --surface-color: #F5F5F5;
  --text-primary: #212121;
  --text-secondary: #757575;
}

🧪 测试

# 运行embed应用测试
cd embed
npm test

# 运行API服务测试
cd api
npm test

# 运行端到端测试
npm run test:e2e

📱 浏览器支持

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+
• 移动端浏览器

🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📄 许可证

MIT License - 详见 LICENSE 文件

🆘 支持

如果您遇到问题或需要帮助：

• 📧 邮箱：support@yourdomain.com
• 💬 在线客服：演示页面
• 📖 文档：完整文档
• 🐛 问题反馈：GitHub Issues

🎯 路线图

• 支持更多第三方AI服务
• 添加语音消息功能
• 实现消息历史记录
• 支持多人会话
• 添加更多主题模板
• 实现插件系统

---

感谢使用聊天浮窗组件！ 🎉