emall-web/.trae/rules/project_rules.md

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

出参: // 同注册出参

2. 邮件管理模块

2.1 创建未来邮件

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 获取邮件列表

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 获取邮件详情

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 更新邮件（投递前）

PUT /api/v1/mails/{mailId}
入参: // 同创建邮件，但所有字段可选
出参: // 同创建邮件出参

2.5 撤销发送

POST /api/v1/mails/{mailId}/revoke
出参:
{
  "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": "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写作辅助

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 情感分析

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 获取时间线

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 获取统计数据

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 获取用户订阅信息

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