UG Admin 使用指南
本指南面向使用 UG Admin 为新项目搭建管理后台的开发者。先创建所选框架的项目，再配置品牌、接入自己的后端，最后添加业务模块。已有用户、部门、角色、字典功能可以复用，真实账号、授权和数据由后端提供。
开始之前
准备好 UG Admin 模板源码和 mise.toml 指定的 Bun 版本，在模板根目录执行一次 bun install --frozen-lockfile。已有可用依赖时不重复安装。创建器需要当前安装的 UG UI 分发包；如果提示缺少构建产物，先按 UG UI 联调 准备兼容包，不手改 node_modules。
先分清两个目录，后面的命令不要混用：
| 工作目录 | 用来做什么 | 常用命令 |
|---|---|---|
ug-admin 模板根目录 |
阅读文档、创建独立项目、维护模板 | bun run dev:docs、bun run create:project |
生成的 my-admin 根目录 |
开发自己的业务、接服务、构建上线 | bun run dev、bun run scaffold:resource、bun run build |
bun run dev:docs 打开独立文档服务，默认地址 http://127.0.0.1:3400。文档页无需后台账号，搜索覆盖全部已收录文章；代码块可复制，章节链接可分享。模板维护说明见 开发指南。
选择应用并启动
React 和 Vue 是两套原生实现。新项目使用创建器导出其中一端，不手工复制应用目录，也不需要维护另一端：
# 在 ug-admin 模板根目录执行，下面选择 Vue
bun run create:project --framework vue --dir ../my-admin --name my-admin
# React 项目改为 --framework react
cd ../my-admin
bun install
bun run dev
--framework 只能选择 react 或 vue；--dir 指定一个尚不存在的目录；--name 使用小写英文和连字符。打开终端输出的地址，用登录页的演示账户确认页面可以运行，然后再接自己的服务。React 默认 3401，Vue 默认 3402；端口被占用时以终端地址为准。
目标目录必须不存在，创建器不覆盖文件、不初始化 Git、不安装依赖。输出保留当前核心后台及共享依赖，不带学习页面、仓库测试、node_modules 或本地环境文件。UG UI 当前安装的构建包打入 vendor/，生成项目通过相对文件依赖安装，不使用邻仓链接；请保留 vendor 和首次安装生成的 bun.lock。创建前需准备好模板本身的依赖与 UG UI 构建产物，创建器不会自动重建组件库。
生成项目根目录为 src/shared/public，没有 apps 工作区；下文 src 路径在模板仓库对应 apps//src，共享路径在生成项目为 shared。生成项目使用 bun run dev/build/typecheck/check；以下双端 mise 命令用于模板仓库本身。
命令均在 ug-admin 根目录运行：
# 首次准备依赖；已有可用依赖时不必重复执行
mise run install
# 按需要选一端启动
mise run dev:react
mise run dev:vue
Bun 版本以 mise.toml 为准。React 默认端口为 3401，Vue 为 3402；端口被占用时以 Vite 日志中的实际地址为准。首次运行 Playwright 若缺少 Chromium，执行 bunx playwright install chromium。
本地默认可使用登录页的演示账户。演示会话、基础管理数据与任务保存在本地浏览器，只用于验证页面流程；不能据此判断真实服务的身份、权限或数据状态。用户、部门和角色是正式模板能力，字段及保护规则见 基础管理合同。
默认导航提供正式的组织、用户、角色、字典和界面设置，个人中心从右上角头像菜单进入。首页展示有权查看的管理数据统计、用户状态分布和最近新增用户，数据来自当前配置的 DataProvider；演示模式使用演示数据。设置改动立即保存到当前浏览器。需要学习任务、资源或表单等扩展示例时，在所选应用环境中显式设置 VITE_ADMIN_EXAMPLES=true；关闭后示例路由与旧页签也不能恢复。正式身份关系与新系统扩展见 组织、用户与权限体系。字典类型、条目和真实任务优先级消费见 字典合同；关闭 examples 不会关闭字典管理。
连接真实服务
把所选应用的 .env.example 复制为同目录 .env.development.local。这些变量只允许保存浏览器可见配置：
| 变量 | 用途 |
|---|---|
VITE_AUTH_PROVIDER |
demo 或 http；本地默认 demo，生产默认 http 并禁止 demo |
VITE_DATA_PROVIDER |
mock 或 http；本地默认 mock，生产默认 http 并禁止 mock |
VITE_API_BASE_URL |
数据接口根地址，默认 /api |
VITE_ADMIN_API_URL |
认证接口根地址，默认 /api |
VITE_ADMIN_EXAMPLES |
是否开启学习示例；默认 false，只接受 true / false |
连接真实服务时将两种模式都设为 http；仅切换数据模式不会改变认证模式。.env.example 中的 demo/mock 用于本地演示，生产构建前移除该覆盖或显式改为 http，不把本地文件直接当生产配置。
认证、数据与访问控制可分别注入 Provider；端点、会话映射、Cookie 与资源响应格式见 后端 Adapter 合同。默认 /api 需要同源服务或部署代理；开发时设置 UG_API_PROXY_TARGET 可启用 /api 代理；不设置时不代理。生产配置见 部署指南。
demo 与 HTTP 使用各自的品牌命名空间会话键，不共用旧的 ug-admin-session。HTTP checkAuth() 通过 GET /auth/session 验证服务端会话，401/403 返回匿名并清理本地 HTTP 会话，网络故障不会被当成已登录。切换模式后确认登录页模式和真实网络请求，不清空其他应用存储；演示 E2E 不能证明真实认证已接通。
Auth 和 Data HTTP 提供者均默认 credentials: "include"，可分别覆盖；它们是独立配置，不是互相继承。跨源 Cookie 仍需匹配服务端 CORS、Cookie 和 CSRF 策略，也可采用同源代理。不能仅填写两个 API 地址就判断登录态已正确传给数据服务。
服务端必须独立执行授权。浏览器配置、前端路由守卫和按钮显隐均不承载服务端密钥或最终授权决定。
配置产品品牌
品牌事实源为 packages/admin-core/src/config/brand.ts。默认复用现有 UG 图片；消费产品获得授权后可以使用自己的名称和素材，无须改公共 UG UI 组件。
在所选应用 src/project.ts 的 projectBrand 中配置；启动入口负责在初始化认证和挂载应用前应用配置，无须修改 main：
export const projectBrand = {
name: "示例业务后台",
logoLight: "/brand/logo-light.svg",
logoDark: "/brand/logo-dark.svg",
favicon: "/brand/favicon.svg",
storageNamespace: "example-console",
defaultTheme: { mode: "light" },
login: {
eyebrow: "EXAMPLE CONSOLE",
title: "欢迎回到业务后台",
description: "管理团队、账户与业务协作。",
highlights: ["团队与权限管理", "统一业务入口"],
},
};
示例图片路径不是仓库自带文件：先把获授权资源放入所选应用的 public/brand/，并核对部署后的 URL。品牌应在认证、偏好和应用挂载前确定，不在运行中的页面反复切换。维护模板共享品牌能力时同步双端；只消费 Vue 的独立项目不自动改 React。
storageNamespace 仅允许字母、数字、点、下划线和连字符，并以字母或数字开头。存储键由 getAdminStorageKey(suffix) 派生；换前缀会隔离会话、偏好、标签和演示数据，不会自动迁移历史数据。已有用户偏好优先于默认主题；修改默认值不应覆盖用户已保存的选择。
添加页面与调整外观
先在生成项目根目录创建一个订单列表：
bun run scaffold:resource --name orders --label 订单 --crud
# 双端模板需加 --framework react 或 vue；本项目生成的单端项目会自动识别
生成结果为 src/modules/orders/index.ts、api.ts 和当前框架的列表页面。按下面顺序完成接入：
- 在
api.ts调整记录类型与资源映射，默认字段是id/name，资源名是orders。 - 在列表页面调整列与查询条件；查询、分页、刷新、错误状态已接通。
- 在
index.ts调整菜单标题、路径、图标及权限声明。模块会自动被发现，不改核心路由表。 - 后端提供订单接口，并向当前身份授予模块声明的权限。权限目录登记不会自动给账号授权；演示数据也不会自动生成订单记录。
- 后端授予 orders:list/read/create/update/delete，按接口合同实现资源；核对查询、新增、详情、编辑、删除与拒绝访问。生成的名称字段只是起点，按业务扩展 Row/Input、表单、详情与后端 DTO。
常见 CRUD 可以复用 DataProvider；审批、导出等独立动作可以由模块 API 封装 HTTP 客户端或 custom 调用。后端路径、字段、状态和包裹格式的差异留在 backend 或模块 API，不扩充框架核心，也不把页面改成依赖某个后端 DTO。
| 要做的事情 | 入口 |
|---|---|
| 业务页面、菜单、权限和图标 | src/modules/<业务名>/index.ts 默认导出 id、pages、可选 permissions/enabled |
| 业务内容和接口适配 | 同一个业务模块目录；通用后端接入放 src/backend/，project.ts 只负责启动注入 |
| 模板内置页面维护 | packages/admin-core/management/pages.ts 和双端 modules/system；普通业务不修改这些文件 |
| 列表、表单、详情布局 | apps/<framework>/src/patterns/ |
| 全局壳层与账户区 | apps/<framework>/src/layout/ |
| 默认侧栏、主题和用户偏好 | packages/admin-core/config/admin-layout.ts、config/preferences.ts |
| 核心/示例启动模块与业务权限登记 | 所选应用 src/app/routing/modules.ts；共享 config/app-modules.ts 与 auth/permissions.ts |
| 正式用户、部门和角色管理 | packages/admin-core/management/ 与各端 src/modules/system/management/ |
页面使用对应框架 @ug666/ui-* 公开组件。应用样式只安排内容布局，组件颜色与状态遵守 UG UI Token。公共组件的缺口按授权范围回到 ug-ui 修复，不在应用中复制基础控件或穿透内部样式。
运行 bun run scaffold:resource --name orders --label 订单 创建业务模块；在双端模板仓库中追加 --framework vue 或 --framework react，--dry-run 只预览路径。默认只生成目标端三个文件：index.ts、api.ts 和列表页面。追加 --crud 则生成五个文件，再包含原生新增/编辑页与详情页；提供异步权限检查、字段校验、422 错误、写入防重复、删除确认及未保存提醒。不启动配置引擎，不修改核心。编辑入口需要 read + update，保存成功返回列表并刷新查询；自定义操作留在模块内。
index.ts 声明模块 id 和 pages 数组，一个模块可以有多个页面。每项的 page 只需 id/path/title，可选 permission、parentId、hidden、activeMenuId、order 和 pageType；load 使用当前框架的原生懒加载。permissions 登记业务权限目录，icon 可直接使用当前框架的图标组件，无须扩充核心图标枚举。应用通过 modules/*/index.ts 自动发现模块，新增文件后刷新开发页面即可；重复 ID/路径、核心路由冲突和父级循环会在启动时明确报错。
默认列表查询同名资源，读取 id/name 字段，并提供查询、刷新、分页、取消信号和错误反馈。修改字段、详情、编辑等都留在业务模块，业务接口在 api.ts 中通过已有 Provider 的 custom 方法、HTTP 客户端或项目 Adapter 接入，审批等动作不扩充核心接口。模块登记不授予权限，后端需要提供同名资源和对应权限；Mock 不会为任意新资源自动伪造数据。
模板仓库的 system 模块保持双端完整覆盖；所有模块统一登记，没有核心页面 ID 枚举。生成项目采用源码维护方式，升级时审阅模板修复并迁入，避免覆盖 project.ts、backend/、modules/ 和本地环境配置；不承诺自动升级。
联调相邻 UG UI
先按 问题归属 区分调用问题与公共组件缺陷。组件缺陷修在 UG UI，Admin 通过公开 API 消费修复，不用补丁样式或重复控件兜底。独立项目的 vendor 是分发快照，修复应从源包生成新的兼容快照或采用已发布版本，并更新锁文件；不能手改快照，也不能假定邻仓修改已经进入当前安装版本。生成项目的 AGENTS 保留这一边界。
只有依赖的能力尚未发布或需要验证本地组件修改时，使用 mise run link:ui。它构建相邻 ug-ui 的 Core、Web、React、Vue 并更新本地链接，不修改包版本。详细路径覆盖方式见 开发指南。
该任务会改依赖链接并清理 Vite 预构建缓存。用户要求保持 node_modules 原状时不要执行。不要直接编辑依赖目录解决组件问题。
验证与部署输出
开发代理、生产环境文件、可复制的 Nginx 配置、深层路由回退和升级步骤见 部署指南。前后端共同阅读 接口规范与代码位置。
独立项目在自己的根目录执行：
bun run check
bun run build
真实上线前把认证和数据都切为 http，确认登录恢复、过期会话、授权拒绝、列表分页和写入后持久化。把 dist 部署到静态服务，为前端路由配置回退到 index.html，并让 /api 实际转发到后端。VITE_ 配置会在构建时进入前端，不能放服务端密钥；部署后只修改环境文件不会改变已有构建，需要重新构建。
以下命令只用于维护双端模板，不要求独立项目安装另一端：
mise run check:react
mise run check:vue
mise run check
mise run e2e
前两项用于单端排查；框架改动按 开发指南的完成检查 选择范围，共享行为覆盖双端直接消费者。报告写入 temp/playwright/，测试源码位于 tests/e2e/，配置位于 tests/playwright.config.ts。
E2E 固定启动 demo/mock 专用服务，不继承 .env.development.local 的真实接口模式，也不复用已有开发服务。React/Vue 的学习示例项目使用 3401/3402，默认核心项目使用 3420/3421；配置显式控制模块开关。运行前确认这四个端口可用，测试不自动终止其他服务。真实后端验收需单独安排，不把带增删操作的演示测试直接指向实际数据。
| 应用 | 构建命令 | 静态输出 |
|---|---|---|
| React | bun run --cwd apps/react build |
apps/react/dist |
| Vue | bun run --cwd apps/vue build |
apps/vue/dist |
独立生成项目在自身根目录执行 bun run build，部署 dist；上表双端命令只用于模板仓库。部署服务需处理 SPA 路由回退和真实 API 转发；构建通过不代表这些外部配置已完成。构建产物、依赖和本地环境文件不提交。
常见问题
| 现象 | 先检查什么 |
|---|---|
| 创建项目提示目标存在 | 换一个新目录；创建器不会覆盖已有项目 |
| 生成了页面但菜单不出现 | 模块默认导出、enabled、页面权限与当前身份是否匹配；检查终端冲突提示 |
| 新业务列表为空或报资源不存在 | 脚手架只生成前端查询，不创建后端接口、数据库或演示种子 |
| 换了 API 地址仍是演示登录 | 同时设置 VITE_AUTH_PROVIDER=http 与 VITE_DATA_PROVIDER=http，重启开发服务 |
| 页面能打开，但登录或请求失败 | 确认真实请求地址、代理、Cookie/CORS 和响应映射；不会自动连接后端 |
| 登录后仍提示无权限 | 后端身份返回的权限要与模块声明一致，后端接口也要独立授权 |
| 刷新某个业务地址返回 404 | 静态服务缺少 SPA 路由回退；API 请求不能一起回退为 HTML |
| UG UI 控件显示异常 | 先核对当前安装版本的公开 API；公共组件缺陷回 ug-ui 修复，不用业务 CSS 隐藏 |