增加后台管理模块

2025-10-27 23:57:31 +08:00
parent 3c1ba8e801
commit 0016453f20
420 changed files with 5650 additions and 1449 deletions
@@ -0,0 +1,312 @@
+# 管理后台前端开发指南
+
+## 项目概述
+
+情绪博物馆管理后台是一个基于 Vue 3 + TypeScript + Element Plus 的现代化管理系统，用于管理系统的管理员、用户和数据。
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+cd web-admin
+npm install
+```
+
+### 2. 启动开发服务器
+
+```bash
+npm run dev
+```
+
+访问 http://localhost:5174
+
+### 3. 登录系统
+
+使用默认账号登录：
+- 账号: admin
+- 密码: admin123
+
+## 项目结构
+
+```
+web-admin/
+├── src/
+│   ├── api/                    # API接口定义
+│   │   ├── admin.ts           # 管理员API
+│   │   ├── auth.ts            # 认证API
+│   │   └── user.ts            # 用户API
+│   ├── layouts/               # 布局组件
+│   │   └── Layout.vue         # 主布局
+│   ├── router/                # 路由配置
+│   │   └── index.ts           # 路由定义
+│   ├── stores/                # 状态管理
+│   │   ├── index.ts           # Pinia实例
+│   │   └── admin.ts           # 管理员状态
+│   ├── types/                 # TypeScript类型
+│   │   ├── admin.ts           # 管理员类型
+│   │   ├── common.ts          # 通用类型
+│   │   ├── env.d.ts           # 环境变量类型
+│   │   └── user.ts            # 用户类型
+│   ├── utils/                 # 工具函数
+│   │   ├── request.ts         # Axios封装
+│   │   ├── storage.ts         # 本地存储
+│   │   └── validate.ts        # 表单验证
+│   ├── views/                 # 页面组件
+│   │   ├── admin/             # 管理员管理
+│   │   │   └── AdminList.vue
+│   │   ├── user/              # 用户管理
+│   │   │   └── UserList.vue
+│   │   ├── Dashboard.vue      # 仪表盘
+│   │   ├── Login.vue          # 登录页
+│   │   └── NotFound.vue       # 404页面
+│   ├── App.vue                # 根组件
+│   └── main.ts                # 入口文件
+├── .env.development           # 开发环境配置
+├── .env.production            # 生产环境配置
+├── index.html                 # HTML模板
+├── package.json               # 项目配置
+├── tsconfig.json              # TypeScript配置
+└── vite.config.ts             # Vite配置
+```
+
+## 核心功能
+
+### 1. 登录认证
+
+登录流程：
+1. 用户输入账号密码
+2. 调用登录API
+3. 保存Token到localStorage
+4. 保存管理员信息到Pinia
+5. 跳转到仪表盘
+
+代码示例：
+```typescript
+// stores/admin.ts
+const login = async (loginForm: AdminLoginRequest) => {
+  const res = await loginApi(loginForm)
+  token.value = res.data.accessToken
+  adminInfo.value = res.data.adminInfo
+  localStorage.setItem('adminToken', res.data.accessToken)
+  router.push('/')
+}
+```
+
+### 2. 路由守卫
+
+所有路由都需要登录才能访问（除了登录页）：
+
+```typescript
+// router/index.ts
+router.beforeEach((to, from, next) => {
+  const token = localStorage.getItem('adminToken')
+  
+  if (to.path === '/login') {
+    if (token) {
+      next('/')
+    } else {
+      next()
+    }
+  } else {
+    if (token) {
+      next()
+    } else {
+      next('/login')
+    }
+  }
+})
+```
+
+### 3. API请求拦截
+
+自动添加Token到请求头：
+
+```typescript
+// utils/request.ts
+service.interceptors.request.use((config) => {
+  const token = localStorage.getItem('adminToken')
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`
+  }
+  return config
+})
+```
+
+### 4. 响应拦截
+
+统一处理错误：
+
+```typescript
+service.interceptors.response.use(
+  (response) => {
+    const res = response.data
+    if (res.code !== 200) {
+      ElMessage.error(res.message)
+      if (res.code === 401) {
+        router.push('/login')
+      }
+      return Promise.reject(new Error(res.message))
+    }
+    return res
+  },
+  (error) => {
+    // 错误处理
+  }
+)
+```
+
+## 开发规范
+
+### 1. 命名规范
+
+- 组件名：PascalCase (如 AdminList.vue)
+- 文件名：kebab-case (如 admin-list.ts)
+- 变量名：camelCase (如 adminInfo)
+- 常量名：UPPER_CASE (如 API_BASE_URL)
+
+### 2. 类型定义
+
+所有API接口都应该有类型定义：
+
+```typescript
+// types/admin.ts
+export interface Admin {
+  id: string
+  account: string
+  username: string
+  // ...
+}
+
+export interface AdminPageRequest {
+  current: number
+  size: number
+  // ...
+}
+```
+
+### 3. API调用
+
+使用封装的request工具：
+
+```typescript
+// api/admin.ts
+export function getAdminPage(params: AdminPageRequest) {
+  return request<ApiResponse<PageResult<Admin>>>({
+    url: '/admin/page',
+    method: 'get',
+    params
+  })
+}
+```
+
+### 4. 状态管理
+
+使用Pinia进行状态管理：
+
+```typescript
+// stores/admin.ts
+export const useAdminStore = defineStore('admin', () => {
+  const token = ref<string>('')
+  const adminInfo = ref<Admin | null>(null)
+  
+  const login = async (loginForm: AdminLoginRequest) => {
+    // ...
+  }
+  
+  return { token, adminInfo, login }
+})
+```
+
+## 常见问题
+
+### 1. Token过期处理
+
+Token过期时会自动跳转到登录页，用户需要重新登录。
+
+### 2. 跨域问题
+
+开发环境通过Vite代理解决：
+
+```typescript
+// vite.config.ts
+server: {
+  proxy: {
+    '/api': {
+      target: 'http://localhost:8080',
+      changeOrigin: true
+    }
+  }
+}
+```
+
+### 3. 构建优化
+
+生产环境构建时会自动进行代码分割和压缩：
+
+```bash
+npm run build
+```
+
+## 部署
+
+### 1. 构建
+
+```bash
+npm run build
+```
+
+### 2. Nginx配置
+
+```nginx
+server {
+    listen 80;
+    server_name admin.emotion-museum.com;
+    
+    root /var/www/web-admin/dist;
+    index index.html;
+    
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+    
+    location /api {
+        proxy_pass http://localhost:8080;
+    }
+}
+```
+
+### 3. 环境变量
+
+生产环境需要配置正确的API地址：
+
+```
+VITE_APP_BASE_API=https://api.emotion-museum.com
+```
+
+## 扩展功能
+
+### 添加新页面
+
+1. 在 `views` 目录创建新组件
+2. 在 `router/index.ts` 添加路由
+3. 在布局组件的菜单中添加入口
+
+### 添加新API
+
+1. 在 `types` 目录定义类型
+2. 在 `api` 目录创建API函数
+3. 在组件中调用API
+
+### 添加新状态
+
+1. 在 `stores` 目录创建新的store
+2. 在组件中使用store
+
+## 技术支持
+
+如有问题，请查看：
+- [Vue 3 文档](https://cn.vuejs.org/)
+- [Element Plus 文档](https://element-plus.org/)
+- [TypeScript 文档](https://www.typescriptlang.org/)
+- [Vite 文档](https://cn.vitejs.dev/)