# 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)

- 初始版本发布
- 用户端完整功能
- 管理端完整功能