前后端 API 对比分析
Date: 2026-03-04
Status: Open
Type: 架构分析
一、后端已有、前端缺失的 API
1. Friendships API (/api/v1/friends)
| 方法 |
路径 |
功能 |
前端状态 |
| POST |
/requests |
发送好友请求 |
缺失 |
| GET |
/requests/inbox |
获取收件箱 |
缺失 |
| GET |
/requests/outgoing |
获取发出的请求 |
缺失 |
| POST |
/requests/{id}/accept |
接受好友请求 |
缺失 |
| POST |
/requests/{id}/decline |
拒绝好友请求 |
缺失 |
| DELETE |
/requests/{id} |
取消好友请求 |
缺失 |
| GET |
`` |
获取好友列表 |
缺失 |
| DELETE |
/{id} |
删除好友 |
缺失 |
2. Inbox Messages API (/api/v1/inbox/messages)
| 方法 |
路径 |
功能 |
前端状态 |
| GET |
`` |
获取消息列表 |
缺失 |
| POST |
/{id}/accept |
接受邀请 |
缺失 |
| POST |
/{id}/dismiss |
忽略消息 |
缺失 |
3. Chat/AgUi 流式 API
| 功能 |
前端状态 |
| 发送消息 SSE 流式 |
仅有 Mock |
| 加载历史记录 |
仅有 Mock |
前端 AgUiService 只有本地 mock (throw UnimplementedError)，未实现真实 API 调用。
4. Infra API
| 方法 |
路径 |
功能 |
前端状态 |
| GET |
/infra/health |
基础设施健康检查 |
未使用 |
二、前端已有、后端已实现的 API
Auth API (/api/v1/auth)
| 方法 |
路径 |
后端 |
前端 |
| POST |
/verifications |
✅ |
✅ |
| POST |
/verifications/verify |
✅ |
✅ |
| POST |
/verifications/resend |
✅ |
✅ |
| POST |
/sessions |
✅ |
✅ |
| POST |
/sessions/refresh |
✅ |
✅ |
| DELETE |
/sessions |
✅ |
✅ |
| POST |
/password-reset |
✅ |
✅ |
| POST |
/password-reset/confirm |
✅ |
✅ |
| GET |
/users |
✅ |
未使用 |
Users API (/api/v1/users)
| 方法 |
路径 |
后端 |
前端 |
| GET |
/me |
✅ |
✅ |
| PATCH |
/me |
✅ |
✅ |
| POST |
/search |
✅ |
✅ |
Schedule Items API (/api/v1/schedule-items)
| 方法 |
路径 |
后端 |
前端 |
| POST |
`` |
✅ |
仅有 Mock |
| GET |
`` (range query) |
✅ |
仅有 Mock |
| GET |
/{id} |
✅ |
仅有 Mock |
| PATCH |
/{id} |
✅ |
仅有 Mock |
| DELETE |
/{id} |
✅ |
仅有 Mock |
| POST |
/{id}/share |
✅ |
缺失 |
三、待实现功能清单
| 优先级 |
功能 |
说明 |
| P0 |
FriendsApi |
前端无 Friendships API 客户端 |
| P0 |
InboxMessagesApi |
前端无 Inbox Messages API 客户端 |
| P0 |
Chat/AgUi 后端连接 |
前端 AgUiService 未实现真实 API |
| P1 |
CalendarService 真实 API |
MockCalendarService → 真实 API 调用 |
| P1 |
Schedule Share 接口 |
前端未调用 POST /{id}/share |
| P2 |
Infra Health 集成 |
可用于前端健康检查 |
四、相关文件位置
前端 API 客户端
apps/lib/features/auth/data/auth_api.dart - Auth APIapps/lib/features/users/data/users_api.dart - Users APIapps/lib/features/calendar/data/services/mock_calendar_service.dart - Calendar Mockapps/lib/features/chat/data/services/ag_ui_service.dart - Chat/AgUi Mockapps/lib/features/chat/data/services/mock_history_service.dart - History Mock
后端 Router
backend/src/v1/auth/router.py - Auth 路由backend/src/v1/users/router.py - Users 路由backend/src/v1/friendships/router.py - Friendships 路由backend/src/v1/inbox_messages/router.py - Inbox Messages 路由backend/src/v1/schedule_items/router.py - Schedule Items 路由backend/src/v1/infra/router.py - Infra 路由
qzl