create-windy 0.3.18 → 0.4.0

package/template/apps/server/src/work-order/task.test.ts

@@ -33,9 +33,14 @@ describe("示例工单后台任务", () => {
         workOrderDataScopeBinding,
       ),
     });
+    const definitions = createModuleTaskDefinitions(
+      hosts,
+      createFoundationSnapshot().features,
+    );
+    expect(definitions[0]?.auditAction).toBe("task.execute");
     const scheduler = new SchedulerService(
       new InMemorySchedulerRepository(),
-      createModuleTaskDefinitions(hosts, createFoundationSnapshot().features),
+      definitions,
       runtime,
     );
     await scheduler.initialize();

package/template/apps/web/Dockerfile

@@ -4,6 +4,7 @@ FROM oven/bun:1.3.14-alpine AS deps
 WORKDIR /app
 
 COPY package.json bun.lock ./
+COPY windy.modules.json windy.modules.json
 # windy-copy:deps begin
 COPY apps/license/package.json apps/license/package.json
 COPY apps/server/package.json apps/server/package.json
@@ -27,9 +28,13 @@ RUN --mount=type=cache,id=windy-bun-1.3.14,target=/root/.bun/install/cache,shari
 FROM deps AS build
 # windy-copy:build begin
 COPY apps/web apps/web
+COPY packages/example-work-order packages/example-work-order
+COPY packages/jobs packages/jobs
 COPY packages/license-sdk packages/license-sdk
 COPY packages/modules packages/modules
+COPY packages/server-sdk packages/server-sdk
 COPY packages/shared packages/shared
+COPY packages/storage packages/storage
 # windy-copy:build end
 RUN bun run --cwd apps/web build
 

package/template/apps/web/package.json

@@ -18,6 +18,7 @@
     "@tanstack/vue-form": "^1.33.0",
     "@tanstack/vue-table": "^8.21.3",
     "@vueuse/core": "^14.3.0",
+    "@southwind-ai/example-work-order": "workspace:*",
     "@southwind-ai/license": "workspace:*",
     "@southwind-ai/shared": "workspace:*",
     "class-variance-authority": "^0.7.1",

package/template/apps/web/scripts/validate-admin-ui-composition.ts

@@ -0,0 +1,106 @@
+import moduleAssembly from "../../../windy.modules.json";
+import {
+  systemAdminUiManifests,
+  validateProjectModuleAssembly,
+} from "@southwind-ai/modules/admin-ui";
+import {
+  projectAdminUiManifest,
+  type AdminUiManifestSource,
+} from "@southwind-ai/modules";
+import { webComposition } from "../src/app/web-composition";
+import {
+  resolveAdminUiComposition,
+  validateAdminRoutePathCollisions,
+  type AdminUiModule,
+} from "../src/router/admin-ui-composition";
+import { validatePlatformAdminRouteKeys } from "../src/router/manifest-routes";
+import { platformAdminRouteBindings } from "../src/router/platform-admin-route-bindings";
+import { reservedWebRoutePathList } from "../src/router/reserved-route-paths";
+
+const assembly = validateProjectModuleAssembly(moduleAssembly);
+const installedModules = await Promise.all(
+  assembly.modules
+    .filter(
+      (
+        entry,
+      ): entry is typeof entry & {
+        readonly package: string;
+      } => entry.enabled && entry.package !== null,
+    )
+    .map(async (entry) => {
+      const [adminLoaded, manifestLoaded]: readonly [unknown, unknown] =
+        await Promise.all([
+          import(`${entry.package}/admin`),
+          import(`${entry.package}/manifest`),
+        ]);
+      if (!isAdminUiModuleExport(adminLoaded)) {
+        throw new Error(
+          `Module ${entry.name} 缺少 windyAdminUiModule 标准导出`,
+        );
+      }
+      if (!isModuleManifestExport(manifestLoaded)) {
+        throw new Error(
+          `Module ${entry.name} 缺少 windyModuleManifest 标准导出`,
+        );
+      }
+      if (adminLoaded.windyAdminUiModule.manifest.name !== entry.name) {
+        throw new Error(
+          `Module package ${entry.package} 导出了错误 Admin UI：${adminLoaded.windyAdminUiModule.manifest.name}`,
+        );
+      }
+      const expectedAdminManifest = projectAdminUiManifest(
+        manifestLoaded.windyModuleManifest,
+      );
+      if (
+        JSON.stringify(adminLoaded.windyAdminUiModule.manifest) !==
+        JSON.stringify(expectedAdminManifest)
+      ) {
+        throw new Error(
+          `Module ${entry.name} 的 ./admin 与 ./manifest 投影不一致`,
+        );
+      }
+      return adminLoaded.windyAdminUiModule;
+    }),
+);
+
+const composition = resolveAdminUiComposition({
+  declaration: webComposition,
+  assembly,
+  platformModules: systemAdminUiManifests(),
+  installedModules,
+});
+validateAdminRoutePathCollisions(composition, reservedWebRoutePathList);
+validatePlatformAdminRouteKeys(
+  platformAdminRouteBindings.map(({ routeKey }) => routeKey),
+);
+
+function isAdminUiModuleExport(
+  value: unknown,
+): value is { readonly windyAdminUiModule: AdminUiModule } {
+  if (!isRecord(value) || !isRecord(value.windyAdminUiModule)) return false;
+  const module = value.windyAdminUiModule;
+  return (
+    isRecord(module.manifest) &&
+    typeof module.manifest.name === "string" &&
+    typeof module.manifest.version === "string" &&
+    Array.isArray(module.manifest.adminRoutes) &&
+    typeof module.hostRange === "string" &&
+    Array.isArray(module.pages)
+  );
+}
+
+function isModuleManifestExport(
+  value: unknown,
+): value is { readonly windyModuleManifest: AdminUiManifestSource } {
+  if (!isRecord(value) || !isRecord(value.windyModuleManifest)) return false;
+  const manifest = value.windyModuleManifest;
+  return (
+    typeof manifest.name === "string" &&
+    typeof manifest.version === "string" &&
+    Array.isArray(manifest.adminRoutes)
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/template/apps/web/src/app/web-composition.ts

@@ -0,0 +1,24 @@
+import { defineWebComposition } from "../router/admin-ui-composition";
+
+/**
+ * 客户拥有的 Admin UI 覆盖声明。
+ *
+ * 模块的窄 Manifest 与默认页面来自 package 标准 `./admin` 导出；这里只覆盖客户
+ * 自己接管的页面 loader 与呈现偏好，不复制路径、标题、Feature 或 Permission。
+ */
+export const webComposition = defineWebComposition({
+  overrides: [
+    // @windy-module work-order begin
+    {
+      moduleName: "work-order",
+      pages: [
+        {
+          routeKey: "work-order.ticket.list",
+          load: () => import("../pages/work-orders/WorkOrderListPage.vue"),
+        },
+      ],
+    },
+    // @windy-module work-order end
+  ],
+  presentation: [],
+});

package/template/apps/web/src/app/web-composition.webtest.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from "vitest";
+import { webComposition } from "./web-composition";
+
+describe("project-owned Web 组合声明", () => {
+  test("示例工单只覆盖 moduleName 与 lazy page loader", () => {
+    const registration = webComposition.overrides.find(
+      ({ moduleName }) => moduleName === "work-order",
+    );
+
+    expect(registration?.moduleName).toBe("work-order");
+    expect(registration?.pages).toHaveLength(1);
+    expect(registration?.pages[0]?.routeKey).toBe("work-order.ticket.list");
+    expect(registration?.pages[0]?.load).toBeTypeOf("function");
+  });
+});

package/template/apps/web/src/layout/AppSidebar.vue

@@ -40,6 +40,7 @@ import { useAccessSnapshot } from "@/composables/useAccessSnapshot";
 import { useLicenseRuntime } from "@/composables/useLicenseRuntime";
 // @windy-module system.license end
 import { usePlatformSettings } from "@/composables/usePlatformSettings";
+import { webAdminUiComposition } from "@/router/web-composition-host";
 import { authorizedSidebarMenus } from "./navigation";
 
 interface NavigationGroup {
@@ -74,7 +75,13 @@ const license = useLicenseRuntime();
 const platform = usePlatformSettings();
 const openGroups = reactive<Record<string, boolean>>(loadOpenGroups());
 const authorizedMenus = computed(() =>
-  access.snapshot.value ? authorizedSidebarMenus(access.snapshot.value) : [],
+  access.snapshot.value
+    ? authorizedSidebarMenus(
+        access.snapshot.value,
+        webAdminUiComposition.presentation,
+        webAdminUiComposition,
+      )
+    : [],
 );
 const settingsMenu = computed(() =>
   findMenu(authorizedMenus.value, "system.settings"),

package/template/apps/web/src/layout/NavigationSearchDialog.vue

@@ -23,6 +23,7 @@ import {
 import { Input } from "@/components/ui/input";
 import { useAccessSnapshot } from "@/composables/useAccessSnapshot";
 import { useGlobalSearch } from "@/composables/useGlobalSearch";
+import { webAdminUiComposition } from "@/router/web-composition-host";
 import GlobalSearchResults from "./GlobalSearchResults.vue";
 import { authorizedSidebarMenus } from "./navigation";
 
@@ -42,7 +43,13 @@ const businessSearch = useGlobalSearch(query);
 
 const items = computed(() =>
   access.snapshot.value
-    ? flattenMenus(authorizedSidebarMenus(access.snapshot.value))
+    ? flattenMenus(
+        authorizedSidebarMenus(
+          access.snapshot.value,
+          webAdminUiComposition.presentation,
+          webAdminUiComposition,
+        ),
+      )
     : [],
 );
 const results = computed(() => {

package/template/apps/web/src/layout/navigation.ts

@@ -5,6 +5,7 @@ import type {
   MenuNode,
   PermissionDefinition,
 } from "@southwind-ai/shared";
+import type { AdminRoutePresentation } from "../router/admin-ui-composition";
 
 export interface WebAccessActor {
   id: string;
@@ -47,6 +48,11 @@ export interface WebAccessDecision {
   reason: "allowed" | "missing-permission" | "feature-disabled";
 }
 
+export interface AdminRouteActivation {
+  readonly knownRouteKeys: ReadonlySet<string>;
+  readonly visibleRouteKeys: ReadonlySet<string>;
+}
+
 export const dashboardMenu: MenuNode = {
   key: "dashboard",
   title: "工作台",
@@ -80,9 +86,11 @@ export function evaluateWebAccess(
 
 export function authorizedSidebarMenus(
   snapshot: WebAccessSnapshot,
+  presentation: ReadonlyMap<string, AdminRoutePresentation> = new Map(),
+  activation?: AdminRouteActivation,
 ): MenuNode[] {
   return [dashboardMenu, ...snapshot.menus]
-    .map((menu) => authorizeMenu(menu, snapshot))
+    .map((menu) => authorizeMenu(menu, snapshot, presentation, activation))
     .filter((menu): menu is MenuNode => Boolean(menu))
     .sort((left, right) => left.order - right.order);
 }
@@ -94,14 +102,31 @@ export function canToggleFeatureFlags(snapshot: WebAccessSnapshot): boolean {
 function authorizeMenu(
   menu: MenuNode,
   snapshot: WebAccessSnapshot,
+  presentation: ReadonlyMap<string, AdminRoutePresentation>,
+  activation?: AdminRouteActivation,
 ): MenuNode | undefined {
   if (!menu.visible) return undefined;
+  if (
+    activation?.knownRouteKeys.has(menu.key) &&
+    !activation.visibleRouteKeys.has(menu.key)
+  ) {
+    return undefined;
+  }
+  const override = presentation.get(menu.key);
+  if (override?.hidden) return undefined;
   const children = menu.children
-    ?.map((child) => authorizeMenu(child, snapshot))
-    .filter((child): child is MenuNode => Boolean(child));
+    ?.map((child) => authorizeMenu(child, snapshot, presentation, activation))
+    .filter((child): child is MenuNode => Boolean(child))
+    .sort((left, right) => left.order - right.order);
   const access = evaluateWebAccess(snapshot, menu);
   if (!access.allowed || (menu.type === "catalog" && children?.length === 0)) {
     return undefined;
   }
-  return { ...menu, children };
+  return {
+    ...menu,
+    ...(override?.title === undefined ? {} : { title: override.title }),
+    ...(override?.icon === undefined ? {} : { icon: override.icon }),
+    ...(override?.order === undefined ? {} : { order: override.order }),
+    children,
+  };
 }

package/template/apps/web/src/layout/navigation.webtest.ts

@@ -6,6 +6,7 @@ import {
   evaluateWebAccess,
   type WebAccessSnapshot,
 } from "./navigation";
+import type { AdminRoutePresentation } from "../router/admin-ui-composition";
 
 describe("Web 访问快照", () => {
   test("菜单同时受服务端权限和 Feature 有效态约束", () => {
@@ -45,6 +46,56 @@ describe("Web 访问快照", () => {
       "system.audit",
     );
   });
+
+  test("客户可按稳定 Route Key 隐藏、排序或替换菜单呈现", () => {
+    const snapshot = accessSnapshot();
+    snapshot.menus[0]!.children!.push({
+      key: "system.role",
+      title: "角色管理",
+      type: "menu",
+      order: 20,
+      visible: true,
+      path: "/admin/system/roles",
+    });
+    const presentation = new Map<string, AdminRoutePresentation>([
+      [
+        "system.audit",
+        {
+          routeKey: "system.audit",
+          title: "操作留痕",
+          icon: "scroll-text",
+          order: 30,
+        },
+      ],
+      [
+        "system.role",
+        {
+          routeKey: "system.role",
+          hidden: true,
+        },
+      ],
+    ]);
+
+    const menus = authorizedSidebarMenus(snapshot, presentation);
+    const audit = menus[1]?.children?.[0];
+
+    expect(audit).toMatchObject({
+      key: "system.audit",
+      title: "操作留痕",
+      icon: "scroll-text",
+      order: 30,
+    });
+    expect(flattenKeys(menus)).not.toContain("system.role");
+  });
+
+  test("根装配清单关闭 Admin 呈现后不保留失效菜单", () => {
+    const menus = authorizedSidebarMenus(accessSnapshot(), new Map(), {
+      knownRouteKeys: new Set(["system.audit"]),
+      visibleRouteKeys: new Set(),
+    });
+
+    expect(flattenKeys(menus)).not.toContain("system.audit");
+  });
 });
 
 function accessSnapshot(): WebAccessSnapshot {

package/template/apps/web/src/pages/dashboard/dashboard-presenter.ts

@@ -5,6 +5,7 @@ import {
   authorizedSidebarMenus,
   type WebAccessSnapshot,
 } from "@/layout/navigation";
+import { webAdminUiComposition } from "@/router/web-composition-host";
 
 export interface DashboardMetric {
   label: string;
@@ -32,7 +33,11 @@ export function buildDashboardModel(
 ): DashboardModel {
   const features = snapshot?.features || [];
   const availableMenuCount = snapshot
-    ? authorizedSidebarMenus(snapshot)
+    ? authorizedSidebarMenus(
+        snapshot,
+        webAdminUiComposition.presentation,
+        webAdminUiComposition,
+      )
         .flatMap((menu) => (menu.children?.length ? menu.children : [menu]))
         .filter((menu) => menu.key !== "dashboard" && Boolean(menu.path)).length
     : 0;

package/template/apps/web/src/pages/work-orders/WorkOrderListPage.vue

@@ -0,0 +1,202 @@
+<script setup lang="ts">
+import type {
+  WorkOrder,
+  WorkOrderPriority,
+  WorkOrderWorkflowStatus,
+} from "@southwind-ai/example-work-order/contract";
+import { DEFAULT_PAGE_SIZE } from "@southwind-ai/shared";
+import { RefreshCwIcon, SearchIcon } from "@lucide/vue";
+import { onMounted, shallowRef } from "vue";
+import DataPagination from "@/components/common/DataPagination.vue";
+import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableEmpty,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table";
+import { formatDateTime } from "@/lib/date-time";
+import { listWorkOrders } from "@/services/work-order-api";
+
+const items = shallowRef<WorkOrder[]>([]);
+const page = shallowRef(1);
+const pageSize = shallowRef(DEFAULT_PAGE_SIZE);
+const total = shallowRef(0);
+const query = shallowRef("");
+const loading = shallowRef(false);
+const error = shallowRef("");
+
+onMounted(() => void load());
+
+async function load() {
+  if (loading.value) return;
+  loading.value = true;
+  error.value = "";
+  try {
+    const result = await listWorkOrders({
+      page: page.value,
+      pageSize: pageSize.value,
+      q: query.value,
+    });
+    items.value = result.items;
+    page.value = result.page;
+    pageSize.value = result.pageSize;
+    total.value = result.total;
+  } catch (currentError) {
+    error.value =
+      currentError instanceof Error ? currentError.message : "工单加载失败";
+  } finally {
+    loading.value = false;
+  }
+}
+
+function search() {
+  page.value = 1;
+  void load();
+}
+
+function setPage(value: number) {
+  page.value = value;
+  void load();
+}
+
+function setPageSize(value: number) {
+  pageSize.value = value;
+  page.value = 1;
+  void load();
+}
+
+const priorityLabels: Record<WorkOrderPriority, string> = {
+  low: "低",
+  medium: "中",
+  high: "高",
+};
+const workflowLabels: Record<WorkOrderWorkflowStatus, string> = {
+  open: "待处理",
+  "in-progress": "处理中",
+  resolved: "已解决",
+};
+</script>
+
+<template>
+  <main class="space-y-5">
+    <header class="space-y-2">
+      <h1 class="text-2xl font-semibold text-foreground">工单管理</h1>
+      <p class="text-sm text-muted-foreground">
+        示例业务模块提供的工单列表，入口、权限和功能开关均来自 Module Manifest。
+      </p>
+    </header>
+
+    <Alert v-if="error" variant="destructive">
+      <AlertTitle>无法加载工单</AlertTitle>
+      <AlertDescription>{{ error }}</AlertDescription>
+    </Alert>
+
+    <Card>
+      <CardHeader>
+        <CardTitle>工单列表</CardTitle>
+        <CardDescription>
+          按当前账号的数据范围查看工单，可使用标题或描述搜索。
+        </CardDescription>
+      </CardHeader>
+      <CardContent class="space-y-4">
+        <form class="flex flex-col gap-2 sm:flex-row" @submit.prevent="search">
+          <Input
+            v-model="query"
+            aria-label="搜索工单"
+            placeholder="搜索标题或描述"
+            class="sm:max-w-sm"
+          />
+          <Button type="submit" :disabled="loading">
+            <SearchIcon data-icon="inline-start" />
+            搜索
+          </Button>
+          <Button
+            type="button"
+            variant="outline"
+            :disabled="loading"
+            @click="load"
+          >
+            <RefreshCwIcon
+              data-icon="inline-start"
+              :class="{ 'animate-spin': loading }"
+            />
+            刷新
+          </Button>
+        </form>
+
+        <div class="overflow-hidden rounded-md border">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>工单</TableHead>
+                <TableHead>优先级</TableHead>
+                <TableHead>进度</TableHead>
+                <TableHead>负责人</TableHead>
+                <TableHead>最近更新</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              <TableEmpty v-if="!loading && items.length === 0" :colspan="5">
+                暂无符合条件的工单
+              </TableEmpty>
+              <TableRow v-for="item in items" :key="item.id">
+                <TableCell>
+                  <div class="space-y-1">
+                    <p class="font-medium text-foreground">{{ item.title }}</p>
+                    <p class="line-clamp-2 text-xs text-muted-foreground">
+                      {{ item.description }}
+                    </p>
+                  </div>
+                </TableCell>
+                <TableCell>
+                  <Badge
+                    :variant="
+                      item.priority === 'high' ? 'destructive' : 'outline'
+                    "
+                  >
+                    {{ priorityLabels[item.priority] }}
+                  </Badge>
+                </TableCell>
+                <TableCell>
+                  <Badge
+                    :variant="
+                      item.workflowStatus === 'resolved'
+                        ? 'secondary'
+                        : 'default'
+                    "
+                  >
+                    {{ workflowLabels[item.workflowStatus] }}
+                  </Badge>
+                </TableCell>
+                <TableCell>{{ item.ownerId }}</TableCell>
+                <TableCell>{{ formatDateTime(item.updatedAt) }}</TableCell>
+              </TableRow>
+            </TableBody>
+          </Table>
+        </div>
+
+        <DataPagination
+          :page="page"
+          :page-size="pageSize"
+          :total="total"
+          @update:page="setPage"
+          @update:page-size="setPageSize"
+        />
+      </CardContent>
+    </Card>
+  </main>
+</template>

package/template/apps/web/src/pages/work-orders/WorkOrderListPage.webtest.ts

@@ -0,0 +1,51 @@
+import { flushPromises, mount } from "@vue/test-utils";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import WorkOrderListPage from "./WorkOrderListPage.vue";
+
+const mocks = vi.hoisted(() => ({
+  list: vi.fn(),
+}));
+
+vi.mock("@/services/work-order-api", () => ({
+  listWorkOrders: mocks.list,
+}));
+
+describe("WorkOrderListPage", () => {
+  beforeEach(() => {
+    mocks.list.mockReset();
+    mocks.list.mockResolvedValue({
+      items: [
+        {
+          id: "ticket_1",
+          title: "登录异常",
+          description: "用户无法进入工作台",
+          priority: "high",
+          workflowStatus: "in-progress",
+          ownerId: "user_1",
+          status: "active",
+          createdAt: "2026-07-29T01:00:00.000Z",
+          createdBy: "user_1",
+          updatedAt: "2026-07-29T02:00:00.000Z",
+          updatedBy: "user_1",
+        },
+      ],
+      page: 1,
+      pageSize: 10,
+      total: 1,
+    });
+  });
+
+  test("加载并呈现当前数据范围内的工单", async () => {
+    const wrapper = mount(WorkOrderListPage);
+    await flushPromises();
+
+    expect(mocks.list).toHaveBeenCalledWith({
+      page: 1,
+      pageSize: 10,
+      q: "",
+    });
+    expect(wrapper.text()).toContain("登录异常");
+    expect(wrapper.text()).toContain("高");
+    expect(wrapper.text()).toContain("处理中");
+  });
+});