docs: add Friends API documentation to runtime-route.md

2026-02-28 12:19:02 +08:00
parent 9b48939de8
commit 2b40d08c78
1 changed files with 179 additions and 0 deletions
@@ -444,6 +444,185 @@

 ---

+## Friends
+
+### POST /friends/requests
+
+发送好友请求（需要认证）。
+
+**Request:**
+```json
+{
+  "target_user_id": "string (uuid)",
+  "content": "string? (max 500 chars)"
+}
+```
+
+**Response:** 201 Created
+```json
+{
+  "id": "uuid",
+  "from_user_id": "uuid",
+  "to_user_id": "uuid",
+  "content": "string?",
+  "status": "pending",
+  "created_at": "string (ISO 8601)",
+  "updated_at": "string (ISO 8601)"
+}
+```
+
+**Errors:**
+- 400: 不能添加自己为好友
+- 401: 未认证
+- 404: 目标用户不存在
+- 409: 已是好友或请求已存在
+- 422: 请求参数无效
+
+---
+
+### GET /friends/requests/inbox
+
+获取收到的好友请求（需要认证）。
+
+**Response:** 200 OK
+```json
+[
+  {
+    "id": "uuid",
+    "from_user_id": "uuid",
+    "to_user_id": "uuid",
+    "content": "string?",
+    "status": "pending",
+    "created_at": "string (ISO 8601)",
+    "updated_at": "string (ISO 8601)"
+  }
+]
+```
+
+**Errors:**
+- 401: 未认证
+
+---
+
+### GET /friends/requests/outgoing
+
+获取发出的好友请求（需要认证）。
+
+**Response:** 200 OK
+```json
+[
+  {
+    "id": "uuid",
+    "from_user_id": "uuid",
+    "to_user_id": "uuid",
+    "content": "string?",
+    "status": "pending",
+    "created_at": "string (ISO 8601)",
+    "updated_at": "string (ISO 8601)"
+  }
+]
+```
+
+**Errors:**
+- 401: 未认证
+
+---
+
+### POST /friends/requests/{id}/accept
+
+接受好友请求（需要认证）。
+
+**Response:** 200 OK
+```json
+{
+  "id": "uuid",
+  "from_user_id": "uuid",
+  "to_user_id": "uuid",
+  "content": "string?",
+  "status": "accepted",
+  "created_at": "string (ISO 8601)",
+  "updated_at": "string (ISO 8601)"
+}
+```
+
+**Errors:**
+- 401: 未认证
+- 404: 请求不存在
+- 409: 请求已被处理
+
+---
+
+### POST /friends/requests/{id}/decline
+
+拒绝好友请求（需要认证）。
+
+**Response:** 200 OK
+```json
+{
+  "id": "uuid",
+  "from_user_id": "uuid",
+  "to_user_id": "uuid",
+  "content": "string?",
+  "status": "declined",
+  "created_at": "string (ISO 8601)",
+  "updated_at": "string (ISO 8601)"
+}
+```
+
+**Errors:**
+- 401: 未认证
+- 404: 请求不存在
+- 409: 请求已被处理
+
+---
+
+### DELETE /friends/requests/{id}
+
+取消发出的好友请求（需要认证）。
+
+**Response:** 204 No Content
+
+**Errors:**
+- 401: 未认证
+- 404: 请求不存在
+
+---
+
+### GET /friends
+
+获取好友列表（需要认证）。
+
+**Response:** 200 OK
+```json
+[
+  {
+    "id": "uuid",
+    "friend_id": "uuid",
+    "username": "string",
+    "avatar_url": "string?",
+    "bio": "string?",
+    "created_at": "string (ISO 8601)"
+  }
+]
+```
+
+**Errors:**
+- 401: 未认证
+
+---
+
+### DELETE /friends/{id}
+
+删除好友（需要认证）。
+
+**Response:** 204 No Content
+
+**Errors:**
+- 401: 未认证
+- 404: 好友关系不存在
+
+---
+
 ## Agent Chat

 ### POST /agent-chats