sxc-frontend/web/docs/API接口文档.md

SSXZ Web 项目 API 接口文档

目录

• 基础信息
• 认证机制
• 通用响应格式
• API接口列表
  • 基础信息模块
  • 聊天消息模块
  • 服务导航模块
  • 常见问题模块
  • 媒体处理模块
  • 意见反馈模块

基础信息

• API基础地址: http://192.168.1.5:9580/client-api
• API密钥: 在环境变量 VITE_API_SECRET 中配置
• 请求超时: 600秒
• 文件上传超时: 300秒

认证机制

所有API请求需要包含以下头部信息：

1. 时间戳: h-timestamp
2. 签名: h-sign
3. 认证令牌: access-auth-token (可选，从localStorage获取)

签名生成规则:

// 1. 将请求参数按ASCII码排序
// 2. 拼接排序后的参数值
// 3. 在末尾添加API密钥
// 4. 对拼接后的字符串进行MD5加密并转为大写

通用响应格式

interface ResponseData<T = any> {
    code: number,      // 状态码，200表示成功
    data: T,           // 响应数据
    message: string    // 响应消息
}

API接口列表

基础信息模块

获取网站基础信息

• 接口地址: GET /v1/websiteSet/selWebsiteSet
• 描述: 获取网站基础配置信息
• 请求参数: 无

• 响应数据:

  type Basic = {
  competentUnit: string,        // 主管单位
  organizer: string,            // 承办单位
  icpRecord: string,            // ICP备案
  websiteIdentifier: string,    // 网站标识码
  securityRecord: string,       // 网安备案号
  officeHours: string,          // 办公时间
  officeAddress: string,        // 办公地址
  dutyPhone: string,            // 值班电话
  fax: string,                  // 传真
  reportPhone: string,          // 举报电话
  reportMail: string,           // 举报信件
  serviceHotline: string,       // 服务热线
  miniAppQrcodeUrl: string,     // 小程序二维码URL
  miniAppLink: string,          // 小程序链接URL
  policyFileUrl: string,        // 政策文件
  urlLink: string,              // 小程序链接 URLLink
  shortLink: string,            // 小程序链接 ShortLink
  }
  

点赞或踩

• 接口地址: POST /v1/chat/likeOrStepOn
• 描述: 对聊天内容进行点赞或踩评价

• 请求参数:

  type likeOrStepParams = {
  chatId: string,       // 聊天ID
  likeOrStepOn: number  // 1:点赞, 2:踩
  }
  

• 响应数据: null

---

聊天消息模块

发送消息(流式响应)

• 接口地址: GET /v1/chat/sendMsg
• 描述: 发送聊天消息并接收流式响应
• 请求方式: EventSource (Server-Sent Events)

• 请求参数:

  type streamChatParams = {
  message: string,           // 消息内容
  conversationId: string     // 对话ID
  }
  

• 请求头:

  Content-Type: text/event-stream; charset=utf-8
  h-timestamp: [时间戳]
  h-sign: [签名]
  

• 响应事件类型:

1. conversation.chat.created: 创建对话

   {
    "event": {"value": "conversation.chat.created"},
    "chat": {
      "id": "聊天ID",
      "conversationID": "对话ID"
    }
   }
   

2. conversation.message.delta: 消息增量

   {
    "event": {"value": "conversation.message.delta"},
    "message": {
      "content": "消息内容片段"
    }
   }
   

3. conversation.chat.completed: 对话完成

   {
    "event": {"value": "conversation.chat.completed"}
   }
   

4. conversation.message.completed: 消息完成

   {
    "event": {"value": "conversation.message.completed"},
    "message": {
      "content": "完整消息内容",
      "contentType": {"value": "text|card"}
    }
   }
   

---

服务导航模块

获取服务指南分类

• 接口地址: GET /v1/serviceGuide/guideCategory
• 描述: 获取服务指南分类列表
• 请求参数: 无

• 响应数据:

  type CategoryResult = categoryItem[]
  
  interface categoryItem {
  id: number,              // 分类ID
  categoryName: string,    // 分类名称
  imgUrl: string,          // 分类图片URL
  profile: string,         // 分类简介
  profileWap: string,      // 移动端分类简介
  }
  

获取服务指南内容

• 接口地址: GET /v1/serviceGuide/guideItem
• 描述: 获取指定分类下的服务指南内容

• 请求参数:

  type ServiceParams = {
  categoryId: number|string,  // 分类ID
  pageNum: number,           // 页码
  pageSize: number           // 每页数量
  }
  

• 响应数据:

  type ServiceResult = {
  total: number,             // 总记录数
  size: number,              // 每页数量
  current: number,           // 当前页码
  pages: number,             // 总页数
  records: ServiceContent[],  // 记录列表
  success: boolean,          // 是否成功
  message: string            // 消息
  }
  
  interface ServiceContent {
  itemContent: string        // 服务内容
  }
  

---

常见问题模块

获取常见问题列表

• 接口地址: GET /v1/questions/selCommonQuestionsRandom
• 描述: 获取常见问题列表

• 请求参数:

  type CommonProblemParams = {
  pageNum: number,    // 页码
  pageSize: number,   // 每页数量
  keyword: string     // 关键词
  }
  

• 响应数据:

  type CommonProblemResult = {
  total: number,                    // 总记录数
  size: number,                     // 每页数量
  current: number,                  // 当前页码
  pages: number,                    // 总页数
  records: CommonProblemList[],      // 记录列表
  success: boolean,                 // 是否成功
  message: string                   // 消息
  }
  
  type CommonProblemList = commonProblemItem[]
  
  interface commonProblemItem {
  questionContent: string,    // 问题内容
  remark: string | null,      // 备注
  }
  

---

媒体处理模块

文字转语音

• 接口地址: POST /v1/chat/textToSpeech
• 描述: 将文字转换为语音

• 请求参数:

  type TextToSpeechParams = {
  text: string    // 要转换的文字
  }
  

• 响应数据:

  type TextToSpeechResult = {
  audioUrl: string    // 语音文件URL
  }
  

• 超时时间: 300秒

语音转文字

• 接口地址: POST /v1/chat/transcribe
• 描述: 将语音文件转换为文字
• 请求参数:
  • 文件上传 (multipart/form-data)
  • 字段名: file

• 响应数据:

  type TranscribeResult = {
  text: string    // 识别后的文字
  }
  

• 超时时间: 300秒

获取语音反馈令牌

• 接口地址: GET /v1/chat/getFeedbackToken
• 描述: 获取语音反馈所需的令牌

• 请求头:

  Authorization: xT5v2pA7eJ9rL0fD3gH8kM4nZ6bW2cY
  

• 响应数据: 令牌字符串

---

意见反馈模块

提交意见反馈

• 接口地址: POST /v1/feedback/subFeedback
• 描述: 提交用户意见反馈

• 请求参数:

  type OpinionParams = {
  feedbackContent: string,    // 反馈内容
  phone: string,              // 联系电话
  }
  

• 响应数据: null

---

错误处理

错误码说明

• 200: 请求成功
• NETWORK_ERROR: 网络连接失败
• 其他业务错误码: 根据具体接口定义

错误响应示例

{
    "code": 400,
    "data": null,
    "message": "参数错误"
}

---

注意事项

1. 所有API请求都需要携带时间戳和签名
2. 文件上传接口使用multipart/form-data格式
3. 聊天消息接口使用EventSource实现流式响应
4. 请求超时时间为600秒，文件上传和媒体处理接口超时时间为300秒
5. 认证令牌从localStorage中获取，如存在则添加到请求头

---

更新记录

• 2024-01-01: 初始版本
• 2024-01-15: 添加媒体处理模块接口
• 2024-02-01: 更新签名算法