## 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原则，并考虑了扩展性和安全性。