social-app/docs/protocols/models/users.md

Users 协议

本文档定义 /api/v1/users 的用户管理协议。

Base URL: /api/v1/users

---

端点

方法	路径	说明
GET	/me	获取当前用户信息
PATCH	/me	更新当前用户信息
POST	/me/avatar	上传头像图片并更新头像地址
POST	/search	搜索用户
GET	/{user_id}	获取指定用户信息

---

UserContext 数据结构

{
  "id": "uuid",
  "username": "string",
  "phone": "+14155552671 | null",
  "avatar_url": "https://... | null",
  "bio": "string | null",
  "settings": {
    "version": 1,
    "preferences": {
      "interface_language": "zh-CN",
      "ai_language": "zh-CN",
      "timezone": "Asia/Shanghai",
      "country": "CN"
    },
    "privacy": {},
    "notification": {}
  }
}

字段说明：

• id: 用户唯一标识符 (UUID)
• username: 用户名，当前后端更新接口约束为最大 30 字符（最小长度未在 API 层强制）
• phone: E.164 格式手机号，可为 null
• avatar_url: 头像 URL，可为 null
• bio: 个人简介，最大 200 字符，可为 null
• settings: 用户偏好设置

---

1) GET /me

获取当前登录用户信息。

Request

无请求体。

Response

UserContext 对象。

---

2) PATCH /me

更新当前用户信息（部分更新）。

Request

{
  "username": "newname",
  "avatar_url": "https://example.com/avatar.jpg",
  "bio": "Hello world"
}

至少提供一个字段。

Response

更新后的 UserContext 对象。

---

3) POST /search

按用户名或手机号搜索用户。

Request

{
  "query": "john"
}

query 最小 1 字符，最大 100 字符。

Response

UserContext 对象数组。

---

4) POST /me/avatar

上传头像（multipart/form-data）。

Request

字段	类型	必填	说明
file	file	是	图片文件（image/jpeg / image/png / image/webp）

Response

{
  "url": "https://..."
}

说明：

• 上传成功后后端会同步更新当前用户 avatar_url。
• 文件大小上限由后端配置 storage.avatar.max_size_mb 控制。

---

5) GET /{user_id}

获取指定用户信息。

Path Parameters

• user_id: 用户 UUID

Response

UserContext 对象。

---

Compatibility Strategy

• 策略：backward-compatible
• 本次仅修正文档约束描述与实现一致，不改变接口字段与响应结构。