From 01dbbc053af45c8b7687081ee360c34ef8681758 Mon Sep 17 00:00:00 2001 From: tianfeng <769204422@qq.com> Date: Tue, 26 May 2026 16:06:23 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E9=A1=B9=E7=9B=AE=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 项目说明.md | 242 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 项目说明.md diff --git a/项目说明.md b/项目说明.md new file mode 100644 index 0000000..21be8e2 --- /dev/null +++ b/项目说明.md @@ -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 `。 +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*