create-windy 0.3.19 → 0.4.1

package/template/packages/database/drizzle/meta/_journal.json

@@ -309,6 +309,13 @@
       "when": 1785269877377,
       "tag": "0043_activate_agent_dependencies",
       "breakpoints": true
+    },
+    {
+      "idx": 44,
+      "version": "7",
+      "when": 1785400645941,
+      "tag": "0044_sweet_tarantula",
+      "breakpoints": true
     }
   ]
 }

package/template/packages/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/database",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/database/src/schema/platform-settings.ts

@@ -19,6 +19,7 @@ import {
 // @windy-module system.settings begin
 import {
   boolean,
+  integer as settingsInteger,
   jsonb as settingsJsonb,
   pgTable as settingsTable,
   text,
@@ -58,6 +59,8 @@ export const platformWatermarkPolicies = settingsTable(
       .default(["username", "displayName"])
       .notNull(),
     customContent: settingsVarchar("custom_content", { length: 80 }).notNull(),
+    opacityPercent: settingsInteger("opacity_percent").default(8).notNull(),
+    fontSize: settingsInteger("font_size").default(14).notNull(),
     ...auditColumns,
   },
 );

package/template/packages/example-work-order/package.json

@@ -13,8 +13,14 @@
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3"
   },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
   "exports": {
     ".": "./index.ts",
+    "./admin": "./src/admin.ts",
+    "./contract": "./src/contract.ts",
+    "./manifest": "./src/manifest.ts",
     "./migration-bundle": "./src/migration-bundle.ts"
   }
 }

package/template/packages/example-work-order/src/admin-page.ts

@@ -0,0 +1,78 @@
+import { defineComponent, h, onMounted, ref } from "vue";
+import type { WorkOrder, WorkOrderPage } from "./contract.js";
+
+export default defineComponent({
+  name: "DefaultWorkOrderAdminPage",
+  setup() {
+    const items = ref<WorkOrder[]>([]);
+    const loading = ref(true);
+    const error = ref("");
+
+    onMounted(async () => {
+      try {
+        const response = await fetch("/api/work-orders?page=1&pageSize=20");
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        const payload: unknown = await response.json();
+        if (!isWorkOrderPage(payload)) throw new Error("响应结构无效");
+        items.value = payload.items;
+      } catch {
+        error.value = "工单加载失败，请稍后重试。";
+      } finally {
+        loading.value = false;
+      }
+    });
+
+    return () =>
+      h("main", { class: "space-y-4 p-6" }, [
+        h("header", { class: "space-y-1" }, [
+          h("h1", { class: "text-2xl font-semibold" }, "工单管理"),
+          h(
+            "p",
+            { class: "text-sm text-muted-foreground" },
+            "模块 package 提供的默认页面；项目可在 Web Composition 中替换。",
+          ),
+        ]),
+        loading.value
+          ? h("p", "正在加载工单…")
+          : error.value
+            ? h("p", { role: "alert" }, error.value)
+            : h(
+                "ul",
+                { class: "divide-y rounded-md border" },
+                items.value.map((item) =>
+                  h("li", { class: "space-y-1 p-4", key: item.id }, [
+                    h("p", { class: "font-medium" }, item.title),
+                    h(
+                      "p",
+                      { class: "text-sm text-muted-foreground" },
+                      `${item.workflowStatus} · ${item.priority}`,
+                    ),
+                  ]),
+                ),
+              ),
+      ]);
+  },
+});
+
+function isWorkOrderPage(value: unknown): value is WorkOrderPage {
+  return (
+    isRecord(value) &&
+    Array.isArray(value.items) &&
+    value.items.every(
+      (item) =>
+        isRecord(item) &&
+        typeof item.id === "string" &&
+        typeof item.title === "string" &&
+        typeof item.description === "string" &&
+        typeof item.priority === "string" &&
+        typeof item.workflowStatus === "string",
+    ) &&
+    typeof value.page === "number" &&
+    typeof value.pageSize === "number" &&
+    typeof value.total === "number"
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/template/packages/example-work-order/src/admin.ts

@@ -0,0 +1,35 @@
+import {
+  defineAdminUiManifest,
+  defineWindyAdminUiModule,
+} from "@southwind-ai/modules/admin-ui";
+
+export const workOrderAdminUiManifest = defineAdminUiManifest({
+  name: "work-order",
+  version: "0.1.0",
+  adminRoutes: [
+    {
+      key: "work-order.ticket.list",
+      path: "/admin/work-orders",
+      title: "工单管理",
+      surface: "sidebar",
+      directAccess: "guarded",
+      permissionKey: "work-order.ticket.read",
+      featureKey: "work-order.ticket",
+    },
+  ],
+});
+
+/**
+ * package 标准 Admin 导出，提供可独立装配的默认页面。
+ * 项目可以通过 project-owned Web Composition 覆盖页面 loader。
+ */
+export const windyAdminUiModule = defineWindyAdminUiModule({
+  manifest: workOrderAdminUiManifest,
+  hostRange: "^0.1.0",
+  pages: [
+    {
+      routeKey: "work-order.ticket.list",
+      load: () => import("./admin-page.js"),
+    },
+  ],
+});

package/template/packages/example-work-order/src/manifest.test.ts

@@ -1,8 +1,15 @@
 import { describe, expect, test } from "bun:test";
-import { workOrderModule } from "./manifest.js";
+import {
+  windyAdminUiModule,
+  workOrderAdminUiManifest,
+} from "@southwind-ai/example-work-order/admin";
+import {
+  windyModuleManifest,
+  workOrderModule,
+} from "@southwind-ai/example-work-order/manifest";
 
 describe("示例工单 Module Manifest", () => {
-  test("业务能力保留 API 与任务但不进入 Windy Admin Surface", () => {
+  test("业务能力注册 API、任务与 Windy Admin Surface", () => {
     const manifest = workOrderModule();
 
     expect(manifest.name).not.toBe("system");
@@ -16,16 +23,54 @@ describe("示例工单 Module Manifest", () => {
       "work-order.ticket.manage",
     ]);
     expect(manifest.apiPermissions).toHaveLength(5);
-    expect(manifest.menus).toEqual([]);
-    expect(manifest.adminRoutes).toEqual([]);
+    expect(
+      manifest.apiPermissions.map(({ auditAction }) => auditAction),
+    ).toEqual([
+      "data.read",
+      "data.read",
+      "crud.create",
+      "crud.update",
+      "crud.delete",
+    ]);
+    expect(manifest.menus).toEqual([
+      {
+        key: "work-order.ticket.list",
+        title: "工单管理",
+        type: "menu",
+        order: 100,
+        visible: true,
+        path: "/admin/work-orders",
+        icon: "clipboard-list",
+        featureKey: "work-order.ticket",
+        permissionKey: "work-order.ticket.read",
+      },
+    ]);
+    expect(manifest.adminRoutes).toEqual([
+      {
+        key: "work-order.ticket.list",
+        path: "/admin/work-orders",
+        title: "工单管理",
+        surface: "sidebar",
+        directAccess: "guarded",
+        featureKey: "work-order.ticket",
+        permissionKey: "work-order.ticket.read",
+      },
+    ]);
     expect(manifest.auditActions).toEqual(
-      expect.arrayContaining(["crud.create", "crud.update", "crud.delete"]),
+      expect.arrayContaining([
+        "crud.create",
+        "crud.update",
+        "crud.delete",
+        "data.read",
+        "task.execute",
+      ]),
     );
     expect(manifest.tasks).toContainEqual(
       expect.objectContaining({
         key: "work-order.ticket.snapshot",
         featureKey: "work-order.ticket",
         permissionKey: "work-order.ticket.manage",
+        auditAction: "task.execute",
       }),
     );
     expect(manifest.providers).toEqual([
@@ -50,5 +95,17 @@ describe("示例工单 Module Manifest", () => {
       persistence: "postgresql-with-memory-fallback",
       uiComposition: "external-business-app",
     });
+    expect(workOrderAdminUiManifest.adminRoutes).toEqual(manifest.adminRoutes);
+    expect(windyModuleManifest).toEqual(manifest);
+    expect(windyAdminUiModule).toMatchObject({
+      manifest: workOrderAdminUiManifest,
+      hostRange: "^0.1.0",
+      pages: [
+        expect.objectContaining({
+          routeKey: "work-order.ticket.list",
+          load: expect.any(Function),
+        }),
+      ],
+    });
   });
 });

package/template/packages/example-work-order/src/manifest.ts

@@ -2,11 +2,14 @@ import {
   defineSearchProvider,
   featureKey,
   licenseVersionKey,
+  type AuditActionType,
 } from "@southwind-ai/shared";
 import {
   WORK_ORDER_INITIAL_MIGRATION_ID,
+  WORK_ORDER_MODULE_DEPENDENCIES,
   workOrderMigrationBundle,
 } from "./migration-bundle.js";
+import { workOrderAdminUiManifest } from "./admin.js";
 
 const FEATURE_KEY = featureKey("work-order.ticket");
 
@@ -16,19 +19,52 @@ export function workOrderModule() {
     version: "0.1.0",
     label: "示例工单",
     description: "可删除的业务模块示例，演示完整平台能力接入。",
-    menus: [],
-    adminRoutes: [],
+    dependencies: [...WORK_ORDER_MODULE_DEPENDENCIES],
+    menus: [
+      {
+        key: "work-order.ticket.list",
+        title: "工单管理",
+        type: "menu" as const,
+        order: 100,
+        visible: true,
+        path: "/admin/work-orders",
+        icon: "clipboard-list",
+        permissionKey: "work-order.ticket.read",
+        featureKey: FEATURE_KEY,
+      },
+    ],
+    adminRoutes: [...workOrderAdminUiManifest.adminRoutes],
     permissions: [
       permission("read", "查看工单"),
       permission("create", "创建工单"),
       permission("manage", "管理工单"),
     ],
     apiPermissions: [
-      binding("GET", "/api/work-orders", "work-order.ticket.read"),
-      binding("GET", "/api/work-orders/:id", "work-order.ticket.read"),
-      binding("POST", "/api/work-orders", "work-order.ticket.create"),
-      binding("PUT", "/api/work-orders/:id", "work-order.ticket.manage"),
-      binding("DELETE", "/api/work-orders/:id", "work-order.ticket.manage"),
+      binding("GET", "/api/work-orders", "work-order.ticket.read", "data.read"),
+      binding(
+        "GET",
+        "/api/work-orders/:id",
+        "work-order.ticket.read",
+        "data.read",
+      ),
+      binding(
+        "POST",
+        "/api/work-orders",
+        "work-order.ticket.create",
+        "crud.create",
+      ),
+      binding(
+        "PUT",
+        "/api/work-orders/:id",
+        "work-order.ticket.manage",
+        "crud.update",
+      ),
+      binding(
+        "DELETE",
+        "/api/work-orders/:id",
+        "work-order.ticket.manage",
+        "crud.delete",
+      ),
     ],
     features: [
       {
@@ -61,6 +97,7 @@ export function workOrderModule() {
         description: "统计当前工单待办和高优先级积压，写入调度执行结果。",
         permissionKey: "work-order.ticket.manage",
         featureKey: FEATURE_KEY,
+        auditAction: "task.execute",
         intervalSeconds: 900,
         maxAttempts: 3,
         retryDelaySeconds: 60,
@@ -88,7 +125,9 @@ export function workOrderModule() {
       "crud.create" as const,
       "crud.update" as const,
       "crud.delete" as const,
+      "data.read" as const,
       "data.search" as const,
+      "task.execute" as const,
     ],
     metadata: {
       removableExample: true,
@@ -99,6 +138,12 @@ export function workOrderModule() {
   };
 }
 
+/**
+ * package 标准 Manifest 导出。构建与 Server 可用它核对窄 Admin 投影，
+ * 浏览器只能从 `./admin` 子路径加载。
+ */
+export const windyModuleManifest = workOrderModule();
+
 function permission(action: "read" | "create" | "manage", label: string) {
   return {
     key: `work-order.ticket.${action}`,
@@ -115,11 +160,13 @@ function binding(
   method: "GET" | "POST" | "PUT" | "DELETE",
   path: string,
   permissionKey: string,
+  auditAction: AuditActionType,
 ) {
   return {
     method,
     path,
     permissionKey,
     featureKey: "work-order.ticket",
+    auditAction,
   };
 }

package/template/packages/example-work-order/src/migration-bundle.ts

@@ -7,6 +7,14 @@ import {
 export const WORK_ORDER_INITIAL_MIGRATION_ID =
   "work-order.0001.create-work-orders";
 
+export const WORK_ORDER_MODULE_DEPENDENCIES = [
+  "system",
+  "system.identity",
+  "system.search",
+  "system.scheduler",
+  "system.storage",
+] as const;
+
 export const workOrderMigrationBundle: MigrationBundle = {
   formatVersion: MIGRATION_BUNDLE_FORMAT_VERSION,
   module: "work-order",

package/template/packages/example-work-order/src/server-module.ts

@@ -5,7 +5,7 @@ import type {
   ModuleSearchProvider,
   ModuleTaskHandler,
 } from "@southwind-ai/server-sdk";
-import { workOrderModule } from "./manifest.js";
+import { windyModuleManifest } from "./manifest.js";
 
 export interface WorkOrderServerBindings {
   readonly routes: readonly ModuleRouteDefinition[];
@@ -20,7 +20,7 @@ export function createWorkOrderServerModule(
   bindings: WorkOrderServerBindings,
 ): InstallableServerModule<ModuleManifest> {
   return {
-    manifest: workOrderModule(),
+    manifest: windyModuleManifest,
     setup(host) {
       host.registerUploadPolicy({
         purpose: "work-order.ticket.attachment",

package/template/packages/jobs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/jobs",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/modules/index.ts

@@ -8,3 +8,7 @@ export * from "./src/system-module-catalog.js";
 export * from "./src/system-api-permissions.js";
 export * from "./src/tool-composition.js";
 export * from "./src/ai-network-policy.js";
+export * from "./src/project-module-assembly.js";
+export * from "./src/module-host-range.js";
+export * from "./src/admin-ui-manifest.js";
+export * from "./src/system-admin-ui-catalog.js";

package/template/packages/modules/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/modules",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -15,7 +15,8 @@
     "@southwind-ai/shared": "workspace:^"
   },
   "exports": {
-    ".": "./index.ts"
+    ".": "./index.ts",
+    "./admin-ui": "./src/admin-ui-entry.ts"
   },
   "publishConfig": {
     "access": "public"

package/template/packages/modules/src/admin-ui-entry.ts

@@ -0,0 +1,8 @@
+export * from "./admin-ui-manifest.js";
+export * from "./module-host-range.js";
+export * from "./project-module-assembly.js";
+export * from "./system-admin-ui-catalog.js";
+export type {
+  AdminRouteSurface,
+  ModuleAdminRouteDefinition,
+} from "./manifest.js";

package/template/packages/modules/src/admin-ui-manifest.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test";
+import {
+  defineAdminUiManifest,
+  defineWindyAdminUiModule,
+  projectAdminUiManifest,
+} from "./admin-ui-manifest.js";
+import { systemModuleManifests } from "./system-module-catalog.js";
+import { systemAdminUiManifests } from "./system-admin-ui-catalog.js";
+
+describe("Admin UI 窄 Manifest", () => {
+  test("从完整 Manifest 只投影身份与 Admin Route", () => {
+    const full = systemModuleManifests().find(
+      ({ name }) => name === "system.identity",
+    )!;
+    const projected = projectAdminUiManifest(full);
+
+    expect(projected).toEqual({
+      name: full.name,
+      version: full.version,
+      adminRoutes: full.adminRoutes,
+    });
+    expect(projected).not.toHaveProperty("permissions");
+    expect(projected).not.toHaveProperty("migrations");
+  });
+
+  test("系统窄目录与完整 Manifest 的 Admin Route 保持同源", () => {
+    const full = new Map(
+      systemModuleManifests().map((manifest) => [
+        manifest.name,
+        projectAdminUiManifest(manifest),
+      ]),
+    );
+
+    expect(systemAdminUiManifests()).toEqual([...full.values()]);
+  });
+
+  test("标准 Admin UI Module 保留 Host range 与页面绑定", () => {
+    const manifest = defineAdminUiManifest({
+      name: "case",
+      version: "1.0.0",
+      adminRoutes: [],
+    });
+    const module = defineWindyAdminUiModule({
+      manifest,
+      hostRange: "^0.1.0",
+      pages: [],
+    });
+
+    expect(module.manifest).toBe(manifest);
+    expect(module.hostRange).toBe("^0.1.0");
+  });
+});

package/template/packages/modules/src/admin-ui-manifest.ts

@@ -0,0 +1,53 @@
+import type { ModuleAdminRouteDefinition, ModuleManifest } from "./manifest.js";
+
+/**
+ * 浏览器可见的最小 Module 契约。Server Manifest 的 Migration、Task、Provider、
+ * Audit 和持久化元数据不得进入这个类型或 Web bundle。
+ */
+export interface AdminUiManifest {
+  readonly name: string;
+  readonly version: string;
+  readonly adminRoutes: readonly ModuleAdminRouteDefinition[];
+}
+
+export type AdminPageLoader<TPage = unknown> = () => Promise<{
+  readonly default: TPage;
+}>;
+
+export interface AdminPageBinding<TPage = unknown> {
+  readonly routeKey: string;
+  readonly load: AdminPageLoader<TPage>;
+}
+
+export interface WindyAdminUiModule<TPage = unknown> {
+  readonly manifest: AdminUiManifest;
+  readonly hostRange: string;
+  readonly pages: readonly AdminPageBinding<TPage>[];
+}
+
+export type AdminUiManifestSource = Pick<
+  ModuleManifest,
+  "name" | "version" | "adminRoutes"
+>;
+
+export function defineAdminUiManifest(
+  manifest: AdminUiManifest,
+): AdminUiManifest {
+  return manifest;
+}
+
+export function defineWindyAdminUiModule<TPage>(
+  module: WindyAdminUiModule<TPage>,
+): WindyAdminUiModule<TPage> {
+  return module;
+}
+
+export function projectAdminUiManifest(
+  manifest: AdminUiManifestSource,
+): AdminUiManifest {
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    adminRoutes: manifest.adminRoutes.map((route) => ({ ...route })),
+  };
+}