# hyperfAdminWeb

**Repository Path**: kamon/hyperf-admin-web

## Basic Information

- **Project Name**: hyperfAdminWeb
- **Description**: 一个基于Hyperf3.2+vue3的企业级后台基础框架前端
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-28
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vben 5 通用基础系统

基于 Vue Vben Admin 5 的通用中后台前端基础框架。项目面向后续多类管理系统开发，统一提供登录、权限、动态菜单、系统管理、表单、列表和布局等基础能力。

> AI 或人工开发前请先阅读 [AGENTS.md](./AGENTS.md)，其中定义了仓库边界、Vben 5 实现规范、动态路由契约和验证标准。

## 项目特性

- Vue 3 + TypeScript + Vite 的现代化前端技术栈。
- Vben 5 布局、主题、标签页、水印和国际化基础能力。
- 基于后端菜单的动态路由与按钮权限。
- 统一请求、认证失效、业务响应解包和错误处理。
- Ant Design Vue + Vben Form + VXE Table 的统一交互适配。
- 账号、角色、菜单、部门、权限、选项、地址、系统设置、操作日志和报表中心等基础管理页面。
- 用户中心修改密码、登录退出与可选钉钉登录集成。
- pnpm workspace + Turbo 的 monorepo 工程管理。

## 技术栈

| 类别       | 方案                                     |
| ---------- | ---------------------------------------- |
| 核心框架   | Vue 3、TypeScript、Vue Router、Pinia     |
| 构建工具   | Vite、Turbo、pnpm workspace              |
| UI         | Vben 5、Ant Design Vue、Tailwind CSS     |
| 表单与表格 | Vben Form、VXE Table                     |
| 请求与状态 | `@vben/request`、Pinia                   |
| 测试       | Vitest、Playwright                       |
| 工程质量   | Oxfmt、Oxlint、ESLint、Stylelint、Cspell |

## 环境要求

- Node.js `^22.18.0 || ^24.0.0`
- pnpm `>= 11.0.0`
- 可访问的配套后端服务

项目通过 `packageManager` 锁定 pnpm 版本，不要使用 npm 或 Yarn 生成额外锁文件。

## 快速开始

### 1. 安装依赖

```bash
corepack enable
pnpm install
```

### 2. 配置环境

常用配置文件：

- `apps/web-antd/.env`：应用名称、命名空间、Store 安全密钥和权限数据解密参数。
- `apps/web-antd/.env.development`：开发端口和 API 基础路径。
- `apps/web-antd/.env.production`：生产 API 路径、路由模式和构建选项。
- `apps/web-antd/vite.config.ts`：本地开发代理目标。

默认开发环境为：

```text
前端：http://localhost:5666
API 前缀：/basic-api/system
本地代理：/basic-api/* -> http://127.0.0.1:9301/*
```

首次用于真实环境时，必须替换默认安全密钥，并确保权限解密参数与后端一致。不得提交生产 Token、密码或其他秘密。

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

```bash
pnpm dev:antd
```

启动后访问 <http://localhost:5666>。登录、菜单和系统管理功能需要配套后端正常运行。

## 目录结构

```text
.
├── apps/
│   ├── web-antd/              # 当前主业务应用
│   └── backend-mock/          # Vben 模拟后端应用
├── packages/
│   ├── @core/                 # Vben 核心共享能力
│   └── effects/               # 表格、布局、插件等可复用能力
├── internal/                  # 构建、lint 和 Vite 配置
├── scripts/                   # 仓库级工具脚本
├── docs/                      # Vben 文档应用
└── AGENTS.md                  # AI 与团队开发规范
```

`apps/web-antd/src` 中的主要边界：

```text
src/
├── adapter/                 # Vben Form / VXE Table / Ant Design 适配
├── api/
│   ├── core/              # 登录、用户、菜单及后端适配
│   └── system/            # 系统管理 API 与契约类型
├── layouts/                 # 应用布局与全局用户交互
├── router/                  # 路由、权限生成和守卫
├── store/                   # 应用状态
└── views/
    ├── _core/              # 登录、异常页等框架页面
    ├── dashboard/          # 仪表盘
    ├── report/             # 报表配置、报表任务和通用导出组件
    └── system/             # 系统管理页面
```

## API 约定

- 页面统一使用 `#/api/request` 的 `requestClient`，不单独创建请求实例。
- 当前标准响应格式为 `{ code, message, result }`，`code === 0` 表示成功。
- `requestClient` 已统一处理 Authorization、语言、业务解包与错误提示。
- 系统管理端点放在 `apps/web-antd/src/api/system/index.ts`，类型放在同目录 `types.ts`。
- 后端字段以真实契约为准；需要转换时在 API / adapter 边界集中处理。

## 报表中心与导出任务

报表中心包含两类页面：

- `apps/web-antd/src/views/report/columns`：维护报表模块、数据源服务和默认列配置。
- `apps/web-antd/src/views/report/tasks`：查看任务状态、下载文件、重置或手动投递任务。

业务列表需要“导出数据”时，统一使用报表中心的通用导出组件，不要复制旧项目的 `CheckboxModal`，也不要在各业务页重复实现字段勾选与 `/report/task_add` 提交流程。

标准接入方式：

```vue
<script lang="ts" setup>
import { Button } from 'ant-design-vue';

import { createIconifyIcon } from '@vben/icons';

import { useVbenVxeGrid } from '#/adapter/vxe-table';
import { useReportExportTaskModal } from '#/views/report/components';

const DownloadIcon = createIconifyIcon('lucide:download');

const [Grid, gridApi] = useVbenVxeGrid({
  formOptions,
  gridOptions,
  tableTitle: '配件订单',
});

const [ReportExportTaskModal, reportExportTask] = useReportExportTaskModal({
  getFormData: () => gridApi.formApi.getValues(),
  getTableColumns: () => gridOptions.columns,
  modules: 'sales_parts_order',
});

function openExportTask() {
  reportExportTask.open();
}
</script>

<template>
  <Grid>
    <template #toolbar-tools>
      <Button size="small" type="primary" @click="openExportTask">
        <DownloadIcon class="mr-1 size-4" />
        导出
      </Button>
    </template>
  </Grid>

  <ReportExportTaskModal />
</template>
```

常用参数：

- `modules`：报表模块代码，支持 `'sales_parts_order'`、`'module_a,module_b'` 或 `{ module, label }[]`。
- `getFormData`：打开弹窗时读取当前查询条件。Vben VXE Grid 页面优先使用 `gridApi.formApi.getValues()`。
- `getTableColumns`：报表配置使用“列表表头”来源时读取当前列表列。Vben VXE Grid 页面优先返回 `gridOptions.columns`。
- `tableColumns`：静态列表列配置，适合非 Grid 或列配置不会变化的页面。
- `formData`：非 Grid 页面可直接传入查询条件对象或 ref。
- `taskTitle`：可选任务标题，支持字符串或 `(context) => string`。
- `onSuccess`：任务创建成功后的回调，可用于刷新列表或跳转提醒。

组件会按模块读取 `/report_column/columns` 判断表头来源：配置列模式使用后端 JSON，列表表头模式优先使用 `getTableColumns` / `tableColumns`。用户选择本次导出列后提交 `/report/task_add` 创建任务，并自动过滤分页、token、密码、secret 等控制或敏感字段。

## 动态路由约定

应用当前使用后端权限模式，菜单从 `/menu/system_menu` 获取，经前端 adapter 规范化后注册到 Vue Router。

后端菜单必须满足：

- 顶级 `path` 使用绝对路径，例如 `/system`。
- 子级 `path` 使用相对片段，例如 `menu`，实际 URL 为 `/system/menu`。
- `name` 必须在整个路由表内唯一。
- `component` 对应 `src/views` 下的文件路径，它不是浏览器 URL。
- `redirect` 必须指向已注册的实际路由。叶子页不应因为组件名为 `index.vue` 就重定向到不存在的 `/index` URL。
- 菜单管理主要维护路由和 `permission` 权限码；API 路径只用于后端精确覆盖权限，普通接口留空走后端控制器注解权限。
- 按钮权限使用 `v-access:code="['permission_code']"` 或 `useAccess().hasAccessByCodes()`；超级管理员 `/auth/codes` 返回 `['*']` 表示全部权限，前端公共权限判断会把 `*` 作为通配符处理。

路由契约和适配详情见 `apps/web-antd/src/api/core/backend-adapter.ts` 与 [AGENTS.md](./AGENTS.md)。

## 开发约定

- 系统管理列表优先使用 `Page + useVbenVxeGrid`。
- CRUD 表单使用 `useVbenForm`，长表单使用 `useVbenDrawer`，短且独立的任务使用 `useVbenModal`。
- 表格操作列使用 `VbenTableAction`，行内操作统一为图标按钮并提供 tooltip，不混用文本按钮和图标按钮；文本按钮只放在工具栏、页签右上角或弹窗底部等命令区。
- `#toolbar-tools` 中的 Ant Design Vue 按钮统一使用 `size="small"`。
- 所有按钮点击后会发起请求的操作都必须体现 loading / disabled / lock 状态，避免网络延迟时用户误判为无响应。
- 列表导出报表任务统一使用 `#/views/report/components` 的 `useReportExportTaskModal`。
- 业务应用适配优先放在 `apps/web-antd`，不为单一页面直接修改 `packages/@core`。
- 不手工修改 `dist/`、`.turbo/` 或其他生成物。

完整实现和交付规范以 [AGENTS.md](./AGENTS.md) 为准。

## 常用命令

```bash
# 开发
pnpm dev:antd

# 主应用类型检查
pnpm -F @vben/web-antd typecheck

# 针对性单元测试
pnpm exec vitest run path/to/file.test.ts --dom

# 全量单元测试
pnpm test:unit

# 代码检查
pnpm lint
pnpm check

# 构建主应用
pnpm build:antd

# 预览生产构建
pnpm preview
```

## 构建与部署

```bash
pnpm build:antd
```

主应用构建产物位于 `apps/web-antd/dist`。生产环境默认使用 hash 路由，API 基础路径由 `apps/web-antd/.env.production` 控制。部署时需要在网关或 Web 服务器中将该路径转发到配套后端。

## 提交规范

提交信息遵循 Conventional Commits，常用类型包括：

- `feat`：新功能。
- `fix`：问题修复。
- `refactor`：不改变外部行为的重构。
- `perf`：性能优化。
- `test`：测试变更。
- `docs`：文档变更。
- `chore`：工程和依赖维护。
- `ci`：持续集成变更。

提交前请确认变更范围清晰，且已完成与风险相匹配的测试和检查。

## 浏览器支持

支持现代浏览器，不支持 Internet Explorer。Tailwind CSS 4 的最低要求为 Safari 16.4+、Chrome 111+ 和 Firefox 128+。

## 上游与许可证

本项目基于 [Vue Vben Admin](https://github.com/vbenjs/vue-vben-admin) 开发，上游文档见 [Vben Admin Documentation](https://doc.vben.pro/)。

项目遵循 [MIT License](./LICENSE)。