117 lines
3.8 KiB
Markdown
117 lines
3.8 KiB
Markdown
|
# 前后端 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 API
|
||
|
|
- `apps/lib/features/users/data/users_api.dart` - Users API
|
||
|
|
- `apps/lib/features/calendar/data/services/mock_calendar_service.dart` - Calendar Mock
|
||
|
|
- `apps/lib/features/chat/data/services/ag_ui_service.dart` - Chat/AgUi Mock
|
||
|
|
- `apps/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 路由
|