create-windy 0.3.18 → 0.4.0

package/template/apps/web/src/router/admin-ui-module-registry-plugin.ts

@@ -0,0 +1,55 @@
+import type { ProjectModuleAssembly } from "@southwind-ai/modules/admin-ui";
+
+interface AdminUiModuleRegistryPlugin {
+  readonly name: string;
+  readonly enforce: "pre";
+  resolveId(id: string): string | undefined;
+  load(id: string): string | undefined;
+}
+
+export const adminUiModuleRegistryId = "virtual:windy-admin-ui-modules";
+const resolvedRegistryId = `\0${adminUiModuleRegistryId}`;
+
+export function adminUiModuleRegistryPlugin(
+  assembly: ProjectModuleAssembly,
+): AdminUiModuleRegistryPlugin {
+  const source = renderAdminUiModuleRegistry(assembly);
+  return {
+    name: "windy-admin-ui-module-registry",
+    enforce: "pre",
+    resolveId(id) {
+      return id === adminUiModuleRegistryId ? resolvedRegistryId : undefined;
+    },
+    load(id) {
+      return id === resolvedRegistryId ? source : undefined;
+    },
+  };
+}
+
+export function renderAdminUiModuleRegistry(
+  assembly: ProjectModuleAssembly,
+): string {
+  const packages = enabledPackageRegistrations(assembly);
+  const imports = packages.map(
+    ({ package: packageName }, index) =>
+      `import { windyAdminUiModule as module${index} } from ${JSON.stringify(
+        `${packageName}/admin`,
+      )};`,
+  );
+  const identifiers = packages.map((_, index) => `module${index}`).join(", ");
+  return [
+    ...imports,
+    `export const installedAdminUiModules = [${identifiers}];`,
+    "",
+  ].join("\n");
+}
+
+function enabledPackageRegistrations(assembly: ProjectModuleAssembly) {
+  return assembly.modules.filter(
+    (
+      entry,
+    ): entry is typeof entry & {
+      readonly package: string;
+    } => entry.enabled && entry.package !== null,
+  );
+}

package/template/apps/web/src/router/admin-ui-module-registry-plugin.webtest.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "vitest";
+import { validateProjectModuleAssembly } from "@southwind-ai/modules/admin-ui";
+import { renderAdminUiModuleRegistry } from "./admin-ui-module-registry-plugin";
+
+describe("Admin UI package 虚拟注册表", () => {
+  test("只静态导入已启用 package 的标准 ./admin 导出", () => {
+    const source = renderAdminUiModuleRegistry({
+      schemaVersion: 1,
+      modules: [
+        entry("enabled", "@customer/enabled", true, 100),
+        entry("disabled", "@customer/disabled", false, 200),
+        entry("system", null, true, 300),
+      ],
+    });
+
+    expect(source).toContain('from "@customer/enabled/admin";');
+    expect(source).not.toContain("@customer/disabled");
+    expect(source).not.toContain("system/admin");
+    expect(source).toContain("windyAdminUiModule as module0");
+  });
+
+  test("无效装配清单在 Vite 解析前 fail closed", () => {
+    expect(() =>
+      validateProjectModuleAssembly({
+        schemaVersion: 1,
+        modules: [entry("one", "@customer/one", true, -1)],
+      }),
+    ).toThrow("order 无效");
+  });
+});
+
+function entry(
+  name: string,
+  packageName: string | null,
+  enabled: boolean,
+  order: number,
+) {
+  return {
+    name,
+    package: packageName,
+    enabled,
+    order,
+    admin: { visible: true },
+    config: {},
+  };
+}

package/template/apps/web/src/router/business-routes.ts

@@ -1,23 +1,39 @@
 import type { RouteRecordRaw } from "vue-router";
-import type { BusinessAdminRouteRegistration } from "@/app/business-routes";
+import type { AdminUiModule } from "./admin-ui-composition";
+import { isolateAdminPageLoader } from "./admin-extension-loader";
 
 export function materializeBusinessAdminRoutes(
-  registrations: readonly BusinessAdminRouteRegistration[],
+  modules: readonly AdminUiModule[],
 ): RouteRecordRaw[] {
-  assertBusinessAdminRouteRegistrations(registrations);
-  return registrations.map((registration) => ({
-    path: registration.path,
-    name: registration.name,
-    component: registration.component,
-    props: registration.props,
-    meta: {
-      title: registration.title,
-      layout: "admin",
-      businessRouteKey: registration.key,
-      featureKey: registration.featureKey,
-      permissionKey: registration.permissionKey,
-    },
-  }));
+  return modules.flatMap((module) =>
+    module.manifest.adminRoutes.map((definition) => {
+      const binding = module.pages.find(
+        ({ routeKey }) => routeKey === definition.key,
+      );
+      if (!binding) {
+        throw new Error(
+          `${module.manifest.name} 缺少 Admin Route 页面绑定：${definition.key}`,
+        );
+      }
+      const guarded = definition.directAccess !== "authenticated";
+      return {
+        path: definition.path,
+        name: definition.key,
+        component: isolateAdminPageLoader(
+          module.manifest.name,
+          definition.key,
+          binding.load,
+        ),
+        meta: {
+          title: definition.title,
+          layout: "admin",
+          businessRouteKey: definition.key,
+          featureKey: guarded ? definition.featureKey : undefined,
+          permissionKey: guarded ? definition.permissionKey : undefined,
+        },
+      };
+    }),
+  );
 }
 
 export function assertNoRouteCollisions(
@@ -37,32 +53,3 @@ export function assertNoRouteCollisions(
     names.add(route.name);
   }
 }
-
-function assertBusinessAdminRouteRegistrations(
-  registrations: readonly BusinessAdminRouteRegistration[],
-): void {
-  const keys = new Set<string>();
-  for (const registration of registrations) {
-    for (const [field, value] of [
-      ["key", registration.key],
-      ["path", registration.path],
-      ["title", registration.title],
-      ["featureKey", registration.featureKey],
-      ["permissionKey", registration.permissionKey],
-    ] as const) {
-      if (!value.trim()) {
-        throw new Error(`业务 Web Route 的 ${field} 不能为空`);
-      }
-    }
-    if (!registration.path.startsWith("/")) {
-      throw new Error(`业务 Web Route 必须使用绝对路径：${registration.path}`);
-    }
-    if (registration.path.includes(":pathMatch")) {
-      throw new Error(`业务 Web Route 不能注册兜底路径：${registration.path}`);
-    }
-    if (keys.has(registration.key)) {
-      throw new Error(`业务 Web Route Key 重复：${registration.key}`);
-    }
-    keys.add(registration.key);
-  }
-}

package/template/apps/web/src/router/business-routes.webtest.ts

@@ -3,24 +3,17 @@ import {
   assertNoRouteCollisions,
   materializeBusinessAdminRoutes,
 } from "./business-routes";
+import type { AdminUiModule } from "./admin-ui-composition";
 
 describe("project-owned 业务路由接缝", () => {
-  test("统一生成带 Feature 与 RBAC Guard 的管理路由", () => {
-    const [route] = materializeBusinessAdminRoutes([
-      {
-        key: "case.record",
-        path: "/cases",
-        name: "case-records",
-        title: "案件",
-        component: {},
-        featureKey: "case.record",
-        permissionKey: "case.record.read",
-      },
-    ]);
+  test("只用 routeKey 和隔离后的 lazy loader 绑定 Manifest 路由", async () => {
+    const load = async () => ({ default: {} });
+    const [route] = materializeBusinessAdminRoutes([adminUiModule(load)]);
 
     expect(route).toMatchObject({
       path: "/cases",
-      name: "case-records",
+      name: "case.record",
+      component: expect.any(Function),
       meta: {
         title: "案件",
         layout: "admin",
@@ -29,32 +22,21 @@ describe("project-owned 业务路由接缝", () => {
         permissionKey: "case.record.read",
       },
     });
+    expect(
+      await (route!.component as AdminUiModule["pages"][number]["load"])(),
+    ).toEqual({ default: {} });
   });
 
-  test("拒绝空 Guard、重复 Key 与兜底路径", () => {
-    expect(() =>
-      materializeBusinessAdminRoutes([
-        {
-          key: "case.record",
-          path: "/cases",
-          title: "案件",
-          component: {},
-          featureKey: "",
-          permissionKey: "case.record.read",
-        },
-      ]),
-    ).toThrow("featureKey 不能为空");
-    expect(() =>
-      materializeBusinessAdminRoutes([
-        registration("/cases"),
-        registration("/other"),
-      ]),
-    ).toThrow("业务 Web Route Key 重复");
-    expect(() =>
-      materializeBusinessAdminRoutes([
-        registration("/:pathMatch(.*)*"),
-      ]),
-    ).toThrow("不能注册兜底路径");
+  test("authenticated 路由不附加 Feature 与 Permission Guard", () => {
+    const module = adminUiModule(
+      async () => ({ default: {} }),
+      "authenticated",
+    );
+
+    const [route] = materializeBusinessAdminRoutes([module]);
+
+    expect(route?.meta?.featureKey).toBeUndefined();
+    expect(route?.meta?.permissionKey).toBeUndefined();
   });
 
   test("组合时拒绝与平台路由重复的路径或名称", () => {
@@ -73,13 +55,27 @@ describe("project-owned 业务路由接缝", () => {
   });
 });
 
-function registration(path: string) {
+function adminUiModule(
+  load: AdminUiModule["pages"][number]["load"],
+  directAccess: "guarded" | "authenticated" = "guarded",
+): AdminUiModule {
   return {
-    key: "case.record",
-    path,
-    title: "案件",
-    component: {},
-    featureKey: "case.record",
-    permissionKey: "case.record.read",
+    hostRange: "^0.1.0",
+    manifest: {
+      name: "case",
+      version: "1.2.3",
+      adminRoutes: [
+        {
+          key: "case.record",
+          path: "/cases",
+          title: "案件",
+          surface: "sidebar",
+          directAccess,
+          featureKey: "case.record",
+          permissionKey: "case.record.read",
+        },
+      ],
+    },
+    pages: [{ routeKey: "case.record", load }],
   };
 }

package/template/apps/web/src/router/index.ts

@@ -4,9 +4,9 @@ import {
   type RouterHistory,
   type RouteRecordRaw,
 } from "vue-router";
+import type { Component } from "vue";
 import DashboardPage from "@/pages/dashboard/DashboardPage.vue";
 import HomePage from "@/app/home/HomePage.vue";
-import { installedBusinessAdminRoutes } from "@/app/business-routes";
 import { loginPageComponent } from "@/app/auth/login-page";
 import { errorPageComponents } from "@/app/error-pages";
 import AccessDeniedPage from "@/pages/AccessDeniedPage.vue";
@@ -29,7 +29,6 @@ import PersonalSettingsPage from "@/pages/profile/PersonalSettingsPage.vue";
 // @windy-module system.configuration begin
 import ModuleConfigurationPage from "@/pages/configuration/ModuleConfigurationPage.vue";
 // @windy-module system.configuration end
-import type { SystemResourceKey } from "@/pages/system/resource-config";
 import { useAccessSnapshot } from "@/composables/useAccessSnapshot";
 import {
   useAuthSession,
@@ -50,6 +49,12 @@ import {
   manifestAdminRoute,
   validateWebModuleComposition,
 } from "./manifest-routes";
+import {
+  platformAdminRouteBindings,
+  type PlatformAdminPageKey,
+} from "./platform-admin-route-bindings";
+import { reservedWebRoutePaths } from "./reserved-route-paths";
+import { webAdminUiComposition } from "./web-composition-host";
 
 export interface RouterAccessProvider {
   refresh(): Promise<WebAccessSnapshot>;
@@ -66,46 +71,70 @@ export interface RouterAuthProvider {
   clear(): void;
 }
 
-const systemRoute = (
-  key: string,
-  resourceKey: SystemResourceKey,
-): RouteRecordRaw =>
-  manifestAdminRoute(key, {
-    component: SystemResourceRoutePage,
-    props: { resourceKey },
+const platformAdminPageComponents: Partial<
+  Record<PlatformAdminPageKey, Component>
+> = {
+  resource: SystemResourceRoutePage,
+  profile: PersonalSettingsPage,
+  // @windy-module system.settings begin
+  settings: GlobalSettingsPage,
+  // @windy-module system.settings end
+  // @windy-module system.license begin
+  license: LicensePage,
+  // @windy-module system.license end
+  // @windy-module system.notification begin
+  notification: SystemNotificationsPage,
+  // @windy-module system.notification end
+  // @windy-module system.operations begin
+  operations: SystemOperationsPage,
+  // @windy-module system.operations end
+  // @windy-module system.configuration begin
+  configuration: ModuleConfigurationPage,
+  // @windy-module system.configuration end
+};
+
+const platformAdminRoutes = platformAdminRouteBindings.map((binding) => {
+  const component = platformAdminPageComponents[binding.page];
+  if (!component) {
+    throw new Error(`平台 Admin 页面未绑定：${binding.routeKey}`);
+  }
+  return manifestAdminRoute(binding.routeKey, {
+    component,
+    name: binding.name,
+    ...(binding.resourceKey
+      ? { props: { resourceKey: binding.resourceKey } }
+      : {}),
   });
+});
 
-export const routes: RouteRecordRaw[] = [
+const declaredRoutes: RouteRecordRaw[] = [
   {
-    path: "/login",
+    path: reservedWebRoutePaths.login,
     name: "login",
     component: loginPageComponent,
     meta: { title: "登录", layout: "auth", public: true, guestOnly: true },
   },
   {
-    path: "/change-password",
+    path: reservedWebRoutePaths.changePassword,
     name: "change-password",
     component: ChangePasswordPage,
     meta: { title: "修改密码", layout: "auth" },
   },
   {
-    path: "/",
+    path: reservedWebRoutePaths.home,
     name: "home",
     component: HomePage,
     meta: { title: "首页", layout: "app" },
   },
   {
-    path: "/admin",
+    path: reservedWebRoutePaths.adminHome,
     name: "admin-home",
     component: DashboardPage,
     meta: { title: "工作台", layout: "admin" },
   },
-  // @windy-module system.settings begin
-  manifestAdminRoute("system.settings", { component: GlobalSettingsPage }),
-  // @windy-module system.settings end
-  manifestAdminRoute("system.profile", { component: PersonalSettingsPage }),
+  ...platformAdminRoutes,
   {
-    path: "/access-denied",
+    path: reservedWebRoutePaths.accessDenied,
     name: "access-denied",
     component: AccessDeniedPage,
     props: (route) => ({
@@ -115,7 +144,7 @@ export const routes: RouteRecordRaw[] = [
     meta: { title: "无法访问", layout: "auth" },
   },
   {
-    path: "/service-unavailable",
+    path: reservedWebRoutePaths.serviceUnavailable,
     name: "service-unavailable",
     component: ServiceUnavailablePage,
     props: (route) => ({
@@ -125,7 +154,7 @@ export const routes: RouteRecordRaw[] = [
     meta: { title: "服务暂不可用", layout: "auth", public: true },
   },
   {
-    path: "/error/internal",
+    path: reservedWebRoutePaths.internalError,
     name: "internal-error",
     component: errorPageComponents.internal,
     props: (route) => ({
@@ -141,7 +170,7 @@ export const routes: RouteRecordRaw[] = [
     },
   },
   {
-    path: "/error/maintenance",
+    path: reservedWebRoutePaths.maintenance,
     name: "maintenance",
     component: errorPageComponents.maintenance,
     props: (route) => ({
@@ -157,7 +186,7 @@ export const routes: RouteRecordRaw[] = [
     },
   },
   {
-    path: "/error/network",
+    path: reservedWebRoutePaths.networkError,
     name: "network-error",
     component: errorPageComponents.network,
     props: (route) => ({
@@ -172,37 +201,9 @@ export const routes: RouteRecordRaw[] = [
       errorPage: true,
     },
   },
-  systemRoute("system.user", "users"),
-  systemRoute("system.role", "roles"),
-  systemRoute("system.department", "departments"),
-  systemRoute("system.menu", "menus"),
-  systemRoute("system.dictionary", "dictionaries"),
-  systemRoute("system.feature", "features"),
-  // @windy-module system.license begin
-  manifestAdminRoute("system.license", {
-    name: "runtime-license",
-    component: LicensePage,
-  }),
-  // @windy-module system.license end
-  // @windy-module system.audit begin
-  systemRoute("system.audit", "auditLogs"),
-  // @windy-module system.audit end
-  // @windy-module system.notification begin
-  manifestAdminRoute("system.notification", {
-    component: SystemNotificationsPage,
-  }),
-  // @windy-module system.notification end
-  // @windy-module system.operations begin
-  manifestAdminRoute("system.ops", { component: SystemOperationsPage }),
-  // @windy-module system.operations end
-  // @windy-module system.configuration begin
-  manifestAdminRoute("system.config", {
-    component: ModuleConfigurationPage,
-  }),
-  // @windy-module system.configuration end
-  ...materializeBusinessAdminRoutes(installedBusinessAdminRoutes),
+  ...materializeBusinessAdminRoutes(webAdminUiComposition.modules),
   {
-    path: "/:pathMatch(.*)*",
+    path: reservedWebRoutePaths.notFound,
     name: "not-found",
     component: errorPageComponents.notFound,
     props: (route) => ({
@@ -218,8 +219,17 @@ export const routes: RouteRecordRaw[] = [
   },
 ];
 
+validateWebModuleComposition(declaredRoutes);
+
+export const routes = declaredRoutes.filter((route) => {
+  const routeKey = route.meta?.manifestRouteKey;
+  return (
+    typeof routeKey !== "string" ||
+    webAdminUiComposition.activePlatformRouteKeys.has(routeKey)
+  );
+});
+
 assertNoRouteCollisions(routes);
-validateWebModuleComposition(routes);
 
 export function createAppRouter(
   history: RouterHistory = createWebHistory(),

package/template/apps/web/src/router/manifest-routes.ts

@@ -1,12 +1,11 @@
 import {
-  systemModuleManifests,
-  validateModuleComposition,
+  systemAdminUiManifests,
   type ModuleAdminRouteDefinition,
-} from "@southwind-ai/modules";
+} from "@southwind-ai/modules/admin-ui";
 import type { Component } from "vue";
 import type { RouteRecordRaw } from "vue-router";
 
-export const webModuleManifests = systemModuleManifests();
+export const webModuleManifests = systemAdminUiManifests();
 
 const adminRouteByKey = new Map(
   webModuleManifests.flatMap((module) =>
@@ -44,12 +43,33 @@ export function manifestAdminRoute(
 export function validateWebModuleComposition(
   routes: readonly RouteRecordRaw[],
 ): void {
-  validateModuleComposition(webModuleManifests, {
-    adminRoutes: routes.flatMap((route) => {
+  validatePlatformAdminRouteKeys(
+    routes.flatMap((route) => {
       const key = route.meta?.manifestRouteKey;
       return typeof key === "string" ? [key] : [];
     }),
-  });
+  );
+}
+
+export function validatePlatformAdminRouteKeys(
+  implementedKeys: readonly string[],
+): void {
+  const declared = new Set(adminRouteByKey.keys());
+  const implemented = new Set<string>();
+  for (const key of implementedKeys) {
+    if (!declared.has(key)) {
+      throw new Error(`Admin Route 实现未在窄 Manifest 声明：${key}`);
+    }
+    if (implemented.has(key)) {
+      throw new Error(`Admin Route Handler Key 重复：${key}`);
+    }
+    implemented.add(key);
+  }
+  for (const key of declared) {
+    if (!implemented.has(key)) {
+      throw new Error(`Admin Route ${key} 缺少 Handler`);
+    }
+  }
 }
 
 function findAdminRoute(key: string): ModuleAdminRouteDefinition {

package/template/apps/web/src/router/manifest-routes.webtest.ts

@@ -47,7 +47,15 @@ describe("Manifest 菜单与 Router 契约", () => {
     expect(definitions.some(({ path }) => path === "/admin/profile")).toBe(
       true,
     );
-    expect(definitions.some(({ path }) => path === "/work-orders")).toBe(false);
-    expect(routes.some(({ path }) => path === "/work-orders")).toBe(false);
+    expect(definitions.some(({ path }) => path === "/admin/work-orders")).toBe(
+      false,
+    );
+    // @windy-module work-order begin
+    expect(
+      routes.find(
+        ({ meta }) => meta?.businessRouteKey === "work-order.ticket.list",
+      )?.path,
+    ).toBe("/admin/work-orders");
+    // @windy-module work-order end
   });
 });

package/template/apps/web/src/router/platform-admin-route-bindings.ts

@@ -0,0 +1,58 @@
+import type { SystemResourceKey } from "@/pages/system/resource-config";
+
+export type PlatformAdminPageKey =
+  | "resource"
+  | "settings"
+  | "profile"
+  | "license"
+  | "notification"
+  | "operations"
+  | "configuration";
+
+export interface PlatformAdminRouteBinding {
+  readonly routeKey: string;
+  readonly page: PlatformAdminPageKey;
+  readonly resourceKey?: SystemResourceKey;
+  readonly name?: string;
+}
+
+export const platformAdminRouteBindings: readonly PlatformAdminRouteBinding[] =
+  [
+    { routeKey: "system.profile", page: "profile" },
+    // @windy-module system.settings begin
+    { routeKey: "system.settings", page: "settings" },
+    // @windy-module system.settings end
+    { routeKey: "system.user", page: "resource", resourceKey: "users" },
+    { routeKey: "system.role", page: "resource", resourceKey: "roles" },
+    {
+      routeKey: "system.department",
+      page: "resource",
+      resourceKey: "departments",
+    },
+    { routeKey: "system.menu", page: "resource", resourceKey: "menus" },
+    {
+      routeKey: "system.dictionary",
+      page: "resource",
+      resourceKey: "dictionaries",
+    },
+    { routeKey: "system.feature", page: "resource", resourceKey: "features" },
+    // @windy-module system.license begin
+    {
+      routeKey: "system.license",
+      page: "license",
+      name: "runtime-license",
+    },
+    // @windy-module system.license end
+    // @windy-module system.audit begin
+    { routeKey: "system.audit", page: "resource", resourceKey: "auditLogs" },
+    // @windy-module system.audit end
+    // @windy-module system.notification begin
+    { routeKey: "system.notification", page: "notification" },
+    // @windy-module system.notification end
+    // @windy-module system.operations begin
+    { routeKey: "system.ops", page: "operations" },
+    // @windy-module system.operations end
+    // @windy-module system.configuration begin
+    { routeKey: "system.config", page: "configuration" },
+    // @windy-module system.configuration end
+  ];

package/template/apps/web/src/router/reserved-route-paths.ts

@@ -0,0 +1,14 @@
+export const reservedWebRoutePaths = {
+  login: "/login",
+  changePassword: "/change-password",
+  home: "/",
+  adminHome: "/admin",
+  accessDenied: "/access-denied",
+  serviceUnavailable: "/service-unavailable",
+  internalError: "/error/internal",
+  maintenance: "/error/maintenance",
+  networkError: "/error/network",
+  notFound: "/:pathMatch(.*)*",
+} as const;
+
+export const reservedWebRoutePathList = Object.values(reservedWebRoutePaths);