qzl
c3192a2431
- Add ChatBubble reusable widget for chat messages - Add HomeMockData for chat list mock data - Add HomeScreen widget tests - Add AG-UI chat design and implementation plan docs - Add friendship design docs - Ignore backend/logs directory
137 lines
3.7 KiB
Markdown
137 lines
3.7 KiB
Markdown
# 好友申请与待办消息功能设计
|
|
|
|
**Date:** 2026-02-28
|
|
**Status:** Approved
|
|
|
|
## 1. 数据模型
|
|
|
|
### Friendship 表 (已存在)
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| id | UUID | 主键 |
|
|
| user_low_id | UUID | 用户A ID (固定排序小值) |
|
|
| user_high_id | UUID | 用户B ID (固定排序大值) |
|
|
| initiator_id | UUID? | 发起请求者 |
|
|
| status | VARCHAR(20) | pending/accepted/blocked/declined/canceled |
|
|
| requested_at | TIMESTAMP? | 请求时间 |
|
|
| accepted_at | TIMESTAMP? | 接受时间 |
|
|
| blocked_by | UUID? | 被谁屏蔽 |
|
|
| created_by/updated_by | UUID? | 审计字段 |
|
|
|
|
### InboxMessage 表 (复用)
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| id | UUID | 主键 |
|
|
| recipient_id | UUID | 接收方 |
|
|
| sender_id | UUID? | 发送方 |
|
|
| message_type | VARCHAR(20) | FRIEND_REQUEST / CALENDAR / SYSTEM / GROUP |
|
|
| friendship_id | UUID? | 关联 Friendship |
|
|
| content | TEXT? | 附加消息 |
|
|
| is_read | BOOLEAN | 已读状态 |
|
|
| status | VARCHAR(20) | pending/accepted/rejected/dismissed |
|
|
|
|
## 2. API 设计
|
|
|
|
| 方法 | 路径 | 功能 |
|
|
|------|------|------|
|
|
| POST | /friends/requests | 发送好友请求 |
|
|
| GET | /friends/requests/outgoing | 获取我发出的请求 |
|
|
| GET | /friends/requests/inbox | 获取收到的好友请求 |
|
|
| POST | /friends/requests/{id}/accept | 接受好友请求 |
|
|
| POST | /friends/requests/{id}/decline | 拒绝好友请求 |
|
|
| DELETE | /friends/requests/{id} | 取消我的请求 |
|
|
| GET | /friends | 获取好友列表 |
|
|
| DELETE | /friends/{id} | 删除好友 |
|
|
|
|
## 3. 业务逻辑流程
|
|
|
|
### 3.1 发送好友请求
|
|
|
|
```
|
|
1. 验证 target_user_id != current_user_id
|
|
2. 检查是否已存在 Friendship 记录
|
|
- 已 accepted: 返回 409
|
|
- 已 pending: 返回 409
|
|
- 已 blocked: 返回 403
|
|
3. 创建 Friendship (status=pending, initiator_id=current_user)
|
|
4. 创建 InboxMessage (message_type=FRIEND_REQUEST, recipient=target_user)
|
|
5. 提交事务
|
|
```
|
|
|
|
### 3.2 接受好友请求
|
|
|
|
```
|
|
1. 查询 Friendship 和 InboxMessage
|
|
2. 验证 current_user == recipient
|
|
3. 更新 Friendship (status=accepted, accepted_at=now)
|
|
4. 更新 InboxMessage (status=accepted)
|
|
5. 提交事务
|
|
```
|
|
|
|
### 3.3 拒绝好友请求
|
|
|
|
```
|
|
1. 查询 Friendship 和 InboxMessage
|
|
2. 验证 current_user == recipient
|
|
3. 更新 Friendship (status=declined)
|
|
4. 更新 InboxMessage (status=rejected)
|
|
5. 提交事务
|
|
```
|
|
|
|
### 3.4 获取好友列表
|
|
|
|
```
|
|
查询 Friendship WHERE (user_low_id=current OR user_high_id=current) AND status=accepted
|
|
```
|
|
|
|
## 4. 响应 Schema
|
|
|
|
### FriendRequestResponse
|
|
```python
|
|
{
|
|
"id": "uuid",
|
|
"sender": {"id": "uuid", "username": "string", "avatar_url": "string?"},
|
|
"recipient": {"id": "uuid", "username": "string", "avatar_url": "string?"},
|
|
"content": "string?",
|
|
"status": "pending",
|
|
"created_at": "datetime"
|
|
}
|
|
```
|
|
|
|
### FriendResponse
|
|
```python
|
|
{
|
|
"id": "uuid",
|
|
"friend": {"id": "uuid", "username": "string", "avatar_url": "string?"},
|
|
"status": "accepted",
|
|
"created_at": "datetime",
|
|
"accepted_at": "datetime?"
|
|
}
|
|
```
|
|
|
|
## 5. 边界处理
|
|
|
|
| 场景 | 状态码 | 响应 |
|
|
|------|--------|------|
|
|
| 对自己发送请求 | 400 | Cannot send friend request to yourself |
|
|
| 已是好友 | 409 | Already friends |
|
|
| 已有待处理请求 | 409 | Friend request already exists |
|
|
| 被对方屏蔽 | 403 | Blocked by user |
|
|
| 请求不存在 | 404 | Friend request not found |
|
|
| 无权限操作 | 403 | Not authorized |
|
|
|
|
## 6. 测试用例
|
|
|
|
### 单元测试
|
|
- FriendshipService 业务逻辑
|
|
- 状态转换验证
|
|
- 边界条件处理
|
|
|
|
### 集成测试
|
|
- POST /friends/requests - 成功/失败场景
|
|
- GET /friends/requests/inbox - 返回正确列表
|
|
- POST /friends/requests/{id}/accept - 状态更新
|
|
- DELETE /friends/{id} - 删除好友
|