快速开始

五分钟内跑起一个可用的后台，并把业务页面接上自己的后端。

1. 创建项目

在模板仓库根目录执行，React 或 Vue 二选一，目标目录必须不存在：

bun run create:project --framework react --dir ../my-admin --name my-admin
# 或 --framework vue
cd ../my-admin
bun install
bun run dev

生成的项目只声明依赖，不复制框架源码：

  • @ug666/admin-core：路由、权限、数据契约、管理模型、i18n、断点与表格形态
  • @ug666/admin-react 或 @ug666/admin-vue：页面壳与组合模式
  • @ug666/ui-react 或 @ug666/ui-vue：组件库

升级框架 = 升级依赖版本，不需要人工搬代码。

2. 换品牌

只改一处配置文件：

// src/project.ts
import { configureAdminBrand } from "@ug666/admin-core/config/brand";

configureAdminBrand({
  name: "ACME Admin",
  logoLight: "/acme-logo.svg",
  logoDark: "/acme-logo-dark.svg",
  favicon: "/acme-favicon.ico",
  storageNamespace: "acme",
  defaultTheme: { mode: "dark", preset: "minimal" },
  copy: { "common.save": "提交" }, // 覆盖任意界面文案
});

3. 接入真实后端

实现 AdminDataProvider 后跑一遍内置合规用例，自证契约：

import {
  assertConformance,
  runAdminDataProviderConformance,
} from "@ug666/admin-core/data/conformance";

const report = await runAdminDataProviderConformance(() => createMyProvider(), {
  resource: "users",
  writable: true, // 只读后端传 false
});
assertConformance(report, "my-backend");

用例覆盖分页结构、pageSize 上限、未知记录 not_found、创建往返、更新、删除；失败报告含用例名与原因。协议细节见 接入后端。

4. 生成业务模块

bun run scaffold:resource --framework react --name orders --label 订单 --crud
# 双端模板必须显式指定 --framework react 或 vue

产物：

src/modules/orders/
├─ index.ts        模块登记（自动进入路由、菜单、权限目录）
├─ pages.ts        页面描述：列、筛选、动作与权限键的唯一事实源
├─ OrdersPage.tsx  列表页（列从描述派生）
├─ api.ts          数据访问
└─ OrdersForm / OrdersDetail（--crud 时生成）

5. 删除业务模块

bun run remove:module orders --react            # 只体检：列出模块外引用
bun run remove:module orders --react --apply    # 确认后删除
# 单端项目可省略 --react/--vue；带引用强删加 --force

有模块外引用时会拦截并逐条列出 文件:行号，避免删了目录却留下悬空导入。

6. 手机端

三档视口由 @ug666/admin-core/config/viewport 与 table-mode 决定，页面不自行判断屏幕：

区域 手机（< 48rem） 平板 / 桌面
列表 卡片（强调列取描述里的 primary） 表格
表格形态 默认卡片，可切横向滚动 横向滚动
筛选 搜索区内「更多筛选」展开 工具栏控制高级条件
详情 / 编辑 抽屉整屏 侧边抽屉，按 size 限宽
批量操作条 吸底并留出安全区 常规流式

项目级覆盖：

configureAdminTableMode("scroll"); // 或 "card"

7. 质量门禁

bun run check

依次执行：代码规范 → 依赖边界与循环 → 未用代码 → 双端页面对称 → 三档断点 → 模块孤立页面 → 包导出 → 开源就绪 → 发布就绪 → 检查器自测 → 双端类型检查/测试/构建 → 产物与体积预算。

下一步