# StackRivet-Admin-UI

**Repository Path**: zkmall/stackrivet-admin-ui

## Basic Information

- **Project Name**: StackRivet-Admin-UI
- **Description**: 开源 Vue3 企业后台管理前端 / Admin Dashboard，基于 Vite、TypeScript、Element Plus，支持 RBAC 菜单路由、代码生成 UI、审计、资产管理、国际化，配套 Java 后端。
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# StackRivet Admin UI

[![License](https://img.shields.io/badge/license-Apache--2.0-5E63E0)](LICENSE)
[![Vue](https://img.shields.io/badge/Vue-3.5-5E63E0)](package.json)
[![Vite](https://img.shields.io/badge/Vite-8-5E63E0)](package.json)
[![Element Plus](https://img.shields.io/badge/Element%20Plus-2.14-5E63E0)](package.json)
[![Docs](https://img.shields.io/badge/docs-stackrivet.zkthink.com-5E63E0)](https://stackrivet.zkthink.com/zh/docs)

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

面向 StackRivet AI 原生 Java 企业应用工程基座的开源 Vue 管理端。

StackRivet Admin UI 是 StackRivet Community 版的开源前端：基于 Vue 3.5 + TypeScript + Vite 的管理控制台，连接 `stackrivet-server`，开箱提供系统管理、RBAC 感知路由、审计视图、Asset Service 页面、带治理的代码生成、异步任务操作、生成式工单示例、中英文文案和重新设计的 Element Plus 设计系统。

[官网](https://stackrivet.zkthink.com/zh/) · [文档](https://stackrivet.zkthink.com/zh/docs) · [后端仓库](https://github.com/zkmall/stackrivet-server) · [在线演示](https://stackrivet-admin.zkthink.com) · [English Docs](https://stackrivet.zkthink.com/docs)

> 保留 Element Plus 的开发效率，但交付出来的是有治理、有品牌感、能用于真实企业项目的管理端产品。

## 为什么是 StackRivet Admin UI

默认后台模板起步很快，但后续拥有成本很高。StackRivet Admin UI 面向想要 code-first Spring Boot + Vue 基座、同时不想交付套壳模板视觉的团队。

- **重新设计的 Element Plus**：StackRivet tokens 覆盖默认蓝、默认圆角和默认阴影语言。
- **权限感知导航**：路由声明 `meta.permission`，前端隐藏无权限入口，后端仍然强制鉴权。
- **真实 Community 页面**：用户、角色、菜单、字典、参数、部门、岗位、资产、审计日志、生成器和任务。
- **带治理的生成流程**：配合后端生成器，一次生成后端、前端、权限、OpenAPI 和测试骨架。
- **中英双语内建**：英文和简体中文 locale catalog 由测试保证结构一致。
- **AI 友好的前端规则**：`AGENTS.md`、`llms.txt` 和开发标准会告诉 AI 工具如何安全修改 Vue 和 SCSS。

## 快速开始

先在相邻仓库启动后端：

```bash
cd ../stackrivet-server
docker compose up -d mysql redis
mvn install -DskipTests=true
mvn -pl stackrivet-app spring-boot:run
```

然后启动管理端 UI：

```bash
pnpm install
pnpm dev
```

打开 `http://127.0.0.1:5173/`。

开发服务器会把 `/api/*` 代理到 `http://127.0.0.1:8080`。Actuator 不走前端代理，因为后端管理服务运行在独立且默认绑定本机回环地址的 `:9090` 端口。

设计系统展示页：`http://127.0.0.1:5173/design-system`。

## 开箱即带什么

| 能力域 | Community 版包含 |
| --- | --- |
| 外壳 | 管理布局、登录布局、路由守卫、侧边栏和命令面板 |
| 系统管理 | 用户、角色、菜单、字典、参数、部门和岗位 |
| 安全体验 | 权限感知路由、403 页面、会话处理和 API 错误状态 |
| 审计 | 操作日志、登录日志和异常日志 |
| Asset Service | 资产列表和由 `stackrivet-server` 支撑的存储工作流 |
| 代码生成器 | 带治理的模块生成 UI |
| 异步任务 | 任务列表和任务状态操作 |
| 示例 | 生成式工单模块，展示端到端生成器输出 |
| 设计系统 | tokens、Element Plus 覆盖、排版、高密度表格和表单模式 |
| i18n | `en-US` 和 `zh-CN` 文案目录，Vitest 覆盖 key 对齐 |

## 技术栈

| 层 | 选择 |
| --- | --- |
| 框架 | Vue 3.5 |
| 构建 | Vite 8 |
| 语言 | TypeScript 6 |
| UI | Element Plus 2.14 + StackRivet 设计系统覆盖 |
| 状态 | Pinia 3 |
| 路由 | Vue Router 5 |
| HTTP | Axios，封装后端 `R<T>` 契约 |
| i18n | Vue I18n 11 |
| 质量 | vue-tsc、ESLint、Prettier、Vitest、Playwright |
| 运行时 | Node `>=24 <27`、pnpm `>=11` |

## 项目结构

```text
src/
  api/              # axios client 和 API 模块
  assets/           # 品牌资产和本地静态资源
  components/       # 共享 UI 组件
  composables/      # 共享 Vue composables
  features/         # task 和生成式 ticket 功能模块
  generated/        # 代码生成器输出（gitignored）
  i18n/             # i18n 装配
  layouts/          # AdminLayout 和 LoginLayout
  locales/          # en-US 和 zh-CN 文案目录
  router/           # 路由和权限守卫
  stores/           # Pinia stores
  styles/           # tokens、Element Plus 覆盖、reset、utilities 和字体
  types/            # 共享 TypeScript 类型
  views/            # 页面级视图
```

## 脚本

| 命令 | 用途 |
| --- | --- |
| `pnpm dev` | Vite dev server，支持 HMR |
| `pnpm build` | `vue-tsc --noEmit` 和生产构建 |
| `pnpm preview` | 在 `:5173` 预览生产构建 |
| `pnpm typecheck` | 只做类型检查 |
| `pnpm lint` | ESLint flat config，`--max-warnings=0` |
| `pnpm format` | 对源文件运行 Prettier |
| `pnpm test` | Vitest |
| `pnpm e2e` | Playwright |

## 设计系统规则

修改任何 `.vue` 或 `.scss` 前先读：

- [`AGENTS.md`](AGENTS.md)
- [`llms.txt`](llms.txt)
- [`docs/development-standards.md`](docs/development-standards.md)
- [`CONTRIBUTING.md`](CONTRIBUTING.md)

核心规则简版：

- 所有 Element Plus 组件都通过 `src/styles/element-overrides.scss` 继承 StackRivet tokens。
- 使用 `src/styles/tokens.scss`；不要在 `.vue` 文件中硬编码颜色、间距、字体或圆角。
- 不要留下默认 Element Plus 蓝色风格的原始 `<el-button type="primary">`。
- 数字、计数、金额和日期列使用等宽数字。
- 路由声明 `meta.permission` 或 `null`。
- 用户可见文案必须同时使用 `en-US.ts` 和 `zh-CN.ts` 的 locale key。
- 管理端追求高密度、可扫描，不在 admin shell 内做营销式卡片堆叠。

## 开发校验

```bash
pnpm typecheck
pnpm lint
pnpm test
pnpm build
```

涉及 UI 的改动，还要在浏览器里检查改动页面和 `/design-system`。依赖后端的流程使用 Playwright。

## Community 与商业版本

本仓库包含 Apache-2.0 授权的 Community 管理端前端。公开 Community 文档托管在 StackRivet 官网：

- [中文文档](https://stackrivet.zkthink.com/zh/docs)
- [English docs](https://stackrivet.zkthink.com/docs)
- [价格与版本边界](https://stackrivet.zkthink.com/zh/pricing)

Pro 和 Enterprise 资料会单独交付给授权客户，不属于本公开仓库。

## License

Apache License 2.0。详见 [`LICENSE`](LICENSE) 和 [`NOTICE`](NOTICE)。