# SSXZ Web 项目 API 接口文档

## 目录
- [基础信息](#基础信息)
- [认证机制](#认证机制)
- [通用响应格式](#通用响应格式)
- [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获取)

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

## 通用响应格式

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

## API接口列表

### 基础信息模块

#### 获取网站基础信息

- **接口地址**: `GET /v1/websiteSet/selWebsiteSet`
- **描述**: 获取网站基础配置信息
- **请求参数**: 无
- **响应数据**:

```typescript
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`
- **描述**: 对聊天内容进行点赞或踩评价
- **请求参数**:

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

- **响应数据**: `null`

---

### 聊天消息模块

#### 发送消息(流式响应)

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

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

- **请求头**:

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

- **响应事件类型**:

1. **conversation.chat.created**: 创建对话
   ```json
   {
     "event": {"value": "conversation.chat.created"},
     "chat": {
       "id": "聊天ID",
       "conversationID": "对话ID"
     }
   }
   ```

2. **conversation.message.delta**: 消息增量
   ```json
   {
     "event": {"value": "conversation.message.delta"},
     "message": {
       "content": "消息内容片段"
     }
   }
   ```

3. **conversation.chat.completed**: 对话完成
   ```json
   {
     "event": {"value": "conversation.chat.completed"}
   }
   ```

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

---

### 服务导航模块

#### 获取服务指南分类

- **接口地址**: `GET /v1/serviceGuide/guideCategory`
- **描述**: 获取服务指南分类列表
- **请求参数**: 无
- **响应数据**:

```typescript
type CategoryResult = categoryItem[]

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

#### 获取服务指南内容

- **接口地址**: `GET /v1/serviceGuide/guideItem`
- **描述**: 获取指定分类下的服务指南内容
- **请求参数**:

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

- **响应数据**:

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

interface ServiceContent {
    itemContent: string        // 服务内容
}
```

---

### 常见问题模块

#### 获取常见问题列表

- **接口地址**: `GET /v1/questions/selCommonQuestionsRandom`
- **描述**: 获取常见问题列表
- **请求参数**:

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

- **响应数据**:

```typescript
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`
- **描述**: 将文字转换为语音
- **请求参数**:

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

- **响应数据**:

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

- **超时时间**: 300秒

#### 语音转文字

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

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

- **超时时间**: 300秒

#### 获取语音反馈令牌

- **接口地址**: `GET /v1/chat/getFeedbackToken`
- **描述**: 获取语音反馈所需的令牌
- **请求头**:

```
Authorization: xT5v2pA7eJ9rL0fD3gH8kM4nZ6bW2cY
```

- **响应数据**: 令牌字符串

---

### 意见反馈模块

#### 提交意见反馈

- **接口地址**: `POST /v1/feedback/subFeedback`
- **描述**: 提交用户意见反馈
- **请求参数**:

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

- **响应数据**: `null`

---

## 错误处理

### 错误码说明

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

### 错误响应示例

```json
{
    "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: 更新签名算法