# 接口文档

本地 Base URL：

```
http://127.0.0.1:8001
```

自动生成文档：

- Swagger UI：`/docs`
- ReDoc：`/redoc`

## 1. 健康检查

### `GET /health`

用途：

- 检查服务是否存活。

响应示例：

```json
{
  "status": "ok"
}
```

## 2. 发送消息

### `POST /messages`

用途：

- 保存单聊消息。
- 服务端会根据 `sender_user_id` 和 `peer_user_id` 自动查找或创建会话。
- `client_msg_id` 用于幂等控制。

请求体：

```json
{
  "sender_user_id": 1,
  "peer_user_id": 2,
  "client_msg_id": "msg-20260326-0001",
  "content_type": 1,
  "content_text": "hello"
}
```

字段规则：

- `sender_user_id`：`int > 0`
- `peer_user_id`：`int > 0`，且不能与 `sender_user_id` 相同
- `client_msg_id`：`string`，长度 `1-64`
- `content_type`：`1=text 2=audio 3=image 4=json`
- `content_text`：`content_type=1` 时必填
- `content_json`：`content_type=4` 时必填
- `media_file_key`：`content_type=2` 或 `3` 时必填
- `media_duration_ms`：媒体时长（可选，毫秒）

成功响应（首次入库，`201`）：

```json
{
  "idempotent": false,
  "message": {
    "id": 1006,
    "conversation_id": 1,
    "seq": 6,
    "sender_user_id": 1,
    "role": 1,
    "content_type": 1,
    "content_text": "hello",
    "content_json": null,
    "media_file_key": null,
    "media_duration_ms": null,
    "client_msg_id": "msg-20260326-0001",
    "created_at": "2026-03-26T10:40:00.123000"
  }
}
```

成功响应（幂等命中，`200`）：

```json
{
  "idempotent": true,
  "message": {
    "id": 1006,
    "conversation_id": 1,
    "seq": 6,
    "sender_user_id": 1,
    "role": 1,
    "content_type": 1,
    "content_text": "hello",
    "content_json": null,
    "media_file_key": null,
    "media_duration_ms": null,
    "client_msg_id": "msg-20260326-0001",
    "created_at": "2026-03-26T10:40:00.123000"
  }
}
```

常见错误码：

- `404`：发送人或接收人不存在/不可用
- `409`：会话不是激活状态
- `422`：请求参数校验失败

## 3. 查询消息

### `GET /messages`

用途：

- 按会话分页读取消息。
- 返回结果按 `seq` 正序排列。

Query 参数：

- `conversation_id`（必填）：`int > 0`
- `cursor_seq`（可选）：`int >= 1`，用于向前翻页
- `limit`（可选）：默认 `20`，最大 `100`

请求示例：

```
GET /messages?conversation_id=1&limit=20
GET /messages?conversation_id=1&cursor_seq=50&limit=20
```

响应示例：

```json
{
  "conversation_id": 1,
  "has_more": false,
  "next_cursor_seq": null,
  "items": [
    {
      "id": 1001,
      "conversation_id": 1,
      "seq": 1,
      "sender_user_id": 1,
      "role": 1,
      "content_type": 1,
      "content_text": "Hi, did you finish homework?",
      "content_json": {
        "lang": "en"
      },
      "media_file_key": null,
      "media_duration_ms": null,
      "client_msg_id": "c1-m1",
      "created_at": "2026-03-25T10:00:05"
    }
  ]
}
```

常见错误码：

- `404`：会话不存在
- `422`：请求参数校验失败