# 个人主页背景图 Flutter 对接

个人主页背景图是用户资料字段 `profile_bg_img`，不是背包资源，不是 `profile_card`，也不需要佩戴。App 先自行上传图片拿到 URL，再调用后端保存 URL。

## 保存主页背景图

地址：

```http
POST /api/v1/users/me/profile-bg-img
```

Headers：

| Header | 必填 | 说明 |
| --- | --- | --- |
| `Authorization` | 是 | `Bearer <access_token>` |
| `Content-Type` | 是 | `application/json` |
| `X-App-Code` | 否 | App 编码，默认 `lalu` |

参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 是 | App 已上传好的图片 URL，必须是 `http` 或 `https` 绝对地址。 |

请求示例：

```json
{
  "url": "https://cdn.example.com/profile-bg.png"
}
```

返回值：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "profile_bg_img": "https://cdn.example.com/profile-bg.png",
    "profile": {
      "user_id": "10001",
      "display_user_id": "163001",
      "username": "Alice",
      "avatar": "https://cdn.example.com/avatar.png",
      "profile_bg_img": "https://cdn.example.com/profile-bg.png",
      "profile_completed": true,
      "onboarding_status": "completed"
    }
  }
}
```

Flutter 处理：

| 场景 | 处理 |
| --- | --- |
| 保存成功 | 使用 `data.profile_bg_img` 刷新当前资料页背景图。 |
| 重新打开我的资料页 | 读取个人信息接口返回的 `profile_bg_img`。 |
| 查看别人资料卡 | 使用访问资料卡响应里的 `target_profile.profile_bg_img`。 |

## 个人信息返回字段

当前用户个人信息：

```http
GET /api/v1/users/me
```

我的页概览：

```http
GET /api/v1/users/me/overview
```

访问别人的资料卡：

```http
POST /api/v1/users/{user_id}/visit
```

返回字段：

| 字段 | 说明 |
| --- | --- |
| `profile_bg_img` | 用户主页背景图 URL；未设置时为空字符串。 |
| `profile.profile_bg_img` | `/users/me/overview` 里的用户资料背景图。 |
| `target_profile.profile_bg_img` | 查看别人资料卡时，对方的主页背景图。 |

## 错误处理

| HTTP | code | 场景 |
| --- | --- | --- |
| `400` | `INVALID_ARGUMENT` | `url` 为空、不是 HTTP(S) 绝对地址或长度超过限制。 |
| `401` | `UNAUTHORIZED` | 未登录或 token 无效。 |
| `403` | `PROFILE_REQUIRED` | 当前用户资料未完成。 |
| `404` | `NOT_FOUND` | 当前用户不存在。 |
| `502` | `UPSTREAM_ERROR` | user-service 不可用。 |

相关 IM：无。该接口只保存用户资料字段，不发送 IM，不触发背包或装扮刷新。