create-windy 0.3.18 → 0.4.0

package/template/apps/web/src/router/admin-extension-loader.ts

@@ -0,0 +1,44 @@
+import { defineComponent, h, type Component } from "vue";
+import type { AdminPageBinding } from "./admin-ui-composition";
+
+export function isolateAdminPageLoader(
+  moduleName: string,
+  routeKey: string,
+  load: AdminPageBinding["load"],
+): AdminPageBinding["load"] {
+  return async () => {
+    try {
+      const loaded = await load();
+      if (!loaded?.default) {
+        throw new Error("模块页面缺少 default export");
+      }
+      return loaded;
+    } catch (error) {
+      console.error("Admin Extension 页面加载失败", {
+        moduleName,
+        routeKey,
+        error,
+      });
+      return {
+        default: failureComponent(moduleName, routeKey),
+      };
+    }
+  };
+}
+
+function failureComponent(moduleName: string, routeKey: string): Component {
+  return defineComponent({
+    name: "AdminExtensionLoadFailure",
+    setup() {
+      return () =>
+        h("main", { class: "space-y-3 p-6" }, [
+          h("h1", { class: "text-xl font-semibold" }, "模块页面暂不可用"),
+          h(
+            "p",
+            { class: "text-sm text-muted-foreground" },
+            `模块 ${moduleName} 的页面 ${routeKey} 加载失败。其他管理功能仍可继续使用。`,
+          ),
+        ]);
+    },
+  });
+}

package/template/apps/web/src/router/admin-extension-loader.webtest.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test, vi } from "vitest";
+import { isolateAdminPageLoader } from "./admin-extension-loader";
+
+describe("Admin Extension 页面隔离", () => {
+  test("正常 loader 原样返回页面组件", async () => {
+    const page = { name: "CasePage" };
+    const load = isolateAdminPageLoader("case", "case.record", async () => ({
+      default: page,
+    }));
+
+    expect(await load()).toEqual({ default: page });
+  });
+
+  test("loader 失败时返回 Admin 壳内故障页而不是抛出", async () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const load = isolateAdminPageLoader("case", "case.record", async () => {
+      throw new Error("secret stack");
+    });
+
+    const result = await load();
+
+    expect(result.default).toMatchObject({
+      name: "AdminExtensionLoadFailure",
+    });
+    expect(error).toHaveBeenCalledOnce();
+  });
+
+  test("loader 缺少 default export 时同样隔离为故障页", async () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const load = isolateAdminPageLoader(
+      "case",
+      "case.record",
+      async () => ({}) as never,
+    );
+
+    const result = await load();
+
+    expect(result.default).toMatchObject({
+      name: "AdminExtensionLoadFailure",
+    });
+    expect(error).toHaveBeenCalledWith(
+      "Admin Extension 页面加载失败",
+      expect.objectContaining({
+        moduleName: "case",
+        routeKey: "case.record",
+      }),
+    );
+  });
+});

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

@@ -0,0 +1,33 @@
+export interface AdminUiCompositionValidationPluginOptions {
+  readonly validate?: () => void;
+  readonly validatorEntry?: string;
+  readonly runValidator?: (entry: string) => number;
+}
+
+export interface AdminUiCompositionValidationPlugin {
+  readonly name: string;
+  readonly apply: "build";
+  buildStart(): void;
+}
+
+export function adminUiCompositionValidationPlugin(
+  options: AdminUiCompositionValidationPluginOptions,
+): AdminUiCompositionValidationPlugin {
+  return {
+    name: "windy-admin-ui-composition-validation",
+    apply: "build",
+    buildStart() {
+      if (options.validate) {
+        options.validate();
+        return;
+      }
+      if (!options.validatorEntry || !options.runValidator) {
+        throw new Error("Admin UI 组合构建门禁缺少 validatorEntry 或执行器");
+      }
+      const exitCode = options.runValidator(options.validatorEntry);
+      if (exitCode !== 0) {
+        throw new Error(`Admin UI 组合构建校验失败（exit ${exitCode}）`);
+      }
+    },
+  };
+}

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

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "vitest";
+import { validateProjectModuleAssembly } from "@southwind-ai/modules/admin-ui";
+import { adminUiCompositionValidationPlugin } from "./admin-ui-composition-plugin";
+
+describe("Admin UI 组合构建门禁", () => {
+  test("Vite buildStart 使用运行时同一解析器并 fail closed", () => {
+    const plugin = adminUiCompositionValidationPlugin({
+      validate: () =>
+        validateProjectModuleAssembly({ schemaVersion: 2, modules: [] }),
+    });
+
+    expect(typeof plugin.buildStart).toBe("function");
+    expect(() => {
+      if (typeof plugin.buildStart !== "function") {
+        throw new Error("buildStart 未注册");
+      }
+      plugin.buildStart.call(undefined as never);
+    }).toThrow("schemaVersion 不受支持");
+  });
+});

package/template/apps/web/src/router/admin-ui-composition.ts

@@ -0,0 +1,313 @@
+import {
+  indexProjectModuleAssembly,
+  satisfiesModuleHostRange,
+  type AdminPageBinding as ContractAdminPageBinding,
+  type AdminUiManifest,
+  type ModuleAdminRouteDefinition,
+  type ProjectModuleAssembly,
+  type WindyAdminUiModule,
+} from "@southwind-ai/modules/admin-ui";
+import type { Component } from "vue";
+
+export const ADMIN_UI_HOST_VERSION = "0.1.0";
+
+export type AdminPageBinding = ContractAdminPageBinding<Component>;
+export type AdminUiModule = WindyAdminUiModule<Component>;
+
+export interface AdminUiModuleOverride {
+  readonly moduleName: string;
+  readonly pages: readonly AdminPageBinding[];
+}
+
+export interface AdminRoutePresentation {
+  readonly routeKey: string;
+  readonly hidden?: boolean;
+  readonly title?: string;
+  readonly icon?: string;
+  readonly order?: number;
+}
+
+export interface WebCompositionDeclaration {
+  readonly overrides: readonly AdminUiModuleOverride[];
+  readonly presentation?: readonly AdminRoutePresentation[];
+}
+
+export interface ResolvedAdminUiComposition {
+  readonly modules: readonly AdminUiModule[];
+  readonly adminRoutes: readonly ModuleAdminRouteDefinition[];
+  readonly activePlatformRouteKeys: ReadonlySet<string>;
+  readonly knownRouteKeys: ReadonlySet<string>;
+  readonly activeRouteKeys: ReadonlySet<string>;
+  readonly visibleRouteKeys: ReadonlySet<string>;
+  readonly presentation: ReadonlyMap<string, AdminRoutePresentation>;
+}
+
+export function defineWebComposition(
+  declaration: WebCompositionDeclaration,
+): WebCompositionDeclaration {
+  return declaration;
+}
+
+export function resolveAdminUiComposition(input: {
+  readonly declaration: WebCompositionDeclaration;
+  readonly assembly: ProjectModuleAssembly;
+  readonly platformModules: readonly AdminUiManifest[];
+  readonly installedModules: readonly AdminUiModule[];
+  readonly hostVersion?: string;
+}): ResolvedAdminUiComposition {
+  const hostVersion = input.hostVersion ?? ADMIN_UI_HOST_VERSION;
+  const assemblyByName = indexProjectModuleAssembly(input.assembly);
+  const platformByName = uniqueManifests("平台", input.platformModules);
+  const installedByName = uniqueInstalledModules(input.installedModules);
+  validatePlatformAssembly(platformByName, assemblyByName);
+  validateInstalledAssembly(installedByName, assemblyByName, hostVersion);
+
+  const overrides = uniqueOverrides(input.declaration.overrides);
+  const modules = [...installedByName.values()]
+    .map((module) => applyOverride(module, overrides.get(module.manifest.name)))
+    .map(validatePageBindings)
+    .sort(
+      (left, right) =>
+        assemblyByName.get(left.manifest.name)!.order -
+        assemblyByName.get(right.manifest.name)!.order,
+    );
+
+  validateAdminRouteIdentities([
+    ...platformByName.values(),
+    ...modules.map(({ manifest }) => manifest),
+  ]);
+
+  const activePlatformRoutes = [...platformByName.values()].flatMap(
+    (manifest) =>
+      assemblyByName.get(manifest.name)!.enabled ? manifest.adminRoutes : [],
+  );
+  const businessRoutes = modules.flatMap(
+    ({ manifest }) => manifest.adminRoutes,
+  );
+  const adminRoutes = [...activePlatformRoutes, ...businessRoutes];
+  const knownRouteKeys = new Set(
+    [
+      ...platformByName.values(),
+      ...modules.map(({ manifest }) => manifest),
+    ].flatMap(({ adminRoutes }) => adminRoutes.map(({ key }) => key)),
+  );
+  const presentation = validatePresentation(
+    input.declaration.presentation ?? [],
+    knownRouteKeys,
+  );
+  const activePlatformRouteKeys = new Set(
+    activePlatformRoutes.map(({ key }) => key),
+  );
+  const activeRouteKeys = new Set(adminRoutes.map(({ key }) => key));
+  const visibleRouteKeys = new Set([
+    ...activePlatformRoutes.flatMap(({ key }) => {
+      const owner = [...platformByName.values()].find((manifest) =>
+        manifest.adminRoutes.some((route) => route.key === key),
+      )!;
+      return assemblyByName.get(owner.name)!.admin.visible ? [key] : [];
+    }),
+    ...businessRoutes.flatMap(({ key }) => {
+      const owner = modules.find(({ manifest }) =>
+        manifest.adminRoutes.some((route) => route.key === key),
+      )!;
+      return assemblyByName.get(owner.manifest.name)!.admin.visible
+        ? [key]
+        : [];
+    }),
+  ]);
+
+  return {
+    modules,
+    adminRoutes,
+    activePlatformRouteKeys,
+    knownRouteKeys,
+    activeRouteKeys,
+    visibleRouteKeys,
+    presentation,
+  };
+}
+
+export function validateAdminRoutePathCollisions(
+  composition: ResolvedAdminUiComposition,
+  reservedPaths: readonly string[],
+): void {
+  const paths = new Set<string>();
+  for (const path of [
+    ...reservedPaths,
+    ...composition.adminRoutes.map(({ path }) => path),
+  ]) {
+    if (paths.has(path)) throw new Error(`Web Route 路径重复：${path}`);
+    paths.add(path);
+  }
+}
+
+function uniqueManifests(
+  label: string,
+  manifests: readonly AdminUiManifest[],
+): ReadonlyMap<string, AdminUiManifest> {
+  const result = new Map<string, AdminUiManifest>();
+  for (const manifest of manifests) {
+    if (!manifest.name.trim() || !manifest.version.trim()) {
+      throw new Error(`${label} Admin UI Manifest 身份无效`);
+    }
+    if (result.has(manifest.name)) {
+      throw new Error(`${label} Admin UI Module 重复：${manifest.name}`);
+    }
+    result.set(manifest.name, manifest);
+  }
+  return result;
+}
+
+function uniqueInstalledModules(
+  modules: readonly AdminUiModule[],
+): ReadonlyMap<string, AdminUiModule> {
+  const result = new Map<string, AdminUiModule>();
+  for (const module of modules) {
+    const name = module.manifest.name;
+    if (result.has(name)) throw new Error(`Admin UI Module 重复：${name}`);
+    result.set(name, module);
+  }
+  return result;
+}
+
+function validatePlatformAssembly(
+  platformByName: ReadonlyMap<string, AdminUiManifest>,
+  assemblyByName: ReturnType<typeof indexProjectModuleAssembly>,
+): void {
+  for (const name of platformByName.keys()) {
+    const entry = assemblyByName.get(name);
+    if (!entry) {
+      throw new Error(`平台 Module 未在 windy.modules.json 注册：${name}`);
+    }
+    if (entry.package !== null) {
+      throw new Error(
+        `平台 Module 在 windy.modules.json 中必须使用 package=null：${name}`,
+      );
+    }
+  }
+  for (const entry of assemblyByName.values()) {
+    if (entry.package === null && !platformByName.has(entry.name)) {
+      throw new Error(
+        `windy.modules.json 引用了未知平台 Module：${entry.name}`,
+      );
+    }
+  }
+}
+
+function validateInstalledAssembly(
+  installedByName: ReadonlyMap<string, AdminUiModule>,
+  assemblyByName: ReturnType<typeof indexProjectModuleAssembly>,
+  hostVersion: string,
+): void {
+  for (const module of installedByName.values()) {
+    const entry = assemblyByName.get(module.manifest.name);
+    if (!entry) {
+      throw new Error(
+        `Admin UI Module 未在 windy.modules.json 注册：${module.manifest.name}`,
+      );
+    }
+    if (!entry.enabled) {
+      throw new Error(`已禁用 Module 不应加载 Admin UI：${entry.name}`);
+    }
+    if (entry.package === null) {
+      throw new Error(`平台 Module 不能使用 package Admin UI：${entry.name}`);
+    }
+    if (!satisfiesModuleHostRange(hostVersion, module.hostRange)) {
+      throw new Error(
+        `Admin UI Module ${module.manifest.name} 要求 Host ${module.hostRange}，当前为 ${hostVersion}`,
+      );
+    }
+  }
+  for (const entry of assemblyByName.values()) {
+    if (
+      entry.package !== null &&
+      entry.enabled &&
+      !installedByName.has(entry.name)
+    ) {
+      throw new Error(`已启用 Module 缺少标准 Admin UI 导出：${entry.name}`);
+    }
+  }
+}
+
+function uniqueOverrides(
+  overrides: readonly AdminUiModuleOverride[],
+): ReadonlyMap<string, AdminUiModuleOverride> {
+  const result = new Map<string, AdminUiModuleOverride>();
+  for (const override of overrides) {
+    if (result.has(override.moduleName)) {
+      throw new Error(`Admin UI Override 重复：${override.moduleName}`);
+    }
+    result.set(override.moduleName, override);
+  }
+  return result;
+}
+
+function applyOverride(
+  module: AdminUiModule,
+  override: AdminUiModuleOverride | undefined,
+): AdminUiModule {
+  if (!override) return module;
+  const pages = new Map(
+    module.pages.map((page) => [page.routeKey, page] as const),
+  );
+  for (const page of override.pages) pages.set(page.routeKey, page);
+  return { ...module, pages: [...pages.values()] };
+}
+
+function validatePageBindings(module: AdminUiModule): AdminUiModule {
+  const declared = new Set(module.manifest.adminRoutes.map(({ key }) => key));
+  const bound = new Set<string>();
+  for (const page of module.pages) {
+    if (!declared.has(page.routeKey)) {
+      throw new Error(
+        `${module.manifest.name} 绑定了未知 Admin Route：${page.routeKey}`,
+      );
+    }
+    if (bound.has(page.routeKey)) {
+      throw new Error(
+        `${module.manifest.name} Admin Route 重复绑定：${page.routeKey}`,
+      );
+    }
+    bound.add(page.routeKey);
+  }
+  for (const routeKey of declared) {
+    if (!bound.has(routeKey)) {
+      throw new Error(
+        `${module.manifest.name} 缺少 Admin Route 页面绑定：${routeKey}`,
+      );
+    }
+  }
+  return module;
+}
+
+function validateAdminRouteIdentities(
+  manifests: readonly AdminUiManifest[],
+): void {
+  const keys = new Set<string>();
+  const paths = new Set<string>();
+  for (const route of manifests.flatMap(({ adminRoutes }) => adminRoutes)) {
+    if (keys.has(route.key)) throw new Error(`Admin Route 重复：${route.key}`);
+    if (paths.has(route.path)) {
+      throw new Error(`Admin Route 路径重复：${route.path}`);
+    }
+    keys.add(route.key);
+    paths.add(route.path);
+  }
+}
+
+function validatePresentation(
+  entries: readonly AdminRoutePresentation[],
+  knownRouteKeys: ReadonlySet<string>,
+): ReadonlyMap<string, AdminRoutePresentation> {
+  const byRoute = new Map<string, AdminRoutePresentation>();
+  for (const entry of entries) {
+    if (!knownRouteKeys.has(entry.routeKey)) {
+      throw new Error(`Admin UI 呈现引用未知 Route：${entry.routeKey}`);
+    }
+    if (byRoute.has(entry.routeKey)) {
+      throw new Error(`Admin UI 呈现重复：${entry.routeKey}`);
+    }
+    byRoute.set(entry.routeKey, entry);
+  }
+  return byRoute;
+}

package/template/apps/web/src/router/admin-ui-composition.webtest.ts

@@ -0,0 +1,225 @@
+import { describe, expect, test } from "vitest";
+import type { AdminUiManifest } from "@southwind-ai/modules/admin-ui";
+import {
+  defineWebComposition,
+  resolveAdminUiComposition,
+  validateAdminRoutePathCollisions,
+  type AdminUiModule,
+} from "./admin-ui-composition";
+
+describe("Admin UI 模块组合", () => {
+  test("浏览器 Host 只消费身份、版本、Admin Route 与页面 loader", () => {
+    const load = async () => ({ default: {} });
+    const composition = resolveAdminUiComposition({
+      declaration: defineWebComposition({ overrides: [] }),
+      assembly: assembly([assemblyEntry("case", 100)]),
+      platformModules: [],
+      installedModules: [installed(caseManifest(), load)],
+    });
+
+    expect(composition.modules).toEqual([
+      {
+        hostRange: "^0.1.0",
+        manifest: caseManifest(),
+        pages: [{ routeKey: "case.record", load }],
+      },
+    ]);
+    expect(composition.modules[0]!.manifest).not.toHaveProperty("permissions");
+    expect(composition.modules[0]!.manifest).not.toHaveProperty("migrations");
+  });
+
+  test("启用控制路由，admin.visible 只控制入口呈现", () => {
+    const composition = resolveAdminUiComposition({
+      declaration: { overrides: [] },
+      assembly: assembly([
+        assemblyEntry("case", 200, true, false),
+        assemblyEntry("lead", 100),
+        assemblyEntry("disabled", 300, false),
+      ]),
+      platformModules: [],
+      installedModules: [
+        installed(caseManifest("case", "/cases", "案件")),
+        installed(caseManifest("lead", "/leads", "线索")),
+      ],
+    });
+
+    expect(composition.modules.map(({ manifest }) => manifest.name)).toEqual([
+      "lead",
+      "case",
+    ]);
+    expect(composition.activeRouteKeys.has("case.record")).toBe(true);
+    expect(composition.visibleRouteKeys.has("case.record")).toBe(false);
+    expect(composition.activeRouteKeys.has("disabled.record")).toBe(false);
+  });
+
+  test("项目 override 可替换 package 默认页面 loader", () => {
+    const packageLoad = async () => ({ default: { name: "Package" } });
+    const projectLoad = async () => ({ default: { name: "Project" } });
+    const composition = resolveAdminUiComposition({
+      declaration: {
+        overrides: [
+          {
+            moduleName: "case",
+            pages: [{ routeKey: "case.record", load: projectLoad }],
+          },
+        ],
+      },
+      assembly: assembly([assemblyEntry("case", 100)]),
+      platformModules: [],
+      installedModules: [installed(caseManifest(), packageLoad)],
+    });
+
+    expect(composition.modules[0]?.pages[0]?.load).toBe(projectLoad);
+  });
+
+  test("纯 API 或 Task Module 用空 Admin 导出完成自动装配", () => {
+    const composition = resolveAdminUiComposition({
+      declaration: { overrides: [] },
+      assembly: assembly([assemblyEntry("jobs", 100)]),
+      platformModules: [],
+      installedModules: [
+        {
+          manifest: { name: "jobs", version: "1.0.0", adminRoutes: [] },
+          hostRange: "^0.1.0",
+          pages: [],
+        },
+      ],
+    });
+
+    expect(composition.modules[0]?.manifest.name).toBe("jobs");
+    expect(composition.adminRoutes).toEqual([]);
+  });
+
+  test("未知、重复、Host 不兼容和页面绑定缺失均 fail closed", () => {
+    const valid = installed(caseManifest());
+    expect(() =>
+      resolveAdminUiComposition({
+        declaration: { overrides: [] },
+        assembly: assembly([assemblyEntry("other", 100)]),
+        platformModules: [],
+        installedModules: [valid],
+      }),
+    ).toThrow("未在 windy.modules.json 注册：case");
+    expect(() =>
+      resolveAdminUiComposition({
+        declaration: { overrides: [] },
+        assembly: assembly([assemblyEntry("case", 100)]),
+        platformModules: [],
+        installedModules: [valid, valid],
+      }),
+    ).toThrow("Admin UI Module 重复：case");
+    expect(() =>
+      resolveAdminUiComposition({
+        declaration: { overrides: [] },
+        assembly: assembly([assemblyEntry("case", 100)]),
+        platformModules: [],
+        installedModules: [{ ...valid, hostRange: "^1.0.0" }],
+      }),
+    ).toThrow("要求 Host ^1.0.0");
+    expect(() =>
+      resolveAdminUiComposition({
+        declaration: { overrides: [] },
+        assembly: assembly([assemblyEntry("case", 100)]),
+        platformModules: [],
+        installedModules: [{ ...valid, pages: [] }],
+      }),
+    ).toThrow("缺少 Admin Route 页面绑定：case.record");
+  });
+
+  test("平台清单与 package 标准导出都必须和装配清单双向对应", () => {
+    expect(() =>
+      resolveAdminUiComposition({
+        declaration: { overrides: [] },
+        assembly: assembly([]),
+        platformModules: [caseManifest()],
+        installedModules: [],
+      }),
+    ).toThrow("平台 Module 未在 windy.modules.json 注册：case");
+    expect(() =>
+      resolveAdminUiComposition({
+        declaration: { overrides: [] },
+        assembly: assembly([assemblyEntry("ghost", 100, true, true, null)]),
+        platformModules: [],
+        installedModules: [],
+      }),
+    ).toThrow("windy.modules.json 引用了未知平台 Module：ghost");
+    expect(() =>
+      resolveAdminUiComposition({
+        declaration: { overrides: [] },
+        assembly: assembly([assemblyEntry("case", 100)]),
+        platformModules: [],
+        installedModules: [],
+      }),
+    ).toThrow("已启用 Module 缺少标准 Admin UI 导出：case");
+  });
+
+  test("构建门禁拒绝与登录、首页或 Admin 壳路由碰撞", () => {
+    const composition = resolveAdminUiComposition({
+      declaration: { overrides: [] },
+      assembly: assembly([assemblyEntry("case", 100)]),
+      platformModules: [],
+      installedModules: [installed(caseManifest("case", "/admin"))],
+    });
+
+    expect(() =>
+      validateAdminRoutePathCollisions(composition, ["/login", "/admin"]),
+    ).toThrow("Web Route 路径重复：/admin");
+  });
+});
+
+function assembly(modules: ReturnType<typeof assemblyEntry>[]) {
+  return { schemaVersion: 1 as const, modules };
+}
+
+function assemblyEntry(
+  name: string,
+  order: number,
+  enabled = true,
+  visible = true,
+  packageName: string | null = `@customer/${name}`,
+) {
+  return {
+    name,
+    package: packageName,
+    enabled,
+    order,
+    admin: { visible },
+    config: {},
+  };
+}
+
+function installed(
+  manifest: AdminUiManifest,
+  load: AdminUiModule["pages"][number]["load"] = async () => ({
+    default: {},
+  }),
+): AdminUiModule {
+  return {
+    manifest,
+    hostRange: "^0.1.0",
+    pages: manifest.adminRoutes.map(({ key }) => ({ routeKey: key, load })),
+  };
+}
+
+function caseManifest(
+  name = "case",
+  path = "/cases",
+  title = "案件",
+): AdminUiManifest {
+  const key = `${name}.record`;
+  return {
+    name,
+    version: "1.2.3",
+    adminRoutes: [
+      {
+        key,
+        path,
+        title,
+        surface: "sidebar",
+        directAccess: "guarded",
+        featureKey: key,
+        permissionKey: `${key}.read`,
+      },
+    ],
+  };
+}