qzl
152 lines
2.5 KiB
Markdown
152 lines
2.5 KiB
Markdown
# 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`: 用户名，当前后端更新接口约束为最大 30 字符（最小长度未在 API 层强制）
|
||
- `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` 对象。
|
||
|
||
---
|
||
|
||
## Compatibility Strategy
|
||
|
||
- 策略：`backward-compatible`
|
||
- 本次仅修正文档约束描述与实现一致，不改变接口字段与响应结构。
|