YUSHENG/yusheng-admin

Fork 0

Files

yziiy fd9905ffe7 更新交接文档

2026-01-31 10:23:11 +08:00

22 KiB

Raw Permalink 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. 马迎新春游戏模块 (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: 预留国际化接口
文档: 提供国际化版本文档

22 KiB Raw Permalink Blame History Unescape Escape