emall-web/存入胶囊API文档.md

# 存入胶囊功能 API 文档

## 概述
存入胶囊功能允许用户将邮件保存为时光胶囊状态，邮件将以草稿形式保存，用户可以随时编辑或发送。

## API 接口

### 创建胶囊邮件

**接口地址：** `POST /api/v1/mails`

**接口描述：** 创建一个新邮件并将其保存为时光胶囊状态（草稿）

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| title | string | 是 | 邮件标题 |
| content | string | 是 | 邮件内容 |
| recipientType | string | 是 | 收件人类型：SELF（自己）、SPECIFIC（指定收件人）、PUBLIC（公开信） |
| recipientEmail | string | 否 | 指定收件人邮箱（当recipientType为SPECIFIC时必填） |
| sendTime | string | 否 | 发送时间，ISO格式时间字符串（如：2025-12-31T23:59:59Z） |
| triggerType | string | 否 | 触发类型：TIME（时间）、LOCATION（地点）、EVENT（事件） |
| triggerCondition | object | 否 | 触发条件 |
| triggerCondition.location | object | 否 | 地点触发条件 |
| triggerCondition.location.latitude | number | 否 | 纬度 |
| triggerCondition.location.longitude | number | 否 | 经度 |
| triggerCondition.location.city | string | 否 | 城市 |
| triggerCondition.event | object | 否 | 事件触发条件 |
| triggerCondition.event.keywords | array | 否 | 关键词列表 |
| triggerCondition.event.type | string | 否 | 事件类型 |
| attachments | array | 否 | 附件列表 |
| attachments[].type | string | 否 | 附件类型：IMAGE、VOICE、VIDEO |
| attachments[].url | string | 否 | 附件URL |
| attachments[].thumbnail | string | 否 | 缩略图URL |
| isEncrypted | boolean | 否 | 是否加密 |
| capsuleStyle | string | 否 | 胶囊样式 |
| status | string | 是 | 邮件状态，存入胶囊时固定为：DRAFT |

#### 请求示例

```json
{
  "title": "写给未来的自己",
  "content": "亲爱的未来的我，当你读到这封信时，希望你已经实现了现在的梦想...",
  "recipientType": "SELF",
  "sendTime": "2025-12-31T23:59:59Z",
  "triggerType": "TIME",
  "attachments": [
    {
      "type": "IMAGE",
      "url": "https://example.com/image.jpg",
      "thumbnail": "https://example.com/thumb.jpg"
    }
  ],
  "isEncrypted": false,
  "capsuleStyle": "default",
  "status": "DRAFT"
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | number | 响应状态码，200表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| data.mailId | string | 邮件ID |
| data.capsuleId | string | 胶囊ID |
| data.status | string | 邮件状态：DRAFT、PENDING、DELIVERING、DELIVERED |
| data.createdAt | string | 创建时间，ISO格式时间字符串 |

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "mailId": "mail_1234567890",
    "capsuleId": "capsule_1234567890",
    "status": "DRAFT",
    "createdAt": "2023-07-20T10:30:00Z"
  }
}
```

### 获取胶囊列表

**接口地址：** `GET /api/v1/mails`

**接口描述：** 获取用户的胶囊邮件列表

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | string | 否 | 邮件类型：INBOX、SENT、DRAFT，获取胶囊时使用DRAFT |
| status | string | 否 | 状态筛选：PENDING、DELIVERING、DELIVERED、DRAFT |
| page | number | 否 | 页码，默认为1 |
| size | number | 否 | 每页数量，默认为10 |

#### 请求示例

```
GET /api/v1/mails?type=DRAFT&page=1&size=10
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | number | 响应状态码，200表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| data.list | array | 邮件列表 |
| data.list[].mailId | string | 邮件ID |
| data.list[].title | string | 邮件标题 |
| data.list[].sender | object | 发件人信息 |
| data.list[].recipient | object | 收件人信息 |
| data.list[].sendTime | string | 发送时间 |
| data.list[].deliveryTime | string | 送达时间 |
| data.list[].status | string | 邮件状态 |
| data.list[].hasAttachments | boolean | 是否有附件 |
| data.list[].isEncrypted | boolean | 是否加密 |
| data.list[].capsuleStyle | string | 胶囊样式 |
| data.total | number | 总数量 |
| data.page | number | 当前页码 |
| data.size | number | 每页数量 |

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "mailId": "mail_1234567890",
        "title": "写给未来的自己",
        "sender": {
          "userId": "user_123",
          "username": "张三",
          "avatar": "https://example.com/avatar.jpg"
        },
        "recipient": {
          "userId": "user_123",
          "username": "张三",
          "avatar": "https://example.com/avatar.jpg"
        },
        "sendTime": "2025-12-31T23:59:59Z",
        "deliveryTime": null,
        "status": "DRAFT",
        "hasAttachments": true,
        "isEncrypted": false,
        "capsuleStyle": "default"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 10
  }
}
```

### 获取胶囊详情

**接口地址：** `GET /api/v1/mails/{mailId}`

**接口描述：** 获取指定胶囊邮件的详细信息

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| mailId | string | 是 | 邮件ID |

#### 请求示例

```
GET /api/v1/mails/mail_1234567890
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | number | 响应状态码，200表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| data.mailId | string | 邮件ID |
| data.title | string | 邮件标题 |
| data.content | string | 邮件内容 |
| data.sender | object | 发件人信息 |
| data.recipient | object | 收件人信息 |
| data.sendTime | string | 发送时间 |
| data.createdAt | string | 创建时间 |
| data.deliveryTime | string | 送达时间 |
| data.status | string | 邮件状态 |
| data.triggerType | string | 触发类型 |
| data.triggerCondition | object | 触发条件 |
| data.attachments | array | 附件列表 |
| data.isEncrypted | boolean | 是否加密 |
| data.capsuleStyle | string | 胶囊样式 |
| data.canEdit | boolean | 是否可编辑（草稿状态为true） |
| data.canRevoke | boolean | 是否可撤销（待投递状态为true） |

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "mailId": "mail_1234567890",
    "title": "写给未来的自己",
    "content": "亲爱的未来的我，当你读到这封信时，希望你已经实现了现在的梦想...",
    "sender": {
      "userId": "user_123",
      "username": "张三",
      "avatar": "https://example.com/avatar.jpg",
      "email": "zhangsan@example.com"
    },
    "recipient": {
      "userId": "user_123",
      "username": "张三",
      "avatar": "https://example.com/avatar.jpg",
      "email": "zhangsan@example.com"
    },
    "sendTime": "2025-12-31T23:59:59Z",
    "createdAt": "2023-07-20T10:30:00Z",
    "deliveryTime": null,
    "status": "DRAFT",
    "triggerType": "TIME",
    "triggerCondition": {},
    "attachments": [
      {
        "id": "attach_123",
        "type": "IMAGE",
        "url": "https://example.com/image.jpg",
        "thumbnail": "https://example.com/thumb.jpg",
        "size": 1024000
      }
    ],
    "isEncrypted": false,
    "capsuleStyle": "default",
    "canEdit": true,
    "canRevoke": false
  }
}
```

### 更新胶囊邮件

**接口地址：** `PUT /api/v1/mails/{mailId}`

**接口描述：** 更新胶囊邮件内容（仅草稿状态可更新）

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| mailId | string | 是 | 邮件ID（路径参数） |
| title | string | 否 | 邮件标题 |
| content | string | 否 | 邮件内容 |
| recipientType | string | 否 | 收件人类型：SELF、SPECIFIC、PUBLIC |
| recipientEmail | string | 否 | 指定收件人邮箱（当recipientType为SPECIFIC时必填） |
| sendTime | string | 否 | 发送时间，ISO格式时间字符串 |
| triggerType | string | 否 | 触发类型：TIME、LOCATION、EVENT |
| triggerCondition | object | 否 | 触发条件 |
| attachments | array | 否 | 附件列表 |
| isEncrypted | boolean | 否 | 是否加密 |
| capsuleStyle | string | 否 | 胶囊样式 |

#### 请求示例

```json
{
  "title": "更新后的标题",
  "content": "更新后的内容...",
  "sendTime": "2026-12-31T23:59:59Z"
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | number | 响应状态码，200表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| data.mailId | string | 邮件ID |
| data.capsuleId | string | 胶囊ID |
| data.status | string | 邮件状态 |
| data.updatedAt | string | 更新时间，ISO格式时间字符串 |

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "mailId": "mail_1234567890",
    "capsuleId": "capsule_1234567890",
    "status": "DRAFT",
    "updatedAt": "2023-07-21T14:30:00Z"
  }
}
```

### 删除胶囊邮件

**接口地址：** `DELETE /api/v1/mails/{mailId}`

**接口描述：** 删除指定的胶囊邮件

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| mailId | string | 是 | 邮件ID（路径参数） |

#### 请求示例

```
DELETE /api/v1/mails/mail_1234567890
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | number | 响应状态码，200表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| data.mailId | string | 已删除的邮件ID |

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "mailId": "mail_1234567890"
  }
}
```

## 错误码

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权，需要登录 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 422 | 验证失败 |
| 500 | 服务器内部错误 |

## 注意事项

1. 存入胶囊的邮件状态为DRAFT，可以在任何时候编辑或发送
2. 只有草稿状态的邮件可以编辑或删除
3. 发送时间必须晚于当前时间
4. 附件大小限制为10MB
5. 免费用户每月最多可创建10个胶囊邮件
6. 加密邮件需要额外验证才能查看内容