459 lines
12 KiB
Markdown
459 lines
12 KiB
Markdown
# HA-OVP 前端项目文档
|
||
|
||
## 项目概述
|
||
|
||
HA-OVP（高可用在线视频平台）前端系统包含两个独立的 Vue 3 项目：
|
||
|
||
- **video-platform-web**: 用户端前台，面向普通用户
|
||
- **video-platform-admin**: 管理端后台，面向管理员
|
||
|
||
## 技术栈
|
||
|
||
### 共同技术
|
||
|
||
| 类别 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| 框架 | Vue 3 | ^3.4 |
|
||
| 语言 | TypeScript | ^5.0 |
|
||
| 构建工具 | Vite | ^5.0 |
|
||
| 状态管理 | Pinia | ^2.1 |
|
||
| 路由 | Vue Router | ^4.2 |
|
||
| HTTP客户端 | Axios | ^1.6 |
|
||
| 样式 | SCSS | - |
|
||
| 日期处理 | Day.js | ^1.11 |
|
||
| 进度条 | NProgress | ^0.2 |
|
||
|
||
### 用户端前台 (video-platform-web)
|
||
|
||
| 类别 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| UI组件库 | Vant 4 | ^4.8 |
|
||
| 视频播放器 | DPlayer | - |
|
||
|
||
### 管理端后台 (video-platform-admin)
|
||
|
||
| 类别 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| UI组件库 | Element Plus | ^2.5 |
|
||
| 图标 | @element-plus/icons-vue | ^2.3 |
|
||
| 图表 | ECharts | ^5.5 |
|
||
|
||
## 目录结构
|
||
|
||
### 用户端前台
|
||
|
||
```
|
||
video-platform-web/
|
||
├── public/ # 静态资源
|
||
├── src/
|
||
│ ├── api/ # API 接口封装
|
||
│ │ ├── auth.ts # 认证相关
|
||
│ │ ├── user.ts # 用户相关
|
||
│ │ ├── video.ts # 视频相关
|
||
│ │ ├── comment.ts # 评论相关
|
||
│ │ ├── category.ts # 分类相关
|
||
│ │ ├── danmaku.ts # 弹幕相关
|
||
│ │ ├── favorite.ts # 收藏相关
|
||
│ │ ├── recommend.ts # 推荐相关
|
||
│ │ └── index.ts # 导出
|
||
│ ├── assets/ # 资源文件
|
||
│ ├── components/ # 公共组件
|
||
│ │ ├── layout/ # 布局组件
|
||
│ │ ├── video/ # 视频组件
|
||
│ │ ├── comment/ # 评论组件
|
||
│ │ └── danmaku/ # 弹幕组件
|
||
│ ├── composables/ # 组合式函数
|
||
│ ├── directives/ # 自定义指令
|
||
│ ├── router/ # 路由配置
|
||
│ ├── stores/ # Pinia 状态管理
|
||
│ │ ├── user.ts # 用户状态
|
||
│ │ ├── video.ts # 视频状态
|
||
│ │ ├── favorite.ts # 收藏状态
|
||
│ │ ├── message.ts # 消息状态
|
||
│ │ ├── app.ts # 应用状态
|
||
│ │ └── index.ts # 导出
|
||
│ ├── styles/ # 全局样式
|
||
│ ├── types/ # TypeScript 类型定义
|
||
│ ├── utils/ # 工具函数
|
||
│ ├── views/ # 页面组件
|
||
│ │ ├── home/ # 首页
|
||
│ │ ├── login/ # 登录注册
|
||
│ │ ├── video/ # 视频相关
|
||
│ │ ├── user/ # 用户相关
|
||
│ │ ├── upload/ # 上传
|
||
│ │ ├── message/ # 消息
|
||
│ │ ├── favorite/ # 收藏
|
||
│ │ ├── search/ # 搜索
|
||
│ │ ├── layout/ # 布局
|
||
│ │ └── error/ # 错误页
|
||
│ ├── App.vue # 根组件
|
||
│ └── main.ts # 入口文件
|
||
├── package.json
|
||
├── vite.config.ts
|
||
└── tsconfig.json
|
||
```
|
||
|
||
### 管理端后台
|
||
|
||
```
|
||
video-platform-admin/
|
||
├── public/ # 静态资源
|
||
├── src/
|
||
│ ├── api/ # API 接口封装
|
||
│ │ ├── auth.ts # 管理员认证
|
||
│ │ ├── user.ts # 用户管理
|
||
│ │ ├── video.ts # 视频管理
|
||
│ │ ├── category.ts # 分类管理
|
||
│ │ ├── comment.ts # 评论管理
|
||
│ │ ├── admin.ts # 管理员管理
|
||
│ │ ├── statistics.ts # 统计数据
|
||
│ │ └── index.ts # 导出
|
||
│ ├── assets/ # 资源文件
|
||
│ ├── components/ # 公共组件
|
||
│ │ ├── Breadcrumb.vue # 面包屑
|
||
│ │ └── TagsView.vue # 标签页导航
|
||
│ ├── composables/ # 组合式函数
|
||
│ ├── directives/ # 自定义指令
|
||
│ ├── router/ # 路由配置
|
||
│ ├── stores/ # Pinia 状态管理
|
||
│ │ ├── user.ts # 管理员状态
|
||
│ │ ├── app.ts # 应用状态
|
||
│ │ ├── tagsView.ts # 标签页状态
|
||
│ │ └── index.ts # 导出
|
||
│ ├── styles/ # 全局样式
|
||
│ │ ├── index.scss # 主样式
|
||
│ │ └── variables.scss # 变量定义
|
||
│ ├── types/ # TypeScript 类型定义
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── request.ts # HTTP 请求封装
|
||
│ │ └── format.ts # 格式化工具
|
||
│ ├── views/ # 页面组件
|
||
│ │ ├── dashboard/ # 仪表盘
|
||
│ │ ├── login/ # 登录
|
||
│ │ ├── user/ # 用户管理
|
||
│ │ ├── video/ # 视频管理
|
||
│ │ ├── content/ # 内容管理
|
||
│ │ ├── system/ # 系统管理
|
||
│ │ ├── layout/ # 布局
|
||
│ │ └── error/ # 错误页
|
||
│ ├── App.vue # 根组件
|
||
│ └── main.ts # 入口文件
|
||
├── package.json
|
||
├── vite.config.ts
|
||
└── tsconfig.json
|
||
```
|
||
|
||
## 功能模块
|
||
|
||
### 用户端前台功能
|
||
|
||
#### 认证模块
|
||
- 用户名/邮箱/手机号登录
|
||
- 用户注册
|
||
- 验证码验证
|
||
- JWT Token 自动刷新
|
||
- 登出功能
|
||
|
||
#### 首页模块
|
||
- 视频推荐流
|
||
- 热门视频榜单
|
||
- 分类导航
|
||
- 搜索功能
|
||
|
||
#### 视频模块
|
||
- 视频播放（支持倍速、全屏、画中画）
|
||
- 弹幕系统（发送、显示、样式设置）
|
||
- 视频点赞/投币/收藏/分享
|
||
- 相关视频推荐
|
||
- 视频上传（拖拽上传、进度显示）
|
||
- 我的视频管理
|
||
|
||
#### 评论模块
|
||
- 评论列表（分页、排序）
|
||
- 发表评论
|
||
- 回复评论
|
||
- 评论点赞
|
||
|
||
#### 用户模块
|
||
- 个人中心
|
||
- 个人主页
|
||
- 编辑资料
|
||
- 账号设置
|
||
|
||
#### 社交模块
|
||
- 关注用户
|
||
- 粉丝/关注列表
|
||
- 私信功能
|
||
- 消息通知
|
||
|
||
### 管理端后台功能
|
||
|
||
#### 认证模块
|
||
- 管理员登录
|
||
- 验证码验证
|
||
- 登出功能
|
||
|
||
#### 仪表盘
|
||
- 平台数据概览
|
||
- 数据趋势图表
|
||
- 待审核内容提醒
|
||
|
||
#### 用户管理
|
||
- 用户列表（分页、搜索、筛选）
|
||
- 用户详情
|
||
- 禁用/启用用户
|
||
- 重置密码
|
||
|
||
#### 视频管理
|
||
- 视频列表
|
||
- 视频审核
|
||
- 视频下架
|
||
|
||
#### 内容管理
|
||
- 分类管理
|
||
- 标签管理
|
||
- 评论管理
|
||
|
||
#### 系统管理
|
||
- 管理员管理
|
||
|
||
## API 接口
|
||
|
||
### 请求配置
|
||
|
||
所有 API 请求通过统一的 `request` 工具进行封装：
|
||
|
||
```typescript
|
||
// 基础配置
|
||
baseURL: '/api' // 用户端
|
||
baseURL: '/api/admin' // 管理端
|
||
timeout: 30000
|
||
|
||
// 请求拦截器
|
||
- 自动添加 Authorization Header
|
||
- 显示加载进度
|
||
|
||
// 响应拦截器
|
||
- 统一错误处理
|
||
- Token 过期自动跳转登录
|
||
```
|
||
|
||
### 用户端主要接口
|
||
|
||
| 模块 | 接口 | 说明 |
|
||
|------|------|------|
|
||
| 认证 | POST /auth/login | 登录 |
|
||
| 认证 | POST /auth/register | 注册 |
|
||
| 认证 | GET /auth/captcha | 获取验证码 |
|
||
| 用户 | GET /user/profile/current | 获取当前用户资料 |
|
||
| 用户 | PUT /user/profile | 更新用户资料 |
|
||
| 用户 | POST /user/follow/{id} | 关注用户 |
|
||
| 视频 | GET /content/video/public/list | 获取视频列表 |
|
||
| 视频 | GET /content/video/public/{id} | 获取视频详情 |
|
||
| 视频 | POST /content/video/upload | 上传视频 |
|
||
| 评论 | GET /comment/public/list | 获取评论列表 |
|
||
| 评论 | POST /comment | 发表评论 |
|
||
| 弹幕 | GET /content/danmaku/all/{videoId} | 获取弹幕 |
|
||
| 弹幕 | POST /content/danmaku | 发送弹幕 |
|
||
| 推荐 | GET /recommend/home | 首页推荐 |
|
||
|
||
### 管理端主要接口
|
||
|
||
| 模块 | 接口 | 说明 |
|
||
|------|------|------|
|
||
| 认证 | POST /admin/auth/login | 管理员登录 |
|
||
| 用户 | GET /admin/platform/user/list | 用户列表 |
|
||
| 用户 | PUT /admin/platform/user/{id}/status/{status} | 更新用户状态 |
|
||
| 视频 | GET /admin/platform/content/video/list | 视频列表 |
|
||
| 视频 | POST /admin/platform/content/video/review/{id} | 审核视频 |
|
||
| 分类 | GET /admin/platform/content/category/list | 分类列表 |
|
||
| 评论 | GET /comment/admin/list | 评论列表 |
|
||
| 统计 | GET /statistics/dashboard | 仪表盘数据 |
|
||
|
||
## 开发指南
|
||
|
||
### 环境要求
|
||
|
||
- Node.js >= 18.0
|
||
- pnpm >= 8.0 (推荐) 或 npm >= 9.0
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
# 用户端
|
||
cd video-platform-web
|
||
pnpm install
|
||
|
||
# 管理端
|
||
cd video-platform-admin
|
||
pnpm install
|
||
```
|
||
|
||
### 开发运行
|
||
|
||
```bash
|
||
# 用户端 (端口 3000)
|
||
cd video-platform-web
|
||
pnpm dev
|
||
|
||
# 管理端 (端口 3100)
|
||
cd video-platform-admin
|
||
pnpm dev
|
||
```
|
||
|
||
### 构建部署
|
||
|
||
```bash
|
||
# 构建
|
||
pnpm build
|
||
|
||
# 预览
|
||
pnpm preview
|
||
```
|
||
|
||
### 代理配置
|
||
|
||
在 `vite.config.ts` 中配置后端代理：
|
||
|
||
```typescript
|
||
server: {
|
||
port: 3000, // 或 3100
|
||
proxy: {
|
||
'/api': {
|
||
target: 'http://localhost:9000', // 后端网关地址
|
||
changeOrigin: true,
|
||
rewrite: (path) => path.replace(/^\/api/, '')
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 代码规范
|
||
|
||
### 命名规范
|
||
|
||
- 文件夹：kebab-case（如 `video-player`）
|
||
- Vue组件：PascalCase（如 `VideoPlayer.vue`）
|
||
- TypeScript文件：camelCase（如 `videoService.ts`）
|
||
- 常量：UPPER_SNAKE_CASE
|
||
- CSS类名：kebab-case
|
||
|
||
### 组件规范
|
||
|
||
```vue
|
||
<template>
|
||
<!-- 模板内容 -->
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
// 1. 导入
|
||
import { ref, computed, onMounted } from 'vue'
|
||
import { useRouter } from 'vue-router'
|
||
|
||
// 2. Props 和 Emits
|
||
const props = defineProps<{...}>()
|
||
const emit = defineEmits<{...}>()
|
||
|
||
// 3. 响应式状态
|
||
const loading = ref(false)
|
||
|
||
// 4. 计算属性
|
||
const computed = computed(() => {})
|
||
|
||
// 5. 方法
|
||
const handleClick = () => {}
|
||
|
||
// 6. 生命周期
|
||
onMounted(() => {})
|
||
</script>
|
||
|
||
<style scoped lang="scss">
|
||
// 样式
|
||
</style>
|
||
```
|
||
|
||
### Git 提交规范
|
||
|
||
- `feat`: 新功能
|
||
- `fix`: 修复bug
|
||
- `docs`: 文档更新
|
||
- `style`: 代码格式
|
||
- `refactor`: 重构
|
||
- `test`: 测试
|
||
- `chore`: 构建/工具
|
||
|
||
## 部署说明
|
||
|
||
### Nginx 配置示例
|
||
|
||
```nginx
|
||
# 用户端
|
||
server {
|
||
listen 80;
|
||
server_name www.example.com;
|
||
|
||
root /var/www/video-platform-web;
|
||
index index.html;
|
||
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
location /api {
|
||
proxy_pass http://localhost:9000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
}
|
||
|
||
# 管理端
|
||
server {
|
||
listen 80;
|
||
server_name admin.example.com;
|
||
|
||
root /var/www/video-platform-admin;
|
||
index index.html;
|
||
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
location /api {
|
||
proxy_pass http://localhost:9000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
创建 `.env.production` 文件：
|
||
|
||
```env
|
||
VITE_API_BASE_URL=https://api.example.com
|
||
VITE_APP_TITLE=HAOVP
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 1. 跨域问题
|
||
|
||
确保后端配置了 CORS，或在 Vite 代理中正确配置。
|
||
|
||
### 2. Token 过期
|
||
|
||
前端会自动检测 401 响应并跳转登录页。
|
||
|
||
### 3. 图片/视频上传失败
|
||
|
||
检查文件大小限制和 MinIO 配置。
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0 (2024-03)
|
||
|
||
- 初始版本发布
|
||
- 用户端完整功能
|
||
- 管理端完整功能
|