# API 接口文档

## 认证接口

### 1. 用户注册
- **URL**: `POST /api/auth/register`
- **Body**:
  ```json
  {
    "nickname": "用户昵称",
    "phone": "13800138000",
    "password": "123456",
    "email": "user@example.com"  // 可选
  }
  ```
- **Response**:
  ```json
  {
    "code": 200,
    "message": "注册成功",
    "data": {
      "token": "jwt_token_here",
      "user": { "id": "...", "nickname": "..." }
    }
  }
  ```

### 2. 用户登录
- **URL**: `POST /api/auth/login`
- **Body**:
  ```json
  {
    "phone": "13800138000",
    "password": "123456"
  }
  ```

### 3. 微信登录
- **URL**: `POST /api/auth/wxlogin`
- **Body**:
  ```json
  {
    "code": "wx_code",
    "nickname": "微信用户",
    "avatar": "https://..."
  }
  ```

### 4. 退出登录
- **URL**: `POST /api/auth/logout`
- **Header**: `Authorization: Bearer <token>`

### 5. 获取个人信息
- **URL**: `GET /api/auth/profile`
- **Header**: `Authorization: Bearer <token>`

---

## 消息接口

### 1. 发送消息
- **URL**: `POST /api/message/send`
- **Body**:
  ```json
  {
    "conversationId": "conv_id",
    "type": "text|image|voice|video|file",
    "content": "消息内容",
    "mediaUrl": "https://...",  // 媒体消息
    "mediaDuration": 10          // 语音/视频时长
  }
  ```

### 2. 获取会话消息
- **URL**: `GET /api/message/conversation/:id?page=1&limit=20`

### 3. 撤回消息
- **URL**: `POST /api/message/recall/:messageId`

### 4. 标记已读
- **URL**: `POST /api/message/read`
- **Body**:
  ```json
  {
    "conversationId": "conv_id",
    "messageIds": ["msg1", "msg2"]
  }
  ```

### 5. 创建会话
- **URL**: `POST /api/message/conversation/create`
- **Body**:
  ```json
  {
    "type": "private|group",
    "participants": ["user_id_1", "user_id_2"],
    "groupName": "群名称"  // 群聊时必填
  }
  ```

---

## 通话接口

### 1. 发起语音通话
- **URL**: `POST /api/call/voice`
- **Body**: `{ "calleeId": "user_id" }`

### 2. 发起视频通话
- **URL**: `POST /api/call/video`
- **Body**: `{ "calleeId": "user_id" }`

### 3. 接听通话
- **URL**: `POST /api/call/accept/:callId`

### 4. 拒绝通话
- **URL**: `POST /api/call/reject/:callId`

### 5. 结束通话
- **URL**: `POST /api/call/end/:callId`

### 6. 通话记录
- **URL**: `GET /api/call/history?page=1&limit=20`

### 7. WebRTC 信令
- **Offer**: `POST /api/call/signaling/offer`
- **Answer**: `POST /api/call/signaling/answer`
- **ICE**: `POST /api/call/signaling/ice`

---

## WebSocket 事件

### 客户端 → 服务端

| 事件 | 数据 | 说明 |
|------|------|------|
| `message:send` | `{conversationId, type, content}` | 发送消息 |
| `message:read` | `{conversationId, messageIds}` | 标记已读 |
| `message:typing` | `{conversationId}` | 正在输入 |
| `call:initiate` | `{calleeId, type}` | 发起通话 |
| `call:accept` | `{callId}` | 接听通话 |
| `call:reject` | `{callId}` | 拒绝通话 |
| `call:end` | `{callId}` | 结束通话 |
| `call:offer` | `{callId, offer}` | WebRTC Offer |
| `call:answer` | `{callId, answer}` | WebRTC Answer |
| `call:ice` | `{callId, candidate}` | ICE Candidate |
| `ping` | `{time}` | 心跳 |

### 服务端 → 客户端

| 事件 | 数据 | 说明 |
|------|------|------|
| `message:receive` | `{...message}` | 收到新消息 |
| `message:read:ack` | `{conversationId, readBy}` | 已读确认 |
| `user:online` | `{userId}` | 用户上线 |
| `user:offline` | `{userId}` | 用户下线 |
| `call:incoming` | `{callId, roomId, type, caller}` | 来电邀请 |
| `call:accepted` | `{callId, roomId}` | 对方接听 |
| `call:rejected` | `{callId}` | 对方拒绝 |
| `call:ended` | `{callId, duration}` | 通话结束 |
| `call:offer` | `{callId, offer}` | 转发 Offer |
| `call:answer` | `{callId, answer}` | 转发 Answer |
| `call:ice` | `{callId, candidate}` | 转发 ICE |

---

## 数据模型

### User（用户）
| 字段 | 类型 | 说明 |
|------|------|------|
| openid | String | 微信 OpenID |
| nickname | String | 昵称 |
| avatar | String | 头像URL |
| phone | String | 手机号 |
| online | Boolean | 在线状态 |
| friends | Array | 好友列表 |
| settings | Object | 用户设置 |

### Message（消息）
| 字段 | 类型 | 说明 |
|------|------|------|
| conversationId | ObjectId | 所属会话 |
| sender | ObjectId | 发送者 |
| type | String | 消息类型 |
| content | String | 消息内容 |
| mediaUrl | String | 媒体URL |
| status | String | 发送状态 |
| readBy | Array | 已读用户 |

### Call（通话）
| 字段 | 类型 | 说明 |
|------|------|------|
| type | String | voice/video |
| caller | ObjectId | 发起者 |
| callee | ObjectId | 接收者 |
| status | String | 通话状态 |
| roomId | String | 房间ID |
| duration | Number | 通话时长(秒) |