中台管理系统前端项目介绍与开发手册

EasyBuild Admin 是一套业务无关的企业级中后台前端脚手架。它提供的不是某一个具体的业务系统，而是一套 可复用、可扩展、可快速交付 的通用中后台解决方案。

无论是零售电商、仓储物流、内容运营、企业 OA，还是任何需要后台管理的业务场景，都可以基于此脚手架快速搭建，实现从 0 到 1 的高效落地。

• 业务无关：所有菜单、页面、权限均由后端动态下发，前端不硬编码任何业务逻辑。更换一套后端接口，它就是另一个全新的管理平台。
• 按需组装：脚手架内置了多种通用业务模块（权限管理、基础数据、内容运营、系统配置等），均可根据实际业务自由选择、裁剪或扩展。后端决定“有哪些模块”，前端自动生成对应菜单与导航。
• 即插即用：新增一个业务模块，只需创建页面文件 + 后端注册菜单资源，前端侧边栏自动出现新菜单，无需修改任何路由配置文件。

• GitHub 仓库：https://github.com/jackliuyijun/easybuild-admin
• npm 包：https://www.npmjs.com/package/easybuild-admin

后端驱动的动态菜单系统

这是本脚手架 最核心的设计理念 —— 前端不决定“有什么菜单”，后端说了算。

1. 用户登录成功后，前端自动向后端请求菜单资源接口
2. 后端根据当前用户的角色和权限，返回该用户可见的菜单资源树（包含菜单名称、路径、排序、层级关系等）
3. 前端自动将后端返回的菜单数据转换为路由配置，动态渲染侧边栏导航
4. 菜单数据智能缓存 30 分钟，避免重复请求，页面切换零延迟

开箱即用的企业级能力

• 动态菜单 & 权限：前端零配置即可实现菜单级权限控制。
• 多主题 & 暗黑模式：内置 20+ 精心调校的主题色，深浅模式一键切换。
• 统一 CRUD 模式：搜索 + 表格 + 分页 + CRUD 操作，统一交互范式。
• 类型安全全链路：从 API 响应类型及 Store 状态到组件 Props，TypeScript 全覆盖。

坚持 “选最新的、用最稳的” 原则，所有技术选型均为当前社区最活跃、生态最健全的方案：

六层解耦架构

1. Middleware 层：负责全局路由守卫、权限拦截及请求预处理。
2. Layout 层：侧边栏、顶栏、面包屑、主题引擎、通知中心。
3. 业务模块层 (后端动态驱动)：后端下发菜单 → 前端自动渲染 → 模块自由组合。
4. 通用能力层：高级组件封装，如 CustomTable、CustomForm、FileUpload 等。
5. 基础 UI 层 (Shadcn/ui)：40+ 无障碍基础组件，统一设计语言。
6. 数据通信与状态管理层：Axios 封装，Zustand (App/Sidebar) 与 React Query 缓存。

脚手架内置了一套精心设计的 高级业务组件，封装了中后台最常见的交互模式：

• CustomForm（声明式表单引擎）：支持 JSON 配置，涵盖16+字段类型，内置Zod校验。支持Grid自适应布局、字段联动、数据转换及远程搜索。
• CustomTable（配置化数据表格）：列配置驱动，支持虚拟化、自定义渲染、左右固定列、分页与行选择集成，并支持边框样式定制及其专属空状态展现。
• CustomDialog / ConfirmDialog：多尺寸内置最大化切换机制，独立区分区(Header/Content/Footer)以响应不同弹窗状态；二次操作提供安全确认流的危险预警。
• FileUpload（文件上传组件）：支持图/视/文等多种流文件的精准控制，开放多图排序与直观播放和阅览接口。
• MultiSelect & DateRangePicker：支持远程抗抖多段搜索，日历端全面对准中英文系统精确锁定时间颗粒度。
• Notifications（统一通知系统）：四形态语义囊括场景应用：showMessage、showError、showWarning、showLoading。

方式一：使用 CLI 命令创建（推荐）

一行命令即可创建项目，自动完成模板下载、项目信息替换、Git 初始化和依赖安装：

npx easybuild-admin my-project

也可以通过参数跳过交互，直接创建：

# 指定项目名 + 描述 + 包管理器
npx easybuild-admin my-project -d "我的管理后台" --pm yarn

# 只下载模板，不初始化 git 也不安装依赖
npx easybuild-admin my-project --skip-git --skip-install

方式二：手动下载

如果不使用 CLI，也可以直接从 GitHub 获取代码：

git clone https://github.com/jackliuyijun/easybuild-admin.git my-project
cd my-project
yarn install

开发环境常用命令

# 安装依赖 (Yarn v4)
yarn install

# 启动开发服务器 (默认端口: 4000)
yarn dev

# 生成生产环境构建产物
yarn build:prod

# 静态代码检查与质量控制
yarn lint

src/
├── api/             # API 模块化定义，按业务域拆分文件 (e.g., auth.ts, user.ts)
├── app/             # App Router 路由。包含 layout.tsx, page.tsx 及 api 路由
├── components/      # 组件库
│   ├── ui/          # 基类原子组件 (Shadcn/ui)
│   ├── custom/      # 核心业务高级组件 (CustomForm, CustomTable 等)
│   └── icons/       # 内部使用的图标资源
├── config/          # 全局静态配置文件 (如主题配色、环境常量)
├── constants/       # 业务常量声明 (枚举、响应码等)
├── hooks/           # 通用的自定义 Hooks 及 React Query 的封装
├── lib/             # 外部库实例化 (Axios, Lucide, Crypto-JS 等)
├── store/           # Zustand 状态切片定义
├── styles/          # Tailwind 指令、全局 CSS 变量、自定义 Animations
├── types/           # 全局 TypeScript 类型声明 (.d.ts)
└── middleware.ts    # Next.js 中间件逻辑

1. 编码约定

• 组件定义：统一使用函数组件与 Arrow Functions。
• 文件命名：组件目录使用 PascalCase；Hooks 使用 camelCase 且以 use 开头；类型文件以 .types.ts 结尾。
• Props 调用：必须声明接口 (Interface) 或类型 (Type)，严禁使用 any。
• 优先解耦：尽量编写 Dumb Components，将业务逻辑抽离至自定义 Hooks。
• 配置驱动：高级组件必须支持通过 JSON 配置项完全控制其渲染行为。

2. 与后端对接规范设计

所有 API 请求遵循统一的 请求-响应-异常 三层处理机制：

• 请求层：Axios 拦截器自动注入 Token 请求头，后端无需关心前端如何传递认证信息。
• 异常层：前端自动处理 UN_LOGIN (跳回登录)、网络超时、业务错误弹窗兜底，禁止在页面内重复编写 try-catch。

// 后端接口统一返回标准结构：
{
  "code": "OK",          // 状态码：OK / UN_LOGIN / UN_AUTH / ERROR
  "data": { ... },       // 业务数据
  "msg": "操作成功",      // 提示信息
  "count": 100           // 分页总数（列表接口）
}

所有业务模块的接口遵循 统一命名规范，例如 /{domain}/{module}/queryPage (分页查询)、/{domain}/{module}/addOrEdit (新增/修改)、/{domain}/{module}/disable (状态切换)、/{domain}/{module}/delete (删除)。

使用本模版创建新项目后，请按照以下清单逐一修改，完成项目初始化。

1. 项目基础信息

2. 环境变量与接口地址

3. 业务页面与 API 模块（需删除 / 替换）

模版内置的以下目录包含 示例业务代码，创建新项目时应 全部删除 并替换为自己的业务模块：

4. 菜单图标与颜色映射

5. 可选调整项

快速上手检查清单

✅ 1. 修改 package.json 项目名
✅ 2. 配置三个 .env 文件的 API 地址
✅ 3. 修改 login-config.ts 和 layout.tsx 中的品牌信息
✅ 4. 删除 src/app/ 下的示例业务页面
✅ 5. 清理 src/api/ 和 src/types/ 中的示例文件
✅ 6. 在 api-url.ts 中定义自己的接口路径
✅ 7. 在 routes.ts 中配置菜单图标映射
✅ 8. 替换 public/favicon.ico

需要后端接口配合，后端接口示例项目地址：https://github.com/jackliuyijun/easybuild-admin-api.git