# 前后端 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 路由