PetAgent/docs/API_Documentation.md

# 云屋平台 - API文档

**版本:** 3.0  
**基础URL:** `https://api.yourdomain.com/api/v1` 或 `http://localhost:8000/api/v1` (开发环境)

## 概述

AI宠物伴侣平台API提供用户认证、聊天交互、背景管理、宠物配置和管理功能的端点。所有API端点遵循RESTful约定并返回JSON响应。

## 认证

大多数端点需要通过JWT（JSON网络令牌）进行认证。在Authorization头中包含令牌：

```
Authorization: Bearer <jwt_token>
```

## 错误处理

所有错误响应都遵循此格式：

```json
{
  "detail": "错误消息"
}
```

## 端点

### 用户管理

#### POST `/user/register`
注册新用户。

**请求体：**
```json
{
  "phone": "字符串",
  "password": "字符串",
  "nickname": "字符串",
  "openid": "字符串 (可选)"
}
```

**响应：**
```json
{
  "access_token": "字符串",
  "refresh_token": "字符串",
  "user": {
    "id": "数字",
    "uid": "字符串",
    "nickname": "字符串",
    "avatar": "字符串",
    "phone": "字符串"
  }
}
```

#### POST `/user/login`
认证用户并返回令牌。

**请求体：**
```json
{
  "phone": "字符串",
  "password": "字符串"
}
```

**响应：**
```json
{
  "access_token": "字符串",
  "refresh_token": "字符串",
  "user": {
    "id": "数字",
    "uid": "字符串",
    "nickname": "字符串",
    "avatar": "字符串",
    "phone": "字符串"
  }
}
```

#### POST `/user/wechat_login`
使用微信OAuth登录。

**请求体：**
```json
{
  "code": "字符串"
}
```

**响应：**
```json
{
  "access_token": "字符串",
  "refresh_token": "字符串",
  "user": {
    "id": "数字",
    "uid": "字符串",
    "nickname": "字符串",
    "avatar": "字符串",
    "phone": "字符串"
  }
}
```

#### GET `/user/profile`
获取当前用户资料。

**响应：**
```json
{
  "id": "数字",
  "uid": "字符串",
  "nickname": "字符串",
  "avatar": "字符串",
  "phone": "字符串",
  "status": "数字",
  "created_at": "日期时间"
}
```

#### PUT `/user/profile`
更新用户资料。

**请求体：**
```json
{
  "nickname": "字符串 (可选)",
  "avatar": "字符串 (可选)"
}
```

**响应：**
```json
{
  "id": "数字",
  "uid": "字符串",
  "nickname": "字符串",
  "avatar": "字符串",
  "phone": "字符串",
  "status": "数字",
  "updated_at": "日期时间"
}
```

### 背景管理

#### GET `/background/list`
获取用户可用背景列表。

**查询参数：**
- `visibility` (可选): 按可见性过滤 (1=公开, 2=私有, 3=VIP)
- `page` (可选): 页码 (默认: 1)
- `size` (可选): 页面大小 (默认: 20)

**响应：**
```json
{
  "data": [
    {
      "id": "数字",
      "name": "字符串",
      "resource_url": "字符串",
      "resource_type": "数字",
      "visibility": "数字",
      "bgm_url": "字符串",
      "is_locked": "布尔值",
      "lock_desc": "字符串",
      "price_points": "数字",
      "is_owned": "布尔值",
      "is_default": "布尔值"
    }
  ],
  "total": "数字",
  "page": "数字",
  "size": "数字"
}
```

#### GET `/background/detail/{background_id}`
获取特定背景的详细信息。

**响应：**
```json
{
  "id": "数字",
  "name": "字符串",
  "resource_url": "字符串",
  "resource_type": "数字",
  "visibility": "数字",
  "bgm_url": "字符串",
  "is_locked": "布尔值",
  "lock_desc": "字符串",
  "price_points": "数字",
  "pets": [
    {
      "id": "数字",
      "name": "字符串",
      "avatar": "字符串",
      "coordinate_x": "字符串",
      "coordinate_y": "字符串",
      "scale": "字符串",
      "scene_prompt": "字符串",
      "hello_message": "字符串"
    }
  ]
}
```

#### POST `/background/purchase`
购买锁定的背景。

**请求体：**
```json
{
  "background_id": "数字"
}
```

**响应：**
```json
{
  "success": "布尔值",
  "message": "字符串"
}
```

### 宠物管理

#### GET `/pet/list`
获取当前背景中可用的宠物列表。

**查询参数：**
- `background_id`: 背景ID

**响应：**
```json
{
  "data": [
    {
      "id": "数字",
      "name": "字符串",
      "avatar": "字符串",
      "global_prompt": "字符串",
      "tts_voice_id": "字符串",
      "tts_speed": "字符串",
      "tts_volume": "字符串",
      "coordinate_x": "字符串",
      "coordinate_y": "字符串",
      "scale": "字符串",
      "scene_prompt": "字符串",
      "hello_message": "字符串"
    }
  ]
}
```

#### GET `/pet/detail/{pet_id}`
获取特定宠物的详细信息。

**响应：**
```json
{
  "id": "数字",
  "name": "字符串",
  "avatar": "字符串",
  "global_prompt": "字符串",
  "tts_voice_id": "字符串",
  "tts_speed": "字符串",
  "tts_volume": "字符串",
  "status": "数字"
}
```

### 聊天管理

#### POST `/chat/send`
向AI宠物发送消息。

**请求体：**
```json
{
  "message": "字符串",
  "pet_id": "数字",
  "background_id": "数字",
  "conversation_id": "字符串 (可选)"
}
```

**响应：**
```json
{
  "response": "字符串",
  "conversation_id": "字符串",
  "tokens_used": {
    "input": "数字",
    "output": "数字"
  }
}
```

#### GET `/chat/history`
获取对话的聊天历史记录。

**查询参数：**
- `conversation_id`: 对话ID
- `page` (可选): 页码 (默认: 1)
- `size` (可选): 页面大小 (默认: 20)

**响应：**
```json
{
  "data": [
    {
      "id": "数字",
      "user_msg": "字符串",
      "ai_msg": "字符串",
      "created_at": "日期时间"
    }
  ],
  "total": "数字",
  "page": "数字",
  "size": "数字"
}
```

#### POST `/chat/audio_stream`
发送音频流进行实时处理（需要WebSocket连接）。

**WebSocket端点：** `/ws/audio/{user_id}`

**消息格式：**
```json
{
  "type": "audio_data | end_of_speech",
  "data": "二进制音频数据 | null",
  "timestamp": "ISO字符串"
}
```

### 管理功能

#### GET `/admin/users`
获取用户列表（仅管理员）。

**查询参数：**
- `status` (可选): 按状态过滤
- `page` (可选): 页码 (默认: 1)
- `size` (可选): 页面大小 (默认: 20)

**响应：**
```json
{
  "data": [
    {
      "id": "数字",
      "uid": "字符串",
      "nickname": "字符串",
      "avatar": "字符串",
      "phone": "字符串",
      "status": "数字",
      "created_at": "日期时间"
    }
  ],
  "total": "数字",
  "page": "数字",
  "size": "数字"
}
```

#### PUT `/admin/user/{user_id}/status`
更新用户状态（仅管理员）。

**请求体：**
```json
{
  "status": "数字 (1=激活, 2=禁止登录, 3=禁止发言)"
}
```

**响应：**
```json
{
  "success": "布尔值",
  "message": "字符串"
}
```

#### GET `/admin/chat_logs`
获取聊天日志（仅管理员）。

**查询参数：**
- `user_id` (可选): 按用户ID过滤
- `pet_id` (可选): 按宠物ID过滤
- `start_date` (可选): 按开始日期过滤
- `end_date` (可选): 按结束日期过滤
- `page` (可选): 页码 (默认: 1)
- `size` (可选): 页面大小 (默认: 20)

**响应：**
```json
{
  "data": [
    {
      "id": "数字",
      "user_id": "数字",
      "trace_id": "字符串",
      "pet_id": "数字",
      "bg_id": "数字",
      "user_msg": "字符串",
      "ai_msg": "字符串",
      "tokens_input": "数字",
      "tokens_output": "数字",
      "duration_ms": "数字",
      "conversation_id": "字符串",
      "created_at": "日期时间"
    }
  ],
  "total": "数字",
  "page": "数字",
  "size": "数字"
}
```

#### PUT `/admin/quota/gift`
向用户赠送配额（仅管理员）。

**请求体：**
```json
{
  "user_id": "数字",
  "amount": "数字"
}
```

**响应：**
```json
{
  "success": "布尔值",
  "message": "字符串"
}
```

## WebSocket连接

### 音频流
端点：`ws://localhost:8000/ws/audio/{user_id}`

用于与ASR和TTS服务进行实时音频处理。该连接支持双向音频流，实现无缝语音对话。

## 速率限制

- 未认证端点：每小时每个IP 100个请求
- 已认证端点：每小时每个用户 1000个请求
- 音频处理：每小时每个用户 50个请求

## 响应代码

- `200`: 成功
- `400`: 错误请求
- `401`: 未授权
- `403`: 禁止访问
- `404`: 未找到
- `422`: 验证错误
- `429`: 超出速率限制
- `500`: 内部服务器错误

## 附加资源

- [数据库模式](./database_schema.sql)
- [前端仓库](../frontend/)
- [后端仓库](../backend/)