提交

2025-10-17 16:28:41 +08:00
parent 89dbdc63db
commit 2b634ed4d4
7 changed files with 2265 additions and 123 deletions
--- a/PROJECT_DOCUMENTATION.md
+++ b/PROJECT_DOCUMENTATION.md
@@ -0,0 +1,445 @@
+# 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月*