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：创建新页面结构

// 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 */
.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实现

// 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

// 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 自动化测试

单元测试

// 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年技术先进性