emall/emall-api

Fork 0

Files

XCool cf2273e6da 修改接口文档

2025-10-17 16:21:14 +08:00

17 KiB

Raw Blame History

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

请求参数:

{
  "username": "string",    // 用户名，必填
  "email": "string",       // 邮箱，必填
  "password": "string",    // 密码，必填
  "avatar": "string"       // 头像URL，可选
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "userId": "string",
    "username": "string",
    "email": "string",
    "avatar": "string",
    "token": "string",
    "refreshToken": "string"
  }
}

1.2 用户登录

接口地址: POST /api/v1/auth/login

请求参数:

{
  "email": "string",       // 邮箱，必填
  "password": "string"     // 密码，必填
}

响应示例: 同注册接口

1.3 刷新令牌

接口地址: POST /api/v1/auth/refresh

请求参数:

{
  "refreshToken": "string" // 刷新令牌，必填
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "token": "string",
    "refreshToken": "string"
  }
}

1.4 用户登出

接口地址: POST /api/v1/auth/logout

请求头: 需要包含有效的JWT令牌

响应示例:

{
  "code": 200,
  "message": "success",
  "data": null
}

2. 邮件管理模块

2.1 创建未来邮件

接口地址: POST /api/v1/mails/create (兼容前端格式)

请求参数:

{
  "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"             // 胶囊样式，可选
}

响应示例:

{
  "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: 每页数量

响应示例:

{
  "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

响应示例:

{
  "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

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "mailId": "string",
    "status": "REVOKED"
  }
}

3. 时光胶囊模块

3.1 获取时光胶囊视图

接口地址: GET /api/v1/capsules

响应示例:

{
  "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

请求参数:

{
  "style": "string",                    // 胶囊样式
  "glowIntensity": 0.8                  // 发光强度
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "capsuleId": "string",
    "style": "string",
    "glowIntensity": 0.8
  }
}

4. AI助手模块

4.1 AI写作辅助

接口地址: POST /api/v1/ai/writing-assistant

请求参数:

{
  "prompt": "string",                   // 用户输入，必填
  "type": "OUTLINE",                    // 辅助类型，必填，可选值: OUTLINE(大纲), DRAFT(草稿), COMPLETE(完整)
  "tone": "FORMAL",                     // 语气，必填，可选值: FORMAL(正式), CASUAL(随意), EMOTIONAL(情感), INSPIRATIONAL(励志)
  "length": "MEDIUM",                   // 长度，必填，可选值: SHORT(短), MEDIUM(中), LONG(长)
  "context": "string"                   // 上下文信息，可选
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "content": "string",
    "suggestions": ["string"],
    "estimatedTime": 5                  // 预计写作时间（分钟）
  }
}

4.2 情感分析

接口地址: POST /api/v1/ai/sentiment-analysis

请求参数:

{
  "content": "string"                   // 待分析内容，必填
}

响应示例:

{
  "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

请求参数:

{
  "content": "string",                  // 邮件内容，必填
  "deliveryTime": "string",             // 投递时间，必填
  "context": "string"                   // 上下文信息，可选
}

响应示例:

{
  "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(已接收)

响应示例:

{
  "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

响应示例:

{
  "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

响应示例:

{
  "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

请求参数:

{
  "nickname": "string",                 // 昵称，可选
  "avatar": "string",                   // 头像URL，可选
  "preferredBackground": "string",      // 偏好背景，可选
  "preferredScene": "string"            // 偏好场景，可选
}

响应示例:

{
  "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

响应示例:

{
  "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: 图片文件，必填

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "avatarUrl": "string"
  }
}

7. 推送通知模块

7.1 注册设备

接口地址: POST /api/v1/notification/device

请求参数:

{
  "deviceId": "string",                 // 设备ID，必填
  "platform": "string",                // 平台，必填，可选值: IOS, ANDROID, WEB
  "token": "string",                    // 推送令牌，必填
  "isEnabled": true                     // 是否启用通知，可选
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "deviceId": "string",
    "isRegistered": true
  }
}

7.2 获取通知设置

接口地址: GET /api/v1/notification/settings

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "emailNotification": true,          // 邮件通知
    "pushNotification": true,           // 推送通知
    "deliveryReminder": true,           // 投递提醒
    "receivedNotification": true        // 接收通知
  }
}

7.3 更新通知设置

接口地址: PUT /api/v1/notification/settings

请求参数:

{
  "emailNotification": true,            // 邮件通知，可选
  "pushNotification": true,             // 推送通知，可选
  "deliveryReminder": true,             // 投递提醒，可选
  "receivedNotification": true          // 接收通知，可选
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "emailNotification": true,
    "pushNotification": true,
    "deliveryReminder": true,
    "receivedNotification": true,
    "updatedAt": "string"
  }
}

8. 系统管理模块

8.1 获取用户订阅信息

接口地址: GET /api/v1/user/subscription

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "plan": "FREE",                     // 订阅计划: FREE, PREMIUM
    "remainingMails": 10,               // 剩余邮件数量
    "maxAttachmentSize": 10485760,      // 最大附件大小（字节）
    "features": {
      "advancedTriggers": false,        // 高级触发器
      "customCapsules": false,          // 自定义胶囊
      "aiAssistant": true               // AI助手
    },
    "expireDate": "string"              // 到期日期
  }
}

错误响应格式

所有错误响应都遵循统一格式：

{
  "code": 400,                          // 错误代码
  "message": "error message",           // 错误消息
  "errors": {                           // 详细错误信息（可选）
    "field": "error description"
  }
}

常见错误代码

400: 请求参数错误
401: 未授权（令牌无效或过期）
403: 禁止访问（权限不足）
404: 资源不存在
409: 资源冲突（如邮箱已存在）
429: 请求频率限制
500: 服务器内部错误

使用示例

完整的邮件创建流程

用户登录

curl -X POST "http://localhost:5003/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

创建未来邮件

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"
  }'

获取邮件列表

curl -X GET "http://localhost:5003/api/v1/mails?type=SENT&page=1&size=10" \
  -H "Authorization: Bearer <your_jwt_token>"

注意事项

所有时间字段均使用ISO 8601格式（如：2025-10-16T08:03:58.479Z）
文件上传大小限制为100MB
JWT令牌有效期为24小时
刷新令牌有效期为7天
免费用户每月可创建10封未来邮件
高级触发器（位置、事件）仅限高级用户使用

版本历史

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

17 KiB Raw Blame History Unescape Escape

FutureMail API 接口文档详细说明

项目概述

基础信息

认证说明

1. 用户认证模块

1.1 用户注册

1.2 用户登录

1.3 刷新令牌

1.4 用户登出

2. 邮件管理模块

2.1 创建未来邮件

2.2 获取邮件列表

2.3 获取邮件详情

2.4 更新邮件（投递前）

2.5 撤销发送

3. 时光胶囊模块

3.1 获取时光胶囊视图

3.2 更新胶囊样式

4. AI助手模块

4.1 AI写作辅助

4.2 情感分析

4.3 未来预测

5. 个人空间模块

5.1 获取时间线

5.2 获取统计数据

5.3 获取用户信息

5.4 更新用户信息

6. 文件上传模块

6.1 上传附件

6.2 上传头像

7. 推送通知模块

7.1 注册设备

7.2 获取通知设置

7.3 更新通知设置

8. 系统管理模块

8.1 获取用户订阅信息

错误响应格式

常见错误代码

使用示例

完整的邮件创建流程

注意事项

版本历史

联系方式

17 KiB

Raw Blame History