create-windy 0.2.19 → 0.2.21

package/template/apps/server/src/audit/search-summary.ts

@@ -2,13 +2,26 @@ import type { AuditEvent } from "@southwind-ai/shared";
 import { randomUUIDv7 } from "bun";
 import type { RequestGuardContext } from "../guards.js";
 
+export function searchAuditMetadata(
+  query: string,
+  matched: number,
+): Record<string, unknown> {
+  const normalized = query.trim();
+  return {
+    queryDigest: new Bun.CryptoHasher("sha256")
+      .update(normalized)
+      .digest("hex"),
+    queryLength: normalized.length,
+    matched,
+  };
+}
+
 export function searchAuditEvent(
   context: RequestGuardContext,
   resourceName: string,
   query: string,
   matched: number,
 ): AuditEvent {
-  const normalized = query.trim();
   return {
     id: randomUUIDv7(),
     action: "data.search",
@@ -20,13 +33,7 @@ export function searchAuditEvent(
     },
     target: { type: resourceName },
     requestId: context.requestId,
-    metadata: {
-      queryDigest: new Bun.CryptoHasher("sha256")
-        .update(normalized)
-        .digest("hex"),
-      queryLength: normalized.length,
-      matched,
-    },
+    metadata: searchAuditMetadata(query, matched),
     occurredAt: new Date().toISOString(),
   };
 }

package/template/apps/server/src/example-modules.ts

@@ -1,86 +1,74 @@
-import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+// @windy-module work-order begin
+import {
+  createWorkOrderServerModule,
+  type WorkOrder,
+} from "@southwind-ai/example-work-order";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  InstallableServerModule,
+  ModuleInitializer,
+} from "@southwind-ai/server-sdk";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
-import type { createServerRuntime } from "./runtime.js";
-import type { ScheduledTaskDefinition } from "./scheduler/types.js";
-import type { SearchProvider } from "./search/contracts.js";
+import { platformDataActor } from "./data-access/platform-actor.js";
+import type { ScopedEntityRepository } from "./data-access/scoped-repository.js";
 import type { ManagedDepartment } from "./system/entities.js";
 import type { EntityRepository } from "./system/repository.js";
-import type { RouteApp } from "./system/route-types.js";
-// @windy-module work-order begin
-import type { ModuleInitializer } from "@southwind-ai/server-sdk";
 import { createWorkOrderRepository } from "./work-order/repository.js";
 import { createDrizzleWorkOrderRepository } from "./work-order/drizzle-repository.js";
-import { registerWorkOrderRoutes } from "./work-order/routes.js";
-import { WorkOrderService } from "./work-order/service.js";
+import { createWorkOrderRouteDefinitions } from "./work-order/routes.js";
 import { WorkOrderSearchProvider } from "./work-order/search-provider.js";
-import { createWorkOrderTaskDefinitions } from "./work-order/task.js";
-// @windy-module work-order end
-
-// @windy-module work-order begin
-export const workOrderModuleInitializer: ModuleInitializer = {
-  moduleName: "work-order",
-  initialize(host) {
-    host.registerUploadPolicy({
-      purpose: "work-order.ticket.attachment",
-      maxByteSize: 20 * 1024 * 1024,
-      maxPartByteSize: 4 * 1024 * 1024,
-      sessionTtlMs: 2 * 60 * 60_000,
-      allowedTypes: {
-        "application/pdf": ["pdf"],
-        "image/png": ["png"],
-        "image/jpeg": ["jpg", "jpeg"],
-        "text/plain": ["txt"],
-      },
-      signature: "none",
-    });
-  },
-};
-// @windy-module work-order end
+import { WorkOrderService } from "./work-order/service.js";
 
-export interface ExampleModuleRuntimeDependencies {
-  features: FeatureFlagDefinition[];
+export interface WorkOrderModuleDependencies {
   departments: EntityRepository<ManagedDepartment>;
   db?: NodePgDatabase;
+  /** 测试可注入预置数据的仓储；默认按 db 选择 Drizzle 或内存实现。 */
+  repository?: ScopedEntityRepository<WorkOrder>;
 }
 
-export interface ExampleModuleRuntime {
-  service: WorkOrderService;
-  tasks: ScheduledTaskDefinition[];
-  providers: SearchProvider[];
+export interface WorkOrderModule {
+  readonly manifest: ModuleManifest;
+  setup: InstallableServerModule<ModuleManifest>["setup"];
+  /** @deprecated 测试兼容入口；生产装配使用 manifest + setup。 */
+  readonly initializer: ModuleInitializer;
+  /** 宿主运行时就绪后挂载模块服务；路由与任务 Handler 延迟解析它。 */
+  attach(dependencies: WorkOrderModuleDependencies): void;
 }
 
-export function createExampleModuleRuntime(
-  dependencies: ExampleModuleRuntimeDependencies,
-): ExampleModuleRuntime | undefined {
-  if (!dependencies.features.some(({ key }) => key === "work-order.ticket")) {
-    return undefined;
-  }
-  const service = new WorkOrderService(
-    dependencies.db
-      ? createDrizzleWorkOrderRepository(dependencies.db)
-      : createWorkOrderRepository(),
-    dependencies.departments,
-  );
+/**
+ * 示例工单模块：以 initializer + Host 声明式装配的样板。
+ * Manifest 声明 Route/Task/Provider，初始化器注册实现与受限 Port 定义，
+ * 不再由宿主手工逐项接线。
+ */
+export function createWorkOrderModule(): WorkOrderModule {
+  let service: WorkOrderService | undefined;
+  const requireService = () => {
+    if (!service) throw new Error("示例工单模块尚未挂载");
+    return service;
+  };
+  const serverModule = createWorkOrderServerModule({
+    routes: createWorkOrderRouteDefinitions(requireService),
+    snapshot: () =>
+      requireService().operationalSnapshot(
+        platformDataActor("task_work_order_snapshot", "工单运营快照任务"),
+      ),
+    searchProvider: new WorkOrderSearchProvider(requireService),
+  });
   return {
-    service,
-    tasks: createWorkOrderTaskDefinitions(dependencies.features, service),
-    providers: [new WorkOrderSearchProvider(service)],
+    ...serverModule,
+    initializer: {
+      moduleName: serverModule.manifest.name,
+      initialize: serverModule.setup,
+    },
+    attach(dependencies) {
+      service = new WorkOrderService(
+        dependencies.repository ??
+          (dependencies.db
+            ? createDrizzleWorkOrderRepository(dependencies.db)
+            : createWorkOrderRepository()),
+        dependencies.departments,
+      );
+    },
   };
 }
-
-export interface ExampleModuleRouteDependencies {
-  app: RouteApp;
-  runtime: ReturnType<typeof createServerRuntime>;
-  moduleRuntime?: ExampleModuleRuntime;
-}
-
-export function registerExampleModuleRoutes(
-  dependencies: ExampleModuleRouteDependencies,
-): void {
-  if (!dependencies.moduleRuntime) return;
-  registerWorkOrderRoutes(
-    dependencies.app,
-    dependencies.moduleRuntime.service,
-    dependencies.runtime,
-  );
-}
+// @windy-module work-order end

package/template/apps/server/src/foundation.ts

@@ -13,7 +13,8 @@ import type {
   MenuNode,
   PermissionDefinition,
 } from "@southwind-ai/shared";
-import { installedBusinessModuleFactories } from "./installed-business-modules.js";
+import { resolveLicenseCatalog } from "@southwind-ai/shared";
+import { installedBusinessModules } from "./installed-business-modules.js";
 
 export interface FoundationSnapshot {
   platform: {
@@ -38,8 +39,8 @@ export interface FoundationSnapshot {
 export function loadFoundationModules(): ModuleManifest[] {
   const registry = createModuleRegistry();
   for (const factory of systemModuleFactories) registry.register(factory);
-  for (const factory of installedBusinessModuleFactories) {
-    registry.register(factory);
+  for (const module of installedBusinessModules) {
+    registry.register(() => module.manifest);
   }
   return registry.list();
 }
@@ -72,7 +73,10 @@ export function createFoundationSnapshot(
   config: PlatformConfig = loadPlatformConfig(),
 ): FoundationSnapshot {
   const modules = loadFoundationModules();
-  const catalogs = validateCapabilityCatalogs(modules);
+  const catalogs = validateCapabilityCatalogs(
+    modules,
+    resolveLicenseCatalog(config.license.versions),
+  );
 
   return {
     platform: {

package/template/apps/server/src/guards.test.ts

@@ -71,4 +71,17 @@ describe("guards", () => {
       }).reason,
     ).toBe("entitlement-not-granted");
   });
+
+  test("运行时解析出依赖缺失时拒绝并记录 security.denied", () => {
+    const denied = evaluateFeatureGuard(context, {
+      ...feature,
+      enabled: false,
+      disabledReason: "dependency-missing",
+    });
+
+    expect(denied.allowed).toBe(false);
+    expect(denied.reason).toBe("dependency-missing");
+    expect(denied.auditEvent?.action).toBe("security.denied");
+    expect(denied.auditEvent?.target?.id).toBe(feature.key);
+  });
 });

package/template/apps/server/src/guards.ts

@@ -3,6 +3,7 @@ import type {
   AuditEvent,
   EntitlementKey,
   FeatureFlagDefinition,
+  FeatureFlagState,
   LicenseVersionKey,
 } from "@southwind-ai/shared";
 import { correlationId, isLicenseVersionAllowed } from "@southwind-ai/shared";
@@ -47,6 +48,7 @@ export type GuardDecisionReason =
   | "missing-permission"
   | "role-not-allowed"
   | "feature-disabled"
+  | "dependency-missing"
   | "license-version-not-allowed"
   | "entitlement-not-granted"
   | "license-restricted";
@@ -120,13 +122,21 @@ export function evaluateRoleGuard(
 
 export function evaluateFeatureGuard(
   context: RequestGuardContext,
-  feature: FeatureFlagDefinition,
+  feature: FeatureFlagDefinition & {
+    disabledReason?: FeatureFlagState["reason"];
+  },
 ): GuardDecision {
   if (feature.enabled && feature.visible === "visible") {
     return { allowed: true, reason: "allowed" };
   }
 
-  return deniedDecision(context, "feature-disabled", feature.key);
+  return deniedDecision(
+    context,
+    feature.disabledReason === "dependency-missing"
+      ? "dependency-missing"
+      : "feature-disabled",
+    feature.key,
+  );
 }
 
 export function evaluateEntitlementGuard(

package/template/apps/server/src/index.ts

@@ -2,10 +2,6 @@ import { loadPlatformConfig } from "@southwind-ai/config";
 import pino from "pino";
 import { registerAdminBootstrapRoute } from "./admin/routes.js";
 import { registerSessionContextRoute } from "./session/routes.js";
-import {
-  createFoundationSnapshot,
-  loadFoundationModules,
-} from "./foundation.js";
 import { registerFoundationRoute } from "./foundation-route.js";
 // @windy-module system.scheduler begin
 import { createApplicationServices } from "./application-services.js";
@@ -25,6 +21,7 @@ import {
   createSystemToolHandlers,
   registerAgentRoutes,
 } from "./agent/routes.js";
+import { registerAgentPlatformRuntime } from "./agent/runtime-bootstrap.js";
 // @windy-module system.agent end
 import { registerAuthRoutes, registerAuthSessionRoute } from "./auth/routes.js";
 import { createAuthRuntime } from "./auth/runtime.js";
@@ -44,10 +41,6 @@ import { registerSystemOperationRoutes } from "./system/operations.js";
 import { createPostgresMonitorProbe } from "./system/postgres-monitoring.js";
 // @windy-module system.operations end
 import { registerSystemRoutes } from "./system/routes.js";
-import {
-  createSystemRepositories,
-  synchronizeBuiltInRoles,
-} from "./system/seed.js";
 // @windy-module system.scheduler begin
 import { registerSchedulerRoutes } from "./scheduler/routes.js";
 import { SchedulerWorker } from "./scheduler/worker.js";
@@ -59,25 +52,17 @@ import { registerProfileRoutes } from "./profile/routes.js";
 // @windy-module system.notification begin
 import { registerNotificationRoutes } from "./notification/routes.js";
 // @windy-module system.notification end
-// @windy-module work-order begin
-import {
-  createExampleModuleRuntime,
-  registerExampleModuleRoutes,
-  workOrderModuleInitializer,
-} from "./example-modules.js";
-// @windy-module work-order end
-// @windy-module system.configuration begin
-import { bootstrapModuleConfiguration } from "./configuration/bootstrap.js";
-// @windy-module system.configuration end
 // @windy-module system.storage begin
-import {
-  createStorageRuntime,
-  platformUploadPolicies,
-} from "./storage/runtime.js";
+import { createStorageRuntime } from "./storage/runtime.js";
 import { registerStorageRoutes } from "./storage/routes.js";
 // @windy-module system.storage end
-import { validateServerModuleComposition } from "./module-composition.js";
-import { initializeModuleHosts } from "./module-host.js";
+import { validateInstalledRuntime } from "./module-runtime-validation.js";
+import {
+  adaptModuleSearchProviders,
+  createModuleTaskDefinitions,
+  createModuleToolHandlerMap,
+  installModuleRoutes,
+} from "./module-host.js";
 // @windy-module system.search begin
 import { createSearchHost } from "./search/host.js";
 // @windy-module system.search end
@@ -88,6 +73,7 @@ import {
   createPlatformObservability,
   logPlatformStartup,
 } from "./observability/bootstrap.js";
+import { bootstrapServerModules } from "./module-bootstrap.js";
 
 const logger = pino({ name: "windy-server" });
 const platformConfig = loadPlatformConfig();
@@ -101,45 +87,16 @@ const persistence = createServerPersistence(
 // @windy-module system.audit begin
 await persistence?.auditWriter.recover();
 // @windy-module system.audit end
-// @windy-module system.configuration begin
-const configurationRuntime = await bootstrapModuleConfiguration(
-  platformConfig,
-  persistence?.configVersionRepository,
-);
-// @windy-module system.configuration end
-const foundationSnapshot = createFoundationSnapshot(platformConfig);
-// @windy-module system.configuration begin
-configurationRuntime.bindFoundation(foundationSnapshot);
-// @windy-module system.configuration end
-const foundationModules = loadFoundationModules();
-const moduleHosts = await initializeModuleHosts({
-  modules: foundationModules,
-  initializers: [
-    // @windy-module work-order begin
-    workOrderModuleInitializer,
-    // @windy-module work-order end
-  ],
-  baseUploadPolicies: [
-    // @windy-module system.storage begin
-    ...platformUploadPolicies,
-    // @windy-module system.storage end
-  ],
-});
-void moduleHosts;
-const systemRepositories = createSystemRepositories(foundationSnapshot, {
-  db: persistence?.db,
-});
-const featureSync = await systemRepositories.features.syncManifest(
-  foundationSnapshot.features,
-);
-await systemRepositories.menuRegistry.synchronize({
-  id: "system_bootstrap",
-  type: "service",
-  name: "平台初始化",
-  roleCodes: ["system"],
-  permissionKeys: ["system.menu.manage"],
-});
-await synchronizeBuiltInRoles(systemRepositories, foundationSnapshot);
+const {
+  // @windy-module system.configuration begin
+  configurationRuntime,
+  // @windy-module system.configuration end
+  featureSync,
+  foundationModules,
+  foundationSnapshot,
+  moduleHosts,
+  systemRepositories,
+} = await bootstrapServerModules(platformConfig, persistence);
 // @windy-module system.license begin
 const platformLicenseOptions = createPlatformLicenseRuntimeOptions(process.env);
 const platformLicenseRuntime = new PlatformLicenseRuntime(
@@ -195,33 +152,18 @@ const platformSettings = createPlatformSettingsRuntime(persistence?.db, {
   logoUrl: platformConfig.logoUrl,
 });
 // @windy-module system.settings end
-// @windy-module work-order begin
-const exampleModuleRuntime = createExampleModuleRuntime({
-  features: foundationSnapshot.features,
-  departments: systemRepositories.departments,
-  db: persistence?.db,
-});
-// @windy-module work-order end
-// @windy-module system.search begin
-const businessSearchProviders = [
-  // @windy-module work-order begin
-  ...(exampleModuleRuntime?.providers || []),
-  // @windy-module work-order end
-];
-// @windy-module system.search end
 // @windy-module system.search begin
 const searchHost = createSearchHost(
   foundationModules,
-  { providers: businessSearchProviders },
+  { providers: adaptModuleSearchProviders(moduleHosts) },
   runtime,
 );
 // @windy-module system.search end
 // @windy-module system.scheduler begin
-const businessTaskDefinitions = [
-  // @windy-module work-order begin
-  ...(exampleModuleRuntime?.tasks || []),
-  // @windy-module work-order end
-];
+const moduleTaskDefinitions = createModuleTaskDefinitions(
+  moduleHosts,
+  foundationSnapshot.features,
+);
 const {
   bulkDataService,
   scheduler,
@@ -229,13 +171,14 @@ const {
   notifications: notificationRepository,
   workflow: workflowService,
   governedExportService,
+  durable: durableJobRuntime,
 } = await createApplicationServices({
   persistence,
   systemRepositories,
   foundation: foundationSnapshot,
   runtime,
   storage: storageRuntime,
-  exampleTasks: businessTaskDefinitions,
+  moduleTasks: moduleTaskDefinitions,
   bulkRetentionDays: readPositiveInt(process.env.BULK_DATA_RETENTION_DAYS, 7),
   installModuleDurableHandlers: moduleHosts.installDurableHandlers,
 });
@@ -246,19 +189,15 @@ const schedulerWorker = new SchedulerWorker(
   (result) => observability.metrics.observeSchedulerTick(result),
 );
 // @windy-module system.scheduler end
-
 await bootstrapAdminPassword({
   authService,
   authRepository: persistence?.authRepository,
   repositories: systemRepositories,
   password: process.env.WINDY_BOOTSTRAP_ADMIN_PASSWORD,
 });
-
 const app = createPlatformHttpApp(runtime, observability);
 observability.register(app);
-
 registerAuthSessionRoute(app);
-
 registerAuthRoutes(app, authService, {
   sessionCookieName: platformConfig.security.sessionCookieName,
   secureCookie: process.env.NODE_ENV === "production",
@@ -345,8 +284,19 @@ registerSystemOperationRoutes(app, runtime, foundationSnapshot.features, {
 });
 // @windy-module system.operations end
 // @windy-module system.agent begin
-const toolHandlers = createSystemToolHandlers(systemRepositories, runtime);
+const toolHandlers = new Map([
+  ...createSystemToolHandlers(systemRepositories, runtime),
+  ...createModuleToolHandlerMap(moduleHosts),
+]);
 registerAgentRoutes(app, foundationModules, toolHandlers, runtime);
+registerAgentPlatformRuntime({
+  app,
+  platformConfig,
+  modules: foundationModules,
+  hosts: moduleHosts,
+  runtime,
+  toolHandlers,
+});
 // @windy-module system.agent end
 // @windy-module system.scheduler begin
 registerSchedulerRoutes(app, scheduler, runtime, foundationSnapshot.features);
@@ -360,25 +310,28 @@ registerBulkDataRoutes(
 );
 // @windy-module system.bulk-data end
 // @windy-module work-order begin
-registerExampleModuleRoutes({
-  app,
+installModuleRoutes(moduleHosts, app, {
   runtime,
-  moduleRuntime: exampleModuleRuntime,
+  features: foundationSnapshot.features,
+  jobs: durableJobRuntime.service,
+  storage: {
+    uploads: storageRuntime.uploads,
+    files: storageRuntime.files,
+  },
 });
 // @windy-module work-order end
 
-validateServerModuleComposition({
+validateInstalledRuntime({
   modules: foundationModules,
   routes: app.routes,
   // @windy-module system.scheduler begin
   tasks: scheduledTaskDefinitions,
   // @windy-module system.scheduler end
-  // @windy-module system.agent begin
   tools: toolHandlers,
-  // @windy-module system.agent end
   // @windy-module system.search begin
   providers: searchHost.providerKeys,
   // @windy-module system.search end
+  hosts: moduleHosts,
 });
 
 const port = process.env.PORT ? Number(process.env.PORT) : 9_747;

package/template/apps/server/src/installed-business-modules.ts

@@ -1,10 +1,29 @@
 // @windy-module work-order begin
-import { workOrderModule } from "@southwind-ai/example-work-order";
+import { createWorkOrderModule } from "./example-modules.js";
 // @windy-module work-order end
-import type { ModuleFactory } from "@southwind-ai/modules";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { InstallableServerModule } from "@southwind-ai/server-sdk";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ManagedDepartment } from "./system/entities.js";
+import type { EntityRepository } from "./system/repository.js";
 
-export const installedBusinessModuleFactories: ModuleFactory[] = [
+export interface BusinessModuleRuntime {
+  readonly db?: NodePgDatabase;
+  readonly departments: EntityRepository<ManagedDepartment>;
+}
+
+interface InstalledBusinessModule extends InstallableServerModule<ModuleManifest> {
+  attach(runtime: BusinessModuleRuntime): void;
+}
+
+export const installedBusinessModules: readonly InstalledBusinessModule[] = [
   // @windy-module work-order begin
-  workOrderModule,
+  createWorkOrderModule(),
   // @windy-module work-order end
 ];
+
+export function attachInstalledBusinessModules(
+  runtime: BusinessModuleRuntime,
+): void {
+  for (const module of installedBusinessModules) module.attach(runtime);
+}

package/template/apps/server/src/module-bootstrap.ts

@@ -0,0 +1,83 @@
+import type { PlatformConfig } from "@southwind-ai/config";
+// @windy-module system.configuration begin
+import { bootstrapModuleConfiguration } from "./configuration/bootstrap.js";
+// @windy-module system.configuration end
+import {
+  createFoundationSnapshot,
+  loadFoundationModules,
+} from "./foundation.js";
+import {
+  attachInstalledBusinessModules,
+  installedBusinessModules,
+} from "./installed-business-modules.js";
+import {
+  initializeModuleHosts,
+  synchronizeModuleRolePresets,
+} from "./module-host.js";
+import type { ServerPersistence } from "./persistence.js";
+// @windy-module system.storage begin
+import { platformUploadPolicies } from "./storage/runtime.js";
+// @windy-module system.storage end
+import {
+  createSystemRepositories,
+  synchronizeBuiltInRoles,
+} from "./system/seed.js";
+
+export async function bootstrapServerModules(
+  platformConfig: PlatformConfig,
+  persistence: ServerPersistence | undefined,
+) {
+  // @windy-module system.configuration begin
+  const configurationRuntime = await bootstrapModuleConfiguration(
+    platformConfig,
+    persistence?.configVersionRepository,
+  );
+  // @windy-module system.configuration end
+  const foundationSnapshot = createFoundationSnapshot(platformConfig);
+  // @windy-module system.configuration begin
+  configurationRuntime.bindFoundation(foundationSnapshot);
+  // @windy-module system.configuration end
+  const foundationModules = loadFoundationModules();
+  const moduleHosts = await initializeModuleHosts({
+    modules: foundationModules,
+    installations: installedBusinessModules,
+    baseUploadPolicies: [
+      // @windy-module system.storage begin
+      ...platformUploadPolicies,
+      // @windy-module system.storage end
+    ],
+  });
+  const systemRepositories = createSystemRepositories(foundationSnapshot, {
+    db: persistence?.db,
+  });
+  const featureSync = await systemRepositories.features.syncManifest(
+    foundationSnapshot.features,
+  );
+  await systemRepositories.menuRegistry.synchronize({
+    id: "system_bootstrap",
+    type: "service",
+    name: "平台初始化",
+    roleCodes: ["system"],
+    permissionKeys: ["system.menu.manage"],
+  });
+  await synchronizeBuiltInRoles(systemRepositories, foundationSnapshot);
+  await synchronizeModuleRolePresets(
+    systemRepositories,
+    foundationSnapshot,
+    moduleHosts.rolePresets,
+  );
+  attachInstalledBusinessModules({
+    db: persistence?.db,
+    departments: systemRepositories.departments,
+  });
+  return {
+    // @windy-module system.configuration begin
+    configurationRuntime,
+    // @windy-module system.configuration end
+    featureSync,
+    foundationModules,
+    foundationSnapshot,
+    moduleHosts,
+    systemRepositories,
+  };
+}