# Sass系统

**Repository Path**: yyoti/admin-manage

## Basic Information

- **Project Name**: Sass系统
- **Description**: SaaS 管理平台 — 四川悠缇科技自研的多租户企业级中后台前端方案

基于 Vue 3 + Vite 5 + TypeScript + Element Plus 构建，面向连锁门店、区域代理、集团总部等「一套系统、多组织隔离」的运营场景。内置三种后台布局、RBAC 动态路由、多标签页、亮/暗主题、6 语言国际化（含阿拉伯语 RTL）、ECharts 运营看板、多租户切换等企业级能力。纯静态 SP
- **Primary Language**: HTML
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: vue3, element-plus, Sass, ERP, CRM

## README

<p align="center">
	<img alt="logo" src="./public/favicon.ico" width="120">
</p>
<h1 align="center" style="margin: 30px 0 30px; font-weight: bold;">SaaS 管理平台 v1.0.1</h1>
<h4 align="center">四川悠缇科技 · 多租户企业级中后台前端（Vue 3 + Vite + TypeScript）</h4>
<p align="center">
	<a href="https://gitee.com/yyoti/admin-manage/stargazers"><img src="https://gitee.com/yyoti/admin-manage/badge/star.svg?theme=gvp"></a>
	<a href="https://gitee.com/yyoti/admin-manage"><img src="https://img.shields.io/badge/SaaS管理平台-v1.0.1-brightgreen.svg"></a>
	<a href="https://gitee.com/yyoti/admin-manage/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-blue.svg"></a>
</p>
<p align="center">
	<a href="https://cn.vuejs.org/"><img src="https://img.shields.io/badge/Vue-3.2-42b883?logo=vue.js&logoColor=white"></a>
	<a href="https://cn.vitejs.dev/"><img src="https://img.shields.io/badge/Vite-5-646cff?logo=vite&logoColor=white"></a>
	<a href="https://www.typescriptlang.org/zh/"><img src="https://img.shields.io/badge/TypeScript-4.9-3178C6?logo=typescript&logoColor=white"></a>
	<a href="https://element-plus.org/zh-CN/"><img src="https://img.shields.io/badge/Element%20Plus-2.x-409EFF"></a>
	<a href="https://pinia.vuejs.org/zh/"><img src="https://img.shields.io/badge/Pinia-3.x-ffd859"></a>
	<a href="https://router.vuejs.org/zh/"><img src="https://img.shields.io/badge/Vue%20Router-4.x-42b883?logo=vue.js&logoColor=white"></a>
	<a href="https://axios-http.com/zh/"><img src="https://img.shields.io/badge/Axios-1.x-5A29E4?logo=axios&logoColor=white"></a>
	<a href="https://vue-i18n.intlify.dev/"><img src="https://img.shields.io/badge/Vue%20I18n-9.x-42b883?logo=vue.js&logoColor=white"></a>
	<a href="https://unocss.dev/"><img src="https://img.shields.io/badge/UnoCSS-0.58-333333?logo=unocss&logoColor=white"></a>
	<a href="https://echarts.apache.org/"><img src="https://img.shields.io/badge/ECharts-6.x-AA344D"></a>
</p>

[English](./README.en.md) | **简体中文**

## 平台简介

**admin-manage** 是 [四川悠缇科技](https://gitee.com/yyoti/admin-manage) 自研的 **SaaS 多租户管理后台**前端工程，面向连锁门店、区域代理、集团总部等需要「一套系统、多组织隔离」的运营场景。项目在通用中后台能力之上，内置租户切换、RBAC 动态路由、可配置布局与主题、国际化等企业级特性，可与自研或第三方 Java / Node 等后端 API 对接。

**典型业务场景**

| 场景 | 说明 |
|------|------|
| 多门店运营 | 顶栏 `TenantSwitcher` 切换门店/租户，数据按当前租户隔离（对接后端后生效） |
| 权限与菜单 | 后端下发菜单树，前端 `permission` Store 动态注册路由与侧栏 |
| 运营看板 | 首页统计卡片、ECharts 趋势图、Gitee 提交动态（Git Graph） |
| 系统配置 | 布局模式、暗色主题、标签栏/面包屑、侧栏菜单风格等可视化配置 |

本项目基于 [Apache License 2.0](./LICENSE) 开源，个人与企业均可免费使用。

## 文档导航

| 文档 | 说明 |
|------|------|
| [docs/v1 开发文档](./docs/v1/README.md) | 完整开发与接入指南（推荐） |
| [快速开始](./docs/v1/01-快速开始.md) | 安装、启动、构建 |
| [业务介绍](./docs/v1/07-业务介绍.md) | 业务模块、数据流、对接说明 |
| [部署指南](./docs/v1/08-部署指南.md) | 生产构建、Nginx、环境变量 |
| [动态路由与权限](./docs/v1/09-动态路由与权限.md) | Mock/后端菜单、路由注册 |
| [在线组件文档](http://localhost:3000/docs) | 本地启动后访问 `/docs` |

## 技术栈

| 分类 | 技术 | 说明 |
|------|------|------|
| 核心框架 | Vue 3.2、TypeScript 4.9 | 组合式 API + 严格类型 |
| 构建 | Vite 5 | 多环境、HMR、按需编译 |
| UI | Element Plus 2.x | 按需自动导入 + Sass 主题变量 |
| 状态 / 路由 | Pinia 3、Vue Router 4 | 模块化 Store；动态路由 + 标签页 |
| 网络 | Axios 1.x | 统一拦截器与业务 `code` 约定 |
| 样式 | UnoCSS 0.58、Sass | 原子类 + 布局/主题 SCSS |
| 国际化 | Vue I18n 9 | 6 种语言，含 RTL（阿拉伯语） |
| 图表 | ECharts 6 | 首页看板，`useEcharts` 封装 |
| 图标 | Font Awesome、Lucide、iconfont | 统一 `<Icon />` 组件 |
| 文档站 | markdown-it | 运行时 `/docs` 组件演示 |

工程化：`unplugin-auto-import`、`unplugin-vue-components`、`vue-tsc` 构建前类型检查。

## 核心能力

1. **三种后台布局**：经典侧栏、顶栏通栏、顶部横向菜单；`LayoutSwitcher` / 系统设置面板切换并持久化。
2. **响应式布局**：`useLayoutResponsive` 在 &lt;768px 抽屉侧栏、&lt;992px 自动折叠。
3. **动态路由与 RBAC**：`permission` Store 拉取菜单 → `router.addRoute`；开发阶段使用 `public/mock/routes.json`。
4. **多标签 / 面包屑**：`TagsView` 六种视觉风格；可切换面包屑导航。
5. **多租户切换**：`TenantSwitcher` + `tenant` Store（当前为演示数据，预留 `fetchTenants` / `switchTenant`）。
6. **主题系统**：亮/暗色、多套主题色、语义色、页脚高度、侧栏菜单风格。
7. **国际化**：6 语言懒加载；`LocaleSwitcher` + `useLocale`。
8. **HTTP 封装**：开发环境 `/api` 代理；生产使用 `VITE_API_BASE_URL`。
9. **首页看板**：用户统计、ECharts、Gitee 仓库提交时间线（`GitGraph`）。
10. **组件文档站**：`http://localhost:3000/docs` 可交互演示。

> v1 阶段**未内置**完整登录鉴权、Refresh Token；请求拦截器已预留 Token 注入 TODO，见 [API 请求](./docs/v1/05-API请求.md)。

## 运行环境

| 环境 | 说明 | 命令 |
|------|------|------|
| development | 本地开发，API 代理至本地后端 | `npm run dev` |
| test | 连接测试服务器联调 | `npm run dev:test` |
| production | 生产构建与部署 | `npm run build` |

测试环境构建：`npm run build:test`  
本地预览构建产物：`npm run preview`

**环境要求**：Node.js >= 16，npm >= 8（或 pnpm / yarn）

## 快速开始

```bash
# 安装依赖
npm install

# 启动开发服务器（默认 http://localhost:3000）
npm run dev
```

开发代理默认将 `/api` 转发至 `.env.development` 中的 `PROXY_TARGET`（如 `http://127.0.0.1:9527`）。生产 API 在 `.env.production` 配置 `VITE_API_BASE_URL`。

详细步骤见 [docs/v1/01-快速开始.md](./docs/v1/01-快速开始.md)。

## 部署概要

前端为 **纯静态 SPA**，构建产物位于 `dist/`：

```bash
npm run build
```

将 `dist` 部署至 Nginx / OSS / CDN，并配置：

- `try_files` 回退到 `index.html`（History 模式）
- `/api` 反向代理至后端网关
- 注入生产环境变量（构建时写入，非运行时）

完整 Nginx 示例、环境变量说明见 **[docs/v1/08-部署指南.md](./docs/v1/08-部署指南.md)**。

当前团队生产域名示例：`https://admin.hexinyu.cn`（以实际运维为准）。

## 项目结构

```
admin-manage/
├── docs/v1/                    # Markdown 开发文档
├── public/
│   └── mock/routes.json        # 开发阶段动态菜单 Mock
├── src/
│   ├── api/                    # Axios、Gitee、动态路由 API
│   ├── components/             # Icon、LocaleSwitcher、TenantSwitcher、GitGraph…
│   ├── docs/site/              # 在线组件文档站 (/docs)
│   ├── hooks/                  # useLocale、useLayoutResponsive、useEcharts…
│   ├── layouts/app/            # 后台布局（唯一对外 index.vue）
│   ├── locales/                # 国际化语言包
│   ├── router/                 # 路由、动态路由 helpers
│   ├── stores/modules/         # app、locale、permission、tags、tenant、user
│   ├── utils/                  # theme、storage、buildBreadcrumbs…
│   └── views/                  # 业务页面（含 _fallback 占位）
├── .env.development / .test / .production
├── vite.config.ts
└── uno.config.ts
```

## 环境变量（常用）

| 变量名 | 说明 |
|--------|------|
| `VITE_APP_TITLE` | 应用/企业名称（浏览器标题、品牌区） |
| `VITE_APP_ICP` | ICP 备案号（页脚） |
| `VITE_API_BASE_URL` | 生产/测试构建的 API 根路径 |
| `PROXY_TARGET` | 开发代理目标（仅 Vite，不注入前端） |
| `PROXY_WS_PATH` | WebSocket 独立代理路径（可选） |
| `VITE_GITEE_REPO` | 首页 Git Graph 仓库 `owner/repo` |
| `VITE_GITEE_REPO_URL` | 仓库主页链接 |
| `GITEE_ACCESS_TOKEN` | 开发环境 Gitee 代理令牌（仅 vite.config，不注入前端） |

完整列表见 [docs/v1/01-快速开始.md](./docs/v1/01-快速开始.md) 与 [部署指南](./docs/v1/08-部署指南.md)。

## 国际化（i18n）

默认 **简体中文（zh-CN）**，支持 `en-US`、`ms-MY`、`fr-FR`、`ar`（RTL）、`sw`。业务代码请使用 `useLocale` Hook，禁止硬编码用户可见文案。

扩展语言、新增文案模块的完整步骤见 README 历史章节及 [docs/v1/04-国际化.md](./docs/v1/04-国际化.md)。

## 推荐 IDE

- [VS Code](https://code.visualstudio.com/) + [Vue - Official (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.volar)

## 开源协议

本项目基于 [Apache License 2.0](./LICENSE) 开源。

## 参与贡献

1. Fork 本仓库
2. 新建功能分支（`git checkout -b feat/xxx`）
3. 提交代码（`git commit -m 'feat: 添加 xxx 功能'`）
4. 推送分支（`git push origin feat/xxx`）
5. 新建 Pull Request