emall-api/project_rules.md at main

emall/emall-api

Fork 0

Files

XCool de704db577 初始化

2025-10-16 09:56:36 +08:00

8.9 KiB

Raw Permalink Blame History

使用.Net core 9.0
使用Ef codefirst 自动更新数据库字段
使用Open Api接口文档
使用Mysql数据库

基于你的产品设计，我来帮你定义核心接口的出参入参。以下是主要接口设计：

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

需要的核心接口列表

认证相关
- 用户注册 /api/v1/auth/register
- 用户登录 /api/v1/auth/login
- 刷新token /api/v1/auth/refresh
- 退出登录 /api/v1/auth/logout
邮件管理
- 创建邮件 /api/v1/mails
- 获取邮件列表 /api/v1/mails
- 获取邮件详情 /api/v1/mails/{mailId}
- 更新邮件 /api/v1/mails/{mailId}
- 删除邮件 /api/v1/mails/{mailId}
- 撤销发送 /api/v1/mails/{mailId}/revoke
时光胶囊
- 获取胶囊视图 /api/v1/capsules
- 更新胶囊样式 /api/v1/capsules/{capsuleId}/style
AI助手
- 写作辅助 /api/v1/ai/writing-assistant
- 情感分析 /api/v1/ai/sentiment-analysis
- 未来预测 /api/v1/ai/future-prediction
个人空间
- 时间线 /api/v1/timeline
- 统计数据 /api/v1/statistics
- 用户信息 /api/v1/user/profile
文件上传
- 上传附件 /api/v1/upload/attachment
- 上传头像 /api/v1/upload/avatar
推送通知
- 注册设备 /api/v1/notification/device
- 获取通知设置 /api/v1/notification/settings

这些接口设计考虑了产品的核心功能，包括邮件的创建、管理、投递，以及增强用户体验的AI功能和可视化功能。接口设计遵循RESTful原则，并考虑了扩展性和安全性。

8.9 KiB Raw Permalink Blame History Unescape Escape

1. 用户认证模块

1.1 用户注册

1.2 用户登录

2. 邮件管理模块

2.1 创建未来邮件

2.2 获取邮件列表

2.3 获取邮件详情

2.4 更新邮件（投递前）

2.5 撤销发送

3. 时光胶囊模块

3.1 获取时光胶囊视图

4. AI助手模块

4.1 AI写作辅助

4.2 情感分析

5. 个人空间模块

5.1 获取时间线

5.2 获取统计数据

6. 系统管理模块

6.1 获取用户订阅信息

需要的核心接口列表

8.9 KiB

Raw Permalink Blame History