作为模板使用

复制到业务仓库后的改造顺序，按下面的步骤走完就能接真实接口。

1. 复制整个目录

把 admin-design/ 复制成业务仓库（或作为子目录），改 package.json 的 name， 执行 pnpm install。docs/ 可以一起带走，也可以只保留 src/。

2. 换菜单

只改 src/app/navigation.ts：

export const navigation: NavigationItem[] = [
  { path: '/', label: 'sample.navOverview', icon: LayoutDashboard },
  { path: '/customers', label: 'sample.navCustomers', icon: UsersRound },
]

export const navigationGroups: NavigationGroupDefinition[] = [
  {
    id: 'business',
    label: 'sample.navGroupBusiness',
    icon: LayoutDashboard,
    paths: ['/', '/customers'],
  },
]

navigation 决定"有哪些菜单"，navigationGroups.paths 决定"分组与顺序"。未登记分组的菜单会落到第一个分组， 避免新增页面漏挂菜单。label 可以直接写中文，也可以写 i18n key。

3. 换身份与退出

src/app/app-layout.tsx 里的 currentUser 换成会话数据，signOut() 改成调用身份服务：

const currentUser = { id: session.userId, displayName: session.name, email: session.email }

async function signOut() {
  await auth.logout() // 业务实现
  void navigate('/login')
}

用户菜单与个人中心（UserMenu、UserProfile）已经接好 onSignOut，传进去就会显示退出登录。

4. 接接口

页面里的示例数据集中在这两处：

数据	位置
客户、订单、组织单元、指标	src/pages/sample-data.ts
通知与通知偏好	src/lib/notifications.ts

替换时的约定：加载 / 空 / 错误三态用 LoadingState / EmptyState / ErrorState， 不要各页各写一套；错误态把追踪标识传给 traceId，方便和日志对齐。

if (query.isPending) return <LoadingState />
if (query.isError) return <ErrorState message={t('errorDefault')} traceId={query.error.traceId} />
if (!rows.length) return <EmptyState title={t('empty')} action={<Button>新建客户</Button>} />

5. 换文案

src/lib/i18n.ts 是唯一语言包入口：

export const zhResources = { ... }        // 中文
const enResources: typeof zhResources = { ... }   // 英文，类型强制结构一致

• 组件里用 const { t } = useTranslation() + t('key')。
• 页面文案可以按业务域拆分模块再合并进 resources。
• src/test/unit/i18n-keys.test.ts 会扫描代码里的字面量 key，拦住"用了但没登记"。

6. 换品牌

public/brand/ 下的四个文件直接覆盖，组件不用改：

文件	用途
mark.svg	浅色方标（侧栏、登录页、favicon）
mark-dark.svg	深色方标
wordmark-light.svg	浅色完整标识
wordmark-dark.svg	深色完整标识

登录页、侧栏、文档站都从这里取资源——不要新建图片目录。

品牌文案集中在 src/lib/brand-info.ts（名称、产品名、站点、当前使用版本、控制台安全提示）， 三处输出共用它，改一处即可：

输出位置	实现
终端启动横幅（每个进程只打一次）	scripts/banner.ts
浏览器 F12 控制台	src/lib/brand-console.ts（中文环境走中文，其它语言走英文）

7. 换环境变量

VITE_APP_TITLE=Runlume 标准后台设计
VITE_APP_STORAGE_PREFIX=runlume.        # 业务系统务必改成自己的前缀
VITE_APP_API_BASEURL=/
VITE_APP_PLATFORM_WEB_BASEURL=https://runlume.app  # 终端横幅 / 控制台输出 / 侧栏外链
VITE_APP_DISABLE_DEVTOOL=false          # true 时屏蔽 F12 / 右键 / 查看源码
VITE_BUILD_SOURCEMAP=false              # 测试环境默认 true
VITE_BUILD_COMPRESS=                    # 默认留空；要源站预压缩再填 gzip,brotli（网关需配 gzip_static）

前缀会拼到所有浏览器存储键前面（storageKey()），多个后台同域部署时靠它隔离偏好数据。

示例数据的边界

• 工作台指标、客户、订单、通知、组织单元都是内存示例数据，刷新即恢复初始状态。
• 登录 / 注册 / 找回密码只演示表单与校验，不接身份服务；退出登录只做跳转。
• 上传、提及、树拖拽与懒加载、表格虚拟滚动的接口已留出（uploader、onMove、loadChildren、virtual），替换回调即可。
• 只有偏好类设置会持久化：主题、配色、无障碍、通知偏好、顶栏操作顺序、侧栏宽度 / 圆角 / 动画 / 布局模式、表格列宽、筛选预设、快捷键。