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. 认证相关接口

#### 用户注册
```javascript
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 } }
```

#### 用户登录
```javascript
const loginData = {
  email: 'string',       // 邮箱
  password: 'string'     // 密码
}

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

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

#### 退出登录
```javascript
const response = await authAPI.logout()
// 响应数据: { code: 200, message: 'success' }
```

### 2. 邮件管理接口

#### 创建邮件
```javascript
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 } }
```

#### 获取邮件列表
```javascript
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 } }
```

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

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

#### 删除邮件
```javascript
const mailId = 'string'
const response = await mailAPI.deleteMail(mailId)
// 响应数据: { code: 200, message: 'success' }
```

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

### 3. 时光胶囊接口

#### 获取胶囊视图
```javascript
import { capsuleAPI } from '@/api'

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

#### 更新胶囊样式
```javascript
const capsuleId = 'string'
const style = 'string'
const response = await capsuleAPI.updateCapsuleStyle(capsuleId, style)
// 响应数据: { code: 200, message: 'success' }
```

### 4. AI助手接口

#### 写作辅助
```javascript
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 } }
```

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

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

### 5. 个人空间接口

#### 获取时间线
```javascript
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 } }
```

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

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

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

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

### 6. 文件上传接口

#### 上传附件
```javascript
import { uploadAPI } from '@/api'

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

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

### 7. 推送通知接口

#### 注册设备
```javascript
import { notificationAPI } from '@/api'

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

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

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

## 状态管理

### 用户状态
```javascript
import { userState, userActions } from '@/store'

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

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

### 邮件状态
```javascript
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)
```

### 胶囊状态
```javascript
import { capsuleState, capsuleActions } from '@/store'

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

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

## 工具函数

```javascript
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`

```bash
# 开发环境配置
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. 安装依赖：
```bash
npm install
```

2. 启动开发服务器：
```bash
npm run serve
```

3. 构建生产版本：
```bash
npm run build
```

4. 运行Electron应用：
```bash
npm run electron:serve
```

## 注意事项

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

## 错误处理

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

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