智能语音助手模块接口文档
===================

基础信息
-------
- 基础路径: /api/v1/assistant
- 请求方式: REST
- 数据格式: JSON
- 认证方式: Bearer Token

数据结构
-------

VoiceCommand 语音指令对象:
{
  id: number,          // 指令ID
  phrase: string,      // 语音短语
  action: string,      // 执行动作
  type: string,        // 指令类型
  enabled: boolean,    // 是否启用
  createTime: string   // 创建时间
}

VoiceReminder 语音提醒对象:
{
  id: number,          // 提醒ID
  title: string,       // 提醒标题
  content: string,     // 提醒内容
  time: string,        // 提醒时间
  repeat: string[],    // 重复周期
  voiceEnabled: boolean, // 是否启用语音
  status: string       // 提醒状态
}

VoiceMessage 对话消息对象:
{
  id: number,          // 消息ID
  role: string,        // 消息角色(user/assistant)
  content: string,     // 消息内容
  type: string,        // 消息类型(text/voice)
  time: string,        // 消息时间
  audioUrl?: string    // 语音URL（可选）
}

API 接口
-------

1. 语音识别
POST /api/v1/assistant/recognize
Content-Type: multipart/form-data

请求参数：
| 参数名 | 类型   | 必填 | 说明 |
| audio  | File   | 是   | 语音文件(WAV/MP3) |
| lang   | string | 否   | 语言代码(zh-CN/en-US) |

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "text": "打开电视",
    "confidence": 0.95
  }
}

2. 语音合成
POST /api/v1/assistant/synthesize

请求参数：
{
  "text": "好的，已为您打开电视",
  "voice": "female",
  "rate": 1.0,
  "pitch": 1.0
}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "audioUrl": "https://example.com/audio/123.mp3",
    "duration": 3.5
  }
}

3. 执行语音指令
POST /api/v1/assistant/execute

请求参数：
{
  "command": "打开电视",
  "context": {
    "room": "客厅",
    "device": "tv"
  }
}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "action": "tv_on",
    "status": "success",
    "response": "好的，已为您打开电视"
  }
}

4. 获取语音指令列表
GET /api/v1/assistant/commands

请求参数：
| 参数名 | 类型   | 必填 | 说明 |
| type   | string | 否   | 指令类型 |
| enabled| boolean| 否   | 是否启用 |

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "phrase": "打开电视",
      "action": "tv_on",
      "type": "device",
      "enabled": true,
      "createTime": "2024-03-20 10:00:00"
    }
  ]
}

5. 添加语音提醒
POST /api/v1/assistant/reminders

请求参数：
{
  "title": "吃药提醒",
  "content": "该吃降压药了",
  "time": "08:00",
  "repeat": ["mon", "wed", "fri"],
  "voiceEnabled": true
}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "title": "吃药提醒",
    "content": "该吃降压药了",
    "time": "08:00",
    "repeat": ["mon", "wed", "fri"],
    "voiceEnabled": true,
    "status": "pending"
  }
}

6. 获取对话历史
GET /api/v1/assistant/messages

请求参数：
| 参数名 | 类型   | 必填 | 说明 |
| page   | number | 否   | 页码，默认1 |
| size   | number | 否   | 每页数量，默认20 |

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "records": [
      {
        "id": 1,
        "role": "user",
        "content": "今天天气怎么样",
        "type": "voice",
        "time": "2024-03-20 10:00:00",
        "audioUrl": "https://example.com/audio/q123.mp3"
      },
      {
        "id": 2,
        "role": "assistant",
        "content": "今天天气晴朗，气温20度，适合外出活动",
        "type": "text",
        "time": "2024-03-20 10:00:01"
      }
    ]
  }
}

7. 更新语音设置
PUT /api/v1/assistant/settings

请求参数：
{
  "volume": 80,
  "rate": 1.0,
  "voice": "female",
  "wakeWord": "小助手",
  "autoReply": true
}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "volume": 80,
    "rate": 1.0,
    "voice": "female",
    "wakeWord": "小助手",
    "autoReply": true,
    "updateTime": "2024-03-20 10:00:00"
  }
}

错误码说明
--------
| 错误码 | 说明 |
| 200    | 成功 |
| 400    | 请求参数错误 |
| 401    | 未授权 |
| 403    | 禁止访问 |
| 404    | 资源不存在 |
| 500    | 服务器内部错误 |

注意事项
-------
1. 语音文件格式要求：
   - 支持格式：WAV、MP3
   - 采样率：16kHz
   - 时长限制：60秒

2. 语音识别支持的语言：
   - 中文（zh-CN）
   - 英文（en-US）

3. 语音合成注意事项：
   - 速率范围：0.5-2.0
   - 音量范围：0-100
   - 支持的声音：男声、女声

4. 性能优化��
   - 语音文件建议压缩后上传
   - 长文本建议分段合成
   - 使用WebSocket保持实时连接

5. 安全建议：
   - 语音文件存储时加密
   - 定期清理历史记录
   - 设置访问频率限制