@ai-partner-x/aiko-boot-cli 0.1.4

package/templates/scaffold-default/packages/admin/src/pages/settings-page.tsx

@@ -0,0 +1,335 @@
+import { useState } from "react";
+import { Settings, User, Bell, Palette, Globe, Shield, Check } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Button } from "@/components/ui/button";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
+import { useTheme } from "@/components/admin-ui/theme/theme-provider";
+import type { Appearance, Palette as ThemePalette } from "@/components/admin-ui/theme/theme-provider";
+
+function SettingSection({
+  icon,
+  title,
+  description,
+  children,
+  iconBg,
+}: {
+  icon: React.ReactNode;
+  title: string;
+  description?: string;
+  children: React.ReactNode;
+  iconBg: string;
+}) {
+  return (
+    <div className="overflow-hidden rounded-xl border border-border bg-card shadow-sm">
+      <div className="flex items-center gap-3 border-b border-border px-5 py-4">
+        <div className={cn("flex size-9 items-center justify-center rounded-lg text-primary-foreground", iconBg)}>
+          {icon}
+        </div>
+        <div>
+          <h3 className="font-semibold">{title}</h3>
+          {description && <p className="mt-0.5 text-xs text-muted-foreground">{description}</p>}
+        </div>
+      </div>
+      <div className="p-5">{children}</div>
+    </div>
+  );
+}
+
+function ThemeOption({
+  value,
+  label,
+  active,
+  icon,
+  onClick,
+}: {
+  value: string;
+  label: string;
+  active: boolean;
+  icon: React.ReactNode;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={cn(
+        "relative flex flex-1 flex-col items-center gap-2 rounded-xl border-2 px-3 py-4 transition-all",
+        active ? "border-primary bg-primary/10" : "border-border bg-card hover:border-muted-foreground"
+      )}
+    >
+      <div
+        className={cn(
+          "flex size-12 items-center justify-center rounded-xl",
+          value === "light" && "bg-muted",
+          value === "dark" && "bg-muted-foreground",
+          value === "system" && "bg-gradient-to-br from-muted to-muted-foreground"
+        )}
+      >
+        {icon}
+      </div>
+      <span className={cn("text-sm font-medium", active ? "text-primary" : "text-muted-foreground")}>
+        {label}
+      </span>
+      {active && (
+        <span className="absolute right-2 top-2 flex size-5 items-center justify-center rounded-full bg-primary text-primary-foreground">
+          <Check className="size-3" />
+        </span>
+      )}
+    </button>
+  );
+}
+
+export function SettingsPage() {
+  const { appearance, palette, setTheme: setAppTheme } = useTheme();
+  const [language, setLanguage] = useState("zh-CN");
+  const [notifications, setNotifications] = useState({
+    email: true,
+    push: true,
+    sms: false,
+  });
+
+  return (
+    <div className="flex flex-col overflow-hidden rounded-lg bg-muted/30 shadow-sm">
+      <div className="bg-primary px-6 py-5 text-primary-foreground">
+        <div className="flex items-center gap-3">
+          <div className="flex size-10 items-center justify-center rounded-xl bg-white/20">
+            <Settings className="size-5" />
+          </div>
+          <div>
+            <h1 className="text-xl font-semibold">系统设置</h1>
+            <p className="mt-0.5 text-sm text-primary-foreground/80">管理您的账户和系统偏好设置</p>
+          </div>
+        </div>
+      </div>
+
+      <div className="flex-1 overflow-y-auto p-4">
+        <div className="mx-auto max-w-3xl space-y-4">
+          <SettingSection
+            icon={<User className="size-5" />}
+            title="个人信息"
+            description="管理您的账户基本信息"
+            iconBg="bg-primary"
+          >
+            <div className="mb-5 flex items-center gap-4">
+              <div className="flex size-16 items-center justify-center rounded-2xl bg-primary text-xl font-bold text-primary-foreground">
+                A
+              </div>
+              <div className="flex-1">
+                <h4 className="text-lg font-semibold">Admin</h4>
+                <p className="text-sm text-muted-foreground">系统管理员</p>
+              </div>
+              <Button variant="secondary" size="sm">
+                编辑资料
+              </Button>
+            </div>
+            <div className="grid grid-cols-2 gap-4">
+              <div className="space-y-2">
+                <Label className="text-xs text-muted-foreground">用户名</Label>
+                <Input value="admin" disabled className="bg-muted" />
+              </div>
+              <div className="space-y-2">
+                <Label className="text-xs text-muted-foreground">邮箱地址</Label>
+                <Input value="admin@example.com" disabled className="bg-muted" />
+              </div>
+              <div className="space-y-2">
+                <Label className="text-xs text-muted-foreground">手机号码</Label>
+                <Input value="+86 138****8888" disabled className="bg-muted" />
+              </div>
+              <div className="space-y-2">
+                <Label className="text-xs text-muted-foreground">部门</Label>
+                <Input value="信息技术部" disabled className="bg-muted" />
+              </div>
+            </div>
+          </SettingSection>
+
+          <SettingSection
+            icon={<Bell className="size-5" />}
+            title="通知设置"
+            description="配置消息通知方式"
+            iconBg="bg-amber-500"
+          >
+            <div className="space-y-4">
+              <div className="flex items-center justify-between py-2">
+                <div>
+                  <Label className="font-medium">邮件通知</Label>
+                  <p className="text-xs text-muted-foreground">接收重要事项的邮件提醒</p>
+                </div>
+                <Switch
+                  checked={notifications.email}
+                  onCheckedChange={(v) => setNotifications({ ...notifications, email: v })}
+                />
+              </div>
+              <div className="flex items-center justify-between border-t border-border py-2">
+                <div>
+                  <Label className="font-medium">浏览器推送</Label>
+                  <p className="text-xs text-muted-foreground">在浏览器中接收实时通知</p>
+                </div>
+                <Switch
+                  checked={notifications.push}
+                  onCheckedChange={(v) => setNotifications({ ...notifications, push: v })}
+                />
+              </div>
+              <div className="flex items-center justify-between border-t border-border py-2">
+                <div>
+                  <Label className="font-medium">短信通知</Label>
+                  <p className="text-xs text-muted-foreground">接收紧急事项的短信提醒</p>
+                </div>
+                <Switch
+                  checked={notifications.sms}
+                  onCheckedChange={(v) => setNotifications({ ...notifications, sms: v })}
+                />
+              </div>
+            </div>
+          </SettingSection>
+
+          <SettingSection
+            icon={<Palette className="size-5" />}
+            title="外观设置"
+            description="自定义界面外观主题"
+            iconBg="bg-purple-500"
+          >
+            <div className="flex gap-3">
+              <ThemeOption
+                value="light"
+                label="浅色模式"
+                active={appearance === "light"}
+                onClick={() => setAppTheme({ appearance: "light" as Appearance })}
+                icon={<div className="size-6 rounded-full border-2 border-muted-foreground" />}
+              />
+              <ThemeOption
+                value="dark"
+                label="深色模式"
+                active={appearance === "dark"}
+                onClick={() => setAppTheme({ appearance: "dark" as Appearance })}
+                icon={<div className="size-6 rounded-full bg-muted-foreground" />}
+              />
+              <ThemeOption
+                value="system"
+                label="跟随系统"
+                active={appearance === "system"}
+                onClick={() => setAppTheme({ appearance: "system" as Appearance })}
+                icon={<div className="size-6 rounded-full bg-gradient-to-br from-muted to-muted-foreground" />}
+              />
+            </div>
+
+            <div className="mt-5 grid grid-cols-2 gap-4">
+              <div className="space-y-2">
+                <Label className="text-xs text-muted-foreground">配色</Label>
+                <Select
+                  value={palette}
+                  onValueChange={(v) => setAppTheme({ palette: v as ThemePalette })}
+                >
+                  <SelectTrigger><SelectValue /></SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="default">默认</SelectItem>
+                    <SelectItem value="blue">蓝色</SelectItem>
+                    <SelectItem value="green">绿色</SelectItem>
+                    <SelectItem value="violet">紫色</SelectItem>
+                    <SelectItem value="rose">玫红</SelectItem>
+                    <SelectItem value="amber">琥珀</SelectItem>
+                    <SelectItem value="fiori">Fiori</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+            </div>
+          </SettingSection>
+
+          <SettingSection
+            icon={<Globe className="size-5" />}
+            title="语言和地区"
+            description="设置界面语言和区域格式"
+            iconBg="bg-emerald-500"
+          >
+            <div className="grid grid-cols-2 gap-4">
+              <div className="space-y-2">
+                <Label className="text-xs text-muted-foreground">界面语言</Label>
+                <Select value={language} onValueChange={setLanguage}>
+                  <SelectTrigger><SelectValue /></SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="zh-CN">简体中文</SelectItem>
+                    <SelectItem value="zh-TW">繁體中文</SelectItem>
+                    <SelectItem value="en-US">English (US)</SelectItem>
+                    <SelectItem value="ja-JP">日本語</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+              <div className="space-y-2">
+                <Label className="text-xs text-muted-foreground">时区</Label>
+                <Select value="Asia/Shanghai" onValueChange={() => {}}>
+                  <SelectTrigger><SelectValue /></SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="Asia/Shanghai">(UTC+8) 中国标准时间</SelectItem>
+                    <SelectItem value="Asia/Tokyo">(UTC+9) 日本标准时间</SelectItem>
+                    <SelectItem value="America/New_York">(UTC-5) 美国东部时间</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+              <div className="space-y-2">
+                <Label className="text-xs text-muted-foreground">日期格式</Label>
+                <Select value="YYYY-MM-DD" onValueChange={() => {}}>
+                  <SelectTrigger><SelectValue /></SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="YYYY-MM-DD">2024-12-31</SelectItem>
+                    <SelectItem value="DD/MM/YYYY">31/12/2024</SelectItem>
+                    <SelectItem value="MM/DD/YYYY">12/31/2024</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+              <div className="space-y-2">
+                <Label className="text-xs text-muted-foreground">数字格式</Label>
+                <Select value="1,234.56" onValueChange={() => {}}>
+                  <SelectTrigger><SelectValue /></SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="1,234.56">1,234.56</SelectItem>
+                    <SelectItem value="1.234,56">1.234,56</SelectItem>
+                    <SelectItem value="1 234.56">1 234.56</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+            </div>
+          </SettingSection>
+
+          <SettingSection
+            icon={<Shield className="size-5" />}
+            title="安全设置"
+            description="管理账户安全选项"
+            iconBg="bg-destructive"
+          >
+            <div className="space-y-4">
+              <div className="flex items-center justify-between py-2">
+                <div>
+                  <span className="text-sm font-medium">修改密码</span>
+                  <p className="text-xs text-muted-foreground">上次修改：30 天前</p>
+                </div>
+                <Button variant="outline" size="sm">修改密码</Button>
+              </div>
+              <div className="flex items-center justify-between border-t border-border py-2">
+                <div>
+                  <span className="text-sm font-medium">双因素认证</span>
+                  <p className="text-xs text-muted-foreground">增强账户安全性</p>
+                </div>
+                <Button size="sm" variant="secondary" className="text-emerald-600">已启用</Button>
+              </div>
+              <div className="flex items-center justify-between border-t border-border py-2">
+                <div>
+                  <span className="text-sm font-medium">登录记录</span>
+                  <p className="text-xs text-muted-foreground">查看最近的登录活动</p>
+                </div>
+                <Button variant="outline" size="sm">查看记录</Button>
+              </div>
+            </div>
+          </SettingSection>
+        </div>
+      </div>
+    </div>
+  );
+}

package/templates/scaffold-default/packages/admin/src/providers/app-config.tsx

@@ -0,0 +1,50 @@
+/* eslint-disable react-refresh/only-export-components */
+"use client"
+
+import { createContext, useContext, type ReactNode } from "react"
+
+export type AppTitleConfig = {
+  icon: ReactNode
+  text: string
+}
+
+const defaultTitle: AppTitleConfig = {
+  icon: (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
+    </svg>
+  ),
+  text: "Admin",
+}
+
+const AppConfigContext = createContext<{ title: AppTitleConfig }>({
+  title: defaultTitle,
+})
+
+export function AppConfigProvider({
+  children,
+  title = defaultTitle,
+}: {
+  children: ReactNode
+  title?: AppTitleConfig
+}) {
+  return (
+    <AppConfigContext.Provider value={{ title }}>
+      {children}
+    </AppConfigContext.Provider>
+  )
+}
+
+export function useAppConfig() {
+  return useContext(AppConfigContext)
+}

package/templates/scaffold-default/packages/admin/src/providers/auth-provider.ts

@@ -0,0 +1,2 @@
+// Backward-compatible re-export: admin & mobile share the same backend auth provider from @scaffold/core.
+export { createBackendAuthProvider } from "@scaffold/core"

package/templates/scaffold-default/packages/admin/src/routes/auth.ts

@@ -0,0 +1,9 @@
+import { LOGIN_URL, USE_GUARD } from "@/app.config"
+import { createAuthClientMiddleware, createAuthorizationClientMiddleware } from "@scaffold/core"
+import { redirect } from "react-router"
+
+export const authorizationClientMiddleware = USE_GUARD ? createAuthorizationClientMiddleware() : (_args: unknown, next: () => Promise<unknown>) => { next() }
+
+export const middleware = [createAuthClientMiddleware(() => {
+  redirect(LOGIN_URL)
+}), authorizationClientMiddleware]

package/templates/scaffold-default/packages/admin/src/routes/index.ts

@@ -0,0 +1,85 @@
+import { USE_GUARD } from "@/app.config"
+import { createAuthClientMiddleware, createAuthorizationClientMiddleware } from "@scaffold/core"
+import { ReactNode } from "react"
+import { RouteObject } from "react-router"
+
+type ModuleExport = {
+  routes?: RouteConfig[]
+}
+
+/** 中间件函数类型（与 react-router 约定一致） */
+type MiddlewareFn = (
+  args: { request: Request; context: unknown },
+  next: () => Promise<unknown>
+) => Promise<unknown>
+
+/**
+ * 路由配置，支持树状结构：子路由定义在 children 中；与菜单对齐可配 icon / label / group。
+ * - path 为相对父级路径；index 为 true 时 path 可省略
+ * - 有 children 时，父级可不写 element，渲染时用 <Outlet /> 占位
+ * - anonymous / useGuard 用于在 getModulesContext 中自动注入 middleware，无需在模块里配置
+ * - group 从路由读取，用于菜单分区；groupOrder 指定该分区在菜单中的顺序（越小越靠前）
+ */
+export type RouteConfig = Omit<RouteObject, "children"> & {
+  label?: string
+  icon?: ReactNode
+  /** 是否允许匿名（不注入认证中间件） */
+  anonymous?: boolean
+  /** 是否注入授权中间件 */
+  useGuard?: boolean
+  /** 菜单分区（如 business / analytics / system），与 menu-layout 的 MenuItem.group 对应 */
+  group?: string
+  /** 同 groupName 的多条路由会合并为一个父菜单（如 MM-采购） */
+  groupName?: string
+  /** 分区在菜单中的顺序，数值越小越靠前；同分区取该分区内最小 groupOrder */
+  groupOrder?: number
+  /** 同级菜单顺序（同一 groupName 下多项时），数值越小越靠前 */
+  order?: number
+  children?: RouteConfig[]
+}
+
+const modules = import.meta.glob<ModuleExport>("./modules/*.ts", { eager: true })
+
+/** 按 RouteConfig 的 anonymous / useGuard 递归注入 middleware */
+function applyMiddlewareToRoutes(routes: RouteConfig[], middlewares: MiddlewareFn[]): RouteConfig[] {
+  return routes.map((route) => {
+    const { children, anonymous, useGuard, ...rest } = route
+    const middleware: MiddlewareFn[] = []
+
+    const requiresAuth = anonymous !== true
+
+    if (requiresAuth) {
+      middleware.push(middlewares[0] as MiddlewareFn)
+      if (useGuard !== false) {
+        middleware.push(middlewares[1] as MiddlewareFn)
+      }
+    }
+    const out: RouteConfig = { ...rest, anonymous, useGuard, middleware, children: undefined }
+    if (children?.length) {
+      out.children = applyMiddlewareToRoutes(children, middlewares)
+    }
+    return out
+  })
+}
+
+let _routes: RouteConfig[] = []
+
+export function getModulesContext(): {
+  routes: RouteConfig[]
+  middlewares: MiddlewareFn[]
+} {
+  const authClientMiddleware = createAuthClientMiddleware()
+  const authorizationClientMiddleware = USE_GUARD ? createAuthorizationClientMiddleware() : (_args: unknown, next: () => Promise<unknown>) => next()
+  if (_routes.length === 0) {
+    const routes: RouteConfig[] = []
+    for (const key of Object.keys(modules)) {
+      const mod = modules[key] as ModuleExport
+      if (mod?.routes?.length) routes.push(...mod.routes)
+    }
+    _routes = applyMiddlewareToRoutes(routes, [authClientMiddleware, authorizationClientMiddleware])
+  }
+  return {
+    routes: _routes,
+    middlewares: [authClientMiddleware, authorizationClientMiddleware]
+  }
+}

package/templates/scaffold-default/packages/admin/src/routes/menu.ts

@@ -0,0 +1,176 @@
+import { useMemo } from "react"
+import type { RouteConfig } from "./index"
+import { getModulesContext } from "./index"
+
+export interface MenuItem {
+  id: string
+  label: string
+  icon?: React.ReactNode
+  path?: string
+  children?: MenuItem[]
+  badge?: string | number
+  useGuard?: boolean
+  /** 菜单分区，从 route.group 读取，用于 menu-layout 分区展示与筛选 */
+  group?: string
+}
+
+const DEFAULT_GROUP_ORDER = 999
+
+/**
+ * 从路由读取 group：优先 group，兼容旧字段 groupKey（如 master-data 映射为 business）
+ */
+function getMenuGroup(r: RouteConfig): string {
+  const g = r.group
+  return g ?? "other"
+}
+
+/** 遍历路由树填充 path → RouteConfig，path 为完整路径（如 "/goods-receipt/create"）。 */
+function fillPathToRouteConfig(
+  routeList: RouteConfig[],
+  pathToRouteConfig: Map<string, RouteConfig>,
+  prefix = ""
+): void {
+  for (const r of routeList) {
+    const segment = r.path ?? ""
+    const fullPath = segment ? (prefix ? `${prefix}/${segment}` : `/${segment}`) : prefix || "/"
+    if (r.index) {
+      pathToRouteConfig.set(prefix || "/", r)
+    } else if (segment || fullPath === "/") {
+      pathToRouteConfig.set(fullPath, r)
+    }
+    if (r.children?.length) {
+      const nextPrefix = segment ? (prefix ? `${prefix}/${segment}` : `/${segment}`) : prefix
+      fillPathToRouteConfig(r.children, pathToRouteConfig, nextPrefix)
+    }
+  }
+}
+
+export type RoutesToMenuResult = {
+  menuItems: MenuItem[]
+  pathToRouteConfig: Map<string, RouteConfig>
+}
+
+/**
+ * 将路由配置转为菜单项，并生成 path→RouteConfig 映射（一次遍历出两个结果）。
+ * - group 从 route.group 读取；分区顺序由 route.groupOrder 决定
+ * - 同 groupName 的多个顶层路由合并为一个父菜单（如 MM-采购）
+ * @param routes 聚合后的 RouteConfig[]
+ * @param options.mainItem 首页项（path: "/", group: "main"）
+ */
+export function routesToMenu(
+  routeList: RouteConfig[],
+  options?: { mainItem?: MenuItem }
+): RoutesToMenuResult {
+  const pathToRouteConfig = new Map<string, RouteConfig>()
+  fillPathToRouteConfig(routeList, pathToRouteConfig)
+
+  const topLevel = routeList.filter((r) => r.path !== undefined && !r.index)
+  const byGroupKey = new Map<string, RouteConfig[]>()
+  for (const r of topLevel) {
+    const menuGroup = getMenuGroup(r)
+    const gn = r.groupName ?? r.path ?? ""
+    const key = `${menuGroup}|${gn}`
+    if (!byGroupKey.has(key)) byGroupKey.set(key, [])
+    byGroupKey.get(key)!.push(r)
+  }
+
+  const menuItems: MenuItem[] = []
+  if (options?.mainItem) menuItems.push(options.mainItem)
+
+  /** 每个分区内：(itemOrder, menuItem)[]，分区内按 itemOrder 排序 */
+  const groupToItems = new Map<string, { order: number; item: MenuItem }[]>()
+  const groupOrderMin = new Map<string, number>()
+  for (const [key, configs] of byGroupKey) {
+    const [menuGroup, groupName] = key.split("|")
+    const itemOrder = Math.min(
+      ...configs.map((r) => r.groupOrder ?? DEFAULT_GROUP_ORDER)
+    )
+    if (!groupToItems.has(menuGroup)) {
+      groupToItems.set(menuGroup, [])
+      groupOrderMin.set(menuGroup, itemOrder)
+    }
+    groupOrderMin.set(
+      menuGroup,
+      Math.min(groupOrderMin.get(menuGroup)!, itemOrder)
+    )
+
+    if (configs.length > 1) {
+      const sorted = [...configs].sort(
+        (a, b) => (a.order ?? DEFAULT_GROUP_ORDER) - (b.order ?? DEFAULT_GROUP_ORDER)
+      )
+      const first = sorted[0]
+      const parent: MenuItem = {
+        id: slugify(groupName),
+        label: groupName,
+        icon: first.icon,
+        group: menuGroup,
+        children: sorted.map((r) => ({
+          id: r.path!.replace(/\//g, "-"),
+          label: r.label ?? r.path ?? "",
+          path: "/" + r.path,
+        })),
+      }
+      groupToItems.get(menuGroup)!.push({ order: itemOrder, item: parent })
+    } else {
+      const r = configs[0]
+      if (r.children?.length) {
+        const listChildren = r.children.filter(
+          (c) => c.path && !c.path.includes(":")
+        )
+        const parent: MenuItem = {
+          id: r.path ?? slugify(groupName),
+          label: r.groupName ?? r.label ?? r.path ?? "",
+          icon: r.icon,
+          group: menuGroup,
+          children: listChildren.map((c) => ({
+            id: (c.path ?? "").replace(/\//g, "-"),
+            label: c.label ?? c.path ?? "",
+            path: "/" + (r.path ? r.path + "/" : "") + c.path,
+          })),
+        }
+        groupToItems.get(menuGroup)!.push({ order: itemOrder, item: parent })
+      } else {
+        groupToItems.get(menuGroup)!.push({
+          order: itemOrder,
+          item: {
+            id: (r.path ?? "").replace(/\//g, "-"),
+            label: r.label ?? r.path ?? "",
+            icon: r.icon,
+            path: "/" + (r.path ?? ""),
+            group: menuGroup,
+          },
+        })
+      }
+    }
+  }
+
+  const sortedGroupKeys = [...groupToItems.keys()].sort(
+    (a, b) =>
+      (groupOrderMin.get(a) ?? DEFAULT_GROUP_ORDER) -
+      (groupOrderMin.get(b) ?? DEFAULT_GROUP_ORDER)
+  )
+  for (const g of sortedGroupKeys) {
+    const entries = groupToItems.get(g) ?? []
+    const items = entries
+      .sort((a, b) => a.order - b.order)
+      .map((e) => e.item)
+    menuItems.push(...items)
+  }
+
+  return { menuItems, pathToRouteConfig }
+}
+
+export type UseMenuItemsOptions = { mainItem?: MenuItem }
+
+/**
+ * 根据当前路由配置生成菜单项与 path→RouteConfig 映射（声明式 hook）。
+ * 若 options 含动态值（如 i18n），请用 useMemo 包住 options 以保持引用稳定。
+ */
+export function useMenuItems(options?: UseMenuItemsOptions): RoutesToMenuResult {
+  const { routes } = getModulesContext()
+  return useMemo(() => routesToMenu(routes, options), [routes, options])
+}
+
+function slugify(s: string): string {
+  return s.replace(/\s+/g, "-").replace(/[^\w\u4e00-\u9fa5-]/g, "") || "item"
+}