# ChronoMail - 时光胶囊邮箱 详细文档

## 项目概述

ChronoMail是一个基于Vue3和Electron的时光胶囊邮箱应用，用户可以撰写邮件并设定未来的发送时间，将此刻的心情、想法和祝福寄给未来的自己或他人。项目采用深空主题设计，营造时光穿梭的视觉体验。

## 技术架构

### 前端技术栈
- **Vue 3**: 使用Composition API进行组件开发
- **Vue Router 4**: 负责前端路由管理和导航守卫
- **Vant 4**: 移动端UI组件库，提供丰富的交互组件
- **Axios**: HTTP客户端，用于API请求和响应处理
- **Electron**: 跨平台桌面应用框架

### 项目结构
```
ChronoMail/
├── public/                 # 静态资源
│   ├── favicon.svg        # 网站图标
│   └── index.html         # HTML模板
├── src/                   # 源代码
│   ├── api/               # API接口模块
│   │   ├── index.js       # API方法集合
│   │   └── request.js     # Axios实例和拦截器配置
│   ├── assets/            # 静态资源
│   │   └── styles/        # 样式文件
│   ├── 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 # 胶囊详情
│   │   └── ApiDemo.vue    # API示例
│   ├── App.vue            # 根组件
│   └── main.js            # 应用入口
├── .env.development       # 开发环境变量
├── .env.production        # 生产环境变量
├── babel.config.js        # Babel配置
├── vue.config.js          # Vue CLI配置
└── package.json           # 项目依赖和脚本
```

## 核心功能模块

### 1. 用户认证模块
- **登录功能**: 用户通过邮箱和密码登录系统
- **注册功能**: 新用户注册账号
- **Token管理**: 自动刷新和存储访问令牌
- **路由守卫**: 保护需要登录的页面

### 2. 邮件管理模块
- **撰写邮件**: 创建带有未来发送时间的邮件
- **收件箱**: 查看接收到的邮件
- **发件箱**: 查看已发送的邮件
- **草稿箱**: 管理未发送的邮件草稿
- **邮件操作**: 编辑、删除、撤销发送等

### 3. 时光胶囊模块
- **3D胶囊视图**: 在深空背景中展示时光胶囊
- **胶囊交互**: 点击胶囊查看详情
- **胶囊样式**: 自定义胶囊外观
- **倒计时显示**: 显示距离发送的时间

### 4. AI助手模块
- **写作辅助**: AI帮助生成邮件开头
- **内容建议**: 提供邮件内容建议
- **情感分析**: 分析邮件内容的情感倾向

### 5. 个人空间模块
- **时间线**: 展示用户的邮件历史
- **数据统计**: 邮件发送/接收统计
- **个人信息**: 管理用户资料

## 页面功能详解

### 1. 登录页面 (Login.vue)
- 用户登录表单
- 记住登录状态选项
- 跳转注册页面链接
- 深空主题背景设计

### 2. 注册页面 (Register.vue)
- 用户注册表单
- 密码确认验证
- 用户协议同意选项
- 跳转登录页面链接

### 3. 首页/时光胶囊 (Home.vue)
- 个性化欢迎语
- 3D时光胶囊展示
- 星空动态背景
- 搜索和通知功能
- 底部导航栏
- 悬浮撰写按钮

### 4. 撰写邮件 (Compose.vue)
- 收件人类型选择（自己/指定/公开）
- 发送时间选择（预设时间/自定义时间）
- 邮件标题和内容编辑
- 附件上传功能
- AI写作辅助
- 胶囊样式选择
- 存入草稿和发送按钮

### 5. 收件箱 (Inbox.vue)
- 邮件列表展示
- 邮件状态筛选
- 邮件详情查看
- 搜索功能

### 6. 发件箱 (Sent.vue)
- 已发送邮件列表
- 邮件状态显示
- 撤销发送功能
- 邮件详情查看

### 7. 个人中心 (Profile.vue)
- 用户信息展示
- 订阅信息显示
- 功能设置选项
- 退出登录功能

### 8. 时间线 (Timeline.vue)
- 按时间顺序展示邮件
- 邮件情感标记
- 月份统计图表

### 9. 胶囊详情 (CapsuleDetail.vue)
- 邮件完整内容展示
- 发送/接收信息
- 附件查看
- 相关操作按钮

## 状态管理

项目使用Vue 3的响应式API进行状态管理，主要状态包括：

### 用户状态 (userState)
```javascript
{
  isLoggedIn: boolean,     // 登录状态
  token: string,          // 访问令牌
  refreshToken: string,   // 刷新令牌
  userInfo: {             // 用户信息
    userId: string,
    username: string,
    email: string,
    avatar: string
  },
  subscription: {         // 订阅信息
    plan: string,
    remainingMails: number,
    features: object
  }
}
```

### 邮件状态 (mailState)
```javascript
{
  inboxList: [],          // 收件箱邮件列表
  sentList: [],           // 发件箱邮件列表
  draftList: [],          // 草稿箱邮件列表
  currentMail: {},        // 当前查看的邮件
  totalCounts: {          // 各类邮件计数
    inbox: number,
    sent: number,
    draft: number
  }
}
```

### 胶囊状态 (capsuleState)
```javascript
{
  capsules: [],           // 时光胶囊列表
  scene: string,          // 场景类型
  background: string      // 背景配置
}
```

### 时间线状态 (timelineState)
```javascript
{
  timeline: [],           // 时间线数据
  statistics: {}          // 统计数据
}
```

## API接口设计

### 认证相关
- `POST /api/v1/auth/register` - 用户注册
- `POST /api/v1/auth/login` - 用户登录
- `POST /api/v1/auth/refresh` - 刷新令牌
- `POST /api/v1/auth/logout` - 退出登录

### 邮件管理
- `GET /api/v1/mails` - 获取邮件列表
- `POST /api/v1/mails` - 创建邮件
- `GET /api/v1/mails/{id}` - 获取邮件详情
- `PUT /api/v1/mails/{id}` - 更新邮件
- `DELETE /api/v1/mails/{id}` - 删除邮件
- `POST /api/v1/mails/{id}/revoke` - 撤销发送

### 时光胶囊
- `GET /api/v1/capsules` - 获取胶囊视图
- `PUT /api/v1/capsules/{id}/style` - 更新胶囊样式

### AI助手
- `POST /api/v1/ai/writing-assistant` - 写作辅助
- `POST /api/v1/ai/sentiment-analysis` - 情感分析

### 个人空间
- `GET /api/v1/timeline` - 获取时间线
- `GET /api/v1/statistics` - 获取统计数据
- `GET /api/v1/user/profile` - 获取用户信息

### 文件上传
- `POST /api/v1/upload/attachment` - 上传附件
- `POST /api/v1/upload/avatar` - 上传头像

## 环境配置

### 开发环境 (.env.development)
```
VUE_APP_API_BASE_URL=http://localhost:3000/api/v1
VUE_APP_TITLE=ChronoMail - 未来邮箱
```

### 生产环境 (.env.production)
```
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
```

### 5. 代码检查
```bash
npm run lint
```

## 组件开发规范

### 1. 组件结构
```vue
<template>
  <!-- 模板内容 -->
</template>

<script>
import { ref, computed, onMounted } from 'vue'
import { useRouter } from 'vue-router'

export default {
  name: 'ComponentName',
  setup() {
    // 响应式数据
    const data = ref('')
    
    // 计算属性
    const computedData = computed(() => {
      // 计算逻辑
      return data.value
    })
    
    // 方法
    const method = () => {
      // 方法实现
    }
    
    // 生命周期
    onMounted(() => {
      // 初始化逻辑
    })
    
    // 返回需要在模板中使用的数据和方法
    return {
      data,
      computedData,
      method
    }
  }
}
</script>

<style scoped>
/* 组件样式 */
</style>
```

### 2. 状态管理
- 使用响应式API创建状态
- 通过操作方法修改状态
- 避免直接修改状态，使用提供的操作方法

### 3. API调用
- 使用统一的API模块
- 处理加载状态和错误情况
- 使用async/await处理异步操作

## 样式设计

### 1. 主题色彩
- 主色调：深空蓝 (#0A0E27)
- 强调色：星云紫 (#6A5ACD)
- 点缀色：星光蓝 (#4285F4)
- 背景色：深空黑 (#050714)

### 2. 字体规范
- 主标题：24px，粗体
- 副标题：18px，中等
- 正文：14px，常规
- 辅助文本：12px，常规

### 3. 间距规范
- 大间距：24px
- 中间距：16px
- 小间距：8px
- 微间距：4px

### 4. 组件样式
- 使用Vant组件库作为基础
- 通过CSS变量覆盖默认样式
- 使用scoped样式避免污染

## 部署说明

### 1. Web应用部署
1. 执行构建命令：`npm run build`
2. 将dist目录上传至Web服务器
3. 配置服务器路由重定向

### 2. Electron应用打包
1. 安装electron-builder：`npm install electron-builder --save-dev`
2. 配置package.json的build字段
3. 执行打包命令：`npm run electron:build`

## 性能优化

### 1. 代码分割
- 使用路由懒加载
- 按需加载组件
- 分离第三方库

### 2. 资源优化
- 图片压缩和懒加载
- 字体文件优化
- CSS代码压缩

### 3. 缓存策略
- 静态资源长期缓存
- API响应缓存
- 离线数据缓存

## 测试策略

### 1. 单元测试
- 组件渲染测试
- 方法逻辑测试
- 状态管理测试

### 2. 集成测试
- 页面跳转测试
- API调用测试
- 用户交互测试

### 3. 端到端测试
- 关键流程测试
- 跨浏览器兼容性测试
- 移动端适配测试

## 常见问题

### 1. API请求失败
- 检查网络连接
- 确认API地址配置
- 验证Token有效性

### 2. 页面加载缓慢
- 检查资源大小
- 优化图片资源
- 启用Gzip压缩

### 3. 移动端适配问题
- 检查视口设置
- 调整字体大小
- 优化触摸交互

## 未来规划

### 1. 功能扩展
- 多媒体邮件支持
- 群组邮件功能
- 邮件模板库

### 2. 技术升级
- 迁移到Vite构建工具
- 引入TypeScript
- 实现PWA功能

### 3. 用户体验优化
- 个性化主题
- 智能推荐系统
- 社交分享功能

## 联系方式

如有问题或建议，请联系开发团队。

---

*最后更新时间：2024年6月*