YUSHENG/yusheng-admin

Fork 0

Files

yziiy 6df60fcd9f 更新

2026-01-29 18:19:22 +08:00

23 KiB

Raw Blame History

项目交接文档

一、项目概述

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. LX传奇游戏模块 (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 环境准备

安装 Node.js
- 版本要求: ^18.18.0 || ^20.9.0 || >=22.0.0
- 推荐使用 nvm 管理 Node 版本
安装 pnpm
```
npm install -g pnpm
```

克隆项目

git clone [项目地址]
cd [项目目录]

安装依赖
```
pnpm install
```

4.2 开发命令

# 启动开发服务器
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 环境配置

项目支持三种环境配置：

开发环境 (.env)
- 端口: 8848
- 自动代理到测试服务器
预发布环境 (.env.staging)
- 用于预发布测试
生产环境 (.env.production)
- 路由模式: hash
- CDN: 关闭
- 压缩: 关闭

4.4 代理配置

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

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

4.5 API 配置

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

// 测试环境
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: 构建/工具链相关

示例：

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

五、核心功能说明

5.1 权限管理

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

路由权限
- 在路由 meta 中配置 roles 字段
- 用户登录后根据角色动态加载路由
按钮权限
- 使用 <Auth> 组件包裹需要权限控制的按钮
- 使用 v-auth 指令控制元素显示
接口权限
- 请求拦截器自动添加 token
- 响应拦截器统一处理权限错误

5.2 路由管理

5.2.1 路由结构

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

5.2.2 路由配置

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

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 使用示例

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 组件快速构建搜索表单：

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

5.6.2 表单验证

使用 Element Plus 表单验证：

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

5.7 文件上传

5.7.1 图片上传

使用 UploadImage 组件：

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

5.7.2 OSS 上传

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

5.8 富文本编辑器

使用 wangEditor 5：

<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 部署：

# 构建镜像
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 构建

# 生产环境构建
pnpm build

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

6.2.2 部署

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

6.2.3 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 环境变量配置

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

API 地址: src/utils/http/config.ts
路由模式: .env.production 中的 VITE_ROUTER_HISTORY
公共路径: .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 问题反馈

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

查看项目 README 和文档
搜索相关 issue
联系项目负责人
提交新的 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: 预留国际化接口
文档: 提供国际化版本文档

附录

A. 快速开始检查清单

安装 Node.js (版本符合要求)
安装 pnpm
克隆项目代码
安装项目依赖
配置环境变量
启动开发服务器
访问 http://localhost:8848
使用测试账号登录

B. 部署检查清单

修改 API 地址
配置路由模式
执行构建命令
检查构建产物
配置 Web 服务器
部署到服务器
测试线上环境
配置域名和 SSL

C. 代码提交检查清单

代码符合规范
通过 ESLint 检查
通过 TypeScript 检查
功能测试通过
提交信息符合规范
更新相关文档

D. 常用命令速查

# 开发
pnpm dev                    # 启动开发服务器
pnpm build                  # 构建生产环境
pnpm preview                # 预览构建结果

# 代码质量
pnpm lint                   # 代码检查和格式化
pnpm typecheck              # TypeScript 类型检查

# 依赖管理
pnpm install                # 安装依赖
pnpm update                 # 更新依赖
pnpm clean:cache            # 清理缓存

# Git
git add .                   # 添加所有更改
git commit -m "feat: xxx"   # 提交更改
git push                    # 推送到远程

23 KiB Raw Blame History Unescape Escape