122 lines
4.8 KiB
Markdown
122 lines
4.8 KiB
Markdown
# Social Relations API
|
||
|
||
本文定义 App 端访问记录、关注、好友申请和好友关系接口。关系事实由 `user-service` 持久化；腾讯云 IM 只负责把好友申请消息送进聊天窗口，不作为好友关系事实来源。
|
||
|
||
## Core Flow
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant A as User A App
|
||
participant G as gateway-service
|
||
participant U as user-service
|
||
participant IM as Tencent IM
|
||
participant B as User B App
|
||
|
||
A->>G: POST /api/v1/users/{B}/friend-requests
|
||
G->>U: ApplyFriend(A, B)
|
||
U-->>G: pending application
|
||
G-->>A: application=pending
|
||
A->>IM: send custom friend request message to B
|
||
IM-->>B: chat window message
|
||
B->>G: POST /api/v1/users/{A}/friend-requests/accept
|
||
G->>U: AcceptFriendApplication(B, A)
|
||
U-->>G: bidirectional friendship
|
||
G-->>B: friend record
|
||
```
|
||
|
||
关键边界：
|
||
|
||
- 申请接口只创建 pending 申请，不直接发 IM。
|
||
- 同意必须调用 accept 接口，不能只靠 IM 消息状态。
|
||
- 删除好友是双向删除。
|
||
- 自己访问自己、关注自己、加自己好友全部拒绝。
|
||
- 重复访问只增加访问次数，不重复增加 `visitors_count`。
|
||
- 重复关注、重复取消关注、重复同意、重复删除都按幂等处理。
|
||
|
||
## HTTP Endpoints
|
||
|
||
所有接口都要求完成资料的登录态，响应统一使用 `{code,message,request_id,data}` envelope。
|
||
|
||
| Method | Path | Purpose |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/v1/users/{user_id}/visit` | 记录访问用户主页 |
|
||
| `GET` | `/api/v1/users/me/visitors?page=1&page_size=20` | 我的访问记录 |
|
||
| `POST` | `/api/v1/users/{user_id}/follow` | 关注用户 |
|
||
| `DELETE` | `/api/v1/users/{user_id}/follow` | 取消关注 |
|
||
| `GET` | `/api/v1/users/me/following?page=1&page_size=20` | 我的关注列表 |
|
||
| `POST` | `/api/v1/users/{user_id}/friend-requests` | 申请添加好友 |
|
||
| `POST` | `/api/v1/users/{user_id}/friend-requests/accept` | 同意该用户发来的好友申请 |
|
||
| `GET` | `/api/v1/users/me/friend-requests?direction=incoming&page=1&page_size=20` | 好友申请列表，`direction` 支持 `incoming`/`outgoing` |
|
||
| `GET` | `/api/v1/users/me/friends?page=1&page_size=20` | 我的好友列表 |
|
||
| `DELETE` | `/api/v1/users/{user_id}/friend` | 删除好友 |
|
||
|
||
## Response Examples
|
||
|
||
申请好友：
|
||
|
||
```json
|
||
{
|
||
"application": {
|
||
"requester_user_id": "10001",
|
||
"target_user_id": "10002",
|
||
"status": "pending",
|
||
"created_at_ms": 1777996800000,
|
||
"updated_at_ms": 1777996800000
|
||
},
|
||
"already_friends": false
|
||
}
|
||
```
|
||
|
||
同意好友：
|
||
|
||
```json
|
||
{
|
||
"friend": {
|
||
"user_id": "10002",
|
||
"friend_user_id": "10001",
|
||
"friended_at_ms": 1777996810000
|
||
}
|
||
}
|
||
```
|
||
|
||
关注：
|
||
|
||
```json
|
||
{
|
||
"following": true,
|
||
"follower_stats": {
|
||
"visitors_count": 0,
|
||
"following_count": 1,
|
||
"friends_count": 0,
|
||
"updated_at_ms": 1777996800000
|
||
}
|
||
}
|
||
```
|
||
|
||
## Storage
|
||
|
||
| Table | Owner | Purpose |
|
||
| --- | --- | --- |
|
||
| `user_profile_stats` | user-service | 我的页计数 read model：访问人数、关注数、好友数 |
|
||
| `user_profile_visits` | user-service | 用户主页访问去重记录，主键 `(app_code,target_user_id,visitor_user_id)` |
|
||
| `user_follows` | user-service | 单向关注关系，取消关注只改状态 |
|
||
| `user_friend_applications` | user-service | 好友申请，pending/accepted |
|
||
| `user_friendships` | user-service | 双向好友边，每个好友关系写两行 |
|
||
|
||
计数更新和关系边写入必须在同一个 MySQL 事务中完成。`user_profile_stats` 是首屏计数来源，不能在 `/users/me/overview` 里实时扫关系表。
|
||
|
||
## Room Feed Integration
|
||
|
||
- `GET /api/v1/rooms/feeds?tab=visited` 是房间访问历史，只由 JoinRoom 成功后写入 room-service 的房间 feed 索引；不要使用 `/users/{user_id}/visit` 用户主页访问记录填充。
|
||
- `GET /api/v1/rooms/feeds?tab=following` 由 gateway 调用 `ListFollowing` 读取关注用户，再把关系用户和 `followed_at_ms` 传给 room-service 查询 active 房间卡片。
|
||
- `GET /api/v1/rooms/feeds?tab=friend` 由 gateway 调用 `ListFriends` 读取好友用户，再把关系用户和 `friended_at_ms` 传给 room-service 查询 active 房间卡片。
|
||
- `GET /api/v1/rooms/feeds?tab=followed` 是房间关注列表，只读取 room-service 的 `room_follows` 用户-房间关系，再 join active 房间卡片。
|
||
- 好友/用户关注关系事实仍归 user-service；房间关注关系事实归 room-service，不能用 user-service 的用户关注表替代。
|
||
|
||
## App Notes
|
||
|
||
- 好友申请成功后，App 发送腾讯 IM 自定义消息给对方；消息里携带 `requester_user_id` 和申请状态展示参数。
|
||
- 聊天窗口点击同意时调用 `/api/v1/users/{requester_user_id}/friend-requests/accept`。
|
||
- 如果 accept 返回成功，App 再刷新好友列表或本地会话状态。
|
||
- 如果 IM 消息丢失，pending 申请仍可在 `/api/v1/users/me/friend-requests?direction=incoming` 找回。
|