hyapp-server/docs/flutter对接/个人主页背景图Flutter对接.md

个人主页背景图 Flutter 对接

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

保存主页背景图

地址：

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 绝对地址。

请求示例：

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

返回值：

{
  "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。

个人信息返回字段

当前用户个人信息：

GET /api/v1/users/me

我的页概览：

GET /api/v1/users/me/overview

访问别人的资料卡：

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，不触发背包或装扮刷新。