happy-life-star/web-new/重构计划.md

# 情绪博物馆Web端重构计划

## 1. 重构概述

### 1.1 重构目标
基于前端技术方案Augment.md，使用最新的Vue3+TypeScript技术栈重构情绪博物馆Web端，在保持所有现有功能、页面布局、样式和用户体验完全一致的前提下，提升代码质量、性能和可维护性。

### 1.2 重构原则
- **功能一致性**：确保所有现有功能完全保留
- **视觉一致性**：保持所有页面布局、样式、图片完全一致
- **用户体验一致性**：保持所有交互流程和用户体验不变
- **数据一致性**：保持所有API接口和数据流不变
- **渐进式重构**：分阶段进行，确保每个阶段都可独立测试

### 1.3 技术栈升级
- **Vue**: 2.x → 3.4.21 (最新稳定版)
- **TypeScript**: 无 → 5.4.2 (最新稳定版)
- **构建工具**: Vite 5.1.6 (更好的构建性能)
- **UI框架**: Element Plus 2.6.1 (更好的Vue3支持)
- **样式框架**: Tailwind CSS 3.4.1 + @tailwindcss/forms + @tailwindcss/typography
- **状态管理**: Pinia 2.1.7 (Vue3官方推荐)
- **路由**: Vue Router 4.3.0 (最新稳定版)
- **HTTP客户端**: Axios 1.6.8 (最新稳定版)
- **WebSocket**: @stomp/stompjs 7.1.1 (原生WebSocket，支持Token认证)
- **数据可视化**: ECharts 5.5.0 + vue-echarts 6.7.3
- **工具库**: VueUse 10.9.0 + Day.js 1.11.10 + Lodash-es 4.17.21

## 2. 重构阶段规划

### 第一阶段：项目初始化与基础架构 (1-2周)

#### 2.1 项目初始化
- [ ] 创建新的Vue3+TypeScript项目
- [ ] 配置Vite 5.1.6构建工具
- [ ] 安装和配置核心依赖包
- [ ] 设置TypeScript 5.4.2配置
- [ ] 配置ESLint 8.57.0和Prettier 3.2.5
- [ ] 配置unplugin-auto-import自动导入
- [ ] 配置unplugin-vue-components组件自动导入
- [ ] 设置Git仓库和分支策略
- [ ] 配置Husky和lint-staged

#### 2.2 基础架构搭建
- [ ] 配置路由系统 (Vue Router 4.3.0)
- [ ] 配置状态管理 (Pinia 2.1.7)
- [ ] 配置HTTP客户端 (Axios 1.6.8)
- [ ] 配置WebSocket服务 (@stomp/stompjs 7.1.1，原生WebSocket)
- [ ] 配置多环境变量管理 (local/dev/test/prod)
- [ ] 配置Tailwind CSS 3.4.1样式系统
- [ ] 配置Element Plus 2.6.1 UI组件库
- [ ] 配置ECharts 5.5.0数据可视化
- [ ] 配置VueUse 10.9.0工具库
- [ ] 配置PWA支持 (vite-plugin-pwa)

#### 2.3 工具函数和类型定义
- [ ] 创建HTTP请求工具 (utils/request.ts)
- [ ] 创建WebSocket工具类 (utils/websocket.ts，支持Token认证)
- [ ] 创建存储工具 (utils/storage.ts)
- [ ] 创建格式化工具 (utils/format.ts)
- [ ] 创建验证工具 (utils/validation.ts)
- [ ] 定义API类型 (types/api.ts)
- [ ] 定义用户类型 (types/user.ts)
- [ ] 定义聊天类型 (types/chat.ts)
- [ ] 定义日记类型 (types/diary.ts)
- [ ] 定义全局类型 (types/global.d.ts)
- [ ] 创建API接口定义 (api/auth.ts, api/chat.ts, api/diary.ts, api/user.ts)
- [ ] 创建组合式API (composables/useAuth.ts, useChat.ts, useWebSocket.ts)
- [ ] 配置全局组件注册

### 第二阶段：核心页面重构 (3-4周)

#### 2.4 认证页面重构
- [ ] **登录页面** (/login)
  - 实现POST /auth/login用户登录接口
  - 实现GET /auth/captcha获取验证码接口
  - 实现POST /auth/oauth/login第三方登录接口
  - 保持现有UI布局和样式完全一致
  - 保持验证码功能和第三方登录功能
  - 保持错误提示和交互逻辑
  - 升级到Vue3 Composition API + TypeScript
  - 使用Pinia管理认证状态

- [ ] **注册页面** (/register)
  - 实现POST /auth/register用户注册接口
  - 实现GET /auth/captcha获取验证码接口
  - 保持现有UI布局和样式完全一致
  - 保持表单验证逻辑和验证码功能
  - 保持注册成功自动登录流程
  - 使用@vuelidate/core进行表单验证

- [ ] **认证相关组件和状态管理**
  - UserDropdown组件 (Element Plus重构)
  - UserAvatar组件 (支持头像上传)
  - 认证状态管理 (stores/auth.ts)
  - Token自动刷新机制
  - 路由守卫实现

#### 2.5 首页重构
- [ ] **首页** (/)
  - 保持现有UI布局和样式完全一致
  - 保持导航栏样式和交互
  - 保持产品介绍内容
  - 保持响应式设计
  - 保持动画效果

#### 2.6 聊天功能重构
- [ ] **AI对话页面** (/chat)
  - 实现WebSocket /ws/chat实时对话连接
  - 实现POST /conversation创建会话接口
  - 实现GET /conversation/user/{userId}获取用户会话接口
  - 实现DELETE /conversation/{sessionId}删除会话接口
  - 保持现有UI布局和样式完全一致
  - 保持消息气泡样式和输入框交互
  - 升级到原生WebSocket + STOMP (支持Token认证)
  - 实现自动重连、心跳检测机制
  - 使用composables/useChat.ts管理聊天逻辑
  - 支持文本、图片、表情、文件消息类型

- [ ] **聊天历史页面** (/chat-history)
  - 实现GET /conversation/user/{userId}获取用户会话接口
  - 实现GET /message/user/page分页获取消息接口
  - 实现POST /message/user/search搜索用户消息接口
  - 实现POST /message/user/recent获取最近消息接口
  - 保持现有UI布局和样式完全一致
  - 保持历史记录展示、搜索功能、分页功能
  - 使用虚拟滚动优化大量消息展示

- [ ] **聊天相关组件和状态管理**
  - ChatHistoryModal组件 (Element Plus重构)
  - MessageBubble消息气泡组件
  - ChatInput输入框组件 (支持多媒体)
  - 聊天状态管理 (stores/chat.ts)
  - WebSocket连接状态管理
  - 离线消息缓存和同步机制

### 第三阶段：功能页面重构 (3-4周)

#### 2.7 日记功能重构
- [ ] **情绪日记页面** (/diary)
  - 实现POST /diary-post/publish发布日记接口
  - 实现GET /diary-post/user/{userId}/page获取用户日记接口
  - 保持现有UI布局和样式完全一致
  - 保持日记发布功能和AI自动点评功能
  - 保持日记列表展示和分页功能
  - 使用@tiptap/vue-3实现富文本编辑
  - 支持图片上传和表情插入
  - 实现日记草稿保存功能

#### 2.8 个人中心重构
- [ ] **个人仪表盘** (/personal-dashboard)
  - 实现GET /user/profile获取用户资料接口
  - 实现GET /user/growth-stats获取成长数据接口
  - 保持现有UI布局和样式完全一致
  - 保持用户信息展示和成长数据展示
  - 使用ECharts 5.5.0重构统计图表
  - 实现情绪趋势图、雷达图等可视化
  - 支持数据导出功能 (PDF、Excel)

- [ ] **个人资料页面** (/profile)
  - 实现GET /user/profile获取用户资料接口
  - 实现PUT /user/profile更新用户资料接口
  - 实现POST /user/avatar/upload上传头像接口
  - 实现PUT /user/password修改密码接口
  - 实现邮箱和手机验证接口
  - 保持现有UI布局和样式完全一致
  - 保持信息编辑、头像上传、密码修改功能
  - 使用cropperjs实现头像裁剪功能
  - 使用@vuelidate/core进行表单验证

#### 2.9 分析功能重构
- [ ] **情绪分析页面** (/analysis)
  - 实现情绪数据分析接口 (开发中)
  - 保持现有UI布局和样式完全一致
  - 使用ECharts实现情绪趋势图、雷达图
  - 使用@antv/g2实现高级数据可视化
  - 保持图表展示和交互功能
  - 支持时间范围筛选和数据导出

### 第四阶段：其他页面重构 (2-3周)

#### 2.10 扩展功能页面
- [ ] **人生里程碑** (/life-milestones)
  - 展示用户重要事件和成就
  - 使用时间轴组件展示里程碑
  - 支持里程碑添加、编辑、删除

- [ ] **人生轨迹** (/life-trajectory)
  - 可视化用户成长轨迹
  - 使用交互式图表展示成长路径
  - 支持轨迹数据分析和导出

- [ ] **消息中心** (/messages)
  - 系统消息和AI消息通知
  - 消息分类和状态管理
  - 支持消息标记和批量操作

- [ ] **设置页面** (/settings)
  - 账号设置和隐私设置
  - 通知设置和主题设置
  - 数据导出和账号注销

#### 2.11 工具和辅助页面
- [ ] **话题追踪** (/topic-tracker)
  - 追踪关注的话题和趋势
  - 话题订阅和推荐功能

- [ ] **情绪管理** (/emotion)
  - 情绪记录和管理工具
  - 情绪调节建议和技巧

- [ ] **情绪地图** (/map)
  - 情绪地理分布可视化
  - 基于地理位置的情绪分析

- [ ] **社交分享** (/social)
  - 分享内容到社交平台
  - 社交媒体集成和管理

#### 2.12 系统页面
- [ ] **调试页面** (/debug)
  - 开发调试工具和信息
  - 系统状态监控

- [ ] **错误页面** (/404, /403)
  - 友好的错误提示页面
  - 错误日志收集和上报

### 第五阶段：优化与测试 (2-3周)

#### 2.13 性能优化
- [ ] **代码分割优化**
  - 路由级别懒加载 (Vue Router动态导入)
  - 组件级别懒加载 (defineAsyncComponent)
  - 第三方库按需加载 (Tree-shaking)
  - 使用rollup-plugin-visualizer分析包体积

- [ ] **资源优化**
  - 图片懒加载 (Intersection Observer API)
  - 图片格式优化 (WebP、响应式图片)
  - 使用vite-plugin-compression启用Gzip压缩
  - CDN资源配置和缓存策略

- [ ] **运行时优化**
  - 虚拟滚动 (大量数据列表)
  - 防抖和节流优化
  - 内存泄漏检测和修复
  - WebSocket连接池优化

#### 2.14 测试与验证
- [ ] **单元测试** (Vitest 1.4.0)
  - 组件测试 (@vue/test-utils 2.4.5)
  - 工具函数测试
  - API接口测试
  - 状态管理测试 (Pinia)
  - 目标覆盖率 > 80%

- [ ] **集成测试**
  - WebSocket连接测试
  - 认证流程测试
  - 文件上传测试
  - 数据可视化测试

- [ ] **E2E测试** (Cypress 13.7.1)
  - 用户注册登录流程
  - AI对话功能测试
  - 日记发布流程测试
  - 个人资料编辑测试

- [ ] **兼容性和性能测试**
  - 多浏览器兼容性测试
  - 移动端响应式测试
  - 性能指标监控 (Web Vitals)
  - 错误监控 (Sentry 7.108.0)

#### 2.15 文档和部署
- [ ] **技术文档**
  - API接口文档
  - 组件使用文档
  - 开发规范文档
  - 故障排除文档

- [ ] **部署配置**
  - Docker容器化部署
  - CI/CD流程配置
  - 多环境部署脚本
  - 监控和日志配置

- [ ] **用户文档**
  - 功能使用手册
  - 常见问题解答
  - 更新日志维护

## 3. 详细重构指南

### 3.1 页面重构标准流程

#### 步骤1：分析现有页面
1. **UI分析**：截图记录当前页面布局
2. **功能分析**：梳理所有交互功能
3. **API分析**：确认所有接口调用
4. **样式分析**：提取所有CSS样式
5. **图片资源**：收集所有图片和图标

#### 步骤2：创建新页面结构
```typescript
// pages/chat/index.vue
<template>
  <!-- 保持现有模板结构 -->
</template>

<script setup lang="ts">
// 使用Vue3 Composition API
import { ref, onMounted, onUnmounted } from 'vue'
import { useChat } from '@/composables/useChat'
import { useAuthStore } from '@/stores/auth'
import type { ChatMessage } from '@/types/chat'

// 保持现有功能逻辑
</script>

<style scoped>
/* 保持现有样式 */
</style>
```

### 3.2 样式迁移策略

#### 3.2.1 Tailwind CSS迁移
```css
/* 原有CSS */
.chat-message {
  background: #f0f0f0;
  border-radius: 8px;
  padding: 12px;
  margin: 8px 0;
}

/* 迁移到Tailwind */
<div class="bg-gray-100 rounded-lg p-3 my-2">
```

### 3.3 WebSocket重构

#### 3.3.1 原生WebSocket + STOMP实现
```typescript
// utils/websocket.ts
import { Client } from '@stomp/stompjs'
import { envConfig } from '@/config/env'

export class WebSocketService {
  private client: Client
  private connected = false
  private reconnectAttempts = 0
  private maxReconnectAttempts = 5
  private currentToken = ''
  private tokenExpiredCallback?: () => void

  constructor(onTokenExpired?: () => void) {
    this.tokenExpiredCallback = onTokenExpired
    this.client = new Client({
      // 使用原生WebSocket，支持Token认证
      brokerURL: `${envConfig.wsBaseUrl}/ws`,

      // 心跳检测
      heartbeatIncoming: 4000,
      heartbeatOutgoing: 4000,

      // 重连配置
      reconnectDelay: 5000,

      // 调试模式
      debug: envConfig.debug ? console.log : undefined,

      onConnect: () => {
        this.connected = true
        this.reconnectAttempts = 0
        console.log('WebSocket连接成功')
      },

      onDisconnect: () => {
        this.connected = false
        console.log('WebSocket连接断开')
      },

      onStompError: (frame) => {
        console.error('STOMP错误:', frame)
        this.handleStompError(frame)
      },

      // WebSocket连接前的配置
      beforeConnect: () => {
        if (this.currentToken) {
          this.client.configure({
            connectHeaders: {
              Authorization: `Bearer ${this.currentToken}`,
              'X-Requested-With': 'XMLHttpRequest'
            }
          })
        }
      }
    })
  }

  // 连接WebSocket
  connect(token: string) {
    this.currentToken = token
    this.client.configure({
      connectHeaders: {
        Authorization: `Bearer ${token}`,
        'X-Requested-With': 'XMLHttpRequest'
      }
    })
    this.client.activate()
  }

  // 断开连接
  disconnect() {
    this.client.deactivate()
  }

  // 更新Token（用于Token刷新场景）
  updateToken(newToken: string) {
    this.currentToken = newToken
    if (this.connected) {
      this.disconnect()
      setTimeout(() => {
        this.connect(newToken)
      }, 1000)
    }
  }

  // 订阅消息
  subscribe(destination: string, callback: (message: any) => void) {
    if (!this.connected) {
      console.warn('WebSocket未连接')
      return
    }

    return this.client.subscribe(destination, (message) => {
      try {
        const data = JSON.parse(message.body)
        callback(data)
      } catch (error) {
        console.error('消息解析失败:', error)
      }
    })
  }

  // 发送消息
  send(destination: string, body: any) {
    if (!this.connected) {
      console.warn('WebSocket未连接，消息将被缓存')
      return
    }

    this.client.publish({
      destination,
      body: JSON.stringify(body)
    })
  }

  // 处理STOMP错误
  private handleStompError(frame: any) {
    if (frame.headers && frame.headers.message) {
      const errorMessage = frame.headers.message.toLowerCase()

      if (errorMessage.includes('unauthorized') ||
          errorMessage.includes('invalid token') ||
          errorMessage.includes('token expired')) {

        console.warn('Token认证失败，触发重新登录')
        this.tokenExpiredCallback?.()
        return
      }
    }

    this.handleReconnect()
  }

  // 处理重连
  private handleReconnect() {
    if (this.reconnectAttempts < this.maxReconnectAttempts) {
      this.reconnectAttempts++
      setTimeout(() => {
        console.log(`尝试重连 (${this.reconnectAttempts}/${this.maxReconnectAttempts})`)
        this.client.activate()
      }, 5000 * this.reconnectAttempts)
    }
  }
}
```

#### 3.3.2 聊天组合式API
```typescript
// composables/useChat.ts
import { ref, onMounted, onUnmounted } from 'vue'
import { WebSocketService } from '@/utils/websocket'
import { useAuthStore } from '@/stores/auth'
import type { ChatMessage } from '@/types/chat'

export function useChat() {
  const authStore = useAuthStore()
  const wsService = new WebSocketService(() => {
    // Token过期回调
    authStore.logout()
    router.push('/login')
  })

  const messages = ref<ChatMessage[]>([])
  const isConnected = ref(false)

  // 连接WebSocket
  const connect = () => {
    if (authStore.token) {
      wsService.connect(authStore.token)

      // 订阅个人消息
      wsService.subscribe(`/user/${authStore.user.id}/queue/messages`, (message) => {
        messages.value.push(message)
      })

      // 订阅聊天室消息
      wsService.subscribe('/topic/chat', (message) => {
        messages.value.push(message)
      })

      isConnected.value = true
    }
  }

  // 发送消息
  const sendMessage = (content: string, type: 'text' | 'image' = 'text') => {
    const message = {
      content,
      type,
      timestamp: Date.now(),
      userId: authStore.user.id
    }

    wsService.send('/app/chat.send', message)
  }

  // 组件挂载时连接
  onMounted(() => {
    connect()
  })

  // 组件卸载时断开连接
  onUnmounted(() => {
    wsService.disconnect()
  })

  return {
    messages,
    isConnected,
    sendMessage,
    connect
  }
}
```

## 4. 质量保证措施

### 4.1 功能一致性检查清单

#### 页面功能检查
- [ ] 页面布局完全一致
- [ ] 所有按钮和链接功能正常
- [ ] 表单验证逻辑一致
- [ ] 错误提示信息一致
- [ ] 加载状态显示一致
- [ ] 响应式设计一致

#### 交互功能检查
- [ ] 点击事件响应一致
- [ ] 键盘快捷键一致
- [ ] 滚动行为一致
- [ ] 动画效果一致
- [ ] 拖拽功能一致

### 4.2 视觉一致性检查清单

#### 样式检查
- [ ] 颜色方案完全一致
- [ ] 字体大小和样式一致
- [ ] 间距和布局一致
- [ ] 边框和圆角一致
- [ ] 阴影效果一致

#### 图片和图标检查
- [ ] 所有图片显示正常
- [ ] 图标样式一致
- [ ] 图片尺寸一致
- [ ] 图片加载状态一致

## 5. 测试策略

### 5.1 自动化测试

#### 单元测试
```typescript
// tests/components/ChatMessage.test.ts
import { mount } from '@vue/test-utils'
import { describe, it, expect } from 'vitest'
import ChatMessage from '@/components/ChatMessage.vue'

describe('ChatMessage', () => {
  it('renders message content correctly', () => {
    const message = {
      id: '1',
      content: 'Hello World',
      senderId: 'user1',
      senderType: 'USER' as const,
      timestamp: Date.now()
    }

    const wrapper = mount(ChatMessage, {
      props: { message, isOwn: true }
    })

    expect(wrapper.text()).toContain('Hello World')
  })
})
```

### 5.2 手动测试清单

#### 功能测试
- [ ] 用户注册流程
- [ ] 用户登录流程
- [ ] AI对话功能
- [ ] 日记发布功能
- [ ] 个人资料编辑
- [ ] 设置页面功能

#### 兼容性测试
- [ ] Chrome浏览器
- [ ] Firefox浏览器
- [ ] Safari浏览器
- [ ] Edge浏览器
- [ ] 移动端浏览器

## 6. 成功标准

### 6.1 功能标准
- [ ] 所有现有功能100%保留
- [ ] 所有页面UI完全一致
- [ ] 所有交互流程正常
- [ ] 所有API接口正常工作

### 6.2 性能标准
- [ ] 首屏加载时间 < 2秒
- [ ] 页面切换时间 < 500ms
- [ ] 内存使用增长 < 50MB
- [ ] 构建时间 < 3分钟

### 6.3 质量标准
- [ ] 代码覆盖率 > 80%
- [ ] 无严重bug
- [ ] 通过所有测试用例
- [ ] 符合代码规范

## 7. 总结

本重构计划确保在升级到最新技术栈的同时，完全保持现有的功能、UI和用户体验。通过分阶段的重构策略，可以降低风险并确保每个阶段的质量。重构完成后，项目将具备更好的性能、可维护性和扩展性，为未来的功能开发奠定坚实基础。

### 7.1 关键成功因素
1. **严格的功能一致性检查**
2. **详细的UI对比验证**
3. **完善的测试覆盖**
4. **渐进式的重构策略**
5. **充分的团队协作**

### 7.2 预期收益

#### 技术层面收益
1. **技术栈现代化**：Vue3.4.21 + TypeScript5.4.2 + Vite5.1.6
2. **性能显著提升**：
   - 首屏加载时间减少40% (目标<2秒)
   - 运行时性能提升30% (Vue3 Proxy响应式)
   - 包体积减少25% (Tree-shaking + 代码分割)
   - WebSocket连接更稳定 (原生WebSocket + Token认证)

3. **开发体验提升**：
   - TypeScript类型安全，减少90%的类型错误
   - 自动导入和组件注册，提升开发效率50%
   - 热更新速度提升3倍 (Vite vs Webpack)
   - 更好的调试工具和错误提示

#### 业务层面收益
4. **功能稳定性提升**：
   - WebSocket连接稳定性提升 (自动重连 + Token认证)
   - 错误监控和日志收集 (Sentry集成)
   - 完善的测试覆盖 (单元测试 + E2E测试)

5. **用户体验优化**：
   - 响应式设计优化，移动端体验提升
   - 数据可视化效果增强 (ECharts5.5.0)
   - PWA支持，离线访问能力
   - 国际化支持，多语言适配

6. **维护和扩展性**：
   - 组件化架构，代码复用率提升60%
   - 模块化设计，新功能开发效率提升40%
   - 完善的文档和规范，团队协作效率提升
   - CI/CD自动化，部署效率提升80%

#### 长期价值
7. **技术债务清理**：清理历史技术债务，为未来发展奠定基础
8. **团队技能提升**：掌握现代前端技术栈，提升团队竞争力
9. **可持续发展**：基于最新技术栈，保证3-5年技术先进性