客服与反馈系统

HackathonWeekly 客服与反馈功能的开发指南

客服与反馈系统

客服与反馈系统为用户提供统一的客服入口，支持 AI 智能客服、社群服务和文档帮助等功能。

功能特性

统一客服入口：浮动按钮或内联组件，方便用户随时获取帮助
多种服务方式：AI 客服、社群二维码、帮助文档
管理后台：管理员可配置社群二维码和相关设置
响应式设计：支持桌面端和移动端
主题适配：支持亮色和暗色主题

系统架构

前端组件

src/modules/shared/components/
├── CustomerServiceWidget.tsx     # 主入口组件
└── CustomerServiceModal.tsx      # 弹窗组件

后端 API

src/server/routes/customer-service.ts  # API 路由

管理后台

src/app/(app)/app/(account)/admin/customer-service/
├── page.tsx                          # 管理页面
├── layout.tsx                        # 布局文件
└── components/
    └── CustomerServiceAdmin.tsx      # 管理组件

数据库模型

model CustomerServiceConfig {
  id          String   @id @default(cuid())
  qrCodeUrl   String?  // 社群二维码URL
  qrCodeAlt   String?  // 二维码描述文本
  isActive    Boolean  @default(true)
  updatedBy   String   // 更新人员ID
  updatedAt   DateTime @updatedAt
  createdAt   DateTime @default(now())
  
  updatedByUser User   @relation(fields: [updatedBy], references: [id])
  
  @@map("customer_service_config")
}

配置说明

1. 基础配置

在 src/config/index.ts 中配置客服功能：

customerService: {
  // 是否启用客服功能
  enabled: true,
  // AI 客服配置（预留接口）
  aiChat: {
    enabled: false,
    provider: "openai" as const,
  },
  // 社群服务配置
  community: {
    enabled: true,
    qrCodeUpload: true,
  },
  // 反馈系统配置
  feedback: {
    enabled: true,
    docsIntegration: true,
  },
}

2. 类型定义

在 src/config/types.ts 中添加类型：

customerService: {
  enabled: boolean;
  aiChat: {
    enabled: boolean;
    provider?: "openai" | "zhipu" | "qwen";
  };
  community: {
    enabled: boolean;
    qrCodeUpload: boolean;
  };
  feedback: {
    enabled: boolean;
    docsIntegration: boolean;
  };
};

使用方法

1. 基础组件使用

import { CustomerServiceWidget } from "@/components/shared/CustomerServiceWidget";

// 浮动按钮样式（默认）
<CustomerServiceWidget />

// 内联按钮样式
<CustomerServiceWidget variant="inline" />

// 自定义样式
<CustomerServiceWidget 
  variant="floating" 
  className="custom-styles"
/>

2. 快捷操作组件

import { CustomerServiceQuickActions } from "@/components/shared/CustomerServiceWidget";

<CustomerServiceQuickActions />

3. 单独使用弹窗

import { CustomerServiceModal } from "@/components/shared/CustomerServiceModal";

function MyComponent() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <CustomerServiceModal
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
      defaultTab="community" // 可选：默认打开的标签页
    />
  );
}

API 接口

公开接口

获取客服配置

GET /api/customer-service/config

响应：

{
  "qrCodeUrl": "https://example.com/qr-code.png",
  "qrCodeAlt": "扫码加入微信群"
}

管理员接口

需要管理员权限，通过 Better Auth 中间件保护。

获取完整配置

GET /api/customer-service/admin/config

响应：

{
  "id": "clxxxxxx",
  "qrCodeUrl": "https://example.com/qr-code.png",
  "qrCodeAlt": "扫码加入微信群",
  "isActive": true,
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "updatedByUser": {
    "id": "clxxxxxx",
    "name": "管理员",
    "email": "admin@example.com"
  }
}

更新配置

PUT /api/customer-service/admin/config
Content-Type: application/json

{
  "qrCodeUrl": "https://example.com/new-qr-code.png",
  "qrCodeAlt": "扫码关注公众号"
}

删除配置

DELETE /api/customer-service/admin/config/:id

管理后台使用

访问管理后台

管理员用户可通过以下路径访问：

/app/admin/customer-service

功能说明

社群二维码管理
- 上传二维码图片（支持 JPG、PNG、WebP）
- 设置二维码描述文字
- 实时预览效果
配置管理
- 保存配置更改
- 查看更新历史
- 重新加载配置
预览功能
- 浮动按钮效果预览
- 内联按钮效果预览
- 实时查看配置效果

开发注意事项

1. 权限控制

查看客服功能：所有用户
管理配置：仅管理员用户
API 保护：使用 Better Auth 中间件

2. 文件上传

二维码图片通过现有的上传系统处理：

使用 ImageUpload 组件
支持 S3 兼容存储
自动压缩和优化

3. 响应式适配

组件已适配移动端：

浮动按钮在移动端显示为底部抽屉
弹窗内容自适应屏幕大小
支持触摸操作

4. 主题适配

所有组件支持亮色/暗色主题：

使用 Tailwind CSS 的 dark: 前缀
自动跟随系统主题设置
兼容现有主题切换功能

AI 客服集成方案

实现步骤

在配置中启用 AI 客服
添加对应的环境变量
实现 AI API 调用逻辑
更新 CustomerServiceModal 组件
添加对话界面和状态管理

故障排除

常见问题

二维码不显示
- 检查图片 URL 是否有效
- 确认存储服务配置正确
- 查看浏览器网络请求
管理后台无法访问
- 确认用户具有管理员权限
- 检查认证中间件配置
- 验证路由配置正确
配置不生效
- 检查 config.customerService.enabled
- 重启开发服务器
- 清除浏览器缓存

调试方法

// 开启调试日志
console.log("CustomerService Config:", config.customerService);

// 检查 API 响应
fetch("/api/customer-service/config")
  .then(res => res.json())
  .then(console.log);

扩展开发

添加新的服务类型

更新配置类型定义
修改 CustomerServiceModal 组件
添加对应的 API 接口
更新管理后台界面

自定义样式

// 自定义浮动按钮样式
<CustomerServiceWidget 
  className="bottom-8 right-8 bg-custom-color hover:bg-custom-hover"
/>

集成第三方客服

// 示例：集成 Intercom
const initializeIntercom = () => {
  window.Intercom('boot', {
    app_id: process.env.NEXT_PUBLIC_INTERCOM_APP_ID,
  });
};

更新日志

v1.0.0 - 基础功能实现
- 客服组件和弹窗
- 社群二维码功能
- 管理后台
- API 接口
v1.1.0 - 计划功能
- AI 客服集成
- 工单系统
- 多语言支持
- 移动端优化

客服与反馈系统

On this page