# 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。