create-windy 0.3.19 → 0.4.0

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

@@ -0,0 +1,56 @@
+import moduleAssembly from "../../../../windy.modules.json";
+import {
+  defineWindyServerComposition,
+  type WindyServerModuleAdapter,
+  type WindyServerModuleAttachment,
+} from "@southwind-ai/server-sdk";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ManagedDepartment } from "../system/entities.js";
+import type { EntityRepository } from "../system/repository.js";
+// @windy-module work-order begin
+import { createWorkOrderModule } from "../example-modules.js";
+// @windy-module work-order end
+
+export interface ProjectBusinessModuleRuntime {
+  readonly db?: NodePgDatabase;
+  readonly departments: EntityRepository<ManagedDepartment>;
+}
+
+// @windy-module work-order begin
+const workOrderModule = createWorkOrderModule();
+// @windy-module work-order end
+
+const projectAdapters: readonly WindyServerModuleAdapter<ModuleManifest>[] = [
+  // @windy-module work-order begin
+  {
+    name: "work-order",
+    hostRange: "^0.1.0",
+    runtimeMode: "project-attachment",
+    create: () => workOrderModule,
+  },
+  // @windy-module work-order end
+];
+
+const projectAttachments: readonly WindyServerModuleAttachment<ProjectBusinessModuleRuntime>[] =
+  [
+    // @windy-module work-order begin
+    {
+      name: "work-order",
+      attach: (runtime) => workOrderModule.attach(runtime),
+    },
+    // @windy-module work-order end
+  ];
+
+/**
+ * 客户拥有的 Server 组合声明。
+ *
+ * 标准 package Adapter 由 Host 动态加载；只有需要客户 Repository 的本地 Adapter
+ * 才在这里覆盖，并通过显式 attachment 获得项目运行时。动态 package 永远不会收到
+ * 数据库或平台内部 Repository。
+ */
+export const serverCompositionDeclaration = defineWindyServerComposition({
+  assembly: moduleAssembly,
+  adapters: projectAdapters,
+  attachments: projectAttachments,
+});

package/template/apps/server/src/application-services.ts

@@ -219,6 +219,8 @@ export async function createApplicationServices(
       : new InMemorySchedulerRepository(),
     taskDefinitions,
     runtime: input.runtime,
+    resolveActor: (actorId) =>
+      resolveCurrentSystemActor(input.systemRepositories, actorId),
     // @windy-module system.workflow begin
     workflow,
     // @windy-module system.workflow end

package/template/apps/server/src/bulk-data/service.ts

@@ -28,6 +28,10 @@ import type {
 } from "./types.js";
 export * from "./input-validation.js";
 
+export type BulkResumeAuthorization = (
+  job: BulkDataJob,
+) => Promise<string | undefined>;
+
 export class BulkDataService {
   private readonly handlers = new Map<string, BulkResourceHandler>();
   private readonly limits: BulkDataLimits;
@@ -40,6 +44,7 @@ export class BulkDataService {
     private readonly now: () => Date = () => new Date(),
     blobStore?: BlobStore,
     private readonly durable?: LegacyDurableAdapter,
+    private readonly authorizeResume?: BulkResumeAuthorization,
   ) {
     this.limits = { ...defaultBulkDataLimits, ...limits };
     this.artifacts = new BulkArtifactStore(repository, blobStore);
@@ -155,6 +160,15 @@ export class BulkDataService {
     if (!job || job.status !== "running" || job.attempt !== generation) {
       return;
     }
+    const denial = this.authorizeResume
+      ? await this.authorizeResume(job)
+      : this.durable
+        ? "resume-authorization-unavailable"
+        : undefined;
+    if (denial) {
+      await this.repository.retryOrFail(job.id, denial, this.now());
+      return;
+    }
     await this.processClaimed(job);
   }
 

package/template/apps/server/src/data-governance/export/authorization-port.ts

@@ -77,7 +77,7 @@ export class SystemGovernedExportAuthorization implements GovernedExportAuthoriz
             key: request.policyKey,
             resourceType: request.resourceType,
             version: request.policyVersion,
-            featureKey: featureKey("system.rbac"),
+            featureKey: featureKey("system.user"),
             exportPermissionKey: "system.user.export",
           }
         : undefined;

package/template/apps/server/src/data-governance/export/postgres-api-fixture.ts

@@ -14,7 +14,11 @@ import { DrizzleDurableJobRepository } from "../../jobs/drizzle-repository.js";
 import { DurableJobService } from "../../jobs/service.js";
 import { DurableJobWorker } from "../../jobs/worker.js";
 import { createPlatformObservability } from "../../observability/bootstrap.js";
-import { createServerRuntime, type AuditEventWriter } from "../../runtime.js";
+import {
+  createServerRuntime,
+  type AuditEventWriter,
+  type ServerRuntimeOptions,
+} from "../../runtime.js";
 import { identityRouteConfigs } from "../../system/identity-route-config.js";
 import { registerSystemRoutes } from "../../system/routes.js";
 import { createSystemRepositories } from "../../system/seed.js";
@@ -67,7 +71,7 @@ export async function createPostgresApiFixture(
   const actors = governanceActors();
   const actorResolver = bearerActorResolver(actors);
   const logs: Array<Record<string, unknown>> = [];
-  const runtime = createServerRuntime({}, { actorResolver, auditWriter });
+  const runtime = createGovernanceRuntime({ actorResolver, auditWriter });
   const stack = createGovernanceStack({
     db,
     runtime,
@@ -94,6 +98,18 @@ export async function createPostgresApiFixture(
   };
 }
 
+export function createGovernanceRuntime(
+  options: Pick<ServerRuntimeOptions, "actorResolver" | "auditWriter">,
+) {
+  return createServerRuntime(
+    {},
+    {
+      ...options,
+      featureCatalog: createFoundationSnapshot().features,
+    },
+  );
+}
+
 export function createGovernanceStack(input: {
   db: NodePgDatabase;
   runtime: ReturnType<typeof createServerRuntime>;

package/template/apps/server/src/data-governance/export/postgres-recovery.integration.test.ts

@@ -5,7 +5,7 @@ import { Pool } from "pg";
 import { FileAuditRecoveryQueue } from "../../audit/recovery-queue.js";
 import { ReliableAuditWriter } from "../../audit/reliable-writer.js";
 import { DrizzleAuditLogWriter } from "../../audit/drizzle-log-store.js";
-import { createServerRuntime, type AuditEventWriter } from "../../runtime.js";
+import type { AuditEventWriter } from "../../runtime.js";
 import {
   assertNoCanaries,
   createExport,
@@ -17,6 +17,7 @@ import {
 import {
   apiRequest,
   approveExport,
+  createGovernanceRuntime,
   createGovernanceStack,
   createPostgresApiFixture,
   ownerCanaries,
@@ -249,10 +250,10 @@ async function exerciseRecoveryQueue(
     join(fixture.storageRoot, "audit-recovery.json"),
   );
   const reliable = reliableWriter(primary, queue);
-  const runtime = createServerRuntime(
-    {},
-    { actorResolver: fixture.actorResolver, auditWriter: reliable },
-  );
+  const runtime = createGovernanceRuntime({
+    actorResolver: fixture.actorResolver,
+    auditWriter: reliable,
+  });
   const stack = createGovernanceStack({
     db: fixture.db,
     runtime,
@@ -294,10 +295,10 @@ async function exerciseDoubleFault(
       },
     },
   );
-  const runtime = createServerRuntime(
-    {},
-    { actorResolver: fixture.actorResolver, auditWriter: reliable },
-  );
+  const runtime = createGovernanceRuntime({
+    actorResolver: fixture.actorResolver,
+    auditWriter: reliable,
+  });
   const stack = createGovernanceStack({
     db: fixture.db,
     runtime,

package/template/apps/server/src/data-governance/export/routes-test-fixture.ts

@@ -11,7 +11,8 @@ import { DurableArtifactService } from "../../jobs/artifact-service.js";
 import { InMemoryDurableExecutionRepository } from "../../jobs/in-memory-execution.js";
 import { DurableJobService } from "../../jobs/service.js";
 import { DurableJobWorker } from "../../jobs/worker.js";
-import { createServerRuntime, type AuditEventWriter } from "../../runtime.js";
+import type { AuditEventWriter } from "../../runtime.js";
+import { createRouteTestRuntime } from "../../system/route-test-runtime.js";
 import { FakeRouteApp } from "../../system/route-test-app.js";
 import type { GovernedExportApprovalPort } from "./approval-port.js";
 import { GovernedExportJobRuntime } from "./job-runtime.js";
@@ -34,7 +35,9 @@ export async function createFixture(
       await auditWriter?.write(event, policy);
     },
   };
-  const runtime = createServerRuntime(
+  const foundation = createFoundationSnapshot();
+  const runtime = createRouteTestRuntime(
+    foundation,
     { WINDY_DEV_ADMIN_TOKEN: "token" },
     { auditWriter: writer },
   );
@@ -86,12 +89,7 @@ export async function createFixture(
     { approvalRequired: true, retentionSeconds: 3600 },
   );
   const app = new FakeRouteApp();
-  registerGovernedUserExportRoutes(
-    app,
-    service,
-    runtime,
-    createFoundationSnapshot().features,
-  );
+  registerGovernedUserExportRoutes(app, service, runtime, foundation.features);
   return {
     app,
     approval,

package/template/apps/server/src/data-governance/user-plaintext-routes.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { createFoundationSnapshot } from "../foundation.js";
-import { createServerRuntime, type AuditEventWriter } from "../runtime.js";
+import type { AuditEventWriter } from "../runtime.js";
+import { createRouteTestRuntime } from "../system/route-test-runtime.js";
 import { FakeRouteApp } from "../system/route-test-app.js";
 import { registerSystemRoutes } from "../system/routes.js";
 import { createSystemRepositories } from "../system/seed.js";
@@ -249,7 +250,8 @@ describe("用户敏感字段 API", () => {
 async function fixture(auditWriter?: AuditEventWriter) {
   const snapshot = createFoundationSnapshot();
   const repositories = createSystemRepositories(snapshot);
-  const runtime = createServerRuntime(
+  const runtime = createRouteTestRuntime(
+    snapshot,
     { WINDY_DEV_ADMIN_TOKEN: "token" },
     { auditWriter },
   );

package/template/apps/server/src/feature/routes.authorization.test.ts

@@ -95,6 +95,26 @@ describe("Feature Flag 管理授权", () => {
     expect(item).toMatchObject({ key: "system.rbac", enabled: true });
   });
 
+  test("Feature 管理核心能力不能关闭或隐藏", async () => {
+    const fixture = await createFixture(actor(["developer"], true));
+
+    for (const body of [
+      { enabled: false },
+      { visible: "hidden" },
+      { licenseVersionOverride: ["advanced"] },
+    ]) {
+      const response = (await updateFeature(
+        fixture,
+        body,
+        "system.feature",
+      )) as Response;
+      expect(response.status).toBe(409);
+      await expect(response.json()).resolves.toMatchObject({
+        error: "FEATURE_CONTROL_IMMUTABLE",
+      });
+    }
+  });
+
   test("Feature Flag 更新明确使用关键审计策略", async () => {
     const policies: string[] = [];
     const fixture = await createFixture(actor(["developer"], true), {
@@ -166,7 +186,12 @@ async function createFixture(
     },
   );
   const app = new FakeRouteApp();
-  registerFeatureFlagRoutes(app, repositories.features, runtime);
+  registerFeatureFlagRoutes(
+    app,
+    repositories.features,
+    runtime,
+    snapshot.features.find(({ key }) => key === "system.feature")!,
+  );
   const guardContext = await runtime.createGuardContext(
     new Request("http://localhost/api/system/features/system.profile"),
   );

package/template/apps/server/src/feature/routes.ts

@@ -25,21 +25,16 @@ export function registerFeatureFlagRoutes(
   app: RouteApp,
   repository: ManifestFeatureRepository,
   runtime: ServerRuntime,
+  feature: FeatureFlagDefinition,
 ) {
   app.get("/system/features", async (rawContext) => {
     const { guardContext, query } = routeContext(rawContext);
-    return withFeaturePermission(
-      runtime,
-      guardContext,
-      "read",
-      undefined,
-      () => {
-        const listQuery = parseListQuery(query);
-        return listQuery instanceof Response
-          ? listQuery
-          : repository.list(listQuery, ["key", "label", "module"]);
-      },
-    );
+    return withFeaturePermission(runtime, guardContext, "read", feature, () => {
+      const listQuery = parseListQuery(query);
+      return listQuery instanceof Response
+        ? listQuery
+        : repository.list(listQuery, ["key", "label", "module"]);
+    });
   });
 
   app.get("/system/features/export", async (rawContext) => {
@@ -48,7 +43,7 @@ export function registerFeatureFlagRoutes(
       runtime,
       guardContext,
       "read",
-      undefined,
+      feature,
       async () => {
         const listQuery = parseListQuery(query);
         if (listQuery instanceof Response) return listQuery;
@@ -78,7 +73,7 @@ export function registerFeatureFlagRoutes(
       runtime,
       guardContext,
       "read",
-      undefined,
+      feature,
       async () => {
         const id = requiredId(params);
         return (await repository.get(id)) || notFound("features", id);
@@ -92,11 +87,21 @@ export function registerFeatureFlagRoutes(
       runtime,
       guardContext,
       "manage",
-      undefined,
+      feature,
       async () => {
         const id = requiredId(params);
         const input = readStatePatch(body);
         if (input instanceof Response) return input;
+        if (id === feature.key && wouldDisableFeatureControl(input)) {
+          return Response.json(
+            {
+              error: "FEATURE_CONTROL_IMMUTABLE",
+              message:
+                "功能开关管理是核心恢复能力，不能关闭、隐藏或限制 License。",
+            },
+            { status: 409 },
+          );
+        }
         const item = await repository.updateState(
           id,
           input,
@@ -156,6 +161,19 @@ function readStatePatch(
   };
 }
 
+function wouldDisableFeatureControl(
+  input: Partial<
+    Pick<ManagedFeature, "enabled" | "visible" | "licenseVersionOverride">
+  >,
+): boolean {
+  return (
+    input.enabled === false ||
+    input.visible === "hidden" ||
+    (input.licenseVersionOverride !== undefined &&
+      input.licenseVersionOverride !== null)
+  );
+}
+
 function readLicenseVersionOverride(
   record: Record<string, unknown>,
 ): LicenseVersionKey[] | null | undefined | Response {

package/template/apps/server/src/foundation-activation.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import {
+  // @windy-module system.settings begin
+  composeModuleMenus,
+  validateModuleComposition,
+  // @windy-module system.settings end
+  systemModuleManifests,
+} from "@southwind-ai/modules";
+import { applyPlatformModuleActivation } from "./foundation.js";
+
+describe("平台 Module 运行时启停", () => {
+  // @windy-module system.operations begin
+  test("停用只关闭能力与入口，保留静态实现声明用于一致性校验", () => {
+    const source = systemModuleManifests().find(
+      ({ name }) => name === "system.operations",
+    )!;
+    const disabled = applyPlatformModuleActivation(source, false);
+
+    expect(disabled.features.every(({ enabled }) => !enabled)).toBe(true);
+    expect(disabled.features.every(({ visible }) => visible === "hidden")).toBe(
+      true,
+    );
+    expect(
+      disabled.menus
+        .flatMap(({ children }) => children ?? [])
+        .every(({ visible }) => !visible),
+    ).toBe(true);
+    expect(
+      disabled.menus
+        .filter(({ type }) => type === "catalog")
+        .every(({ visible }) => visible),
+    ).toBe(true);
+    expect(disabled.apiPermissions).toEqual(source.apiPermissions);
+    expect(disabled.adminRoutes).toEqual(source.adminRoutes);
+  });
+  // @windy-module system.operations end
+
+  // @windy-module system.settings begin
+  test("停用一个平台 Module 不改变共享菜单目录壳", () => {
+    const modules = systemModuleManifests().map((manifest) =>
+      applyPlatformModuleActivation(
+        manifest,
+        manifest.name !== "system.settings",
+      ),
+    );
+
+    expect(() => validateModuleComposition(modules)).not.toThrow();
+    expect(
+      composeModuleMenus(modules)
+        .find(({ key }) => key === "system.configuration")
+        ?.children?.find(({ key }) => key === "system.settings")?.visible,
+    ).toBe(false);
+  });
+  // @windy-module system.settings end
+
+  test("启用时保留原始 Manifest 身份", () => {
+    const source = systemModuleManifests()[0]!;
+    expect(applyPlatformModuleActivation(source, true)).toBe(source);
+  });
+});

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

@@ -14,7 +14,10 @@ import type {
   PermissionDefinition,
 } from "@southwind-ai/shared";
 import { resolveLicenseCatalog } from "@southwind-ai/shared";
-import { installedBusinessModules } from "./installed-business-modules.js";
+import {
+  runtimeBusinessModules,
+  serverComposition,
+} from "./module-host/runtime-composition.js";
 
 export interface FoundationSnapshot {
   platform: {
@@ -34,12 +37,21 @@ export interface FoundationSnapshot {
   auditActions: string[];
   auditActionCatalog: readonly AuditActionDefinition[];
   licenseCatalog: readonly LicenseCatalogDefinition[];
+  disabledModuleNames: readonly string[];
 }
 
 export function loadFoundationModules(): ModuleManifest[] {
   const registry = createModuleRegistry();
-  for (const factory of systemModuleFactories) registry.register(factory);
-  for (const module of installedBusinessModules) {
+  for (const factory of systemModuleFactories) {
+    const manifest = factory();
+    registry.register(() =>
+      applyPlatformModuleActivation(
+        manifest,
+        serverComposition.enabledModuleNames.has(manifest.name),
+      ),
+    );
+  }
+  for (const module of runtimeBusinessModules) {
     registry.register(() => module.manifest);
   }
   return registry.list();
@@ -47,10 +59,48 @@ export function loadFoundationModules(): ModuleManifest[] {
 
 export function loadSystemModules(): ModuleManifest[] {
   const registry = createModuleRegistry();
-  for (const factory of systemModuleFactories) registry.register(factory);
+  for (const factory of systemModuleFactories) {
+    const manifest = factory();
+    registry.register(() =>
+      applyPlatformModuleActivation(
+        manifest,
+        serverComposition.enabledModuleNames.has(manifest.name),
+      ),
+    );
+  }
   return registry.list();
 }
 
+export function applyPlatformModuleActivation(
+  manifest: ModuleManifest,
+  enabled: boolean,
+): ModuleManifest {
+  if (enabled) return manifest;
+  return {
+    ...manifest,
+    metadata: {
+      ...manifest.metadata,
+      runtimeActivation: "disabled",
+    },
+    features: manifest.features.map((feature) => ({
+      ...feature,
+      enabled: false,
+      visible: "hidden",
+    })),
+    menus: manifest.menus.map(hideMenu),
+  };
+}
+
+function hideMenu(menu: MenuNode): MenuNode {
+  return {
+    ...menu,
+    visible: menu.type === "catalog" ? menu.visible : false,
+    ...(menu.children
+      ? { children: menu.children.map((child) => hideMenu(child)) }
+      : {}),
+  };
+}
+
 function collectMenus(modules: ModuleManifest[]): MenuNode[] {
   return composeModuleMenus(modules);
 }
@@ -89,7 +139,13 @@ export function createFoundationSnapshot(
       name: config.name,
       enableAI: config.enableAI,
       databaseDialect: config.database.dialect,
-      licenseEnabled: config.license.enabled,
+      licenseEnabled:
+        config.license.enabled &&
+        modules.some(
+          ({ name, metadata }) =>
+            name === "system.license" &&
+            metadata?.runtimeActivation !== "disabled",
+        ),
       auditEnabled: config.audit.enabled,
       ruoyiCompatibilityEnabled: config.compatibility.ruoyiVue.enabled,
     },
@@ -105,5 +161,8 @@ export function createFoundationSnapshot(
     auditActions: collectAuditActions(modules),
     auditActionCatalog: catalogs.auditActions,
     licenseCatalog: catalogs.licenseVersions,
+    disabledModuleNames: modules
+      .filter(({ metadata }) => metadata?.runtimeActivation === "disabled")
+      .map(({ name }) => name),
   };
 }

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

@@ -8,6 +8,8 @@ import {
 import {
   evaluateEntitlementGuard,
   evaluateFeatureGuard,
+  evaluateLicenseRestrictionGuard,
+  evaluateLicenseVersionGuard,
   evaluatePermissionGuard,
   type RequestGuardContext,
 } from "./guards.js";
@@ -72,6 +74,27 @@ describe("guards", () => {
     ).toBe("entitlement-not-granted");
   });
 
+  test("License 未启用时跳过版本、Entitlement 与限制模式", () => {
+    const unrestricted = {
+      ...context,
+      licenseEnforced: false,
+      license: { restricted: true as const, status: "expired" as const },
+    };
+    const licensedFeature = {
+      ...feature,
+      requiredEntitlement: entitlementKey("capability.audit"),
+      allowedLicenseVersions: [],
+    };
+
+    expect(
+      evaluateEntitlementGuard(unrestricted, licensedFeature).allowed,
+    ).toBe(true);
+    expect(
+      evaluateLicenseVersionGuard(unrestricted, licensedFeature).allowed,
+    ).toBe(true);
+    expect(evaluateLicenseRestrictionGuard(unrestricted).allowed).toBe(true);
+  });
+
   test("运行时解析出依赖缺失时拒绝并记录 security.denied", () => {
     const denied = evaluateFeatureGuard(context, {
       ...feature,

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

@@ -58,6 +58,7 @@ export interface RequestGuardContext {
     status?: "valid" | "expired" | "clock-rollback" | "invalid" | "missing";
     restricted?: boolean;
   };
+  licenseEnforced?: boolean;
 }
 
 export type GuardDecisionReason =
@@ -84,6 +85,7 @@ export interface RequestGuardContextOptions {
   resolveLicense?: (
     request: Request,
   ) => RequestGuardContext["license"] | undefined;
+  licenseEnforced?: boolean;
 }
 
 export type PermissionGuardRequirement = Pick<
@@ -107,6 +109,7 @@ export function createRequestGuardContext(
     clientIp: options.clientIp,
     userAgent: options.userAgent,
     license: options.resolveLicense?.(request),
+    licenseEnforced: options.licenseEnforced,
   };
 }
 
@@ -176,6 +179,9 @@ export function evaluateEntitlementGuard(
   context: RequestGuardContext,
   feature: FeatureFlagDefinition,
 ): GuardDecision {
+  if (context.licenseEnforced === false) {
+    return { allowed: true, reason: "allowed" };
+  }
   if (
     !feature.requiredEntitlement ||
     context.license?.entitlements?.includes(feature.requiredEntitlement)
@@ -194,6 +200,9 @@ export function evaluateLicenseVersionGuard(
   context: RequestGuardContext,
   feature: FeatureFlagDefinition,
 ): GuardDecision {
+  if (context.licenseEnforced === false) {
+    return { allowed: true, reason: "allowed" };
+  }
   if (isLicenseVersionAllowed(feature, context.license?.versionKey)) {
     return { allowed: true, reason: "allowed" };
   }
@@ -208,6 +217,9 @@ export function evaluateLicenseRestrictionGuard(
   context: RequestGuardContext,
   explicitlyAllowed = false,
 ): GuardDecision {
+  if (context.licenseEnforced === false) {
+    return { allowed: true, reason: "allowed" };
+  }
   if (!context.license?.restricted || explicitlyAllowed) {
     return { allowed: true, reason: "allowed" };
   }