diff --git a/docs/BYTEDESK_INTEGRATION_GUIDE.md b/docs/BYTEDESK_INTEGRATION_GUIDE.md
new file mode 100644
index 00000000..c179b9ff
--- /dev/null
+++ b/docs/BYTEDESK_INTEGRATION_GUIDE.md
@@ -0,0 +1,918 @@
+# Bytedesk客服系统 - 前端工程师集成手册
+
+**版本**: v1.0
+**最后更新**: 2025-01-07
+**适用项目**: vf_react
+**后端服务器**: http://43.143.189.195
+
+---
+
+## 📋 目录
+
+- [1. 集成概述](#1-集成概述)
+- [2. 快速开始（5分钟集成）](#2-快速开始5分钟集成)
+- [3. 详细集成步骤](#3-详细集成步骤)
+- [4. 配置说明](#4-配置说明)
+- [5. 高级功能](#5-高级功能)
+- [6. 样式定制](#6-样式定制)
+- [7. 故障排查](#7-故障排查)
+- [8. 常见问题FAQ](#8-常见问题faq)
+- [9. 性能优化](#9-性能优化)
+- [10. 安全注意事项](#10-安全注意事项)
+
+---
+
+## 1. 集成概述
+
+### 1.1 什么是Bytedesk客服系统？
+
+Bytedesk是一个开源的在线客服系统，为您的网站提供实时客户服务功能。本手册将指导您将Bytedesk客服Widget集成到vf_react项目中。
+
+### 1.2 集成架构
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ vf_react前端项目 │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ App.jsx │ │
+│ │ ┌──────────────────────────────────────────────┐ │ │
+│ │ │ BytedeskWidget组件 │ │ │
+│ │ │ - 动态加载客服脚本 │ │ │
+│ │ │ - 显示悬浮客服图标 │ │ │
+│ │ │ - 处理用户交互 │ │ │
+│ │ └──────────────────────────────────────────────┘ │ │
+│ └────────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────────┘
+ │
+ │ HTTP/WebSocket
+ ↓
+┌────────────────────────────────────────────────────────────┐
+│ Bytedesk后端服务 (43.143.189.195) │
+│ - API接口: :9003 │
+│ - WebSocket: :9885 │
+│ - Nginx反向代理: :80 │
+└────────────────────────────────────────────────────────────┘
+```
+
+### 1.3 集成特点
+
+- ✅ **零侵入**: 不修改vf_react原有代码逻辑
+- ✅ **即插即用**: 复制文件 + 修改配置即可使用
+- ✅ **样式隔离**: 使用Shadow DOM，不影响全局样式
+- ✅ **异步加载**: 不阻塞页面渲染
+- ✅ **跨页面**: 在所有页面显示客服图标
+- ✅ **响应式**: 自动适配移动端和PC端
+
+---
+
+## 2. 快速开始（5分钟集成）
+
+### 步骤1: 复制集成文件
+
+将`bytedesk-integration`文件夹复制到vf_react项目的`src/`目录下：
+
+```bash
+# 在vf_react项目根目录执行
+cd D:\【Git】\vf_react
+cp -r bytedesk-integration src/
+```
+
+文件结构：
+```
+vf_react/
+├── src/
+│ ├── bytedesk-integration/ # 客服集成文件夹
+│ │ ├── components/
+│ │ │ └── BytedeskWidget.jsx # 客服Widget组件
+│ │ ├── config/
+│ │ │ └── bytedesk.config.js # 配置文件
+│ │ ├── App.jsx.example # 集成示例代码
+│ │ ├── .env.bytedesk.example # 环境变量示例
+│ │ └── 前端工程师集成手册.md # 本手册
+│ ├── App.jsx # 您的主App文件
+│ └── ...
+└── package.json
+```
+
+### 步骤2: 配置环境变量
+
+复制环境变量模板到项目根目录并配置：
+
+```bash
+# 复制模板
+cp src/bytedesk-integration/.env.bytedesk.example .env.local
+
+# 编辑配置文件
+vim .env.local
+```
+
+**必需配置项**（在.env.local中）:
+```bash
+# Bytedesk服务器地址
+REACT_APP_BYTEDESK_API_URL=http://43.143.189.195
+
+# 组织ID（由管理员提供）
+REACT_APP_BYTEDESK_ORG=df_org_uid
+
+# 工作组ID（由管理员提供）
+REACT_APP_BYTEDESK_SID=df_wg_aftersales
+```
+
+> **注意**: ORG和SID需要从管理员处获取，或登录后台http://43.143.189.195/admin/查看。
+
+### 步骤3: 集成到App.jsx
+
+打开`src/App.jsx`，参考`App.jsx.example`添加以下代码：
+
+```jsx
+// 1. 导入组件和配置（在文件顶部添加）
+import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
+import { getBytedeskConfig } from './bytedesk-integration/config/bytedesk.config';
+
+function App() {
+ // 2. 获取配置
+ const bytedeskConfig = getBytedeskConfig();
+
+ return (
+
+ {/* 您的原有代码保持不变 */}
+
+ {/* 3. 添加客服Widget（在return的JSX最后添加） */}
+
+
+ );
+}
+
+export default App;
+```
+
+### 步骤4: 启动项目测试
+
+```bash
+# 安装依赖（如果需要）
+npm install
+
+# 启动开发服务器
+npm start
+```
+
+打开浏览器，您应该在页面右下角看到客服图标（💬）。
+
+---
+
+## 3. 详细集成步骤
+
+### 3.1 文件说明
+
+#### BytedeskWidget.jsx
+React组件，负责加载和管理Bytedesk客服Widget。
+
+**主要功能**:
+- 动态加载客服脚本（https://www.weiyuai.cn/embed/bytedesk-web.js）
+- 初始化客服Widget
+- 生命周期管理（加载、卸载、清理）
+- 错误处理
+
+**Props**:
+```typescript
+interface BytedeskWidgetProps {
+ config: Object; // 配置对象（必需）
+ autoLoad?: boolean; // 是否自动加载（默认true）
+ onLoad?: (bytedesk) => void; // 加载成功回调
+ onError?: (error) => void; // 加载失败回调
+}
+```
+
+#### bytedesk.config.js
+配置文件，包含客服系统的所有配置项。
+
+**主要函数**:
+- `getBytedeskConfig()`: 获取基础配置
+- `getBytedeskConfigWithUser(user)`: 获取带用户信息的配置
+- `shouldShowCustomerService(pathname)`: 判断是否在当前页面显示客服
+
+### 3.2 集成方式选择
+
+根据您的需求，选择合适的集成方式：
+
+#### 方式一: 全局集成（推荐）
+
+**适用场景**: 所有页面都需要客服功能
+
+```jsx
+import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
+import { getBytedeskConfig } from './bytedesk-integration/config/bytedesk.config';
+
+function App() {
+ const bytedeskConfig = getBytedeskConfig();
+
+ return (
+
+ {/* 您的页面内容 */}
+
+
+
+ );
+}
+```
+
+#### 方式二: 按页面显示
+
+**适用场景**: 只在特定页面显示客服（如排除登录页、支付页）
+
+```jsx
+import { useLocation } from 'react-router-dom';
+import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
+import { getBytedeskConfig, shouldShowCustomerService } from './bytedesk-integration/config/bytedesk.config';
+
+function App() {
+ const location = useLocation();
+ const bytedeskConfig = getBytedeskConfig();
+ const showBytedesk = shouldShowCustomerService(location.pathname);
+
+ return (
+
+ {/* 您的页面内容 */}
+
+ {showBytedesk && (
+
+ )}
+
+ );
+}
+```
+
+自定义页面规则（修改`bytedesk.config.js`）:
+
+```javascript
+export const shouldShowCustomerService = (pathname) => {
+ // 在以下页面显示客服
+ const allowedPages = [
+ '/',
+ '/home',
+ '/products',
+ '/pricing',
+ ];
+
+ // 在以下页面隐藏客服
+ const blockedPages = [
+ '/login',
+ '/register',
+ '/payment',
+ ];
+
+ if (blockedPages.some(page => pathname.startsWith(page))) {
+ return false;
+ }
+
+ return allowedPages.some(page => pathname.startsWith(page));
+};
+```
+
+#### 方式三: 带用户信息集成
+
+**适用场景**: 需要将登录用户信息传递给客服端
+
+```jsx
+import { useContext } from 'react';
+import BytedeskWidget from './bytedesk-integration/components/BytedeskWidget';
+import { getBytedeskConfigWithUser } from './bytedesk-integration/config/bytedesk.config';
+import { AuthContext } from './contexts/AuthContext';
+
+function App() {
+ const { user } = useContext(AuthContext);
+ const bytedeskConfig = getBytedeskConfigWithUser(user);
+
+ return (
+
+ {/* 您的页面内容 */}
+
+
+
+ );
+}
+```
+
+用户信息格式:
+```javascript
+const user = {
+ id: '12345', // 用户ID（必需）
+ name: '张三', // 用户名
+ email: 'user@example.com', // 邮箱
+ mobile: '13800138000', // 手机号
+};
+```
+
+---
+
+## 4. 配置说明
+
+### 4.1 环境变量配置
+
+在`.env.local`文件中配置（项目根目录）:
+
+```bash
+# ========== 必需配置 ==========
+
+# 后端服务地址
+REACT_APP_BYTEDESK_API_URL=http://43.143.189.195
+
+# 组织ID
+REACT_APP_BYTEDESK_ORG=df_org_uid
+
+# 工作组ID
+REACT_APP_BYTEDESK_SID=df_wg_aftersales
+
+# ========== 可选配置 ==========
+
+# 客服类型 (2=人工客服, 1=机器人)
+REACT_APP_BYTEDESK_TYPE=2
+
+# 语言 (zh-cn, en, ja, ko)
+REACT_APP_BYTEDESK_LOCALE=zh-cn
+
+# 图标位置 (bottom-right, bottom-left, top-right, top-left)
+REACT_APP_BYTEDESK_PLACEMENT=bottom-right
+
+# 图标边距（像素）
+REACT_APP_BYTEDESK_MARGIN_BOTTOM=20
+REACT_APP_BYTEDESK_MARGIN_SIDE=20
+
+# 主题模式 (system, light, dark)
+REACT_APP_BYTEDESK_THEME_MODE=system
+
+# 主题色
+REACT_APP_BYTEDESK_THEME_COLOR=#0066FF
+
+# 自动弹出（不推荐）
+REACT_APP_BYTEDESK_AUTO_POPUP=false
+```
+
+### 4.2 代码配置
+
+在`bytedesk.config.js`中直接修改:
+
+```javascript
+export const bytedeskConfig = {
+ // API服务地址
+ apiUrl: 'http://43.143.189.195',
+ htmlUrl: 'http://43.143.189.195/chat/',
+
+ // 客服图标位置
+ placement: 'bottom-right',
+
+ // 边距设置
+ marginBottom: 20,
+ marginSide: 20,
+
+ // 自动弹出
+ autoPopup: false,
+
+ // 语言设置
+ locale: 'zh-cn',
+
+ // 客服图标配置
+ bubbleConfig: {
+ show: true,
+ icon: '💬', // 可以使用emoji或图片URL
+ title: '在线客服',
+ subtitle: '点击咨询',
+ },
+
+ // 主题配置
+ theme: {
+ mode: 'system', // light | dark | system
+ backgroundColor: '#0066FF',
+ textColor: '#ffffff',
+ },
+
+ // 聊天配置
+ chatConfig: {
+ org: 'df_org_uid',
+ t: '2', // 2=人工客服, 1=机器人
+ sid: 'df_wg_aftersales',
+ },
+};
+```
+
+---
+
+## 5. 高级功能
+
+### 5.1 多工作组支持
+
+根据页面显示不同工作组的客服：
+
+```javascript
+// bytedesk.config.js
+export const getBytedeskConfigByPath = (pathname) => {
+ const config = getBytedeskConfig();
+
+ // 根据路径选择工作组
+ if (pathname.startsWith('/sales')) {
+ return {
+ ...config,
+ chatConfig: {
+ ...config.chatConfig,
+ sid: 'df_wg_sales', // 销售组
+ },
+ };
+ } else if (pathname.startsWith('/support')) {
+ return {
+ ...config,
+ chatConfig: {
+ ...config.chatConfig,
+ sid: 'df_wg_support', // 技术支持组
+ },
+ };
+ }
+
+ return config; // 默认售后组
+};
+```
+
+使用示例:
+```jsx
+import { useLocation } from 'react-router-dom';
+import { getBytedeskConfigByPath } from './bytedesk-integration/config/bytedesk.config';
+
+function App() {
+ const location = useLocation();
+ const bytedeskConfig = getBytedeskConfigByPath(location.pathname);
+
+ return (
+
+
+
+ );
+}
+```
+
+### 5.2 条件性显示
+
+根据用户登录状态或角色显示客服：
+
+```jsx
+function App() {
+ const { user } = useContext(AuthContext);
+ const bytedeskConfig = getBytedeskConfig();
+
+ // 只为普通用户显示客服（管理员不显示）
+ const showBytedesk = user && user.role === 'customer';
+
+ return (
+
+ {showBytedesk && (
+
+ )}
+
+ );
+}
+```
+
+### 5.3 事件回调
+
+监听客服系统的加载状态：
+
+```jsx
+function App() {
+ const bytedeskConfig = getBytedeskConfig();
+
+ const handleLoad = (bytedesk) => {
+ console.log('客服系统加载成功', bytedesk);
+ // 可以在这里执行自定义逻辑
+ // 例如: 发送统计事件
+ };
+
+ const handleError = (error) => {
+ console.error('客服系统加载失败', error);
+ // 可以在这里显示降级方案
+ // 例如: 显示备用联系方式
+ };
+
+ return (
+
+
+
+ );
+}
+```
+
+### 5.4 自定义触发按钮
+
+隐藏默认图标，使用自定义按钮：
+
+```jsx
+import { useState } from 'react';
+
+function App() {
+ const [showBytedesk, setShowBytedesk] = useState(false);
+
+ // 隐藏默认图标
+ const bytedeskConfig = {
+ ...getBytedeskConfig(),
+ bubbleConfig: {
+ show: false, // 隐藏默认图标
+ },
+ };
+
+ return (
+
+ {/* 自定义按钮 */}
+
+
+ {showBytedesk && (
+
+ )}
+
+ );
+}
+```
+
+---
+
+## 6. 样式定制
+
+### 6.1 修改主题色
+
+在配置中修改主题色：
+
+```javascript
+// bytedesk.config.js
+theme: {
+ mode: 'light',
+ backgroundColor: '#FF6600', // 您的品牌色
+ textColor: '#ffffff',
+},
+```
+
+### 6.2 修改图标位置
+
+```javascript
+// bytedesk.config.js
+placement: 'bottom-left', // 左下角
+marginBottom: 30, // 距底部30px
+marginSide: 30, // 距左侧30px
+```
+
+### 6.3 使用自定义图标
+
+使用图片URL替换emoji:
+
+```javascript
+// bytedesk.config.js
+bubbleConfig: {
+ show: true,
+ icon: 'https://yourdomain.com/images/service-icon.png',
+ title: '在线客服',
+ subtitle: '点击咨询',
+},
+```
+
+### 6.4 样式不冲突
+
+Bytedesk Widget使用Shadow DOM技术，样式完全隔离，不会影响您的全局CSS。
+
+---
+
+## 7. 故障排查
+
+### 7.1 客服图标不显示
+
+**可能原因**:
+1. 环境变量未配置
+2. 配置文件路径错误
+3. 后端服务未启动
+4. 脚本加载失败
+
+**解决方案**:
+```bash
+# 1. 检查.env.local文件是否存在
+ls -la .env.local
+
+# 2. 检查环境变量是否加载
+console.log(process.env.REACT_APP_BYTEDESK_API_URL);
+
+# 3. 检查后端服务状态
+curl http://43.143.189.195/api/health
+
+# 4. 查看浏览器控制台错误
+# 打开浏览器开发者工具 -> Console标签页
+```
+
+### 7.2 连接不上后端
+
+**检查清单**:
+```bash
+# 1. 后端服务是否运行
+# 联系后端工程师确认docker容器状态
+
+# 2. 防火墙是否开放
+# 确认80端口可访问
+
+# 3. CORS配置
+# 后端需要在.env.production中添加您的前端地址:
+# BYTEDESK_CORS_ALLOWED_ORIGINS=http://your-frontend-domain.com
+```
+
+### 7.3 ORG或SID错误
+
+**获取正确配置**:
+1. 登录管理后台: http://43.143.189.195/admin/
+2. 导航到"设置" -> "组织信息"，复制`组织UID`
+3. 导航到"客服管理" -> "工作组"，复制`工作组ID`
+4. 更新`.env.local`文件
+5. 重启开发服务器: `npm start`
+
+### 7.4 开发环境正常，生产环境异常
+
+**检查清单**:
+```bash
+# 1. 确认生产环境的环境变量
+# 查看构建时的配置
+
+# 2. 检查CORS配置
+# 后端需要添加生产域名到CORS白名单
+
+# 3. 检查HTTPS/HTTP
+# 如果前端使用HTTPS，后端也应使用HTTPS
+
+# 4. 查看生产环境日志
+npm run build
+# 检查构建产物中的配置
+```
+
+---
+
+## 8. 常见问题FAQ
+
+### Q1: 客服系统会影响页面性能吗？
+
+**A**: 不会。客服脚本采用异步加载，不会阻塞页面渲染。Widget总大小约50KB（gzip后），首次加载后会被浏览器缓存。
+
+### Q2: 可以在移动端使用吗？
+
+**A**: 可以。Bytedesk Widget完全响应式，自动适配移动端和PC端。
+
+### Q3: 是否支持离线消息？
+
+**A**: 支持。用户在客服离线时发送的消息会被保存，客服上线后可以查看。
+
+### Q4: 可以集成到React Native吗？
+
+**A**: BytedeskWidget是为Web设计的。React Native需要使用Bytedesk的原生SDK（另外提供）。
+
+### Q5: 如何隐藏特定页面的客服？
+
+**A**: 使用`shouldShowCustomerService`函数（见3.2节"方式二"）。
+
+### Q6: 可以同时配置多个工作组吗？
+
+**A**: 可以。参考5.1节"多工作组支持"。
+
+### Q7: 用户信息是否安全？
+
+**A**: 是的。所有通信使用WebSocket加密传输，用户信息不会被第三方获取。建议生产环境使用HTTPS。
+
+### Q8: 是否需要付费？
+
+**A**: Bytedesk社区版（当前使用）完全免费，License有效期至2040年12月31日。
+
+---
+
+## 9. 性能优化
+
+### 9.1 按需加载
+
+只在需要时加载客服系统：
+
+```jsx
+import { useState, useEffect } from 'react';
+
+function App() {
+ const [loadBytedesk, setLoadBytedesk] = useState(false);
+
+ // 延迟5秒加载（页面渲染完成后）
+ useEffect(() => {
+ const timer = setTimeout(() => {
+ setLoadBytedesk(true);
+ }, 5000);
+
+ return () => clearTimeout(timer);
+ }, []);
+
+ return (
+
+ {/* 您的页面内容 */}
+
+ {loadBytedesk && (
+
+ )}
+
+ );
+}
+```
+
+### 9.2 Lazy Import
+
+使用React.lazy延迟导入组件：
+
+```jsx
+import { lazy, Suspense } from 'react';
+
+const BytedeskWidget = lazy(() => import('./bytedesk-integration/components/BytedeskWidget'));
+
+function App() {
+ return (
+
+ {/* 您的页面内容 */}
+
+
+
+
+
+ );
+}
+```
+
+### 9.3 缓存优化
+
+客服脚本会自动被浏览器缓存，无需额外配置。
+
+---
+
+## 10. 安全注意事项
+
+### 10.1 环境变量安全
+
+```bash
+# ❌ 错误: 不要在代码中硬编码配置
+const config = {
+ apiUrl: 'http://43.143.189.195',
+ org: 'df_org_uid',
+};
+
+# ✅ 正确: 使用环境变量
+const config = {
+ apiUrl: process.env.REACT_APP_BYTEDESK_API_URL,
+ org: process.env.REACT_APP_BYTEDESK_ORG,
+};
+```
+
+### 10.2 敏感信息保护
+
+```javascript
+// ❌ 不要传递敏感信息
+const user = {
+ id: '12345',
+ password: 'user-password', // 不要传递密码
+ creditCard: '1234-5678', // 不要传递信用卡
+};
+
+// ✅ 只传递必要信息
+const user = {
+ id: '12345',
+ name: '张三',
+ email: 'user@example.com',
+};
+```
+
+### 10.3 HTTPS使用
+
+生产环境强烈建议使用HTTPS:
+
+```bash
+# 开发环境
+REACT_APP_BYTEDESK_API_URL=http://43.143.189.195
+
+# 生产环境
+REACT_APP_BYTEDESK_API_URL=https://kefu.yourdomain.com
+```
+
+### 10.4 内容安全策略（CSP）
+
+如果您的项目使用CSP，需要允许以下域名：
+
+```html
+
+```
+
+---
+
+## 11. 获取帮助
+
+### 11.1 联系方式
+
+- **技术支持**: 访问 http://43.143.189.195/chat/ 在线咨询
+- **管理员**: 联系您的项目管理员获取ORG和SID
+- **后端工程师**: 联系后端团队确认服务器状态
+
+### 11.2 日志查看
+
+```javascript
+// 在浏览器控制台查看Bytedesk日志
+// 日志前缀为 [Bytedesk]
+
+// 示例:
+[Bytedesk] 开始加载客服Widget...
+[Bytedesk] Widget脚本加载成功
+[Bytedesk] 初始化Widget
+[Bytedesk] Widget初始化成功
+```
+
+### 11.3 调试技巧
+
+```javascript
+// 1. 检查配置是否正确
+console.log('Bytedesk配置:', getBytedeskConfig());
+
+// 2. 检查环境变量
+console.log('API URL:', process.env.REACT_APP_BYTEDESK_API_URL);
+console.log('ORG:', process.env.REACT_APP_BYTEDESK_ORG);
+console.log('SID:', process.env.REACT_APP_BYTEDESK_SID);
+
+// 3. 检查Widget是否加载
+console.log('BytedeskWeb对象:', window.BytedeskWeb);
+```
+
+---
+
+## 12. 版本历史
+
+| 版本 | 日期 | 更新内容 |
+|------|------|---------|
+| v1.0 | 2025-01-07 | 初始版本，支持基础集成功能 |
+
+---
+
+## 13. 附录
+
+### 13.1 完整配置示例
+
+```javascript
+// bytedesk.config.js - 完整配置
+export const bytedeskConfig = {
+ apiUrl: 'http://43.143.189.195',
+ htmlUrl: 'http://43.143.189.195/chat/',
+ placement: 'bottom-right',
+ marginBottom: 20,
+ marginSide: 20,
+ autoPopup: false,
+ locale: 'zh-cn',
+ bubbleConfig: {
+ show: true,
+ icon: '💬',
+ title: '在线客服',
+ subtitle: '点击咨询',
+ },
+ theme: {
+ mode: 'system',
+ backgroundColor: '#0066FF',
+ textColor: '#ffffff',
+ },
+ chatConfig: {
+ org: 'df_org_uid',
+ t: '2',
+ sid: 'df_wg_aftersales',
+ },
+};
+```
+
+### 13.2 文件清单
+
+集成所需的所有文件：
+
+```
+bytedesk-integration/
+├── components/
+│ └── BytedeskWidget.jsx # React组件（必需）
+├── config/
+│ └── bytedesk.config.js # 配置文件（必需）
+├── App.jsx.example # 集成示例（参考）
+├── .env.bytedesk.example # 环境变量示例（参考）
+└── 前端工程师集成手册.md # 本手册（参考）
+```
+
+---
+
+**祝您集成顺利！**
+
+如有任何问题，请随时联系技术支持。