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 数据结构

```json
{
  "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`: 用户名，3-30 字符
- `phone`: E.164 格式手机号，可为 null
- `avatar_url`: 头像 URL，可为 null
- `bio`: 个人简介，最大 200 字符，可为 null
- `settings`: 用户偏好设置

---

## 1) GET `/me`

获取当前登录用户信息。

### Request

无请求体。

### Response

`UserContext` 对象。

---

## 2) PATCH `/me`

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

### Request

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

至少提供一个字段。

### Response

更新后的 `UserContext` 对象。

---

## 3) POST `/search`

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

### Request

```json
{
  "query": "john"
}
```

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

### Response

`UserContext` 对象数组。

---

## 4) POST `/me/avatar`

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

### Request

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

### Response

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

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

---

## 5) GET `/{user_id}`

获取指定用户信息。

### Path Parameters

- `user_id`: 用户 UUID

### Response

`UserContext` 对象。