social-app/docs/protocols/models/friendships.md

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

{
  "target_user_id": "uuid",
  "content": "string | null"
}

• target_user_id: 目标用户 ID
• content: 申请消息，最大 200 字符

FriendRequestResponse

{
  "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

{
  "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。