create-windy 0.3.19 → 0.4.1

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);

package/template/apps/web/src/router/shared-scaffold-neutrality.webtest.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "vitest";
 import type { RouteRecordRaw } from "vue-router";
 import routerSource from "./index.ts?raw";
 import fixtureSource from "./router-test-fixtures.ts?raw";
+import compositionSource from "../app/web-composition.ts?raw";
 import { collectRouteAccess } from "./router-test-fixtures";
 
 describe("Router shared-scaffold 中性契约", () => {
@@ -25,16 +26,21 @@ describe("Router shared-scaffold 中性契约", () => {
     expect(routerSource).toContain("component: errorPageComponents.network");
   });
 
-  test("平台路由组合 project-owned 业务注册表且保持在兜底页之前", () => {
+  test("平台路由组合 project-owned Admin UI 声明且保持在兜底页之前", () => {
     expect(routerSource).toContain(
-      'import { installedBusinessAdminRoutes } from "@/app/business-routes";',
+      'import { webAdminUiComposition } from "./web-composition-host";',
     );
     const businessIndex = routerSource.indexOf(
-      "...materializeBusinessAdminRoutes(installedBusinessAdminRoutes)",
+      "...materializeBusinessAdminRoutes(webAdminUiComposition.modules)",
+    );
+    const fallbackIndex = routerSource.indexOf(
+      "path: reservedWebRoutePaths.notFound",
     );
-    const fallbackIndex = routerSource.indexOf('path: "/:pathMatch(.*)*"');
     expect(businessIndex).toBeGreaterThan(0);
     expect(businessIndex).toBeLessThan(fallbackIndex);
+    expect(compositionSource).toContain("defineWebComposition");
+    expect(compositionSource).not.toContain("featureKey");
+    expect(compositionSource).not.toContain("permissionKey");
   });
 
   test("测试快照只从项目注入路由递归派生访问键", () => {

package/template/apps/web/src/router/web-composition-host.ts

@@ -0,0 +1,20 @@
+import {
+  systemAdminUiManifests,
+  validateProjectModuleAssembly,
+} from "@southwind-ai/modules/admin-ui";
+import { installedAdminUiModules } from "virtual:windy-admin-ui-modules";
+import moduleAssembly from "../../../../windy.modules.json";
+import { webComposition } from "../app/web-composition";
+import { resolveAdminUiComposition } from "./admin-ui-composition";
+
+/**
+ * Host 对项目组合声明的唯一解析入口。
+ *
+ * Router、Navigation 和 Vite 构建门禁必须消费同一结果，避免运行时与构建时规则漂移。
+ */
+export const webAdminUiComposition = resolveAdminUiComposition({
+  declaration: webComposition,
+  assembly: validateProjectModuleAssembly(moduleAssembly),
+  platformModules: systemAdminUiManifests(),
+  installedModules: installedAdminUiModules,
+});

package/template/apps/web/src/services/work-order-api.ts

@@ -0,0 +1,16 @@
+import type {
+  WorkOrderListQuery,
+  WorkOrderPage,
+} from "@southwind-ai/example-work-order/contract";
+import { apiRequest } from "./http";
+
+export function listWorkOrders(query: WorkOrderListQuery = {}) {
+  const params = new URLSearchParams();
+  if (query.page !== undefined) params.set("page", String(query.page));
+  if (query.pageSize !== undefined) {
+    params.set("pageSize", String(query.pageSize));
+  }
+  if (query.q?.trim()) params.set("q", query.q.trim());
+  const search = params.toString();
+  return apiRequest<WorkOrderPage>(`/work-orders${search ? `?${search}` : ""}`);
+}

package/template/apps/web/src/services/work-order-api.webtest.ts

@@ -0,0 +1,21 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  request: vi.fn(),
+}));
+
+vi.mock("./http", () => ({ apiRequest: mocks.request }));
+
+import { listWorkOrders } from "./work-order-api";
+
+describe("示例工单 API", () => {
+  beforeEach(() => mocks.request.mockReset());
+
+  test("列表查询保留分页与搜索条件", () => {
+    listWorkOrders({ page: 2, pageSize: 20, q: "登录" });
+
+    expect(mocks.request).toHaveBeenCalledWith(
+      "/work-orders?page=2&pageSize=20&q=%E7%99%BB%E5%BD%95",
+    );
+  });
+});

package/template/apps/web/src/virtual-admin-ui-modules.d.ts

@@ -0,0 +1,5 @@
+declare module "virtual:windy-admin-ui-modules" {
+  import type { AdminUiModule } from "./router/admin-ui-composition";
+
+  export const installedAdminUiModules: readonly AdminUiModule[];
+}