# CozSweet 多角色聊天前端对接

## 3. Character IDs

前端先调用：

```http
GET <API_BASE_URL>/api/characters?capability=chat
```

聊天业务统一使用响应里的 `items[].id`。当前规范 ID 是：

```text
elio
maya-tan
nayeli-cervantes
```

只允许传递角色目录响应中的 `items[].id`，不要传展示名或 `@handle`。

角色响应中的 `capabilities` 是后端权威开关。`chat=false` 时不得开放输入框；直接调用聊天接口会得到 `CHARACTER_DISABLED`，不会返回 Elio 历史。

## 4. Send Message

### Request URL

```http
POST <API_BASE_URL>/api/chat/send
Content-Type: application/json
Authorization: Bearer <TOKEN>
```

### Parameters

| Field | Type | Required | Example | Meaning |
| --- | --- | --- | --- | --- |
| `characterId` | string | 新前端必传 | `maya-tan` | 当前聊天角色 ID |
| `message` | string | 与图片至少一项有值 | `Hello Maya` | 用户文本，最多 4000 字符 |
| `imageId` | string | 否 | `abc123` | 上传图片 ID |
| `imageThumbUrl` | string | 否 | `/images/...` | 缩略图 |
| `imageMediumUrl` | string | 否 | `/images/...` | 模型识图使用 |
| `imageOriginalUrl` | string | 否 | `/images/...` | 原图 |
| `imageWidth` | integer | 否 | `1080` | 图片宽 |
| `imageHeight` | integer | 否 | `1440` | 图片高 |
| `useWebSocket` | boolean | 否 | `false` | 是否同时通过已连接 WS 推送 |

```bash
curl -X POST 'https://proapi.banlv-ai.com/api/chat/send' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"characterId":"maya-tan","message":"Hello Maya","useWebSocket":false}'
```

响应沿用现有发送结构。前端仍读取 `data.reply`、`data.messageId`、`data.audioUrl`、`data.image` 和 `data.lockDetail`，无需从响应推断角色。

## 5. Chat History

```http
GET <API_BASE_URL>/api/chat/history?characterId=maya-tan&limit=50&offset=0
Authorization: Bearer <TOKEN>
```

| Query | Type | Required | Rule |
| --- | --- | --- | --- |
| `characterId` | string | 新前端必传 | 只返回该角色数据 |
| `limit` | integer | 否 | `1-200`，默认 `50` |
| `offset` | integer | 否 | 最小 `0` |

`messages` 和 `total` 都只统计指定角色。切换角色时必须重新请求 history，不能复用上一个角色的本地数组。

```json
{
  "code": 200,
  "success": true,
  "message": "success",
  "data": {
    "messages": [
      {
        "role": "user",
        "type": "text",
        "content": "Hello Maya",
        "id": "<MESSAGE_ID>",
        "created_at": "2026-07-17T09:00:00Z",
        "audioUrl": null,
        "image": {"type": null, "url": null},
        "lockDetail": {"locked": false, "showContent": true, "showUpgrade": false}
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0,
    "isVip": false
  }
}
```

## 6. Latest Previews

角色会话列表可一次请求所有可聊天角色的最后一条消息：

```http
GET <API_BASE_URL>/api/chat/previews
Authorization: Bearer <TOKEN>
```

```json
{
  "code": 200,
  "success": true,
  "data": {
    "items": [
      {"characterId": "elio", "message": {"id": "...", "role": "assistant", "type": "text", "content": "..."}},
      {"characterId": "maya-tan", "message": null}
    ]
  }
}
```

锁定私密文本不会泄露内容，锁定语音不会返回 `audioUrl`（文字仍正常返回）。图片沿用现有协议，URL 可以存在；前端必须以 `lockDetail.locked=true` 覆盖展示，不能把“URL 非空”当作已解锁。

## 7. Unlock One Message

```http
POST <API_BASE_URL>/api/chat/unlock-private
Content-Type: application/json
Authorization: Bearer <TOKEN>
```

```json
{
  "characterId": "maya-tan",
  "messageId": "<MESSAGE_ID>",
  "lockType": "voice_message",
  "clientLockId": "maya-card-001"
}
```

`messageId` 存在时，后端会核对消息角色。拿 Elio 的 `messageId` 配 Maya 的 `characterId` 会返回 HTTP `409 / CHARACTER_MISMATCH`，且不会扣积分。

前端临时伪造锁卡片没有 `messageId` 时，仍传 `characterId + lockType + clientLockId`。`clientLockId` 的幂等查找范围已包含账号和角色，同一个 ID 可以在不同角色下分别使用。

## 8. Unlock Current Character History

```http
POST <API_BASE_URL>/api/chat/unlock-history
Content-Type: application/json
Authorization: Bearer <TOKEN>
```

```json
{"characterId":"maya-tan"}
```

费用、锁消息数量、成功解锁数量及 `messageIds` 都只计算当前角色。钱包余额仍是账号全局余额。

## 9. Guest History Sync

```http
POST <API_BASE_URL>/api/chat/sync
Content-Type: application/json
Authorization: Bearer <LOGIN_TOKEN>
```

```json
{
  "characterId": "maya-tan",
  "messages": [
    {"role": "user", "content": "Hello", "timestamp": "2026-07-17T09:00:00Z"},
    {"role": "assistant", "content": "Hi", "timestamp": "2026-07-17T09:00:01Z"}
  ]
}
```

每次同步只能包含一个角色。本地若保存了多个角色，前端按角色分组分别调用。

若页面使用用户聊天统计，也必须带角色：

```http
GET <API_BASE_URL>/api/user/stats?characterId=maya-tan
```

其中 `totalMessages`、近期记忆、亲密度、情绪和关系状态都按角色返回。
响应会明确带上 `characterId`、`relationshipStage` 和 `currentMood`，前端不要把这些状态写回其他角色的本地缓存。

## 12. Tip Attribution

只有 Tip 订单使用角色归属：

```json
{
  "planId": "tip_coffee_usd_4_99",
  "payChannel": "stripe",
  "autoRenew": false,
  "recipientCharacterId": "maya-tan"
}
```

Tip 订单必须携带 `recipientCharacterId`。VIP 和积分充值会忽略该字段。

## 13. Failures

| HTTP | `detail.errorCode` | Meaning | Frontend action |
| ---: | --- | --- | --- |
| 403 | `CHARACTER_DISABLED` | 角色或对应能力未开放 | 禁用输入并刷新角色目录 |
| 404 | `CHARACTER_NOT_FOUND` | 角色 ID 不存在 | 清理本地旧角色 ID，回角色列表 |
| 409 | `CHARACTER_MISMATCH` | 消息或双参数属于不同角色 | 不重试、不扣费，刷新当前角色历史 |
| 503 | `CHARACTER_STATE_UNAVAILABLE` | 角色会话状态暂不可用 | 保留输入并稍后重试 |

新前端的角色业务请求必须显式携带角色 ID。应用入口未指定角色时选择 Elio；显式错误、停用或不匹配的角色不会回退 Elio。