emall-api/API接口文档详细说明.md

# 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