422 lines
8.7 KiB
Markdown
422 lines
8.7 KiB
Markdown
|
||
|
||
## 1. 用户认证模块
|
||
|
||
### 1.1 用户注册
|
||
```typescript
|
||
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 用户登录
|
||
```typescript
|
||
POST /api/v1/auth/login
|
||
入参:
|
||
{
|
||
"email": "string",
|
||
"password": "string"
|
||
}
|
||
|
||
出参: // 同注册出参
|
||
```
|
||
|
||
## 2. 邮件管理模块
|
||
|
||
### 2.1 创建未来邮件
|
||
```typescript
|
||
POST /api/v1/mails
|
||
入参:
|
||
{
|
||
"title": "string",
|
||
"content": "string",
|
||
"recipientType": "SELF" | "SPECIFIC" | "PUBLIC", // 收件人类型
|
||
"recipientEmail": "string?", // 指定收件人邮箱（当recipientType为SPECIFIC时必填）
|
||
"sendTime": "string", // ISO时间格式 "2025-12-31T23:59:59Z"
|
||
"triggerType": "TIME" | "LOCATION" | "EVENT",
|
||
"triggerCondition": {
|
||
"location": {
|
||
"latitude": "number?",
|
||
"longitude": "number?",
|
||
"city": "string?"
|
||
},
|
||
"event": {
|
||
"keywords": "string[]?",
|
||
"type": "string?"
|
||
}
|
||
},
|
||
"attachments": [
|
||
{
|
||
"type": "IMAGE" | "VOICE" | "VIDEO",
|
||
"url": "string",
|
||
"thumbnail": "string?"
|
||
}
|
||
],
|
||
"isEncrypted": "boolean",
|
||
"capsuleStyle": "string" // 胶囊皮肤
|
||
}
|
||
|
||
出参:
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"mailId": "string",
|
||
"capsuleId": "string",
|
||
"status": "DRAFT" | "PENDING" | "DELIVERING" | "DELIVERED",
|
||
"createdAt": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 获取邮件列表
|
||
```typescript
|
||
GET /api/v1/mails
|
||
查询参数:
|
||
{
|
||
"type": "INBOX" | "SENT" | "DRAFT", // 邮件类型
|
||
"status": "PENDING" | "DELIVERING" | "DELIVERED", // 状态筛选
|
||
"page": "number",
|
||
"size": "number"
|
||
}
|
||
|
||
出参:
|
||
{
|
||
"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": "boolean",
|
||
"isEncrypted": "boolean",
|
||
"capsuleStyle": "string",
|
||
"countdown": "number?" // 倒计时秒数（仅status=PENDING时返回）
|
||
}
|
||
],
|
||
"total": "number",
|
||
"page": "number",
|
||
"size": "number"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.3 获取邮件详情
|
||
```typescript
|
||
GET /api/v1/mails/{mailId}
|
||
出参:
|
||
{
|
||
"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": "object",
|
||
"attachments": [
|
||
{
|
||
"id": "string",
|
||
"type": "string",
|
||
"url": "string",
|
||
"thumbnail": "string?",
|
||
"size": "number"
|
||
}
|
||
],
|
||
"isEncrypted": "boolean",
|
||
"capsuleStyle": "string",
|
||
"canEdit": "boolean", // 是否可编辑（仅草稿状态）
|
||
"canRevoke": "boolean" // 是否可撤销（仅待投递状态）
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.4 更新邮件（投递前）
|
||
```typescript
|
||
PUT /api/v1/mails/{mailId}
|
||
入参: // 同创建邮件，但所有字段可选
|
||
出参: // 同创建邮件出参
|
||
```
|
||
|
||
### 2.5 撤销发送
|
||
```typescript
|
||
POST /api/v1/mails/{mailId}/revoke
|
||
出参:
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"mailId": "string",
|
||
"status": "REVOKED"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 时光胶囊模块
|
||
|
||
### 3.1 获取时光胶囊视图
|
||
```typescript
|
||
GET /api/v1/capsules
|
||
出参:
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"capsules": [
|
||
{
|
||
"capsuleId": "string",
|
||
"mailId": "string",
|
||
"title": "string",
|
||
"sendTime": "string",
|
||
"deliveryTime": "string",
|
||
"progress": "number", // 0-1 的进度
|
||
"position": {
|
||
"x": "number", // 0-1 相对位置
|
||
"y": "number",
|
||
"z": "number"
|
||
},
|
||
"style": "string",
|
||
"glowIntensity": "number" // 发光强度
|
||
}
|
||
],
|
||
"scene": "SPACE" | "OCEAN", // 场景类型
|
||
"background": "string" // 背景配置
|
||
}
|
||
}
|
||
```
|
||
|
||
## 4. AI助手模块
|
||
|
||
### 4.1 AI写作辅助
|
||
```typescript
|
||
POST /api/v1/ai/writing-assistant
|
||
入参:
|
||
{
|
||
"prompt": "string", // 用户输入
|
||
"type": "OUTLINE" | "DRAFT" | "COMPLETE", // 辅助类型
|
||
"tone": "FORMAL" | "CASUAL" | "EMOTIONAL" | "INSPIRATIONAL", // 语气
|
||
"length": "SHORT" | "MEDIUM" | "LONG", // 长度
|
||
"context": "string?" // 上下文信息
|
||
}
|
||
|
||
出参:
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"content": "string",
|
||
"suggestions": "string[]",
|
||
"estimatedTime": "number" // 预计写作时间（分钟）
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.2 情感分析
|
||
```typescript
|
||
POST /api/v1/ai/sentiment-analysis
|
||
入参:
|
||
{
|
||
"content": "string"
|
||
}
|
||
|
||
出参:
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"sentiment": "POSITIVE" | "NEUTRAL" | "NEGATIVE" | "MIXED",
|
||
"confidence": "number", // 0-1 置信度
|
||
"emotions": [
|
||
{
|
||
"type": "HAPPY" | "SAD" | "HOPEFUL" | "NOSTALGIC" | "EXCITED",
|
||
"score": "number"
|
||
}
|
||
],
|
||
"keywords": "string[]",
|
||
"summary": "string"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 5. 个人空间模块
|
||
|
||
### 5.1 获取时间线
|
||
```typescript
|
||
GET /api/v1/timeline
|
||
查询参数:
|
||
{
|
||
"startDate": "string?",
|
||
"endDate": "string?",
|
||
"type": "ALL" | "SENT" | "RECEIVED"
|
||
}
|
||
|
||
出参:
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"timeline": [
|
||
{
|
||
"date": "string",
|
||
"events": [
|
||
{
|
||
"type": "SENT" | "RECEIVED",
|
||
"mailId": "string",
|
||
"title": "string",
|
||
"time": "string",
|
||
"withUser": {
|
||
"userId": "string",
|
||
"username": "string",
|
||
"avatar": "string"
|
||
},
|
||
"emotion": "string"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.2 获取统计数据
|
||
```typescript
|
||
GET /api/v1/statistics
|
||
出参:
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"totalSent": "number",
|
||
"totalReceived": "number",
|
||
"timeTravelDuration": "number", // 总时间旅行时长（天）
|
||
"mostFrequentRecipient": "string",
|
||
"mostCommonYear": "number",
|
||
"keywordCloud": [
|
||
{
|
||
"word": "string",
|
||
"count": "number",
|
||
"size": "number"
|
||
}
|
||
],
|
||
"monthlyStats": [
|
||
{
|
||
"month": "string",
|
||
"sent": "number",
|
||
"received": "number"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 6. 系统管理模块
|
||
|
||
### 6.1 获取用户订阅信息
|
||
```typescript
|
||
GET /api/v1/user/subscription
|
||
出参:
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"plan": "FREE" | "PREMIUM",
|
||
"remainingMails": "number",
|
||
"maxAttachmentSize": "number",
|
||
"features": {
|
||
"advancedTriggers": "boolean",
|
||
"customCapsules": "boolean",
|
||
"aiAssistant": "boolean"
|
||
},
|
||
"expireDate": "string?"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 需要的核心接口列表
|
||
|
||
1. **认证相关**
|
||
- 用户注册 `/api/v1/auth/register`
|
||
- 用户登录 `/api/v1/auth/login`
|
||
- 刷新token `/api/v1/auth/refresh`
|
||
- 退出登录 `/api/v1/auth/logout`
|
||
|
||
2. **邮件管理**
|
||
- 创建邮件 `/api/v1/mails`
|
||
- 获取邮件列表 `/api/v1/mails`
|
||
- 获取邮件详情 `/api/v1/mails/{mailId}`
|
||
- 更新邮件 `/api/v1/mails/{mailId}`
|
||
- 删除邮件 `/api/v1/mails/{mailId}`
|
||
- 撤销发送 `/api/v1/mails/{mailId}/revoke`
|
||
|
||
3. **时光胶囊**
|
||
- 获取胶囊视图 `/api/v1/capsules`
|
||
- 更新胶囊样式 `/api/v1/capsules/{capsuleId}/style`
|
||
|
||
4. **AI助手**
|
||
- 写作辅助 `/api/v1/ai/writing-assistant`
|
||
- 情感分析 `/api/v1/ai/sentiment-analysis`
|
||
- 未来预测 `/api/v1/ai/future-prediction`
|
||
|
||
5. **个人空间**
|
||
- 时间线 `/api/v1/timeline`
|
||
- 统计数据 `/api/v1/statistics`
|
||
- 用户信息 `/api/v1/user/profile`
|
||
|
||
6. **文件上传**
|
||
- 上传附件 `/api/v1/upload/attachment`
|
||
- 上传头像 `/api/v1/upload/avatar`
|
||
|
||
7. **推送通知**
|
||
- 注册设备 `/api/v1/notification/device`
|
||
- 获取通知设置 `/api/v1/notification/settings`
|
||
|
||
这些接口设计考虑了产品的核心功能，包括邮件的创建、管理、投递，以及增强用户体验的AI功能和可视化功能。接口设计遵循RESTful原则，并考虑了扩展性和安全性。 |