emall/emall-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

初始化

Browse Source
This commit is contained in:
XCool
2025-10-18 16:18:20 +08:00
parent cf2273e6da
commit e287d7bbde
33 changed files with 3575 additions and 303 deletions
Download Patch File Download Diff File Expand all files Collapse all files

372
.trae/rules/save.md Normal file
View File

@@ -0,0 +1,372 @@
# 存入胶囊功能 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. 加密邮件需要额外验证才能查看内容

307
.trae/rules/seed.md Normal file
View File

@@ -0,0 +1,307 @@
# 发送至未来功能 API 文档
## 概述
发送至未来功能允许用户将邮件设置为在未来特定时间自动发送，邮件状态将变为待投递(PENDING)，系统会在指定时间自动处理发送。
## API 接口
### 发送至未来
**接口地址：** `POST /api/v1/mails/send-to-future`
**接口描述：** 将草稿状态的邮件设置为在未来特定时间自动发送
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| mailId | string | 是 | 邮件ID |
| sendTime | string | 是 | 发送时间，ISO格式时间字符串（如：2025-12-31T23:59:59Z） |
| triggerType | string | 否 | 触发类型：TIME（时间）、LOCATION（地点）、EVENT（事件），默认为TIME |
| 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 | 否 | 事件类型 |
#### 请求示例
```json
{
"mailId": "mail_1234567890",
"sendTime": "2025-12-31T23:59:59Z",
"triggerType": "TIME",
"triggerCondition": {}
}
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | number | 响应状态码，200表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| data.mailId | string | 邮件ID |
| data.capsuleId | string | 胶囊ID |
| data.status | string | 邮件状态：PENDING |
| data.sendTime | string | 发送时间 |
| data.countdown | number | 倒计时秒数 |
| data.updatedAt | string | 更新时间，ISO格式时间字符串 |
#### 响应示例
```json
{
"code": 200,
"message": "success",
"data": {
"mailId": "mail_1234567890",
"capsuleId": "capsule_1234567890",
"status": "PENDING",
"sendTime": "2025-12-31T23:59:59Z",
"countdown": 94608000,
"updatedAt": "2023-07-20T10:30:00Z"
}
}
```
### 获取待发送邮件列表
**接口地址：** `GET /api/v1/mails`
**接口描述：** 获取用户的待发送邮件列表
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | string | 否 | 邮件类型：INBOX、SENT、DRAFT，获取待发送时使用SENT |
| status | string | 否 | 状态筛选：PENDING、DELIVERING、DELIVERED、DRAFT，获取待发送时使用PENDING |
| page | number | 否 | 页码，默认为1 |
| size | number | 否 | 每页数量，默认为10 |
#### 请求示例
```
GET /api/v1/mails?type=SENT&status=PENDING&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.list[].countdown | number | 倒计时秒数 |
| 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": "PENDING",
"hasAttachments": true,
"isEncrypted": false,
"capsuleStyle": "default",
"countdown": 94608000
}
],
"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 | 是否可编辑（待发送状态为false） |
| data.canRevoke | boolean | 是否可撤销（待发送状态为true） |
| data.countdown | number | 倒计时秒数 |
#### 响应示例
```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": "PENDING",
"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": false,
"canRevoke": true,
"countdown": 94608000
}
}
```
### 撤销待发送邮件
**接口地址：** `POST /api/v1/mails/{mailId}/revoke`
**接口描述：** 撤销待发送的邮件，将状态改回草稿
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| mailId | string | 是 | 邮件ID（路径参数） |
#### 请求示例
```
POST /api/v1/mails/mail_1234567890/revoke
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | number | 响应状态码，200表示成功 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| data.mailId | string | 邮件ID |
| data.status | string | 邮件状态：DRAFT |
| data.revokedAt | string | 撤销时间，ISO格式时间字符串 |
#### 响应示例
```json
{
"code": 200,
"message": "success",
"data": {
"mailId": "mail_1234567890",
"status": "DRAFT",
"revokedAt": "2023-07-21T14:30:00Z"
}
}
```
## 错误码
| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权，需要登录 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 422 | 验证失败 |
| 500 | 服务器内部错误 |
## 注意事项
1. 发送至未来的邮件状态为PENDING，表示等待系统在未来指定时间自动发送
2. 只有草稿状态(DRAFT)的邮件可以设置为发送至未来
3. 发送时间必须晚于当前时间至少1小时
4. 待发送状态的邮件不能编辑内容，但可以撤销发送
5. 撤销后的邮件状态将变回草稿(DRAFT)，可以重新编辑或设置发送时间
6. 系统会在发送时间到达前10分钟进入投递中状态(DELIVERING)
7. 免费用户每月最多可设置5封邮件发送至未来
8. 附件大小限制为10MB
9. 加密邮件需要额外验证才能查看内容