794 lines
17 KiB
Markdown
794 lines
17 KiB
Markdown
# FutureMail API 接口文档详细说明
|
||
|
||
## 项目概述
|
||
|
||
FutureMail 是一个未来邮件系统，允许用户创建定时发送的邮件，支持多种触发条件（时间、位置、事件），并提供时光胶囊可视化功能。
|
||
|
||
## 基础信息
|
||
|
||
- **API 基础地址**: `http://localhost:5003/api/v1`
|
||
- **认证方式**: JWT Bearer Token
|
||
- **数据格式**: JSON
|
||
- **字符编码**: UTF-8
|
||
|
||
## 认证说明
|
||
|
||
所有需要认证的接口都需要在请求头中添加：
|
||
```
|
||
Authorization: Bearer <your_jwt_token>
|
||
```
|
||
|
||
## 1. 用户认证模块
|
||
|
||
### 1.1 用户注册
|
||
|
||
**接口地址**: `POST /api/v1/auth/register`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"username": "string", // 用户名，必填
|
||
"email": "string", // 邮箱，必填
|
||
"password": "string", // 密码，必填
|
||
"avatar": "string" // 头像URL，可选
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"userId": "string",
|
||
"username": "string",
|
||
"email": "string",
|
||
"avatar": "string",
|
||
"token": "string",
|
||
"refreshToken": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2 用户登录
|
||
|
||
**接口地址**: `POST /api/v1/auth/login`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"email": "string", // 邮箱，必填
|
||
"password": "string" // 密码，必填
|
||
}
|
||
```
|
||
|
||
**响应示例**: 同注册接口
|
||
|
||
### 1.3 刷新令牌
|
||
|
||
**接口地址**: `POST /api/v1/auth/refresh`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"refreshToken": "string" // 刷新令牌，必填
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"token": "string",
|
||
"refreshToken": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.4 用户登出
|
||
|
||
**接口地址**: `POST /api/v1/auth/logout`
|
||
|
||
**请求头**: 需要包含有效的JWT令牌
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 2. 邮件管理模块
|
||
|
||
### 2.1 创建未来邮件
|
||
|
||
**接口地址**: `POST /api/v1/mails/create` (兼容前端格式)
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"title": "string", // 邮件标题，必填
|
||
"content": "string", // 邮件内容，必填
|
||
"recipientType": "SELF", // 收件人类型，必填，可选值: SELF(自己), SPECIFIC(指定), PUBLIC(公开)
|
||
"recipientEmail": "string", // 指定收件人邮箱，当recipientType为SPECIFIC时必填
|
||
"sendTime": "2026-10-16T08:03:58.479Z", // 发送时间，必填，ISO时间格式
|
||
"triggerType": "TIME", // 触发类型，必填，可选值: TIME(时间), LOCATION(位置), EVENT(事件)
|
||
"triggerCondition": { // 触发条件，可选
|
||
"location": {
|
||
"latitude": "number", // 纬度
|
||
"longitude": "number", // 经度
|
||
"city": "string" // 城市
|
||
},
|
||
"event": {
|
||
"keywords": ["string"], // 关键词列表
|
||
"type": "string" // 事件类型
|
||
}
|
||
},
|
||
"attachments": [ // 附件列表，可选
|
||
{
|
||
"type": "IMAGE", // 附件类型，可选值: IMAGE, VOICE, VIDEO
|
||
"url": "string", // 附件URL
|
||
"thumbnail": "string" // 缩略图URL
|
||
}
|
||
],
|
||
"isEncrypted": false, // 是否加密，可选
|
||
"capsuleStyle": "default" // 胶囊样式，可选
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"mailId": "string",
|
||
"capsuleId": "string",
|
||
"status": "DRAFT", // 状态: DRAFT(草稿), PENDING(待投递), DELIVERING(投递中), DELIVERED(已投递)
|
||
"createdAt": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 获取邮件列表
|
||
|
||
**接口地址**: `GET /api/v1/mails`
|
||
|
||
**查询参数**:
|
||
- `type`: 邮件类型，可选值: INBOX(收件箱), SENT(已发送), DRAFT(草稿)
|
||
- `status`: 状态筛选，可选值: PENDING, DELIVERING, DELIVERED
|
||
- `page`: 页码，从1开始
|
||
- `size`: 每页数量
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"mailId": "string",
|
||
"title": "string",
|
||
"sender": {
|
||
"userId": "string",
|
||
"username": "string",
|
||
"avatar": "string"
|
||
},
|
||
"recipient": {
|
||
"userId": "string",
|
||
"username": "string",
|
||
"avatar": "string"
|
||
},
|
||
"sendTime": "string",
|
||
"deliveryTime": "string",
|
||
"status": "string",
|
||
"hasAttachments": true,
|
||
"isEncrypted": false,
|
||
"capsuleStyle": "string",
|
||
"countdown": 86400 // 倒计时秒数（仅status=PENDING时返回）
|
||
}
|
||
],
|
||
"total": 100,
|
||
"page": 1,
|
||
"size": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.3 获取邮件详情
|
||
|
||
**接口地址**: `GET /api/v1/mails/{mailId}`
|
||
|
||
**路径参数**:
|
||
- `mailId`: 邮件ID
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"mailId": "string",
|
||
"title": "string",
|
||
"content": "string",
|
||
"sender": {
|
||
"userId": "string",
|
||
"username": "string",
|
||
"avatar": "string",
|
||
"email": "string"
|
||
},
|
||
"recipient": {
|
||
"userId": "string",
|
||
"username": "string",
|
||
"avatar": "string",
|
||
"email": "string"
|
||
},
|
||
"sendTime": "string",
|
||
"createdAt": "string",
|
||
"deliveryTime": "string",
|
||
"status": "string",
|
||
"triggerType": "string",
|
||
"triggerCondition": {},
|
||
"attachments": [
|
||
{
|
||
"id": "string",
|
||
"type": "string",
|
||
"url": "string",
|
||
"thumbnail": "string",
|
||
"size": 1024
|
||
}
|
||
],
|
||
"isEncrypted": false,
|
||
"capsuleStyle": "string",
|
||
"canEdit": false, // 是否可编辑（仅草稿状态）
|
||
"canRevoke": true // 是否可撤销（仅待投递状态）
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.4 更新邮件（投递前）
|
||
|
||
**接口地址**: `PUT /api/v1/mails/{mailId}`
|
||
|
||
**路径参数**:
|
||
- `mailId`: 邮件ID
|
||
|
||
**请求参数**: 同创建邮件，但所有字段可选
|
||
|
||
**响应示例**: 同创建邮件
|
||
|
||
### 2.5 撤销发送
|
||
|
||
**接口地址**: `POST /api/v1/mails/{mailId}/revoke`
|
||
|
||
**路径参数**:
|
||
- `mailId`: 邮件ID
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"mailId": "string",
|
||
"status": "REVOKED"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 时光胶囊模块
|
||
|
||
### 3.1 获取时光胶囊视图
|
||
|
||
**接口地址**: `GET /api/v1/capsules`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"capsules": [
|
||
{
|
||
"capsuleId": "string",
|
||
"mailId": "string",
|
||
"title": "string",
|
||
"sendTime": "string",
|
||
"deliveryTime": "string",
|
||
"progress": 0.5, // 0-1 的进度
|
||
"position": {
|
||
"x": 0.5, // 0-1 相对位置
|
||
"y": 0.5,
|
||
"z": 0.5
|
||
},
|
||
"style": "string",
|
||
"glowIntensity": 0.8 // 发光强度
|
||
}
|
||
],
|
||
"scene": "SPACE", // 场景类型: SPACE, OCEAN
|
||
"background": "string" // 背景配置
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 更新胶囊样式
|
||
|
||
**接口地址**: `PUT /api/v1/capsules/{capsuleId}/style`
|
||
|
||
**路径参数**:
|
||
- `capsuleId`: 胶囊ID
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"style": "string", // 胶囊样式
|
||
"glowIntensity": 0.8 // 发光强度
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"capsuleId": "string",
|
||
"style": "string",
|
||
"glowIntensity": 0.8
|
||
}
|
||
}
|
||
```
|
||
|
||
## 4. AI助手模块
|
||
|
||
### 4.1 AI写作辅助
|
||
|
||
**接口地址**: `POST /api/v1/ai/writing-assistant`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"prompt": "string", // 用户输入，必填
|
||
"type": "OUTLINE", // 辅助类型，必填，可选值: OUTLINE(大纲), DRAFT(草稿), COMPLETE(完整)
|
||
"tone": "FORMAL", // 语气，必填，可选值: FORMAL(正式), CASUAL(随意), EMOTIONAL(情感), INSPIRATIONAL(励志)
|
||
"length": "MEDIUM", // 长度，必填，可选值: SHORT(短), MEDIUM(中), LONG(长)
|
||
"context": "string" // 上下文信息，可选
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"content": "string",
|
||
"suggestions": ["string"],
|
||
"estimatedTime": 5 // 预计写作时间（分钟）
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.2 情感分析
|
||
|
||
**接口地址**: `POST /api/v1/ai/sentiment-analysis`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"content": "string" // 待分析内容，必填
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"sentiment": "POSITIVE", // 情感倾向: POSITIVE(积极), NEUTRAL(中性), NEGATIVE(消极), MIXED(混合)
|
||
"confidence": 0.85, // 0-1 置信度
|
||
"emotions": [
|
||
{
|
||
"type": "HAPPY", // 情感类型: HAPPY, SAD, HOPEFUL, NOSTALGIC, EXCITED
|
||
"score": 0.7 // 情感分数
|
||
}
|
||
],
|
||
"keywords": ["string"],
|
||
"summary": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 未来预测
|
||
|
||
**接口地址**: `POST /api/v1/ai/future-prediction`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"content": "string", // 邮件内容，必填
|
||
"deliveryTime": "string", // 投递时间，必填
|
||
"context": "string" // 上下文信息，可选
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"prediction": "string", // 预测结果
|
||
"confidence": 0.75, // 0-1 置信度
|
||
"factors": ["string"], // 影响因素
|
||
"suggestions": ["string"] // 建议
|
||
}
|
||
}
|
||
```
|
||
|
||
## 5. 个人空间模块
|
||
|
||
### 5.1 获取时间线
|
||
|
||
**接口地址**: `GET /api/v1/timeline`
|
||
|
||
**查询参数**:
|
||
- `startDate`: 开始日期，可选
|
||
- `endDate`: 结束日期，可选
|
||
- `type`: 类型，可选值: ALL(全部), SENT(已发送), RECEIVED(已接收)
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"timeline": [
|
||
{
|
||
"date": "2025-10-16",
|
||
"events": [
|
||
{
|
||
"type": "SENT", // 事件类型: SENT, RECEIVED
|
||
"mailId": "string",
|
||
"title": "string",
|
||
"time": "08:00:00",
|
||
"withUser": {
|
||
"userId": "string",
|
||
"username": "string",
|
||
"avatar": "string"
|
||
},
|
||
"emotion": "string"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.2 获取统计数据
|
||
|
||
**接口地址**: `GET /api/v1/statistics`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"totalSent": 50, // 总发送数
|
||
"totalReceived": 30, // 总接收数
|
||
"timeTravelDuration": 365, // 总时间旅行时长（天）
|
||
"mostFrequentRecipient": "string", // 最常联系的收件人
|
||
"mostCommonYear": 2025, // 最常见的投递年份
|
||
"keywordCloud": [ // 关键词云
|
||
{
|
||
"word": "string",
|
||
"count": 10,
|
||
"size": 1.0
|
||
}
|
||
],
|
||
"monthlyStats": [ // 月度统计
|
||
{
|
||
"month": "2025-10",
|
||
"sent": 5,
|
||
"received": 3
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.3 获取用户信息
|
||
|
||
**接口地址**: `GET /api/v1/user/profile`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"userId": "string",
|
||
"username": "string",
|
||
"email": "string",
|
||
"avatar": "string",
|
||
"nickname": "string",
|
||
"preferredBackground": "string", // 偏好背景
|
||
"preferredScene": "string", // 偏好场景
|
||
"createdAt": "string",
|
||
"lastLoginAt": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.4 更新用户信息
|
||
|
||
**接口地址**: `PUT /api/v1/user/profile`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"nickname": "string", // 昵称，可选
|
||
"avatar": "string", // 头像URL，可选
|
||
"preferredBackground": "string", // 偏好背景，可选
|
||
"preferredScene": "string" // 偏好场景，可选
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"userId": "string",
|
||
"username": "string",
|
||
"email": "string",
|
||
"nickname": "string",
|
||
"avatar": "string",
|
||
"preferredBackground": "string",
|
||
"preferredScene": "string",
|
||
"updatedAt": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 6. 文件上传模块
|
||
|
||
### 6.1 上传附件
|
||
|
||
**接口地址**: `POST /api/v1/upload/attachment`
|
||
|
||
**请求类型**: `multipart/form-data`
|
||
|
||
**请求参数**:
|
||
- `file`: 文件，必填
|
||
- `type`: 文件类型，必填，可选值: IMAGE, VOICE, VIDEO
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"fileId": "string",
|
||
"fileName": "string",
|
||
"fileSize": 1024,
|
||
"fileType": "string",
|
||
"url": "string",
|
||
"thumbnailUrl": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 上传头像
|
||
|
||
**接口地址**: `POST /api/v1/upload/avatar`
|
||
|
||
**请求类型**: `multipart/form-data`
|
||
|
||
**请求参数**:
|
||
- `file`: 图片文件，必填
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"avatarUrl": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 7. 推送通知模块
|
||
|
||
### 7.1 注册设备
|
||
|
||
**接口地址**: `POST /api/v1/notification/device`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"deviceId": "string", // 设备ID，必填
|
||
"platform": "string", // 平台，必填，可选值: IOS, ANDROID, WEB
|
||
"token": "string", // 推送令牌，必填
|
||
"isEnabled": true // 是否启用通知，可选
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"deviceId": "string",
|
||
"isRegistered": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.2 获取通知设置
|
||
|
||
**接口地址**: `GET /api/v1/notification/settings`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"emailNotification": true, // 邮件通知
|
||
"pushNotification": true, // 推送通知
|
||
"deliveryReminder": true, // 投递提醒
|
||
"receivedNotification": true // 接收通知
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.3 更新通知设置
|
||
|
||
**接口地址**: `PUT /api/v1/notification/settings`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"emailNotification": true, // 邮件通知，可选
|
||
"pushNotification": true, // 推送通知，可选
|
||
"deliveryReminder": true, // 投递提醒，可选
|
||
"receivedNotification": true // 接收通知，可选
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"emailNotification": true,
|
||
"pushNotification": true,
|
||
"deliveryReminder": true,
|
||
"receivedNotification": true,
|
||
"updatedAt": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 8. 系统管理模块
|
||
|
||
### 8.1 获取用户订阅信息
|
||
|
||
**接口地址**: `GET /api/v1/user/subscription`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"plan": "FREE", // 订阅计划: FREE, PREMIUM
|
||
"remainingMails": 10, // 剩余邮件数量
|
||
"maxAttachmentSize": 10485760, // 最大附件大小（字节）
|
||
"features": {
|
||
"advancedTriggers": false, // 高级触发器
|
||
"customCapsules": false, // 自定义胶囊
|
||
"aiAssistant": true // AI助手
|
||
},
|
||
"expireDate": "string" // 到期日期
|
||
}
|
||
}
|
||
```
|
||
|
||
## 错误响应格式
|
||
|
||
所有错误响应都遵循统一格式：
|
||
|
||
```json
|
||
{
|
||
"code": 400, // 错误代码
|
||
"message": "error message", // 错误消息
|
||
"errors": { // 详细错误信息（可选）
|
||
"field": "error description"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 常见错误代码
|
||
|
||
- `400`: 请求参数错误
|
||
- `401`: 未授权（令牌无效或过期）
|
||
- `403`: 禁止访问（权限不足）
|
||
- `404`: 资源不存在
|
||
- `409`: 资源冲突（如邮箱已存在）
|
||
- `429`: 请求频率限制
|
||
- `500`: 服务器内部错误
|
||
|
||
## 使用示例
|
||
|
||
### 完整的邮件创建流程
|
||
|
||
1. **用户登录**
|
||
```bash
|
||
curl -X POST "http://localhost:5003/api/v1/auth/login" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"email": "user@example.com",
|
||
"password": "password123"
|
||
}'
|
||
```
|
||
|
||
2. **创建未来邮件**
|
||
```bash
|
||
curl -X POST "http://localhost:5003/api/v1/mails/create" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer <your_jwt_token>" \
|
||
-d '{
|
||
"title": "给未来的一封信",
|
||
"content": "亲爱的未来的我，...",
|
||
"recipientType": "SELF",
|
||
"sendTime": "2026-10-16T08:03:58.479Z",
|
||
"triggerType": "TIME",
|
||
"triggerCondition": {},
|
||
"attachments": [],
|
||
"isEncrypted": false,
|
||
"capsuleStyle": "default"
|
||
}'
|
||
```
|
||
|
||
3. **获取邮件列表**
|
||
```bash
|
||
curl -X GET "http://localhost:5003/api/v1/mails?type=SENT&page=1&size=10" \
|
||
-H "Authorization: Bearer <your_jwt_token>"
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. 所有时间字段均使用ISO 8601格式（如：`2025-10-16T08:03:58.479Z`）
|
||
2. 文件上传大小限制为100MB
|
||
3. JWT令牌有效期为24小时
|
||
4. 刷新令牌有效期为7天
|
||
5. 免费用户每月可创建10封未来邮件
|
||
6. 高级触发器（位置、事件）仅限高级用户使用
|
||
|
||
## 版本历史
|
||
|
||
- **v1.0.0**: 初始版本，包含基本邮件功能
|
||
- **v1.1.0**: 添加AI助手功能
|
||
- **v1.2.0**: 添加时光胶囊可视化
|
||
- **v1.3.0**: 添加高级触发条件
|
||
|
||
## 联系方式
|
||
|
||
如有问题或建议，请联系：
|
||
- 邮箱：support@futuremail.com
|
||
- 文档：https://docs.futuremail.com
|
||
- GitHub：https://github.com/futuremail/api |