开发指南
前端手册 Admin Uniapp

开发规范

本项目基于 unibest (opens new window) 作为模版，采用 uniapp + Vue 3 + TypeScript + Vite 技术栈，使用 Wot UI (opens new window) 库。

# 0. 实战案例

本小节，提供大家开发移动端功能时，最常用的分页列表页面、树形页面的实战案例。

# 0.1 分页列表

可参考 [系统管理 -> 岗位管理] 功能：

API 接口：/src/api/system/post.ts (opens new window)
列表页面：/src/pages-system/post/index.vue (opens new window)
表单页面：/src/pages-system/post/form.vue (opens new window)

TODO @AI：上面的不太对；列表、详情、表单，有 3 个界面；

# 0.2 树形列表

可参考 [基础设施 -> 访问日志] 功能，使用 z-paging 组件实现高性能分页：

API 接口：/src/api/infra/apiAccessLog.ts (opens new window)
列表页面：/src/pages-infra/api-access-log/index.vue (opens new window)

TODO @AI：上面的也不太对，完善下；

# 1. pages 页面（view）

# 2.1 页面组织

页面按照功能模块进行分包，主要分为：

目录	说明
`pages/`	主包页面，包含 Tabbar 页面（首页、工作流、通讯录、消息、我的）
`pages-core/`	核心分包，包含登录、注册、错误页等
`pages-system/`	系统管理分包
`pages-infra/`	基础设施分包
`pages-bpm/`	工作流分包

为什么要分包？

小程序有主包大小限制（2 MB），分包可以有效减小主包体积，提升首屏加载速度。

TODO @AI：大概是这么个意思。。。。另外，在微信小程序的开发模式下，包会超过 1.5M 大小，编译后就正常了。

# 2.2 页面结构

TODO @AI：参考 “在 apps/web-antd/src/views (opens new window) 或 apps/web-ele/src/views (opens new window) 目录下，每个模块对应一个目录，它的所有功能的 .vue 都放在该目录里。

views 目录结构

一般来说，一个路由对应一个 index.vue 文件，表单弹窗等组件放在 modules 子目录下。”；完善下下面的；

每个功能模块的页面结构如下：

pages-system/post/           # 岗位管理
├── components/              # 页面私有组件
│   └── post-item.vue
├── index.vue                # 列表页面
├── form.vue                 # 表单页面（新增/编辑）
└── detail.vue               # 详情页面（可选）

# 2.3 页面配置

使用 definePage 宏配置页面信息，支持约定式路由：

<script lang="ts" setup>
definePage({
  style: {
    navigationStyle: 'custom', // 自定义导航栏
    navigationBarTitleText: '', // 页面标题
  },
  needLogin: false, // 是否需要登录，默认为 true（一般情况下，不用添加）
})
</script>

关于 definePage 更多的介绍，可见《unibest 官方文档 —— uni 插件》 (opens new window) 文档。

# 2. api 请求

TODO @AI：根据当前项目，调整下。（截图留给我就好了！！！）

在 apps/web-antd/src/api (opens new window) 目录下，每个模块对应一个目录，包含该模块的所有 API 文件。

api 目录结构

每个 API 文件通常包含：

API 方法：调用 requestClient 发起对后端 RESTful API 的请求
interface 类型：定义 API 的请求参数和返回结果的类型，对应后端的 VO 类型

# 2.1 请求封装

项目使用 @vben/request 包进行请求封装，配置文件位于 apps/web-antd/src/api/request.ts (opens new window)。

官方文档

详细的请求配置和使用方式，请参考：服务端交互与数据 Mock (opens new window)

请求封装中包含了以下核心功能：

TODO @AI：下面的，根据项目调整下。

租户支持：自动在请求头中添加 tenant-id 租户编号
访问令牌：自动在请求头中添加 Authorization Bearer Token
刷新令牌：当访问令牌过期时，自动使用 refreshToken 刷新令牌
API 加密：支持请求数据加密和响应数据解密
错误处理：统一的错误消息提示和 401 未登录处理

# 3. component 组件

# 3.1 全局组件

在 @/components (opens new window) 目录下，实现全局公共组件：

components/
├── dict-tag/                 # 字典标签组件
│   └── index.vue
└── system-select/            # 系统选择组件
    ├── dept-select.vue       # 部门选择
    ├── user-select.vue       # 用户选择

更多说明，可见系统组件文档。

# 3.2 页面组件

每个页面的私有组件，放在页面目录下的 components 目录：

pages/index/
├── components/
│   ├── banner.vue            # 轮播图组件
│   ├── menu-section.vue      # 菜单区域组件
│   └── user-header.vue       # 用户头部组件
└── index.vue

# 4. style 样式

项目使用 UnoCSS (opens new window) 作为原子化 CSS 解决方案，可参考如下文档：

《unibest 官方文档 —— UnoCSS》 (opens new window)

# 5. 项目规范

TODO @芋艿：晚点在看；

← 配置读取【v2026-01】→