Toyas/HAOVP
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Refresh deployment and API documentation

Browse Source 
- Align deployment guidance with the current three-node Compose topology
- Document the current frontend architecture and development workflow
- Replace the stale API list with a controller-based route index
This commit is contained in:
Toys-A
2026-08-18 23:37:49 +08:00
parent 23c2912ea8
commit 30c17f01e9
12 changed files with 286 additions and 4126 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/frontend-architecture.md
+17 -444
View File
@@ -1,458 +1,31 @@
# HA-OVP 前端项目文档
# HAOVP 前端架构（当前版本）
## 项目概述
前端包含两个独立的 Vue 3 + TypeScript + Vite 应用：
HA-OVP（高可用在线视频平台）前端系统包含两个独立的 Vue 3 项目：
- `frontend/video-frontend-web`：用户端，端口 3000
- `frontend/video-frontend-admin`：管理端，端口 3100
- **video-platform-web**: 用户端前台，面向普通用户
- **video-platform-admin**: 管理端后台，面向管理员
## 依赖
## 技术栈
两端共用 Vue Router 4、Pinia、Axios、Day.js、NProgress。用户端使用 Vant 4、Artplayer 5.1.7 和 `artplayer-plugin-danmuku` 5.1.0；管理端使用 Element Plus 2.6、ECharts 5.5 和 SortableJS。项目脚本使用 npm、pnpm 均可，具体以各目录 `package.json` 为准。
### 共同技术
## 目录职责
| 类别 | 技术 | 版本 |
|------|------|------|
| 框架 | 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 |
两端均采用 `api`（接口封装）、`components`、`router`、`stores`、`types`、`utils`、`views` 分层。用户端额外包含视频、评论、弹幕和布局组件；管理端包含 dashboard、用户、视频审核、内容分类/标签、评论和系统管理页面。
### 用户端前台 (video-platform-web)
## 请求与认证
| 类别 | 技术 | 版本 |
|------|------|------|
| UI组件库 | Vant 4 | ^4.8 |
| 视频播放器 | DPlayer | - |
开发服务器将 `/api` 去前缀后代理到网关。代理地址由 `VITE_PROXY_TARGET` 控制，默认值是 `http://192.168.1.101:9000`。用户端和管理端分别使用独立的 Axios 封装、Token 存储和路由守卫；生产环境应通过 Nginx/OpenResty 将 `/api` 转发到网关，而不是直连业务服务。
### 管理端后台 (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 frontend/video-frontend-web && npm install && npm run dev
cd frontend/video-frontend-admin && npm install && npm run dev
# 管理端
cd video-platform-admin
pnpm install
# 在各自目录执行
npm run build
npm run preview
```
### 开发运行
```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)
- 初始版本发布
- 用户端完整功能
- 管理端完整功能
用户端播放器是 Artplayer，不再使用早期文档中的 DPlayer。管理端仪表盘接口由 `src/api/statistics.ts` 聚合用户、视频、评论和趋势数据，接口路径以当前 `src/api` 文件为准。