emall-web/README-API.md

ChronoMail 前端API对接文档

项目概述

ChronoMail（未来邮箱）是一个基于Vue 3 + Electron + Vant + Axios构建的跨平台邮件应用，支持发送未来邮件、时光胶囊、AI辅助写作等功能。

技术栈

• 前端框架: Vue 3
• 桌面端: Electron
• 路由: Vue Router 4
• UI组件库: Vant 4
• HTTP客户端: Axios
• 状态管理: Vue 3 Composition API

项目结构

src/
├── api/                 # API接口模块
│   ├── index.js        # API方法集合
│   └── request.js      # Axios实例和拦截器配置
├── assets/             # 静态资源
│   └── styles/         # 样式文件
│       └── global.css  # 全局样式
├── router/             # 路由配置
│   └── index.js        # 路由定义和守卫
├── store/              # 状态管理
│   └── index.js        # 状态和操作方法
├── utils/              # 工具函数
│   └── index.js        # 通用工具函数
├── views/              # 页面组件
│   ├── Login.vue       # 登录页
│   ├── Register.vue    # 注册页
│   ├── Home.vue        # 首页
│   ├── Compose.vue     # 撰写邮件页
│   ├── Inbox.vue       # 收件箱页
│   ├── Sent.vue        # 发件箱页
│   ├── Profile.vue     # 个人中心页
│   ├── Timeline.vue    # 时间线页
│   └── CapsuleDetail.vue # 胶囊详情页
├── App.vue             # 根组件
└── main.js             # 入口文件

API接口说明

1. 认证相关接口

用户注册

import { authAPI } from '@/api'

const registerData = {
  username: 'string',    // 用户名
  email: 'string',       // 邮箱
  password: 'string',    // 密码
  avatar: 'string?'      // 头像URL（可选）
}

const response = await authAPI.register(registerData)
// 响应数据: { code: 200, message: 'success', data: { userId, username, email, avatar, token, refreshToken } }

用户登录

const loginData = {
  email: 'string',       // 邮箱
  password: 'string'     // 密码
}

const response = await authAPI.login(loginData)
// 响应数据同注册

刷新Token

const response = await authAPI.refreshToken(refreshToken)
// 响应数据: { code: 200, message: 'success', data: { token, refreshToken } }

退出登录

const response = await authAPI.logout()
// 响应数据: { code: 200, message: 'success' }

2. 邮件管理接口

创建邮件

import { mailAPI } from '@/api'

const mailData = {
  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'              // 胶囊皮肤
}

const response = await mailAPI.createMail(mailData)
// 响应数据: { code: 200, message: 'success', data: { mailId, capsuleId, status, createdAt } }

获取邮件列表

const params = {
  type: 'INBOX|SENT|DRAFT',  // 邮件类型
  status: 'PENDING|DELIVERING|DELIVERED', // 状态筛选
  page: 1,                   // 页码
  size: 10                   // 每页数量
}

const response = await mailAPI.getMails(params)
// 响应数据: { code: 200, message: 'success', data: { list, total, page, size } }

获取邮件详情

const mailId = 'string'
const response = await mailAPI.getMailDetail(mailId)
// 响应数据: { code: 200, message: 'success', data: { 邮件详情 } }

更新邮件

const mailId = 'string'
const updateData = { /* 同创建邮件，但所有字段可选 */ }
const response = await mailAPI.updateMail(mailId, updateData)
// 响应数据: { code: 200, message: 'success', data: { 更新后的邮件信息 } }

删除邮件

const mailId = 'string'
const response = await mailAPI.deleteMail(mailId)
// 响应数据: { code: 200, message: 'success' }

撤销发送

const mailId = 'string'
const response = await mailAPI.revokeMail(mailId)
// 响应数据: { code: 200, message: 'success', data: { mailId, status: 'REVOKED' } }

3. 时光胶囊接口

获取胶囊视图

import { capsuleAPI } from '@/api'

const response = await capsuleAPI.getCapsules()
// 响应数据: { code: 200, message: 'success', data: { capsules, scene, background } }

更新胶囊样式

const capsuleId = 'string'
const style = 'string'
const response = await capsuleAPI.updateCapsuleStyle(capsuleId, style)
// 响应数据: { code: 200, message: 'success' }

4. AI助手接口

写作辅助

import { aiAPI } from '@/api'

const data = {
  prompt: 'string',           // 用户输入
  type: 'OUTLINE|DRAFT|COMPLETE', // 辅助类型
  tone: 'FORMAL|CASUAL|EMOTIONAL|INSPIRATIONAL', // 语气
  length: 'SHORT|MEDIUM|LONG', // 长度
  context: 'string?'          // 上下文信息
}

const response = await aiAPI.writingAssistant(data)
// 响应数据: { code: 200, message: 'success', data: { content, suggestions, estimatedTime } }

情感分析

const content = 'string'
const response = await aiAPI.sentimentAnalysis(content)
// 响应数据: { code: 200, message: 'success', data: { sentiment, confidence, emotions, keywords, summary } }

未来预测

const data = { /* 预测参数 */ }
const response = await aiAPI.futurePrediction(data)
// 响应数据: { code: 200, message: 'success', data: { 预测结果 } }

5. 个人空间接口

获取时间线

import { userAPI } from '@/api'

const params = {
  startDate: 'string?',  // 开始日期
  endDate: 'string?',    // 结束日期
  type: 'ALL|SENT|RECEIVED' // 类型
}

const response = await userAPI.getTimeline(params)
// 响应数据: { code: 200, message: 'success', data: { timeline } }

获取统计数据

const response = await userAPI.getStatistics()
// 响应数据: { code: 200, message: 'success', data: { 统计数据 } }

获取用户信息

const response = await userAPI.getUserProfile()
// 响应数据: { code: 200, message: 'success', data: { 用户信息 } }

更新用户信息

const data = { /* 用户信息 */ }
const response = await userAPI.updateUserProfile(data)
// 响应数据: { code: 200, message: 'success', data: { 更新后的用户信息 } }

获取用户订阅信息

const response = await userAPI.getSubscription()
// 响应数据: { code: 200, message: 'success', data: { 订阅信息 } }

6. 文件上传接口

上传附件

import { uploadAPI } from '@/api'

const file = /* File对象 */
const response = await uploadAPI.uploadAttachment(file)
// 响应数据: { code: 200, message: 'success', data: { 文件信息 } }

上传头像

const file = /* File对象 */
const response = await uploadAPI.uploadAvatar(file)
// 响应数据: { code: 200, message: 'success', data: { 头像URL } }

7. 推送通知接口

注册设备

import { notificationAPI } from '@/api'

const data = { /* 设备信息 */ }
const response = await notificationAPI.registerDevice(data)
// 响应数据: { code: 200, message: 'success' }

获取通知设置

const response = await notificationAPI.getNotificationSettings()
// 响应数据: { code: 200, message: 'success', data: { 通知设置 } }

更新通知设置

const data = { /* 通知设置 */ }
const response = await notificationAPI.updateNotificationSettings(data)
// 响应数据: { code: 200, message: 'success' }

状态管理

用户状态

import { userState, userActions } from '@/store'

// 获取用户状态
console.log(userState.isLoggedIn)
console.log(userState.userInfo)

// 用户操作
await userActions.login(credentials)
await userActions.logout()
await userActions.getSubscription()

邮件状态

import { mailState, mailActions } from '@/store'

// 获取邮件状态
console.log(mailState.inboxList)
console.log(mailState.currentMail)

// 邮件操作
await mailActions.getMails('INBOX')
await mailActions.getMailDetail(mailId)
await mailActions.createMail(mailData)

胶囊状态

import { capsuleState, capsuleActions } from '@/store'

// 获取胶囊状态
console.log(capsuleState.capsules)

// 胶囊操作
await capsuleActions.getCapsules()
await capsuleActions.updateCapsuleStyle(capsuleId, style)

工具函数

import { formatDate, countdown, validateEmail, validatePassword } from '@/utils'

// 格式化日期
const formattedDate = formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')

// 计算倒计时
const { days, hours, minutes, seconds } = countdown('2025-12-31T23:59:59Z')

// 验证邮箱
const isValidEmail = validateEmail('user@example.com')

// 验证密码强度
const { strength, message } = validatePassword('password123')

环境配置

项目使用环境变量来配置不同环境的API地址：

• 开发环境：.env.development
• 生产环境：.env.production

# 开发环境配置
VUE_APP_API_BASE_URL=http://localhost:3000/api/v1
VUE_APP_TITLE=ChronoMail - 未来邮箱

# 生产环境配置
VUE_APP_API_BASE_URL=https://api.chronomail.com/api/v1
VUE_APP_TITLE=ChronoMail - 未来邮箱

开发指南

1. 安装依赖：

npm install

2. 启动开发服务器：

npm run serve

3. 构建生产版本：

npm run build

4. 运行Electron应用：

npm run electron:serve

注意事项

1. 所有API请求都会自动添加Authorization头，格式为Bearer {token}
2. 当收到401或403响应时，会自动清除用户信息并跳转到登录页
3. 文件上传需要使用FormData格式
4. 日期格式统一使用ISO 8601标准
5. 所有状态变更都应通过相应的Actions方法进行，以保证状态一致性

错误处理

API请求失败时，会显示错误提示并返回Promise.reject，可以在组件中使用try-catch处理：

try {
  const response = await mailAPI.createMail(mailData)
  // 处理成功响应
} catch (error) {
  // 处理错误
  console.error('创建邮件失败:', error)
}