初始化

README-API.md

@@ -0,0 +1,421 @@
+# 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)
+}
+```