yusheng-admin/项目交接文档.md

# 项目交接文档

## 一、项目概述

### 1.1 项目基本信息

- **项目名称**: pure-admin-thin（精简版后台管理系统）
- **项目版本**: 5.9.0
- **技术栈**: Vue 3 + TypeScript + Vite + Element Plus + Pinia
- **开发端口**: 8848
- **Node版本要求**: ^18.18.0 || ^20.9.0 || >=22.0.0
- **包管理器**: pnpm >= 9

### 1.2 项目简介

本项目是基于 vue-pure-admin 精简版开发的后台管理系统，主要用于管理直播平台的各项业务功能。项目采用前后端分离架构，使用 Vue 3 组合式 API 开发，集成了完整的权限管理、路由管理、状态管理等功能。

### 1.3 在线地址

- **测试环境**: https://test.vespa.qxyushen.top
- **API地址**: https://test.vespa.qxyushen.top/adminapi

## 二、技术架构

### 2.1 核心技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.13 | 渐进式 JavaScript 框架 |
| TypeScript | 5.6.3 | JavaScript 的超集 |
| Vite | 6.0.3 | 新一代前端构建工具 |
| Element Plus | 2.9.0 | Vue 3 UI 组件库 |
| Pinia | 2.3.0 | Vue 状态管理库 |
| Vue Router | 4.5.0 | Vue 官方路由管理器 |
| Axios | 1.7.9 | HTTP 请求库 |
| Tailwind CSS | 3.4.16 | 原子化 CSS 框架 |

### 2.2 主要依赖库


- **@pureadmin/table**: 表格组件增强
- **@pureadmin/utils**: 工具函数库
- **@wangeditor/editor**: 富文本编辑器
- **echarts**: 数据可视化图表库
- **dayjs**: 日期处理库
- **ali-oss**: 阿里云 OSS 上传
- **agora-rtc-sdk-ng**: 声网音视频 SDK
- **xlsx**: Excel 导入导出
- **sortablejs**: 拖拽排序库

### 2.3 项目结构

```
项目根目录/
├── .husky/                 # Git hooks 配置
├── build/                  # 构建配置文件
├── mock/                   # Mock 数据
├── public/                 # 静态资源
│   ├── favicon.ico
│   ├── logo.svg
│   └── platform-config.json  # 平台配置文件
├── src/                    # 源代码目录
│   ├── api/               # API 接口
│   │   ├── modules/       # 接口模块
│   │   ├── routes.ts      # 路由接口
│   │   └── user.ts        # 用户接口
│   ├── assets/            # 静态资源
│   │   ├── iconfont/      # 图标字体
│   │   ├── login/         # 登录页资源
│   │   ├── svg/           # SVG 图标
│   │   └── user.jpg       # 默认头像
│   ├── components/        # 公共组件
│   │   ├── ReAuth/        # 权限组件
│   │   ├── ReDialog/      # 对话框组件
│   │   ├── ReIcon/        # 图标组件
│   │   ├── RePureTableBar/ # 表格工具栏
│   │   ├── SearchForm/    # 搜索表单
│   │   ├── UploadImage/   # 图片上传
│   │   └── ...
│   ├── config/            # 配置文件
│   │   └── index.ts       # 全局配置
│   ├── directives/        # 自定义指令
│   │   ├── auth/          # 权限指令
│   │   ├── copy/          # 复制指令
│   │   ├── longpress/     # 长按指令
│   │   └── ...
│   ├── layout/            # 布局组件
│   │   ├── components/    # 布局子组件
│   │   ├── index.vue      # 主布局
│   │   └── frame.vue      # 框架布局
│   ├── plugins/           # 插件配置
│   │   ├── echarts.ts     # ECharts 配置
│   │   └── elementPlus.ts # Element Plus 配置
│   ├── router/            # 路由配置
│   │   ├── modules/       # 路由模块
│   │   ├── index.ts       # 路由入口
│   │   └── utils.ts       # 路由工具
│   ├── store/             # 状态管理
│   │   ├── modules/       # Store 模块
│   │   ├── index.ts       # Store 入口
│   │   └── types.ts       # 类型定义
│   ├── style/             # 全局样式
│   │   ├── index.scss     # 主样式
│   │   ├── reset.scss     # 重置样式
│   │   ├── tailwind.css   # Tailwind 样式
│   │   └── ...
│   ├── utils/             # 工具函数
│   │   ├── http/          # HTTP 请求封装
│   │   ├── auth.ts        # 认证工具
│   │   ├── ali-oss.js     # OSS 上传
│   │   └── ...
│   ├── views/             # 页面视图
│   │   ├── login/         # 登录页
│   │   ├── welcome/       # 欢迎页
│   │   └── ...（详见业务模块）
│   ├── App.vue            # 根组件
│   └── main.ts            # 入口文件
├── types/                 # 类型声明
├── .env                   # 环境变量（开发）
├── .env.production        # 环境变量（生产）
├── .env.staging           # 环境变量（预发布）
├── Dockerfile             # Docker 配置
├── package.json           # 项目依赖
├── tsconfig.json          # TypeScript 配置
├── vite.config.ts         # Vite 配置
└── README.md              # 项目说明
```

## 三、业务模块

### 3.1 核心业务模块


#### 1. 用户管理模块 (Admin)
- **路径**: `src/views/Admin/`
- **功能**:
  - 用户列表管理 (userList)
  - 用户操作日志 (userLog)

#### 2. 房间管理模块 (room)
- **路径**: `src/views/room/`
- **功能**:
  - 房间列表 (roomList)
  - 房间审核 (roomExamine)
  - 房间背景 (roomBackground)
  - 房间标签 (roomTag)
  - 房间类型 (roomType)
  - 房间规则 (roomRules)
  - 房间关系 (roomRelation)
  - 房间补贴 (roomSubsidy)
  - 房间头条 (roomHeadlines)
  - 房间日志 (roomLog)
  - 表情管理 (expression)
  - 小时榜 (hourlyChart)
  - 影院房间 (movieRoom)
  - 红包管理 (RedEnvelope)

#### 3. 财务管理模块 (Financial)
- **路径**: `src/views/Financial/`
- **功能**:
  - 充值管理 (Recharge)
  - 后台充值 (backRecharge)
  - 提现管理 (Withdrawal)
  - 兑换管理 (exchange)

#### 4. 礼物管理模块 (gift)
- **路径**: `src/views/gift/`
- **功能**:
  - 礼物列表 (giftList)
  - 礼物分类 (giftClassif)

#### 5. 等级管理模块 (Level)
- **路径**: `src/views/Level/`
- **功能**:
  - 财富等级 (wealthGrade)
  - 魅力等级 (charmGrade)
  - 歌手等级 (singerLevel)
  - CP等级 (cpLevel)

#### 6. 贵族管理模块 (Nobility)
- **路径**: `src/views/Nobility/`
- **功能**:
  - 贵族列表 (nobilityList)
  - 贵族特权 (nobilityPower)
  - 用户贵族特权 (userPowerByNobility)

#### 7. 活动管理模块 (Activities)
- **路径**: `src/views/Activities/`
- **功能**:
  - 新人活动 (newcomer)
  - 礼包活动 (giftPack)
  - 好礼活动 (goodGift)
  - 充值列表 (RechargeList)

#### 8. 盲盒管理模块 (BlindBox)
- **路径**: `src/views/BlindBox/`
- **功能**:
  - 盲盒列表 (boxList)
  - 开启记录 (openRecord)
  - 转盘管理 (turntable)

#### 9. 每日任务模块 (dailyTasksBox)
- **路径**: `src/views/dailyTasksBox/`
- **功能**:
  - 活动列表 (ActivitiesList)
  - 发放列表 (sendList)

#### 10. 装扮管理模块 (Decorate)
- **路径**: `src/views/Decorate/`
- **功能**:
  - 装扮列表 (decorateList)
  - 用户装扮 (decorateUser)

#### 11. 动态管理模块 (dynamics)
- **路径**: `src/views/dynamics/`
- **功能**:
  - 动态列表 (dynamicsList)
  - 动态话题 (dynamicsTopic)

#### 12. 举报管理模块 (Inform)
- **路径**: `src/views/Inform/`
- **功能**:
  - 举报列表 (reportLIst)
  - 举报类型 (reportType)
  - 用户反馈 (feedback)
  - 安卓日志 (androidlog)

#### 13. 邀请管理模块 (Invited)
- **路径**: `src/views/Invited/`
- **功能**:
  - 邀请列表 (inviteList)
  - 收益列表 (incomeList)

#### 14. 马迎新春游戏模块 (LXlegend)
- **路径**: `src/views/LXlegend/`
- **功能**:
  - 游戏列表 (gameList)
  - 期数列表 (periodsList)
  - 多期列表 (multipleList)

#### 15. 新用户管理模块 (newuser)
- **路径**: `src/views/newuser/`
- **功能**:
  - 新用户列表 (newuserList)
  - 用户标签 (newuserTag)
  - 背包列表 (backpackList)
  - 禁用用户 (disableUser)
  - 歌手用户 (singerUser)
  - 机器人列表 (robotList)

#### 16. 乐园管理模块 (paradise)
- **路径**: `src/views/paradise/`
- **功能**:
  - 乐园列表 (paradiseList)
  - 抽奖/锁定列表 (drawOrlockList)

#### 17. 统计分析模块 (Statistical)
- **路径**: `src/views/Statistical/`
- **功能**:
  - 礼物记录 (giftRecord)
  - 礼物排行 (giftRank)
  - 充值排行 (rechargeRank)
  - 消费排行 (consumerRank)
  - 收礼排行 (acceptGiftsRank)
  - 房间流水排行 (roomFlowRank)
  - 幸运币排行 (luckycoinRank)
  - 幸运币抽奖 (luckycoinLottery)
  - 任务分配 (taskAssignment)

#### 18. 系统管理模块 (system)
- **路径**: `src/views/system/`
- **功能**:
  - 帮助中心 (helpCenter)
  - 幸运币管理 (luckyCoin)
  - 隐私设置 (private)
  - 充值规则 (rechargeRules)
  - 二级密码 (secondPassword)
  - 单页管理 (singlePage)
  - 任务管理 (Tasks)
  - 主题管理 (themeManage)

#### 19. 未成年管理模块 (Underage)
- **路径**: `src/views/Underage/`
- **功能**:
  - 青少年列表 (adolescentList)
  - 青少年类型 (adolescentType)

#### 20. 公会管理模块 (union)
- **路径**: `src/views/union/`
- **功能**:
  - 公会列表 (unionList)
  - 公会规则 (unionRule)
  - 公会补贴 (unionSubsidy)

#### 21. 其他模块
- **广告管理** (advertisement): 广告位管理
- **消息管理** (message): 系统消息推送
- **版本管理** (Version): APP版本控制
- **权限管理** (permission): 角色权限配置

### 3.2 API 接口模块

所有 API 接口统一放在 `src/api/modules/` 目录下，按业务模块划分：


- `activities.ts` - 活动相关接口
- `admin.ts` - 管理员相关接口
- `adolescent.ts` - 青少年相关接口
- `advertisement.ts` - 广告相关接口
- `backpack.ts` - 背包相关接口
- `blindBox.ts` - 盲盒相关接口
- `decorate.ts` - 装扮相关接口
- `dynamics.ts` - 动态相关接口
- `expression.ts` - 表情相关接口
- `Financial.ts` - 财务相关接口
- `game.ts` - 游戏相关接口
- `gift.ts` - 礼物相关接口
- `home.ts` - 首页相关接口
- `hourlyChart.ts` - 小时榜相关接口
- `Inform.ts` - 举报相关接口
- `invite.ts` - 邀请相关接口
- `level.ts` - 等级相关接口
- `message.ts` - 消息相关接口
- `newuserList.ts` - 新用户列表接口
- `newuserTag.ts` - 用户标签接口
- `nobility.ts` - 贵族相关接口
- `permission.ts` - 权限相关接口
- `room.ts` - 房间相关接口
- `statistics.ts` - 统计相关接口
- `system.ts` - 系统相关接口
- `union.ts` - 公会相关接口
- `Version.ts` - 版本相关接口

## 四、开发指南

### 4.1 环境准备

1. **安装 Node.js**
   - 版本要求: ^18.18.0 || ^20.9.0 || >=22.0.0
   - 推荐使用 nvm 管理 Node 版本

2. **安装 pnpm**
   ```bash
   npm install -g pnpm
   ```

3. **克隆项目**
   ```bash
   git clone [项目地址]
   cd [项目目录]
   ```

4. **安装依赖**
   ```bash
   pnpm install
   ```

### 4.2 开发命令

```bash
# 启动开发服务器
pnpm dev

# 构建生产环境
pnpm build

# 构建预发布环境
pnpm build:staging

# 预览构建结果
pnpm preview

# 类型检查
pnpm typecheck

# 代码格式化
pnpm lint

# ESLint 检查
pnpm lint:eslint

# Prettier 格式化
pnpm lint:prettier

# Stylelint 检查
pnpm lint:stylelint

# 清理缓存
pnpm clean:cache
```

### 4.3 环境配置

项目支持三种环境配置：

1. **开发环境** (`.env`)
   - 端口: 8848
   - 自动代理到测试服务器

2. **预发布环境** (`.env.staging`)
   - 用于预发布测试

3. **生产环境** (`.env.production`)
   - 路由模式: hash
   - CDN: 关闭
   - 压缩: 关闭

### 4.4 代理配置

开发环境下，所有 `/adminapi` 开头的请求会被代理到测试服务器：

```typescript
// vite.config.ts
proxy: {
  "/adminapi": {
    target: "https://test.vespa.qxyushen.top",
    changeOrigin: true
  }
}
```

### 4.5 API 配置

后端接口地址配置在 `src/utils/http/config.ts`：

```typescript
// 测试环境
export const URL = "https://test.vespa.qxyushen.top";

// 声网 AppId
export const appIdBySw = "02f7339ec98947deaeab173599891932";
```

### 4.6 开发规范

#### 4.6.1 代码规范

- 使用 TypeScript 开发
- 遵循 ESLint 规则
- 使用 Prettier 格式化代码
- 组件使用 Vue 3 组合式 API (setup script)
- 使用 Pinia 进行状态管理

#### 4.6.2 命名规范

- 组件文件名: PascalCase (如 `UserList.vue`)
- 工具函数: camelCase (如 `getUserInfo`)
- 常量: UPPER_SNAKE_CASE (如 `API_BASE_URL`)
- 类型/接口: PascalCase (如 `UserInfo`)

#### 4.6.3 目录规范

- 页面组件放在 `src/views/` 下，按业务模块分类
- 公共组件放在 `src/components/` 下
- API 接口放在 `src/api/modules/` 下
- 工具函数放在 `src/utils/` 下
- 类型定义放在 `types/` 或对应模块的 `types.ts` 中

#### 4.6.4 Git 提交规范

项目使用 commitlint 规范提交信息，格式如下：

```
<type>(<scope>): <subject>
```

type 类型：
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 重构
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建/工具链相关

示例：
```bash
git commit -m "feat(user): 添加用户列表导出功能"
git commit -m "fix(room): 修复房间列表分页问题"
```

## 五、核心功能说明

### 5.1 权限管理

项目采用基于角色的权限控制（RBAC）：

1. **路由权限**
   - 在路由 meta 中配置 `roles` 字段
   - 用户登录后根据角色动态加载路由

2. **按钮权限**
   - 使用 `<Auth>` 组件包裹需要权限控制的按钮
   - 使用 `v-auth` 指令控制元素显示

3. **接口权限**
   - 请求拦截器自动添加 token
   - 响应拦截器统一处理权限错误

### 5.2 路由管理


#### 5.2.1 路由结构

- **静态路由**: 不需要权限的路由（登录、404等）
- **动态路由**: 根据用户权限动态加载的路由

#### 5.2.2 路由配置

路由配置在 `src/router/modules/` 目录下，按模块划分：

```typescript
export default {
  path: "/user",
  name: "User",
  redirect: "/user/list",
  meta: {
    icon: "user",
    title: "用户管理",
    rank: 1
  },
  children: [
    {
      path: "/user/list",
      name: "UserList",
      component: () => import("@/views/Admin/userList/index.vue"),
      meta: {
        title: "用户列表",
        roles: ["admin"]
      }
    }
  ]
};
```

#### 5.2.3 路由守卫

- **beforeEach**: 权限验证、登录状态检查
- **afterEach**: 进度条关闭、页面标题设置

### 5.3 状态管理

使用 Pinia 进行状态管理，主要模块：

- **user**: 用户信息、登录状态
- **permission**: 权限信息、动态路由
- **multiTags**: 标签页管理
- **settings**: 系统设置

### 5.4 HTTP 请求

#### 5.4.1 请求封装

基于 Axios 封装，位于 `src/utils/http/`：

- 自动添加 token
- 统一错误处理
- 请求/响应拦截
- 支持取消请求

#### 5.4.2 使用示例

```typescript
import { http } from "@/utils/http";

// GET 请求
export const getUserList = (params) => {
  return http.request("get", "/adminapi/user/list", { params });
};

// POST 请求
export const createUser = (data) => {
  return http.request("post", "/adminapi/user/create", { data });
};
```

### 5.5 表格组件

使用 `@pureadmin/table` 增强的 Element Plus 表格：

- 支持分页
- 支持排序
- 支持筛选
- 支持导出
- 支持列配置

### 5.6 表单组件

#### 5.6.1 搜索表单

使用 `SearchForm` 组件快速构建搜索表单：

```vue
<SearchForm
  :columns="searchColumns"
  :model="searchForm"
  @search="handleSearch"
  @reset="handleReset"
/>
```

#### 5.6.2 表单验证

使用 Element Plus 表单验证：

```typescript
const rules = {
  username: [
    { required: true, message: "请输入用户名", trigger: "blur" }
  ],
  email: [
    { type: "email", message: "请输入正确的邮箱", trigger: "blur" }
  ]
};
```

### 5.7 文件上传

#### 5.7.1 图片上传

使用 `UploadImage` 组件：

```vue
<UploadImage
  v-model="form.avatar"
  :limit="1"
  :size="2"
/>
```

#### 5.7.2 OSS 上传

使用阿里云 OSS 直传，配置在 `src/utils/ali-oss.js`

### 5.8 富文本编辑器

使用 wangEditor 5：

```vue
<RichText v-model="form.content" />
```

### 5.9 图表组件

使用 ECharts 5，配置在 `src/plugins/echarts.ts`

### 5.10 音视频功能

使用声网 SDK (agora-rtc-sdk-ng)，AppId 配置在 `src/utils/http/config.ts`

## 六、部署指南

### 6.1 Docker 部署

项目包含 Dockerfile，支持 Docker 部署：

```bash
# 构建镜像
docker build -t pure-admin-thin .

# 运行容器
docker run -d -p 80:80 pure-admin-thin
```

Dockerfile 说明：
- 基础镜像: node:20-alpine
- 构建工具: pnpm
- Web 服务器: nginx
- 暴露端口: 80

### 6.2 传统部署

#### 6.2.1 构建

```bash
# 生产环境构建
pnpm build

# 预发布环境构建
pnpm build:staging
```

#### 6.2.2 部署

将 `dist` 目录下的文件部署到 Web 服务器（Nginx/Apache）

#### 6.2.3 Nginx 配置示例

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /adminapi {
        proxy_pass https://test.vespa.qxyushen.top;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 6.3 环境变量配置

部署前需要根据环境修改以下配置：

1. **API 地址**: `src/utils/http/config.ts`
2. **路由模式**: `.env.production` 中的 `VITE_ROUTER_HISTORY`
3. **公共路径**: `.env.production` 中的 `VITE_PUBLIC_PATH`

### 6.4 性能优化

项目已配置以下优化：

- Vite 构建优化
- 代码分割
- 静态资源压缩（可选）
- CDN 加速（可选）
- 路由懒加载
- 组件按需引入

## 七、常见问题

### 7.1 开发环境问题

**Q: 启动项目报错 "Cannot find module"**
A: 删除 `node_modules` 和 `pnpm-lock.yaml`，重新执行 `pnpm install`

**Q: 端口被占用**
A: 修改 `.env` 文件中的 `VITE_PORT` 配置

**Q: 代理不生效**
A: 检查 `vite.config.ts` 中的 proxy 配置，确保 target 地址正确

### 7.2 构建问题

**Q: 构建内存溢出**
A: 项目已配置 `NODE_OPTIONS=--max-old-space-size=8192`，如仍有问题可适当增加

**Q: 构建后白屏**
A: 检查路由模式配置，hash 模式需要设置 `VITE_ROUTER_HISTORY = "hash"`

### 7.3 权限问题

**Q: 登录后看不到菜单**
A: 检查用户角色配置，确保路由 meta 中的 roles 包含用户角色

**Q: 接口返回 401**
A: Token 过期或无效，需要重新登录

### 7.4 样式问题

**Q: Element Plus 样式不生效**
A: 确保在 `main.ts` 中引入了 `element-plus/dist/index.css`

**Q: Tailwind 样式不生效**
A: 确保在 `main.ts` 中引入了 `./style/tailwind.css`

## 八、技术支持

### 8.1 相关文档

- **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/
- **vue-pure-admin 文档**: https://pure-admin.cn/
- **@pureadmin/utils 文档**: https://pure-admin-utils.netlify.app

### 8.2 常用资源

- **图标库**: 
  - Iconify: https://icon-sets.iconify.design/
  - Element Plus Icons: https://element-plus.org/zh-CN/component/icon.html

- **UI 设计**:
  - Element Plus 设计规范
  - Tailwind CSS 工具类

- **工具库**:
  - dayjs: 日期处理
  - lodash-es: 工具函数
  - @pureadmin/utils: 项目工具函数

### 8.3 问题反馈

如遇到问题，可以通过以下方式反馈：

1. 查看项目 README 和文档
2. 搜索相关 issue
3. 联系项目负责人
4. 提交新的 issue

## 九、项目特色功能

### 9.1 声网音视频集成

项目集成了声网 SDK，支持音视频通话功能：

- **AppId**: 配置在 `src/utils/http/config.ts`
- **SDK**: agora-rtc-sdk-ng v4.23.4
- **功能**: 支持音视频通话、屏幕共享等

### 9.2 阿里云 OSS 上传

支持文件直传到阿里云 OSS：

- **配置**: `src/utils/ali-oss.js`
- **组件**: `UploadImage` 组件封装
- **功能**: 支持图片上传、进度显示、预览等

### 9.3 Excel 导入导出

使用 xlsx 库实现 Excel 功能：

- **导出**: 表格数据导出为 Excel
- **导入**: Excel 文件解析导入
- **组件**: `exportDialog` 组件封装

### 9.4 富文本编辑器

集成 wangEditor 5：

- **组件**: `RichText` 组件
- **功能**: 支持图片上传、视频插入、表格等
- **配置**: 可自定义工具栏

### 9.5 ECharts 图表

集成 ECharts 5 数据可视化：

- **配置**: `src/plugins/echarts.ts`
- **按需引入**: 只引入使用的图表类型
- **响应式**: 自动适配容器大小

### 9.6 拖拽排序

使用 sortablejs 实现拖拽功能：

- **表格行拖拽**: 调整数据顺序
- **菜单拖拽**: 自定义菜单排序
- **组件拖拽**: 页面布局调整

### 9.7 多标签页

支持多标签页功能：

- **标签管理**: 打开、关闭、刷新
- **右键菜单**: 关闭其他、关闭所有
- **缓存**: 支持页面缓存
- **持久化**: 刷新后保持标签状态

### 9.8 主题切换

支持明暗主题切换：

- **配置**: `src/style/theme.scss`
- **切换**: 实时切换，无需刷新
- **持久化**: 记住用户选择

### 9.9 响应式布局

完全响应式设计：

- **移动端适配**: 支持手机、平板访问
- **侧边栏**: 可折叠、自适应
- **表格**: 响应式列显示

### 9.10 国际化支持

虽然当前是非国际化版本，但架构支持国际化：

- **切换版本**: 可切换到国际化分支
- **i18n**: 预留国际化接口
- **文档**: 提供国际化版本文档