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