2026-03-23 14:25:47 +08:00
|
|
|
|
# Users 协议
|
|
|
|
|
|
|
|
|
|
|
|
本文档定义 `/api/v1/users` 的用户管理协议。
|
|
|
|
|
|
|
|
|
|
|
|
Base URL: `/api/v1/users`
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 端点
|
|
|
|
|
|
|
|
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|
|
|
|
|---|---|---|
|
|
|
|
|
|
| GET | `/me` | 获取当前用户信息 |
|
|
|
|
|
|
| PATCH | `/me` | 更新当前用户信息 |
|
2026-04-02 11:52:23 +08:00
|
|
|
|
| POST | `/me/avatar` | 上传头像图片并更新头像地址 |
|
2026-03-23 14:25:47 +08:00
|
|
|
|
| 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)
|
2026-04-23 16:04:04 +08:00
|
|
|
|
- `username`: 用户名，当前后端更新接口约束为最大 30 字符（最小长度未在 API 层强制）
|
2026-03-23 14:25:47 +08:00
|
|
|
|
- `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` 对象数组。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
2026-04-02 11:52:23 +08:00
|
|
|
|
## 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}`
|
2026-03-23 14:25:47 +08:00
|
|
|
|
|
|
|
|
|
|
获取指定用户信息。
|
|
|
|
|
|
|
|
|
|
|
|
### Path Parameters
|
|
|
|
|
|
|
|
|
|
|
|
- `user_id`: 用户 UUID
|
|
|
|
|
|
|
|
|
|
|
|
### Response
|
|
|
|
|
|
|
|
|
|
|
|
`UserContext` 对象。
|
2026-04-23 16:04:04 +08:00
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## Compatibility Strategy
|
|
|
|
|
|
|
|
|
|
|
|
- 策略：`backward-compatible`
|
|
|
|
|
|
- 本次仅修正文档约束描述与实现一致，不改变接口字段与响应结构。
|
