445 lines
10 KiB
Markdown
445 lines
10 KiB
Markdown
# 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月* |