管理前端 · 总览

forge-admin-web 是 forge 的后台管理控制台前端。它最反直觉、也最关键的一点是：整个前端没有一行业务字段是写死的。你不会在前端找到「商品名称」「价格」「上架状态」这些字眼——前端是一台通用渲染引擎，它向后端要一份 PageSchema（页面元数据），然后照着渲染列表、表单、详情、搜索与动作按钮。

一句话概括——后端用 Java 注解声明模型与页面，前端按下发的 schema 解释渲染。其直接结果是：业务侧新增一个 @Model、绑一个菜单，前端零改动就多出一套完整的增删改查页面。

本章面向两类读者：

• 想把控制台跑起来、配出页面的业务开发者——重点读快速开始、页面与路由、字段渲染。
• 想为某个字段/某个页面换上自定义组件的前端开发者——重点读 ★ 自定义与覆盖。

这份文档的目标

读完使用指南，你应当能不看前端源码就：配出页面、看懂列表/表单/详情怎么来的、给任意字段换一个自定义输入/展示组件、切换导航范式与微调主题。想知道「为什么这么设计」，转 设计文档。

技术栈

维度	选型	说明
框架	Vue 3 <script setup> + TypeScript	组合式 API，全程类型安全
UI 库	ant-design-vue 4	表格/表单/分页等重控件复用 antd，壳层自绘
状态	Pinia 3	模块、菜单树、PageSchema 三级缓存
路由	vue-router 4	菜单驱动路由，URL 即列表状态
网络	axios + json-bigint	雪花 ID 全程字符串，统一错误处理
时间	dayjs	日期/时间组件

核心理念：前端是 PageSchema 的解释器

后端把「一个页面长什么样」压缩成一份 PageSchema 下发，前端只负责解释它。整条链路如下：

• 后端是 schema 的唯一生产者：模型字段类型、显示名、是否可搜索/可排序、表单分组、列顺序、动作按钮……全部由后端注解推导后合成进 PageSchema。其生产机制见后端文档数据建模与应用架构。
• 前端是 schema 的唯一消费者：拿到 schema 后，按字段的 component/dataType 选组件、按 formGroups 分组、按 columns 排列、按 actions 画按钮。

为什么这么做

传统后台「一个实体一套页面代码」，N 个实体写 N 遍。元数据驱动把这件事收敛成「后端声明一次、前端渲染引擎兜住所有实体」，新增实体的前端成本趋近于零。代价是前端多了一层「解释 schema」的间接，但这层是一次性写好、所有页面共享的。

能力地图

从「跑起来」到「换组件」，按此顺序阅读：

能力	你能做到	对应篇
起前端	连后端或用 mock 起站点，看到第一个页面	快速开始
页面与路由	理解菜单如何派生路由、列表/表单/详情如何来、URL 如何承载列表状态	页面与路由
字段渲染	看懂一个字段如何按 component 选到输入/单元格组件，掌握内置组件清单	字段渲染
自定义覆盖（★）	为某字段/某模型/某组件类型注册自定义组件，乃至整页替换	自定义与覆盖
主题与壳	切换三种导航范式、改设计令牌、了解暗色现状	主题与应用壳

一眼看全：目录结构

forge-admin-web/src/
├── api/          网络层：http(axios) / meta(元数据) / data(CRUD) / auth(鉴权)
├── stores/       Pinia：app(模块·菜单·schema 缓存) / auth(token·用户)
├── composables/  组合式逻辑：listQuery(URL状态) / resource(schema工具) / expr / toast
├── layouts/      应用壳：MainLayout + 三导航(NavDual/NavTree/NavRail) + TopBar/SubBar...
├── views/        路由视图：Login / HomeRedirect / ModuleHome / Resource{List,Form,Detail}View
├── components/   业务组件：Meta{Table,Form,Detail,Search} / Resource{Form,Detail} / Status...
├── widgets/      ★ 渲染引擎：registry(多维注册表) / FieldInput / FieldCell / inputs/* / cells/*
├── theme/        主题：tokens(antd) / forge.css / shell.css / antd-overrides.css / icons
├── types/        protocol.ts —— 与后端的协议契约（所有 schema 接口定义）
└── router/       路由表

整套分层的设计意图见 整体架构。

下一步

• 快速开始：把控制台跑起来，看到第一个由 schema 驱动的页面。
• 想直接看怎么换组件？跳 ★ 自定义与覆盖。
• 想理解「为什么是渲染引擎而不是写死页面」？转 设计文档 · 渲染引擎。