新增项目说明文件
This commit is contained in:
tianfeng
parent
b6895f78fe
commit
01dbbc053a
242
项目说明.md
Normal file
242
项目说明.md
Normal file
@ -0,0 +1,242 @@
|
||||
# webconsole 项目说明
|
||||
|
||||
> Sugartime 后台管理系统 — 面向中东/南亚市场的社交娱乐平台运营控制台
|
||||
|
||||
---
|
||||
|
||||
## 一、项目概述
|
||||
|
||||
| 项目 | 信息 |
|
||||
|------|------|
|
||||
| **项目名** | sugartime-admin |
|
||||
| **版本** | 4.2.1 |
|
||||
| **定位** | 直播 / 语音聊天社交平台的 Web 运营控制台 |
|
||||
| **目标市场** | 中东、南亚（支持阿拉伯语、孟加拉语、土耳其语等） |
|
||||
| **开发端口** | 9528 |
|
||||
| **构建工具** | Vue CLI 3 |
|
||||
|
||||
---
|
||||
|
||||
## 二、技术栈
|
||||
|
||||
| 层次 | 技术 |
|
||||
|------|------|
|
||||
| **前端框架** | Vue 2.6 + Vue Router 3 + Vuex 3 |
|
||||
| **UI 组件库** | Element UI 2.15 |
|
||||
| **HTTP 客户端** | Axios 0.18（统一封装，Bearer Token 鉴权） |
|
||||
| **图表** | ECharts 4.8 |
|
||||
| **国际化** | 自研 i18n 插件（基于时区自动检测语言） |
|
||||
| **样式** | SCSS + normalize.css，支持暗色主题切换 |
|
||||
| **富媒体** | Video.js 8、SVGA Player、libpag（PAG 动效） |
|
||||
| **文件存储** | 阿里云 OSS（ali-oss SDK） |
|
||||
| **WebSocket** | SockJS + StompJS（实时消息） |
|
||||
| **Mock** | Mock.js（开发环境可选启用） |
|
||||
| **代码规范** | ESLint（babel-eslint）+ EditorConfig |
|
||||
| **测试** | Jest + @vue/test-utils |
|
||||
|
||||
---
|
||||
|
||||
## 三、项目架构
|
||||
|
||||
```
|
||||
webconsole/
|
||||
├── src/
|
||||
│ ├── api/ # 接口定义层（按业务模块分文件）
|
||||
│ ├── assets/ # 静态资源（图片等）
|
||||
│ ├── components/ # 公共组件
|
||||
│ ├── components-register.js # 全局组件注册入口
|
||||
│ ├── constant/ # 常量定义
|
||||
│ ├── directive/ # 自定义指令
|
||||
│ ├── filters/ # 全局过滤器
|
||||
│ ├── icons/ # SVG 图标（svg-sprite-loader）
|
||||
│ ├── flag-icons/ # 国旗图标
|
||||
│ ├── lang/ # 国际化（消息文件 + 时区自动检测）
|
||||
│ ├── layout/ # 整体布局（Sidebar + Navbar + AppMain）
|
||||
│ ├── permission.js # 路由守卫 / 权限控制
|
||||
│ ├── plugin/ # 全局插件注册
|
||||
│ ├── router/ # 路由定义（静态路由 + 动态权限路由）
|
||||
│ ├── settings.js # 全局应用配置
|
||||
│ ├── store/ # Vuex（app / settings / user 模块）
|
||||
│ ├── styles/ # 全局样式、主题变量
|
||||
│ ├── utils/ # 工具库（request、auth、theme 等）
|
||||
│ ├── views/ # 页面视图（按业务模块分目录）
|
||||
│ └── main.js # 应用入口
|
||||
├── mock/ # Mock 数据服务
|
||||
├── public/ # 静态 HTML 模板
|
||||
├── build/ # 构建脚本
|
||||
├── nginx/ # Nginx 配置
|
||||
├── docs/ # 项目文档
|
||||
├── vue.config.js # Vue CLI 配置（代理、Webpack 优化）
|
||||
├── .env.* # 各环境变量配置
|
||||
├── Dockerfile* # 多套 Docker 构建文件
|
||||
└── pipeline* # Jenkins CI/CD Pipeline 文件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、核心模块（views）
|
||||
|
||||
| 模块目录 | 功能说明 |
|
||||
|----------|----------|
|
||||
| `user/` | 用户管理、钻石/金币余额、道具流水、签到、靓号、IM账号等 |
|
||||
| `room/` | 在线房间、贡献余额、房间资料、退款扣除记录 |
|
||||
| `order/` | 订单详情、退款、金币流水、游戏券流水、异常订单 |
|
||||
| `activity/` | 活动配置模板、代理活动、自定义名人堂、房间贡献活动 |
|
||||
| `approval/` | 头像/昵称/照片墙/房间封面/动态内容/银行卡 审核 |
|
||||
| `game/` | PK记录、幸运礼物、LuckyBox、砸金蛋、摩天轮、炸金花、Ludo |
|
||||
| `team/` | 团队管理、成员列表、账单、BD 列表、业务拓展 |
|
||||
| `family/` | 家族配置与列表 |
|
||||
| `cnf/` | 支付配置（国家/渠道/厂商）、礼物、抽奖品、内购产品、枚举参数 |
|
||||
| `sys/` | 系统管理（用户/角色/菜单/资源/区域配置）、Banner、公告、版本 |
|
||||
| `statistics/` | 数据大屏（DataV） |
|
||||
| `log/` | 登录日志、请求日志、房间黑名单、封禁设备 |
|
||||
| `message/` | 消息推送 |
|
||||
| `tools/` | Redis 管理、文件上传、金币分析、Socket 测试、订单补偿 |
|
||||
| `props/` | 道具配置、道具商店、道具赠送 |
|
||||
| `pet/` | 宠物喂养记录、宠物池 |
|
||||
| `dynamic/` | 用户动态、标签、权重配置、黑名单 |
|
||||
| `dashboard/` | 首页仪表盘 |
|
||||
|
||||
---
|
||||
|
||||
## 五、权限与路由机制
|
||||
|
||||
1. **路由守卫**（`permission.js`）：未登录统一跳转 `/login`，白名单仅 `/login`。
|
||||
2. **Token 鉴权**：登录后 Token 存于 Cookie，每次请求在 Header 中携带 `Authorization: Bearer <token>`。
|
||||
3. **动态菜单路由**：登录后调用后端接口获取用户有权限的菜单（`user/getMenus`），通过 `router.addRoutes()` 动态注入。
|
||||
4. **按钮级权限**：通过 `user/buttonPermissions` 接口获取，结合自定义指令控制页面内操作按钮显示。
|
||||
5. **最近访问记录**：每次路由跳转自动记录至 Store，用于快速导航。
|
||||
|
||||
---
|
||||
|
||||
## 六、国际化（i18n）
|
||||
|
||||
- 自研轻量 i18n 插件，注入 `Vue.prototype.$t`。
|
||||
- 消息文件存于 `src/lang/messages/`，通过 `require.context` 自动加载。
|
||||
- **时区自动检测**：根据浏览器时区映射对应语言（阿拉伯语区→`ar`，中国区→`zh`，孟加拉→`bn`，土耳其→`tr`，默认 `en`）。
|
||||
- Element UI 语言同步切换（目前支持 `en` / `zh`）。
|
||||
|
||||
---
|
||||
|
||||
## 七、HTTP 请求封装（`utils/request.js`）
|
||||
|
||||
- 基于 Axios 封装，统一：
|
||||
- `baseURL` = `VUE_APP_BASE_URL` + `/console`（代理前缀）
|
||||
- 超时：60 秒
|
||||
- 请求头：`Authorization: Bearer token`、`Req-Version: v2`、`Req-Client: Ops`
|
||||
- 响应拦截：
|
||||
- `errorCode !== 0` 时自动弹出错误提示
|
||||
- `errorCode === 401` 时清除 Token 并刷新页面重新登录
|
||||
- 请求超时（`ECONNABORTED`）静默处理
|
||||
|
||||
---
|
||||
|
||||
## 八、构建与部署
|
||||
|
||||
### 环境变量（.env.*）
|
||||
|
||||
| 文件 | 对应环境 |
|
||||
|------|----------|
|
||||
| `.env.development` | 本地开发（代理到 `console.atuchat.com`） |
|
||||
| `.env.staging` | 测试环境 |
|
||||
| `.env.production` | 生产环境 |
|
||||
| `.env.prod-atyou` | Atyou 品牌生产环境 |
|
||||
|
||||
### 常用命令
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
npm install
|
||||
|
||||
# 本地开发（端口 9528）
|
||||
npm run dev
|
||||
|
||||
# 生产环境打包
|
||||
npm run build:prod
|
||||
|
||||
# Atyou 环境打包
|
||||
npm run build:atu-prod
|
||||
|
||||
# Staging 打包
|
||||
npm run build:stage
|
||||
|
||||
# 代码检查
|
||||
npm run lint
|
||||
|
||||
# 单元测试
|
||||
npm run test:unit
|
||||
```
|
||||
|
||||
### Webpack 优化
|
||||
|
||||
- 生产环境按时间戳版本号命名 JS/CSS（缓存防穿透）
|
||||
- Code Splitting：`chunk-libs`（第三方）、`chunk-elementUI`（Element UI 单独包）、`chunk-commons`（公共组件）
|
||||
- SVG 使用 `svg-sprite-loader` 合并为雪碧图
|
||||
- 关闭 `productionSourceMap`，提升构建速度与安全性
|
||||
|
||||
### Docker / CI
|
||||
|
||||
- 提供多套 `Dockerfile`（默认、dev、atu、hooka 环境）
|
||||
- Jenkins Pipeline 文件：`pipeline`、`pipeline-atyou`、`pipeline-dev`、`pipeline-hooka`
|
||||
- 部署至 Kubernetes（`admin-dashboard-svc.yaml`）
|
||||
|
||||
---
|
||||
|
||||
## 九、开发规范
|
||||
|
||||
### 环境要求
|
||||
- Node.js ≥ 8.9，npm ≥ 3.0
|
||||
- 推荐编辑器：**VSCode**（必须启用 ESLint 插件）
|
||||
|
||||
### 新增页面流程
|
||||
|
||||
```
|
||||
1. 创建页面目录：src/views/<模块>/<页面名>/index.vue
|
||||
2. 注册路由：src/router/index.js 中添加路由配置
|
||||
3. 定义接口：src/api/<模块>.js 中定义请求方法
|
||||
4. Mock 数据（可选）：src/mock/ 中添加 mock 数据
|
||||
5. 实现业务逻辑
|
||||
```
|
||||
|
||||
### 路由 meta 字段规范
|
||||
|
||||
```js
|
||||
meta: {
|
||||
title: '页面标题', // 显示在侧边栏和面包屑（支持 i18n key）
|
||||
icon: 'svg-name', // 侧边栏图标（src/icons/svg/ 下的文件名）
|
||||
roles: ['admin'], // 角色控制（可选，优先用后端动态菜单）
|
||||
hidden: true, // 不显示在侧边栏
|
||||
breadcrumb: false, // 不显示在面包屑
|
||||
keepAlive: true, // 是否缓存组件
|
||||
activeMenu: '/path' // 指定高亮的侧边栏菜单
|
||||
}
|
||||
```
|
||||
|
||||
### 代码风格
|
||||
- ESLint 规则基于 `eslint-plugin-vue`，严格执行，禁止提交有 lint error 的代码
|
||||
- 样式使用 SCSS，变量集中在 `src/styles/variables.scss`
|
||||
- API 文件按业务模块拆分，统一放在 `src/api/`
|
||||
- 全局常量统一放在 `src/constant/`
|
||||
|
||||
---
|
||||
|
||||
## 十、OSS 文件上传
|
||||
|
||||
阿里云 OSS，Bucket 分类：
|
||||
|
||||
| Bucket Key | 用途 |
|
||||
|------------|------|
|
||||
| `avatar` | 用户头像 |
|
||||
| `svgasource` | SVGA 动效资源 |
|
||||
| `svga_cover` | SVGA 封面 |
|
||||
| `back` | 背景图 |
|
||||
| `start_page` | 启动页 |
|
||||
| `feedback` | 反馈图片 |
|
||||
| `apk` | APK 安装包 |
|
||||
| `other` | 其他资源 |
|
||||
|
||||
全局挂载：`Vue.prototype.$simpleUploadFlie` / `$radmonFilename` / `$getAccessImgUrl`
|
||||
|
||||
---
|
||||
|
||||
*文档生成时间：2026-05-26*
|
||||
Loading…
x
Reference in New Issue
Block a user