649 lines
16 KiB
Markdown
649 lines
16 KiB
Markdown
# web-app Vue 3 重构方案
|
||
|
||
## 📋 方案概述
|
||
|
||
将 web-app 从传统的 jQuery 项目重构为 Vue 3 现代化单页应用（SPA）。
|
||
|
||
## 🎯 重构目标
|
||
|
||
### 技术目标
|
||
- ✅ 使用 Vue 3 + Vite + TypeScript
|
||
- ✅ 组件化、模块化开发
|
||
- ✅ 统一前后端技术栈（与管理后台一致）
|
||
- ✅ 优化性能和用户体验
|
||
- ✅ 便于维护和扩展
|
||
|
||
### 业务目标
|
||
- ✅ 保留所有原有功能
|
||
- ✅ 改善 UI/UX 设计
|
||
- ✅ 适配移动端
|
||
- ✅ 支持主题切换
|
||
- ✅ 国际化支持
|
||
|
||
## 🏗️ 技术栈选择
|
||
|
||
### 核心技术
|
||
```json
|
||
{
|
||
"框架": "Vue 3 (Composition API)",
|
||
"构建工具": "Vite 5",
|
||
"语言": "TypeScript",
|
||
"状态管理": "Pinia",
|
||
"路由": "Vue Router 4",
|
||
"HTTP": "Axios",
|
||
"WebSocket": "原生 WebSocket / Socket.io-client"
|
||
}
|
||
```
|
||
|
||
### UI 框架选择
|
||
|
||
#### 方案一：Element Plus（推荐）
|
||
```bash
|
||
# 优点
|
||
✅ 与管理后台统一（web/ 使用的就是 Element Plus）
|
||
✅ 组件丰富，开箱即用
|
||
✅ 中文文档完善
|
||
✅ 支持深色主题
|
||
✅ TypeScript 支持好
|
||
|
||
# 缺点
|
||
⚠️ 组件较重（如果只需要简单 UI，可能过度设计）
|
||
```
|
||
|
||
#### 方案二：Naive UI
|
||
```bash
|
||
# 优点
|
||
✅ 轻量级，性能好
|
||
✅ TypeScript 原生支持
|
||
✅ 组件设计现代
|
||
✅ 支持深色主题
|
||
|
||
# 缺点
|
||
⚠️ 与管理后台不统一
|
||
```
|
||
|
||
#### 方案三：自定义 UI（参考 auth.html）
|
||
```bash
|
||
# 优点
|
||
✅ 完全自定义，独特设计
|
||
✅ 轻量级
|
||
✅ 可以复用已有的 auth.css 样式
|
||
|
||
# 缺点
|
||
⚠️ 需要自己实现所有组件
|
||
⚠️ 开发时间较长
|
||
```
|
||
|
||
**推荐：Element Plus + 自定义样式**
|
||
- 使用 Element Plus 的基础组件（表单、按钮、对话框等）
|
||
- 自定义主题和关键页面样式
|
||
- 兼顾开发效率和设计独特性
|
||
|
||
## 📂 项目结构
|
||
|
||
### 新项目结构（推荐）
|
||
|
||
```
|
||
web-app-vue/ # 新建的 Vue 项目
|
||
├── public/
|
||
│ ├── favicon.ico
|
||
│ └── img/ # 静态图片资源
|
||
├── src/
|
||
│ ├── api/ # API 接口
|
||
│ │ ├── auth.ts # 认证接口
|
||
│ │ ├── character.ts # 角色接口
|
||
│ │ ├── chat.ts # 对话接口
|
||
│ │ └── index.ts # axios 配置
|
||
│ ├── assets/ # 资源文件
|
||
│ │ ├── styles/ # 全局样式
|
||
│ │ │ ├── index.scss
|
||
│ │ │ ├── variables.scss
|
||
│ │ │ └── dark-theme.scss
|
||
│ │ └── images/
|
||
│ ├── components/ # 通用组件
|
||
│ │ ├── common/ # 基础组件
|
||
│ │ │ ├── AppHeader.vue
|
||
│ │ │ ├── AppSidebar.vue
|
||
│ │ │ └── Loading.vue
|
||
│ │ ├── chat/ # 对话组件
|
||
│ │ │ ├── ChatMessage.vue
|
||
│ │ │ ├── ChatInput.vue
|
||
│ │ │ ├── MessageSwipe.vue
|
||
│ │ │ └── VoiceInput.vue
|
||
│ │ ├── character/ # 角色组件
|
||
│ │ │ ├── CharacterCard.vue
|
||
│ │ │ ├── CharacterList.vue
|
||
│ │ │ ├── CharacterEditor.vue
|
||
│ │ │ └── CharacterImport.vue
|
||
│ │ └── settings/ # 设置组件
|
||
│ │ ├── AIConfig.vue
|
||
│ │ ├── ThemeConfig.vue
|
||
│ │ └── UserProfile.vue
|
||
│ ├── composables/ # 组合式函数
|
||
│ │ ├── useAuth.ts # 认证相关
|
||
│ │ ├── useChat.ts # 对话相关
|
||
│ │ ├── useCharacter.ts # 角色相关
|
||
│ │ └── useWebSocket.ts # WebSocket
|
||
│ ├── layouts/ # 布局组件
|
||
│ │ ├── DefaultLayout.vue # 默认布局
|
||
│ │ ├── AuthLayout.vue # 认证页布局
|
||
│ │ └── ChatLayout.vue # 对话页布局
|
||
│ ├── router/ # 路由配置
|
||
│ │ ├── index.ts
|
||
│ │ └── guards.ts # 路由守卫
|
||
│ ├── stores/ # Pinia 状态管理
|
||
│ │ ├── auth.ts # 用户认证
|
||
│ │ ├── chat.ts # 对话状态
|
||
│ │ ├── character.ts # 角色管理
|
||
│ │ ├── settings.ts # 设置
|
||
│ │ └── index.ts
|
||
│ ├── types/ # TypeScript 类型
|
||
│ │ ├── api.d.ts
|
||
│ │ ├── character.d.ts
|
||
│ │ ├── chat.d.ts
|
||
│ │ └── user.d.ts
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── request.ts # HTTP 请求封装
|
||
│ │ ├── storage.ts # 本地存储
|
||
│ │ ├── websocket.ts # WebSocket 封装
|
||
│ │ ├── format.ts # 格式化
|
||
│ │ └── validate.ts # 验证
|
||
│ ├── views/ # 页面视图
|
||
│ │ ├── auth/ # 认证页
|
||
│ │ │ ├── Login.vue
|
||
│ │ │ └── Register.vue
|
||
│ │ ├── home/ # 主页
|
||
│ │ │ └── Index.vue
|
||
│ │ ├── character/ # 角色页
|
||
│ │ │ ├── List.vue
|
||
│ │ │ ├── Detail.vue
|
||
│ │ │ └── Create.vue
|
||
│ │ ├── chat/ # 对话页
|
||
│ │ │ └── Index.vue
|
||
│ │ ├── settings/ # 设置页
|
||
│ │ │ └── Index.vue
|
||
│ │ └── user/ # 用户中心
|
||
│ │ └── Profile.vue
|
||
│ ├── App.vue # 根组件
|
||
│ └── main.ts # 入口文件
|
||
├── .env.development # 开发环境配置
|
||
├── .env.production # 生产环境配置
|
||
├── index.html
|
||
├── package.json
|
||
├── tsconfig.json
|
||
├── vite.config.ts
|
||
└── README.md
|
||
```
|
||
|
||
### 与现有项目的关系
|
||
|
||
```
|
||
st/
|
||
├── server/ # Go 后端（不变）
|
||
├── web/ # Vue 管理后台（不变）
|
||
├── web-app/ # 旧项目（保留备份）
|
||
└── web-app-vue/ # 新的 Vue 前台（新建）
|
||
└── ...
|
||
```
|
||
|
||
## 🚀 实施步骤
|
||
|
||
### 阶段一：项目初始化（1-2 天）
|
||
|
||
#### 1.1 创建 Vue 项目
|
||
```bash
|
||
# 使用 Vite 创建项目
|
||
npm create vite@latest web-app-vue -- --template vue-ts
|
||
|
||
cd web-app-vue
|
||
npm install
|
||
```
|
||
|
||
#### 1.2 安装依赖
|
||
```bash
|
||
# UI 框架
|
||
npm install element-plus
|
||
|
||
# 路由和状态管理
|
||
npm install vue-router@4 pinia
|
||
|
||
# HTTP 和工具
|
||
npm install axios
|
||
npm install @vueuse/core # Vue 常用组合式函数
|
||
|
||
# 开发依赖
|
||
npm install -D sass
|
||
npm install -D unplugin-vue-components unplugin-auto-import
|
||
```
|
||
|
||
#### 1.3 配置 Vite
|
||
```typescript
|
||
// vite.config.ts
|
||
import { defineConfig } from 'vite'
|
||
import vue from '@vitejs/plugin-vue'
|
||
import AutoImport from 'unplugin-auto-import/vite'
|
||
import Components from 'unplugin-vue-components/vite'
|
||
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
|
||
|
||
export default defineConfig({
|
||
plugins: [
|
||
vue(),
|
||
AutoImport({
|
||
resolvers: [ElementPlusResolver()],
|
||
imports: ['vue', 'vue-router', 'pinia'],
|
||
}),
|
||
Components({
|
||
resolvers: [ElementPlusResolver()],
|
||
}),
|
||
],
|
||
server: {
|
||
port: 3000,
|
||
proxy: {
|
||
'/app': {
|
||
target: 'http://localhost:8888',
|
||
changeOrigin: true,
|
||
},
|
||
},
|
||
},
|
||
})
|
||
```
|
||
|
||
#### 1.4 基础配置
|
||
```typescript
|
||
// src/main.ts
|
||
import { createApp } from 'vue'
|
||
import { createPinia } from 'pinia'
|
||
import ElementPlus from 'element-plus'
|
||
import 'element-plus/dist/index.css'
|
||
import router from './router'
|
||
import App from './App.vue'
|
||
import './assets/styles/index.scss'
|
||
|
||
const app = createApp(App)
|
||
const pinia = createPinia()
|
||
|
||
app.use(pinia)
|
||
app.use(router)
|
||
app.use(ElementPlus)
|
||
app.mount('#app')
|
||
```
|
||
|
||
### 阶段二：核心功能开发（5-7 天）
|
||
|
||
#### 2.1 认证模块（1 天）
|
||
- [x] 登录页面
|
||
- [x] 注册页面
|
||
- [x] Token 管理
|
||
- [x] 路由守卫
|
||
|
||
#### 2.2 角色管理（2 天）
|
||
- [ ] 角色列表
|
||
- [ ] 角色详情
|
||
- [ ] 角色创建/编辑
|
||
- [ ] 角色导入/导出
|
||
- [ ] 收藏功能
|
||
|
||
#### 2.3 对话功能（3 天）
|
||
- [ ] 对话界面
|
||
- [ ] 消息发送
|
||
- [ ] 消息渲染
|
||
- [ ] Swipe 功能
|
||
- [ ] WebSocket 实时通信
|
||
- [ ] 流式输出
|
||
|
||
#### 2.4 设置页面（1 天）
|
||
- [ ] AI 配置
|
||
- [ ] 主题设置
|
||
- [ ] 用户偏好
|
||
|
||
### 阶段三：高级功能（3-5 天）
|
||
|
||
#### 3.1 AI 功能
|
||
- [ ] 多模型支持
|
||
- [ ] Prompt 管理
|
||
- [ ] World Info
|
||
- [ ] 向量记忆
|
||
|
||
#### 3.2 UI/UX 优化
|
||
- [ ] 响应式布局
|
||
- [ ] 移动端适配
|
||
- [ ] 主题切换
|
||
- [ ] 动画效果
|
||
|
||
#### 3.3 文件管理
|
||
- [ ] 头像上传
|
||
- [ ] 文件管理
|
||
- [ ] 图片预览
|
||
|
||
### 阶段四：测试和优化（2-3 天）
|
||
|
||
- [ ] 单元测试
|
||
- [ ] E2E 测试
|
||
- [ ] 性能优化
|
||
- [ ] 打包优化
|
||
- [ ] 部署配置
|
||
|
||
## 📦 关键组件示例
|
||
|
||
### 1. 认证 Store
|
||
|
||
```typescript
|
||
// src/stores/auth.ts
|
||
import { defineStore } from 'pinia'
|
||
import { ref, computed } from 'vue'
|
||
import { login, register, getUserInfo } from '@/api/auth'
|
||
import type { LoginRequest, User } from '@/types/user'
|
||
|
||
export const useAuthStore = defineStore('auth', () => {
|
||
const token = ref<string>(localStorage.getItem('st_access_token') || '')
|
||
const user = ref<User | null>(null)
|
||
|
||
const isLoggedIn = computed(() => !!token.value)
|
||
|
||
async function handleLogin(data: LoginRequest) {
|
||
const res = await login(data)
|
||
token.value = res.data.token
|
||
user.value = res.data.user
|
||
localStorage.setItem('st_access_token', res.data.token)
|
||
localStorage.setItem('st_user_info', JSON.stringify(res.data.user))
|
||
}
|
||
|
||
async function handleLogout() {
|
||
token.value = ''
|
||
user.value = null
|
||
localStorage.removeItem('st_access_token')
|
||
localStorage.removeItem('st_user_info')
|
||
}
|
||
|
||
async function fetchUserInfo() {
|
||
const res = await getUserInfo()
|
||
user.value = res.data
|
||
}
|
||
|
||
return {
|
||
token,
|
||
user,
|
||
isLoggedIn,
|
||
handleLogin,
|
||
handleLogout,
|
||
fetchUserInfo,
|
||
}
|
||
})
|
||
```
|
||
|
||
### 2. HTTP 请求封装
|
||
|
||
```typescript
|
||
// src/utils/request.ts
|
||
import axios from 'axios'
|
||
import { ElMessage } from 'element-plus'
|
||
import { useAuthStore } from '@/stores/auth'
|
||
|
||
const request = axios.create({
|
||
baseURL: import.meta.env.VITE_API_BASE_URL || 'http://localhost:8888',
|
||
timeout: 10000,
|
||
})
|
||
|
||
// 请求拦截器
|
||
request.interceptors.request.use(
|
||
(config) => {
|
||
const authStore = useAuthStore()
|
||
if (authStore.token) {
|
||
config.headers['x-token'] = authStore.token
|
||
}
|
||
return config
|
||
},
|
||
(error) => {
|
||
return Promise.reject(error)
|
||
}
|
||
)
|
||
|
||
// 响应拦截器
|
||
request.interceptors.response.use(
|
||
(response) => {
|
||
const res = response.data
|
||
if (res.code !== 0) {
|
||
ElMessage.error(res.msg || '请求失败')
|
||
return Promise.reject(new Error(res.msg || '请求失败'))
|
||
}
|
||
return res
|
||
},
|
||
(error) => {
|
||
ElMessage.error(error.message || '网络错误')
|
||
return Promise.reject(error)
|
||
}
|
||
)
|
||
|
||
export default request
|
||
```
|
||
|
||
### 3. 角色卡片组件
|
||
|
||
```vue
|
||
<!-- src/components/character/CharacterCard.vue -->
|
||
<template>
|
||
<div class="character-card" @click="handleClick">
|
||
<div class="card-header">
|
||
<img :src="character.avatar" :alt="character.name" class="avatar" />
|
||
<el-icon v-if="isFavorite" class="favorite-icon">
|
||
<Star />
|
||
</el-icon>
|
||
</div>
|
||
<div class="card-body">
|
||
<h3 class="character-name">{{ character.name }}</h3>
|
||
<p class="character-description">{{ character.description }}</p>
|
||
</div>
|
||
<div class="card-footer">
|
||
<el-tag v-for="tag in character.tags" :key="tag" size="small">
|
||
{{ tag }}
|
||
</el-tag>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { computed } from 'vue'
|
||
import type { Character } from '@/types/character'
|
||
|
||
interface Props {
|
||
character: Character
|
||
}
|
||
|
||
const props = defineProps<Props>()
|
||
const emit = defineEmits<{
|
||
click: [character: Character]
|
||
}>()
|
||
|
||
const isFavorite = computed(() => props.character.isFavorite)
|
||
|
||
function handleClick() {
|
||
emit('click', props.character)
|
||
}
|
||
</script>
|
||
|
||
<style scoped lang="scss">
|
||
.character-card {
|
||
border-radius: 12px;
|
||
overflow: hidden;
|
||
cursor: pointer;
|
||
transition: all 0.3s;
|
||
background: var(--el-bg-color);
|
||
|
||
&:hover {
|
||
transform: translateY(-4px);
|
||
box-shadow: 0 8px 16px rgba(0, 0, 0, 0.1);
|
||
}
|
||
|
||
.card-header {
|
||
position: relative;
|
||
|
||
.avatar {
|
||
width: 100%;
|
||
height: 200px;
|
||
object-fit: cover;
|
||
}
|
||
|
||
.favorite-icon {
|
||
position: absolute;
|
||
top: 12px;
|
||
right: 12px;
|
||
color: #f59e0b;
|
||
font-size: 24px;
|
||
}
|
||
}
|
||
|
||
.card-body {
|
||
padding: 16px;
|
||
|
||
.character-name {
|
||
font-size: 18px;
|
||
font-weight: bold;
|
||
margin-bottom: 8px;
|
||
}
|
||
|
||
.character-description {
|
||
color: var(--el-text-color-secondary);
|
||
font-size: 14px;
|
||
line-height: 1.6;
|
||
display: -webkit-box;
|
||
-webkit-line-clamp: 2;
|
||
-webkit-box-orient: vertical;
|
||
overflow: hidden;
|
||
}
|
||
}
|
||
|
||
.card-footer {
|
||
padding: 0 16px 16px;
|
||
display: flex;
|
||
gap: 8px;
|
||
flex-wrap: wrap;
|
||
}
|
||
}
|
||
</style>
|
||
```
|
||
|
||
## 🔄 迁移策略
|
||
|
||
### 渐进式迁移（推荐）
|
||
|
||
1. **Phase 1: 新功能使用 Vue**
|
||
- 保留旧 web-app，用于稳定运行
|
||
- 新功能在 web-app-vue 开发
|
||
- 通过路由切换新旧页面
|
||
|
||
2. **Phase 2: 逐步迁移**
|
||
- 按模块迁移（认证 → 角色 → 对话 → 设置）
|
||
- 每个模块迁移后充分测试
|
||
- 确保功能完整
|
||
|
||
3. **Phase 3: 完全替换**
|
||
- 所有功能迁移完成
|
||
- 彻底删除旧代码
|
||
- web-app-vue 改名为 web-app
|
||
|
||
### 一次性重写（不推荐，风险高）
|
||
|
||
除非你有充足的时间和人力，否则不建议一次性重写整个项目。
|
||
|
||
## 📊 与现有项目的集成
|
||
|
||
### Go 后端配置
|
||
|
||
```go
|
||
// server/initialize/router.go
|
||
|
||
// 前台 Vue 应用静态文件
|
||
webAppVuePath := "../web-app-vue/dist"
|
||
if _, err := os.Stat(webAppVuePath); err == nil {
|
||
Router.Static("/assets", webAppVuePath+"/assets")
|
||
Router.StaticFile("/", webAppVuePath+"/index.html")
|
||
global.GVA_LOG.Info("前台 Vue 应用已启动: " + webAppVuePath)
|
||
}
|
||
```
|
||
|
||
### 环境配置
|
||
|
||
```bash
|
||
# .env.development
|
||
VITE_API_BASE_URL=http://localhost:8888
|
||
VITE_WS_URL=ws://localhost:8888
|
||
|
||
# .env.production
|
||
VITE_API_BASE_URL=https://your-domain.com
|
||
VITE_WS_URL=wss://your-domain.com
|
||
```
|
||
|
||
## 🎯 开发优先级
|
||
|
||
### P0（必须）
|
||
1. ✅ 用户认证（登录/注册）
|
||
2. ✅ 角色列表和详情
|
||
3. ✅ 基本对话功能
|
||
4. ✅ AI 配置
|
||
|
||
### P1（重要）
|
||
5. ⚪ 角色编辑和创建
|
||
6. ⚪ 消息 Swipe
|
||
7. ⚪ 文件上传
|
||
8. ⚪ 设置页面
|
||
|
||
### P2（可选）
|
||
9. ⚪ World Info
|
||
10. ⚪ 向量记忆
|
||
11. ⚪ 高级 AI 功能
|
||
12. ⚪ 主题切换
|
||
|
||
## 📝 注意事项
|
||
|
||
### 1. 保持功能一致性
|
||
- 确保所有原有功能都能在 Vue 版本中实现
|
||
- 参考旧版的交互逻辑
|
||
- 不要遗漏边界情况
|
||
|
||
### 2. 性能优化
|
||
- 使用虚拟滚动（角色列表、消息列表）
|
||
- 图片懒加载
|
||
- 路由懒加载
|
||
- 打包分析和优化
|
||
|
||
### 3. 移动端适配
|
||
- 响应式设计
|
||
- 触摸手势支持
|
||
- 移动端专用布局
|
||
|
||
### 4. 国际化
|
||
- 使用 vue-i18n
|
||
- 支持多语言切换
|
||
- 本地化日期和数字
|
||
|
||
## 📚 学习资源
|
||
|
||
- Vue 3 官方文档: https://cn.vuejs.org/
|
||
- Vite 文档: https://cn.vitejs.dev/
|
||
- Element Plus: https://element-plus.org/zh-CN/
|
||
- Pinia 文档: https://pinia.vuejs.org/zh/
|
||
- TypeScript 文档: https://www.typescriptlang.org/zh/
|
||
|
||
## 🎉 总结
|
||
|
||
### 为什么要重构？
|
||
|
||
1. ✅ **代码质量**：从混乱的 jQuery 代码到清晰的组件化代码
|
||
2. ✅ **开发效率**：热更新、TypeScript、自动导入
|
||
3. ✅ **性能提升**：Vite 构建、按需加载、虚拟滚动
|
||
4. ✅ **易于维护**：模块化、类型安全、单一职责
|
||
5. ✅ **技术统一**：与管理后台使用相同技术栈
|
||
6. ✅ **未来发展**：易于扩展新功能
|
||
|
||
### 建议的时间线
|
||
|
||
- **快速原型**（1 周）：核心功能，可以开始使用
|
||
- **MVP 版本**（2-3 周）：主要功能完成
|
||
- **完整版本**（4-6 周）：所有功能迁移完成
|
||
- **优化打磨**（持续）：性能优化、bug 修复
|
||
|
||
---
|
||
|
||
**更新日期**: 2026-02-10
|
||
**版本**: v1.0.0
|