前端 PC 脚手架 ​

一、项目概述 ​

vue3-admin-single 是数字海南 PC 管理后台单体脚手架，基于 Vue 3、TypeScript 和 Vite 构建，适用于管理后台、运营平台和内部业务系统。

项目已经完成后台应用中通用能力的集成。业务团队可以直接使用统一布局、登录认证、权限菜单、请求封装、状态管理和页面样板，不需要从空项目重复搭建基础设施。

图 1：标准工作台。脚手架已经集成侧边菜单、顶部导航、多标签页、数据指标、图表和内容区布局。

二、项目能力 ​

2.1 能力总览 ​

2.2 标准后台布局 ​

脚手架内置可直接使用的后台应用壳：

• 左侧多级菜单，支持展开、收起和图标展示。
• 顶部导航和面包屑，展示当前页面路径。
• 多标签页，可在业务页面之间快速切换和关闭。
• 页面加载进度、全屏和内容区自适应。
• 统一的 403、404、500、离线和建设中页面。
• 登录页与业务页使用独立布局，避免样式互相影响。

业务页面只需要配置路由并放入 src/views/，即可进入统一布局。

{
  path: '/system/user',
  name: 'SystemUser',
  component: () => import('#/views/system/user/index.vue'),
  meta: {
    icon: 'dh:user-group',
    title: '用户管理',
  },
}

2.3 工作台能力 ​

项目提供标准工作台和综合工作台两类样板，可用于首页、运营驾驶舱和业务门户。

标准工作台包含：

• 数据指标卡。
• 趋势折线图和分类柱状图。
• 指标概览区。
• 数据表格区。
• 侧边菜单和标签页联动。

参考路由：

/demos/workbench/standard
/demos/workbench/portal

工作台源码位于：

examples/pc/src/views/workbench-menu/

2.4 列表页面能力 ​

项目提供卡片列表、摘要列表和摘要卡片三类列表样板，覆盖后台系统常见的信息展示方式。

图 2：卡片列表样板。页面已经处理筛选区、数据摘要、状态标签、长文本和分页布局。

内置列表样板：

页面样板已考虑长标题、空字段、不同状态、分页和筛选项排列，可以直接替换数据字段后用于业务开发。

2.5 表格与筛选能力 ​

后台项目常用的查询区、数据表格、行操作和分页已组合成可运行样板。

图 3：筛选表格样板。页面提供 1 项、2 项、3 项、4 项、8 项和超过 8 项筛选条件的布局参考。

表格能力包括：

• 基础表格、筛选表格和组合表格。
• 查询、重置、分页和每页数量切换。
• 行内查看、更多操作和状态展示。
• 长文本省略和复杂分类字段展示。
• 批量操作、展开行、选项卡和左侧二级导航场景。
• VXE Table 按需加载，避免整库进入构建产物。

参考路由：

/demos/table/basic
/demos/table/filters
/demos/table/composite

参考源码：

examples/pc/src/views/element/ListPatternDemo.vue
examples/pc/src/views/element/asset-ledger-demo.ts

2.6 登录与统一认证 ​

开发模式默认提供本地演示登录，不依赖后端即可进入页面样板。账号选择后会自动带出用户名和密码，完成滑块验证即可登录。

图 4：本地演示登录页。左侧展示产品信息，右侧提供账号、密码、滑块验证和扩展登录入口。

本地演示账号：

项目同时预留 UAA 统一认证能力：

1. 路由守卫检查 URL 或本地状态中的 Access Token。
2. 无 Token 时跳转 UAA 登录页。
3. 登录后获取用户信息、角色和权限菜单。
4. 请求客户端自动携带 Bearer Token。
5. Token 失效后按项目配置刷新或退出登录。

认证相关文件：

2.7 菜单、路由与权限 ​

项目已经打通用户、角色、菜单和页面路由的权限链路。

进入路由
  ↓
检查核心路由和 ignoreAccess
  ↓
检查 Access Token
  ↓
获取用户信息和角色
  ↓
生成可访问菜单与动态路由
  ↓
进入目标页面

相关能力：

• 核心路由与业务路由分离。
• 登录页、异常页等核心页面不依赖动态菜单。
• 支持后端菜单和本地回退菜单。
• 按用户角色生成可访问路由。
• 自动同步菜单、面包屑和标签页。
• 无权限页面跳转到 403。
• 未匹配路由跳转到 404。

路由入口：

2.8 请求与数据管理 ​

统一请求客户端位于 src/api/request.ts。项目已经处理：

• 根据 VITE_GLOB_API_URL 设置请求基础地址。
• 自动添加 Authorization: Bearer <token>。
• 自动添加当前语言请求头。
• 按统一字段解析业务响应。
• 统一处理错误信息和页面提示。
• 处理 Token 过期、重新认证和刷新逻辑。
• 提供独立 Mock Client，方便开发阶段调试。

业务接口只需要声明类型和路径：

import { requestClient } from '#/api/request'

export interface UserItem {
  id: string
  name: string
}

export function getUserListApi() {
  return requestClient.get<UserItem[]>('/users')
}

项目同时集成 TanStack Query，可用于接口缓存、请求去重、轮询、预加载和服务端数据状态管理。

2.9 状态、偏好与国际化 ​

状态管理基于 Pinia：

• src/store/ 存放当前业务状态。
• src/shared/stores/ 存放用户、权限、标签页等共享状态。
• pinia-plugin-persistedstate 提供按需持久化能力。

src/preferences.ts 可覆盖应用名称、首页、Logo、主题、快捷键和顶部工具栏等配置。项目默认使用浅色主题，并关闭非必要的全局搜索、语言切换和主题切换入口，业务可以按需开启。

国际化基于 Vue I18n，语言资源分别放在 src/locales/ 和 src/shared/locales/。请求客户端会把当前语言写入 Accept-Language 请求头。

2.10 设计系统与图标 ​

业务 UI 统一使用：

@szhn/dh-design-pc

业务图标和菜单图标统一使用：

@szhn/dh-design-icons
dh:<图标名>

<script setup lang="ts">
import { Button, Message } from '@szhn/dh-design-pc'

function handleSave() {
  Message.success('保存成功')
}
</script>

<template>
  <Button type="primary" @click="handleSave">
    保存
  </Button>
</template>

项目把 UI 组件和图标作为硬规则，避免业务页面混用多套组件库。完整约束见 .ai/ui-hard-rules.md，图标清单见 .ai/dh-design-icons.md。

2.11 展示模式与业务模式 ​

脚手架通过 VITE_ENABLE_DEMOS 区分展示模式和业务交付模式：

演示源码始终保留在 examples/pc/。关闭演示只是不注册路由，不需要删除样板，业务开发时仍可随时参考。

2.12 Mock 与独立开发 ​

开发环境可通过 VITE_USE_MOCK=true 开启 Mock 服务。Mock 文件统一放在 mock/，后端接口未完成时也可以调试页面和交互。

# .env.development
VITE_USE_MOCK=true

项目提供 mockClient，用于访问不带业务 API Base URL 的本地 Mock 接口。生产环境默认关闭 Mock。

2.13 代码质量与 Git 规范 ​

项目内置：

提交代码时，pre-commit 会检查暂存文件，commit-msg 会校验提交信息。

pnpm lint
pnpm typecheck

git commit -m "feat(user): 新增用户管理页面"

2.14 构建与部署 ​

生产构建提供：

• JavaScript 和 CSS 文件指纹。
• VXE Table 按需加载。
• Gzip 压缩文件。
• Brotli 压缩文件。
• 生产环境移除 debugger。
• 演示页面默认不进入业务交付包。
• VITE_BASE 支持子路径部署。

构建结果输出到根目录 dist/，可以部署到 Nginx、CDN 或对象存储。

pnpm build
pnpm preview

2.15 AI 辅助开发 ​

项目内置 AI 协作规则，让 AI 先理解项目约束，再生成页面和代码。

推荐的 AI 页面开发流程：

读取 AGENTS.md 和 UI 硬规则
  ↓
在 scene-catalog 中查找相近场景
  ↓
参考 examples/pc 中的页面样板
  ↓
使用 DH Design PC 和 DH Design Icons 开发
  ↓
运行 lint 和 typecheck

三、技术栈 ​

四、创建与启动 ​

4.1 环境要求 ​

4.2 创建项目 ​

安装或更新 CLI：

npm config set registry https://npmmirror.digitalhainan.com.cn/
npm install -g @szhn/szhn-cli@latest

创建项目：

szhn-cli init <项目名称>

选择以下模板：

PC Admin Web 单应用版本（Vue 3）

模板对应的 npm 包：

@szhn/template-pc-vue3-admin-single

也可以使用可视化模式：

szhn-cli ui

4.3 启动项目 ​

cd <项目名称>
pnpm install
pnpm dev

默认访问地址：

http://localhost:5555/admin-web/

五、目录结构 ​

vue3-admin-single/
├── .ai/                         # AI 规则、场景索引和术语
├── .husky/                      # Git Hooks
├── docs/                        # 项目开发文档
├── examples/
│   └── pc/                      # 工作台、列表、表格和弹窗样板
├── mock/                        # 本地 Mock 接口
├── plugins/                     # Vite 自定义插件
├── public/                      # 公共静态资源
├── scripts/                     # Node 版本检查等脚本
├── src/
│   ├── adapter/                 # 表单和表格适配器
│   ├── api/                     # 业务接口和请求客户端
│   ├── app-profile/             # 展示模式与业务模式
│   ├── assets/                  # 图片等静态资源
│   ├── config/                  # UAA 和监控配置
│   ├── core/                    # 核心 UI 与偏好能力
│   ├── effects/                 # 权限、请求、布局和公共能力
│   ├── internal/                # 工程内部配置
│   ├── layouts/                 # 基础布局和认证布局
│   ├── locales/                 # 业务语言包
│   ├── router/                  # 路由与权限守卫
│   ├── shared/                  # 共享类型、工具、状态和样式
│   ├── store/                   # 业务 Pinia Store
│   ├── utils/                   # 业务工具函数
│   ├── views/                   # 登录、异常页和业务页面
│   ├── app.vue                  # 根组件
│   ├── bootstrap.ts             # 应用初始化
│   ├── main.ts                  # 应用入口
│   └── preferences.ts           # 应用偏好配置
├── .env.development             # 开发环境变量
├── .env.production              # 生产环境变量
├── AGENTS.md                    # AI 开发入口
├── DESIGN.md                    # 设计规范
├── deploy.sh                    # 部署构建脚本
├── start.sh                     # 本地启动脚本
├── vite.config.mts              # Vite 配置
└── package.json                 # 依赖和命令

业务开发主要修改：

src/api/
src/views/
src/router/routes/modules/
src/store/
src/config/

除非进行框架级维护，不要直接修改 src/core/、src/effects/ 和 src/internal/。

六、环境配置 ​

常用环境变量：

本地联调后端时，修改 vite.config.mts 中的代理目标：

server: {
  host: true,
  port: 5555,
  proxy: {
    '/admin-web/api': {
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/admin-web\/api/, ''),
      target: 'http://localhost:8080/api',
      ws: true,
    },
  },
}

七、常用命令 ​

# 安装依赖
pnpm install

# 启动开发环境，默认包含页面样板
pnpm dev

# 启动业务精简模式
VITE_ENABLE_DEMOS=false pnpm dev

# 生产构建，默认不包含演示页面
pnpm build

# 构建测试环境
pnpm build:test

# 构建分析
pnpm build:analyze

# 预览构建结果
pnpm preview

# ESLint 检查并修复
pnpm lint

# Prettier 格式化
pnpm format

# Vue 和 TypeScript 类型检查
pnpm typecheck

# 一键安装并启动
./start.sh

# 一键安装并构建
./deploy.sh

八、联系与支持 ​

• 源码仓库：vue3-admin-template-single
• 脚手架工具：szhn-cli 使用说明
• PC 组件库：DH Design PC
• 负责人：李畅