sxc-frontend/web

SSXZ Web 项目

这是一个基于 Vue 3、Vite 和 TypeScript 构建的智能客服 Web 应用程序。项目名称"SSXZ"代表"四师在线"，是一个面向用户的智能咨询平台，集成了丰富的功能，包括实时聊天、音频录制/播放、Markdown 渲染，并使用了 Element Plus 构建现代化的用户界面。

项目概述

SSXZ Web 是一个全功能的智能客服系统前端应用，提供以下核心功能：

• 智能对话系统: 支持文本和语音输入的智能问答
• 实时流式对话: 基于 Server-Sent Events (SSE) 的实时消息流
• 多媒体支持: 音频录制、播放和语音转文字功能
• 服务导航: 结构化的服务分类和快速导航
• 常见问题: 预设的 FAQ 系统帮助用户快速找到答案
• 反馈系统: 用户可以对回答进行评价和反馈

技术栈

• 框架: Vue 3 (Composition API)
• 构建工具: Vite 6.2.1
• 语言: TypeScript 5.8
• 状态管理: Pinia 3.0.1
• 路由: Vue Router 4.5.0
• UI 组件库: Element Plus 2.9.6
• CSS 预处理器: Sass 1.85.1
• HTTP 客户端: Axios 1.8.4
• 音频处理:
  • Howler.js 2.2.4 (音频播放)
  • Wavesurfer.js 7.9.4 (音频波形可视化)
  • RecordRTC 5.6.2 (音频录制)
• Markdown 渲染:
  • Markdown-it 14.1.0 (核心解析器)
  • 多种插件支持 (缩写、脚注、任务列表、上下标等)
  • highlight.js 11.11.1 (代码高亮)
  • DOMPurify 3.2.4 (HTML 安全过滤)
• 实时通信: EventSource polyfill 1.0.31
• 工具库:
  • dayjs 1.11.13 (日期处理)
  • md5 2.3.0 (签名生成)
  • github-markdown-css 5.8.1 (Markdown 样式)

项目设置

前置条件

• Node.js (建议使用最新的 LTS 版本)
• npm

安装依赖

npm install

开发环境

启动带有热重载功能的开发服务器：

npm run dev

生产构建

进行类型检查、编译和压缩以用于生产环境：

npm run build

预览生产构建

在本地预览构建后的应用：

npm run preview

代码检查与格式化

npm run format

环境配置

项目使用环境变量进行配置，主要配置文件包括：

• .env.development: 开发环境配置
• .env.production: 生产环境配置

主要环境变量：

• VITE_API_BASE_URL: API 服务器地址
• VITE_API_SECRET: API 认证密钥
• VITE_IMAGE_DOMAIN: 图片资源域名

API 接口

项目采用 RESTful API 设计，所有请求都需要携带时间戳和签名进行认证。详细 API 文档请参考 API接口文档.md。

主要 API 模块：

• 基础信息模块: 网站配置、点赞/踩操作
• 聊天消息模块: 发送消息、SSE 流式响应
• 服务导航模块: 服务分类、服务项目查询
• 常见问题模块: FAQ 列表查询
• 媒体处理模块: 语音转文字、文字转语音
• 意见反馈模块: 用户反馈提交

目录结构

src/
├── api/                    # API 接口模块
│   ├── basic.ts           # 基础信息接口
│   ├── category.ts        # 服务分类接口
│   ├── commonProblem.ts   # 常见问题接口
│   ├── media.ts           # 媒体处理接口
│   ├── message.ts         # 消息相关接口
│   ├── opinion.ts         # 意见反馈接口
│   └── service.ts         # 服务导航接口
├── assets/                # 项目资源
│   ├── base.css           # 基础样式
│   ├── fonts.css          # 字体定义
│   └── main.css           # 主样式文件
├── components/            # 可复用的 Vue 组件
│   ├── SsCommonProblem.vue # 常见问题组件
│   ├── SsFooter.vue       # 页脚组件
│   ├── SsGridEntrance.vue # 网格入口组件
│   ├── SsHeader.vue       # 页头组件
│   ├── SsHeadline.vue     # 标题组件
│   ├── SsHotline.vue      # 热线组件
│   ├── SsInputBox.vue     # 输入框组件
│   ├── SsNavigation.vue   # 导航组件
│   ├── SsOpinion.vue      # 意见反馈组件
│   ├── SsPanel.vue        # 面板组件
│   ├── SsRecording.vue    # 录音组件
│   ├── SsService.vue      # 服务组件
│   └── ss_chat/           # 聊天相关组件
│       ├── SsChat.vue     # 主聊天组件
│       ├── components/    # 聊天子组件
│       │   ├── SsChatHistory.vue
│       │   ├── SsChatInput.vue
│       │   ├── SsChatMessage.vue
│       │   ├── SsChatReply.vue
│       │   └── SsChatSendMessage.vue
│       └── hooks/         # 聊天相关钩子
│           └── useEventSource.ts
├── hooks/                 # 组合式函数
│   └── useClipboard.ts    # 剪贴板操作钩子
├── plugins/               # 全局插件
│   └── globalMethods.ts   # 全局方法插件
├── router/                # Vue Router 配置
│   └── index.ts
├── stores/                # Pinia 状态仓库
│   └── global.ts          # 全局状态
├── types/                 # TypeScript 类型定义
│   ├── api.d.ts           # API 类型定义
│   ├── global.d.ts        # 全局类型定义
│   └── ...                # 其他类型定义文件
├── utils/                 # 工具函数
│   ├── EventSourceWrapper.ts # EventSource 封装
│   ├── PCMAudioPlayer.ts  # PCM 音频播放器
│   ├── common.ts          # 通用工具函数
│   ├── formatDate.ts      # 日期格式化
│   ├── parseMarkdown.ts   # Markdown 解析
│   ├── request.ts         # 请求封装
│   ├── string.extensions.ts # 字符串扩展
│   └── useDeviceDetection.ts # 设备检测
└── views/                 # 页面视图
    └── HomeView.vue       # 主页视图

核心功能详解

聊天系统

聊天系统是项目的核心功能，包含以下特性：

• 实时消息流: 基于 Server-Sent Events (SSE) 实现的实时消息推送
• 多媒体支持: 支持文本、音频等多种输入方式
• 消息历史: 保存和展示聊天记录
• Markdown 渲染: 支持富文本格式的消息展示
• 消息操作: 复制、编辑等消息操作功能

音频处理

项目集成了完整的音频处理功能：

• 音频录制: 使用 RecordRTC 实现高质量音频录制
• 音频播放: 基于 Howler.js 和 Wavesurfer.js 的音频播放和可视化
• 语音转文字: 集成语音识别功能，将音频转换为文本
• 文字转语音: 支持将文本转换为语音播放

服务导航

提供结构化的服务分类和导航功能：

• 服务分类: 展示不同类别的服务项目
• 快速导航: 便捷的服务入口和搜索功能
• 服务详情: 详细的服务介绍和指导

开发指南

组件开发规范

• 使用 Vue 3 Composition API
• 遵循 TypeScript 类型安全
• 组件命名采用 Ss 前缀
• 使用 <script setup> 语法
• 组件样式使用 scoped SCSS

API 调用规范

• 所有 API 请求通过 request.ts 工具封装
• 使用 TypeScript 类型定义确保类型安全
• 遵循 RESTful API 设计原则
• 错误处理统一管理

状态管理

• 使用 Pinia 进行状态管理
• 按功能模块划分 store
• 全局状态存储在 stores/global.ts

浏览器兼容性

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• 移动端浏览器支持

部署说明

生产环境构建

npm run build

构建产物将生成在 dist/ 目录下，可直接部署到静态服务器。

环境变量配置

确保部署前正确配置生产环境的环境变量，特别是 API 地址和密钥。

许可证

[请在此处添加许可证信息]