# tk-admin-framework-vue3

**Repository Path**: Tanking-Hao/tk-admin-framework-vue3

## Basic Information

- **Project Name**: tk-admin-framework-vue3
- **Description**: 中文： Vue3 企业级中后台前端壳，配套 Gin Go 后端，统一布局与权限菜单。
English： Enterprise Vue 3 admin shell with Gin Go backend, layout & RBAC menus.
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: https://gitee.com/Tanking-Hao/tk-admin-framework-vue3
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-13
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: vue3, naive-ui, TypeScript, admin, 后台管理系统

## README

# TK Admin Framework · Vue3 前端

[English](./README.en.md) · 中文

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)

**TK Admin Framework** 是一套面向企业级中后台的全栈方案。本仓库为 **Vue3 前端壳工程**（`tk-admin-framework-vue3`），与 Go 后端（`tk-admin-framework-go` · Gin RESTful API）配套使用，提供统一布局、权限菜单、Design Token 与 RESTful 接口对接能力。

## 在线演示

| 项目 | 说明 |
| --- | --- |
| **演示地址** | [https://tkadmin.20231226.xyz/](https://tkadmin.20231226.xyz/) |
| **当前模式** | **Mock 数据演示**（`VITE_USE_AUTH_MOCK=true`），无需后端即可浏览登录、动态菜单与各业务模块 UI |
| **演示账号** | 账号 `admin`，密码 `123456`；登录页填写**图形验证码**（Mock 模式下验证码为 SVG，按图片所示输入即可） |
| **完整联调演示** | 待 **Go 后端**（`tk-admin-framework-go`）开源发布后，将另行提供对接真实 API 的演示地址 |

> 说明：当前线上环境为纯前端静态部署，数据保存在浏览器内存中，刷新或重新登录后 Mock 内的增删改不会持久化。短信登录、找回密码、导入模板下载等少数能力在 Mock 模式下尚未完全覆盖。

## 界面预览

截图存放在 [`readme-assets/`](./readme-assets/) 目录。在 Cursor / VS Code 中打开本文件后，按 `Ctrl+Shift+V`（macOS：`Cmd+Shift+V`）可预览下方图片；推送到 GitHub / Gitee 后，仓库首页也会自动渲染。

### 工作台首页

<p align="center">
  <img src="readme-assets/preview.png" alt="工作台首页" width="920" />
</p>

### 登录页

<p align="center">
  <img src="readme-assets/login.png" alt="登录页" width="920" />
</p>

### 主题切换

<p align="center">
  <img src="readme-assets/theme.png" alt="主题切换" width="920" />
</p>

| 文件 | 说明 |
| --- | --- |
| [`readme-assets/preview.png`](./readme-assets/preview.png) | 工作台 / 说明首页 |
| [`readme-assets/login.png`](./readme-assets/login.png) | 登录页 |
| [`readme-assets/theme.png`](./readme-assets/theme.png) | 亮暗主题与界面展示 |

更换截图时，直接覆盖上述文件即可（支持 PNG、JPG、WebP）；若改用其他文件名，请同步修改本 README 中的 `src` 路径。

## 特性

- **统一壳层**：顶栏 + 侧栏 + 多页签 + 内容区，支持侧栏折叠与多种布局模式
- **动态菜单与权限**：对接后端「我的菜单」接口，按 `permission` / `roles` 裁剪路由；支持严格菜单模式与本地路由降级
- **Design Token 主题**：亮/暗/企业蓝等多主题，语义色变量驱动，合规扫描禁止业务层写死色值
- **系统管理模块**：用户、角色、岗位、组织、菜单、字典、公告、任务中心、导出模板、代码生成器等
- **系统监控**：主机、磁盘、缓存、组件健康等看板（可 Mock 演示）
- **个人中心**：基本信息、密码修改、头像裁剪上传
- **工程化门禁**：TypeScript 严格类型、ESLint/Prettier、分层架构与导入规范自动化扫描

## 技术栈

| 类别 | 技术 | 版本（约） |
| --- | --- | --- |
| 框架 | Vue 3 | ^3.5 |
| 语言 | TypeScript | ~6.0 |
| 构建 | Vite | ^8.0 |
| 状态 | Pinia | ^3.0 |
| 路由 | Vue Router | ^5.0 |
| UI | Naive UI | ^2.44 |
| HTTP | Axios | ^1.15 |
| 富文本 | wangEditor | ^5.1 |

后端配套栈（`tk-admin-framework-go`）：Go 1.24、Gin、GORM、MySQL、Redis、Casbin、JWT、Viper、Zap、Swag 等。版本明细见 [`src/views/home/homeMeta.ts`](./src/views/home/homeMeta.ts)。

## 环境要求

- **Node.js** ≥ 18（推荐 20 LTS）
- **npm** ≥ 9（仓库保留 `package-lock.json`，CI 使用 `npm ci`）
- **后端服务**（可选）：本地开发时运行 `tk-admin-framework-go`，默认 `http://127.0.0.1:8080`

## 快速开始

### 1. 克隆与安装

```bash
git clone <your-repo-url> tk-admin-framework-vue3
cd tk-admin-framework-vue3
npm ci
```

### 2. 环境变量

复制示例配置并按本机情况修改：

```bash
cp .env.example .env.development.local
```

| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| `VITE_API_BASE` | 浏览器请求 API 基址 | `/api/v1` |
| `VITE_API_PROXY_TARGET` | 开发代理目标（Go 服务地址） | `http://127.0.0.1:8080` |
| `VITE_USE_AUTH_MOCK` | 无后端时使用 Mock 认证与部分 Mock 数据；**与 `VITE_CRYPTO_ENABLED` 互斥** | `false` |
| `VITE_CRYPTO_ENABLED` | 前后端传输加密（rsa-aes256-gcm）；须 `VITE_USE_AUTH_MOCK=false` 且后端 `transportCrypto.enabled=true` | `false` |
| `VITE_PROFILE_MENU_STRICT` | 菜单接口失败时不降级本地路由，进入 403 | `false` |
| `VITE_HOME_DASHBOARD_MOCK` | 首页态势 Mock：`true` 始终 Mock；`false` 仅真实 API；`fallback` 接口失败降级 Mock | `fallback` |

> 敏感或本机覆盖请写入 `.env*.local`（已在 `.gitignore` 中排除，勿提交）。

### 3. 启动开发服务器

```bash
npm run dev
```

浏览器访问 Vite 输出的本地地址（通常为 `http://localhost:5173`）。开发环境下 `/api`、`/uploads` 会代理至 `VITE_API_PROXY_TARGET`。

### 4. 生产构建

```bash
npm run build
npm run preview   # 本地预览 dist
```

## 常用脚本

| 命令 | 说明 |
| --- | --- |
| `npm run dev` | 启动 Vite 开发服务器 |
| `npm run build` | 类型检查 + 生产构建 |
| `npm run preview` | 预览构建产物 |
| `npm run lint` | ESLint 检查 |
| `npm run lint:fix` | ESLint 自动修复 |
| `npm run format` | Prettier 格式化 |
| `npm run format:check` | Prettier 检查 |
| `npm run check:types` | `vue-tsc` 类型检查 |
| `npm run check:rules` | 合规扫描（Token / 禁写规则 / 架构 / 导入） |
| `npm run check` | 类型 + Lint + 合规一键检查 |

合规扫描位于 [`scripts/compliance/`](./scripts/compliance/)，可通过 `COMPLIANCE_STRICT=0` 在非严格模式下仅告警不退出。

## 目录结构

```
tk-admin-framework-vue3/
├── public/                 # 静态资源（favicon、logo 等）
├── readme-assets/          # README 文档用图片（截图、示意图）
├── scripts/
│   └── compliance/         # 架构与样式合规扫描
├── src/
│   ├── api/                # 接口层（不得引用 views）
│   ├── assets/             # 构建内引用的资源
│   ├── components/         # 基础与业务组件（不得引用 views）
│   ├── composables/        # 组合式逻辑
│   ├── constants/          # 常量
│   ├── layout/             # 布局壳层（不宜直接 import api）
│   ├── mock/               # Mock 数据（VITE_USE_AUTH_MOCK 等）
│   ├── router/             # 路由、动态菜单、asyncModules 降级
│   ├── store/              # Pinia
│   ├── theme/              # Design Token 与主题
│   ├── types/              # 类型定义
│   ├── utils/              # 工具函数
│   └── views/              # 页面 SFC
├── .env.example            # 环境变量模板
├── vite.config.ts          # Vite 配置（@ 别名、开发代理）
└── package.json
```

跨目录引用统一使用 `@/` 别名（指向 `src/`），避免深层相对路径。

## 功能模块概览

| 模块 | 路径示例 | 说明 |
| --- | --- | --- |
| 用户态势看板 | `/home` | 在线统计、会话动态、用户趋势、技术栈说明 |
| 个人中心 | `/profile` | 资料、密码、头像 |
| 系统管理 | `/system/*` | 用户、角色、岗位、字典、任务、导出模板等 |
| 组织 / 菜单 / 公告 | 动态菜单下发 | 与后端菜单配置对齐 |
| 代码生成器 | `/system/codegen` | 表元数据、列配置、导出预览、同步差异 |
| 系统监控 | `/security/monitor` | 运行状态看板 |
| 操作 / 登录日志 | 动态菜单 | 审计与登录记录 |

本地异步路由降级源见 [`src/router/asyncModules.ts`](./src/router/asyncModules.ts)。

## 开发约定

1. **样式**：业务代码使用语义 CSS 变量（如 `var(--color-primary)`），禁止裸 `#hex`、CSS 渐变及随意行内色值；色值定义集中在 `src/theme/`。
2. **分层**：`api` / `layout` / `components` / `views` 遵守 [`scan-architecture.mjs`](./scripts/compliance/scan-architecture.mjs) 依赖方向。
3. **导入**：跨顶层目录使用 `@/`，见 [`scan-imports.mjs`](./scripts/compliance/scan-imports.mjs)。
4. **列表页**：系统管理类页面优先复用 `ManageListPageCard`、`TkManageFiltersForm` 等既有模式。
5. **发版同步**：升级依赖或发版后，请同步更新 [`src/views/home/homeMeta.ts`](./src/views/home/homeMeta.ts) 中的技术栈版本。

## 与后端联调

1. 启动 `tk-admin-framework-go`，确保 API 可访问（默认 `:8080`）。
2. 设置 `VITE_API_PROXY_TARGET` 指向后端地址。
3. 保持 `VITE_API_BASE=/api/v1` 与后端路由前缀一致。
4. 无后端演示时可设 `VITE_USE_AUTH_MOCK=true`（须同时 `VITE_CRYPTO_ENABLED=false`）。
5. 开启传输加密：`VITE_USE_AUTH_MOCK=false`、`VITE_CRYPTO_ENABLED=true`，后端 YAML Deploy + `sys.transportCrypto.enabled=true`。前端冷启动在 bootstrap 返回前即按 env 加密（仅 `crypto-params` 明文取公钥），避免 FailClosed 死锁。若热关 `sys.transportCrypto.enabled`，`crypto-params` 返回 118004 时前端会关闸并以明文继续（无需改 env）；排障见 [`docs/fix-transport-crypto-hot-disable-login.md`](./docs/fix-transport-crypto-hot-disable-login.md)。
6. Docker 构建可传 `--build-arg VITE_CRYPTO_ENABLED=true --build-arg VITE_USE_AUTH_MOCK=false` 覆盖 `.env.production`。
7. 导入模板等 blob 接口：前端 `responseType: 'blob'` 自动 skip 加密头；后端须排除对应路径（go ≥ 当前版本已内置 `.../import/template`）。清单见 [`src/constants/transportCryptoExclude.ts`](./src/constants/transportCryptoExclude.ts)。排障见 [`docs/fix-transport-crypto-import-template.md`](./docs/fix-transport-crypto-import-template.md)。

上传文件等静态资源通过 `/uploads` 代理访问后端。

## 更新记录

前端版本见 [`package.json`](./package.json) 的 `version` 字段与 Git 提交历史。

## 联系方式

如有问题、合作或贡献意向，可通过以下方式联系：

| 渠道 | 信息 |
| --- | --- |
| 微信 | `D_Libra_H` |
| QQ | `2798894548` |
| 邮箱 | [dh556699@vip.qq.com](mailto:dh556699@vip.qq.com) |

## 开源协议

本项目采用 [Apache License 2.0](./LICENSE)（[中文参考译文](./LICENSE.zh-CN)）开源。使用、修改与分发时请保留版权声明与许可全文；**以英文原版 LICENSE 为准**。

## 相关仓库

- **前端（本仓库）**：`tk-admin-framework-vue3`
- **后端**：`tk-admin-framework-go`（Gin RESTful API，需单独克隆与部署）