qzl
191 lines
3.1 KiB
Markdown
191 lines
3.1 KiB
Markdown
# Friendships 协议
|
|
|
|
本文档定义 `/api/v1/friends` 的好友申请与管理协议。
|
|
|
|
Base URL: `/api/v1/friends`
|
|
|
|
---
|
|
|
|
## 端点
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|---|---|---|
|
|
| POST | `/requests` | 发送好友申请 |
|
|
| GET | `/requests/inbox` | 获取收到的好友申请列表 |
|
|
| GET | `/requests/outgoing` | 获取发出的好友申请列表 |
|
|
| GET | `/requests/{friendship_id}` | 获取指定好友申请详情 |
|
|
| POST | `/requests/{friendship_id}/accept` | 接受好友申请 |
|
|
| POST | `/requests/{friendship_id}/decline` | 拒绝好友申请 |
|
|
| DELETE | `/requests/{friendship_id}` | 取消发出的好友申请 |
|
|
| GET | `` | 获取好友列表 |
|
|
| DELETE | `/{friendship_id}` | 删除好友 |
|
|
|
|
---
|
|
|
|
## 数据结构
|
|
|
|
### FriendRequestCreate
|
|
|
|
```json
|
|
{
|
|
"target_user_id": "uuid",
|
|
"content": "string | null"
|
|
}
|
|
```
|
|
|
|
- `target_user_id`: 目标用户 ID
|
|
- `content`: 申请消息，最大 200 字符
|
|
|
|
### FriendRequestResponse
|
|
|
|
```json
|
|
{
|
|
"id": "uuid",
|
|
"sender": { /* UserContext */ },
|
|
"recipient": { /* UserContext */ },
|
|
"content": { "type": "request", "message": "string | null" } | null,
|
|
"status": "pending | accepted | rejected | canceled",
|
|
"created_at": "datetime"
|
|
}
|
|
```
|
|
|
|
说明：`status` 对外返回的值包括 `pending`、`accepted`、`rejected`、`canceled`。内部实现中还有 `blocked` 和 `declined` 状态，在返回给客户端时会映射为 `rejected` 或 `canceled`。
|
|
|
|
### FriendResponse
|
|
|
|
```json
|
|
{
|
|
"id": "uuid",
|
|
"friend": { /* UserContext */ },
|
|
"status": "active",
|
|
"created_at": "datetime",
|
|
"accepted_at": "datetime | null"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 1) POST `/requests`
|
|
|
|
发送好友申请。
|
|
|
|
### Request
|
|
|
|
`FriendRequestCreate` 对象。
|
|
|
|
### Response
|
|
|
|
`FriendRequestResponse` 对象，状态码 201。
|
|
|
|
---
|
|
|
|
## 2) GET `/requests/inbox`
|
|
|
|
获取收到的待处理好友申请列表。
|
|
|
|
### Request
|
|
|
|
无请求体。
|
|
|
|
### Response
|
|
|
|
`FriendRequestResponse` 对象数组，状态为 `pending`。
|
|
|
|
---
|
|
|
|
## 3) GET `/requests/outgoing`
|
|
|
|
获取发出的好友申请列表。
|
|
|
|
### Request
|
|
|
|
无请求体。
|
|
|
|
### Response
|
|
|
|
`FriendRequestResponse` 对象数组。
|
|
|
|
---
|
|
|
|
## 4) GET `/requests/{friendship_id}`
|
|
|
|
获取指定好友申请详情。
|
|
|
|
### Path Parameters
|
|
|
|
- `friendship_id`: 好友申请 UUID
|
|
|
|
### Response
|
|
|
|
`FriendRequestResponse` 对象。
|
|
|
|
---
|
|
|
|
## 5) POST `/requests/{friendship_id}/accept`
|
|
|
|
接受好友申请。
|
|
|
|
### Path Parameters
|
|
|
|
- `friendship_id`: 好友申请 UUID
|
|
|
|
### Response
|
|
|
|
`FriendRequestResponse` 对象，状态更新为 `accepted`。
|
|
|
|
---
|
|
|
|
## 6) POST `/requests/{friendship_id}/decline`
|
|
|
|
拒绝好友申请。
|
|
|
|
### Path Parameters
|
|
|
|
- `friendship_id`: 好友申请 UUID
|
|
|
|
### Response
|
|
|
|
`FriendRequestResponse` 对象，状态更新为 `rejected`。
|
|
|
|
---
|
|
|
|
## 7) DELETE `/requests/{friendship_id}`
|
|
|
|
取消发出的好友申请。
|
|
|
|
### Path Parameters
|
|
|
|
- `friendship_id`: 好友申请 UUID
|
|
|
|
### Response
|
|
|
|
204 No Content。
|
|
|
|
---
|
|
|
|
## 8) GET `/`
|
|
|
|
获取好友列表。
|
|
|
|
### Request
|
|
|
|
无请求体。
|
|
|
|
### Response
|
|
|
|
`FriendResponse` 对象数组，状态为 `active`。
|
|
|
|
---
|
|
|
|
## 9) DELETE `/{friendship_id}`
|
|
|
|
删除好友。
|
|
|
|
### Path Parameters
|
|
|
|
- `friendship_id`: 好友关系 UUID
|
|
|
|
### Response
|
|
|
|
204 No Content。
|