create-windy 0.2.19 → 0.2.20

package/template/apps/server/src/runtime-feature.ts

@@ -1,4 +1,10 @@
-import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import {
+  isLicenseVersionAllowed,
+  resolveFeatureState,
+  type FeatureFlagDefinition,
+  type FeatureFlagState,
+} from "@southwind-ai/shared";
+import type { RequestGuardContext } from "./guards.js";
 
 export interface FeatureFlagRuntimeResolver {
   resolve(
@@ -16,11 +22,16 @@ export interface FeatureFlagRuntimeState {
   allowedLicenseVersions?: FeatureFlagDefinition["allowedLicenseVersions"];
 }
 
+/** 运行时解析后的 Feature；disabledReason 复用 shared resolveFeatureState 语义。 */
+export interface ResolvedFeatureFlag extends FeatureFlagDefinition {
+  disabledReason?: FeatureFlagState["reason"];
+}
+
 export class RuntimeFeatureCatalog {
   private readonly definitions = new Map<string, FeatureFlagDefinition>();
   private readonly requestCache = new WeakMap<
     object,
-    Map<string, FeatureFlagDefinition>
+    Map<string, ResolvedFeatureFlag>
   >();
 
   constructor(
@@ -34,18 +45,18 @@ export class RuntimeFeatureCatalog {
   }
 
   resolve(
-    context: object,
+    context: RequestGuardContext,
     manifestFeature: FeatureFlagDefinition,
-  ): Promise<FeatureFlagDefinition> {
+  ): Promise<ResolvedFeatureFlag> {
     this.definitions.set(manifestFeature.key, manifestFeature);
     return this.resolveInternal(context, manifestFeature, new Set());
   }
 
   private async resolveInternal(
-    context: object,
+    context: RequestGuardContext,
     manifestFeature: FeatureFlagDefinition,
     visiting: ReadonlySet<string>,
-  ): Promise<FeatureFlagDefinition> {
+  ): Promise<ResolvedFeatureFlag> {
     const cache = this.cacheFor(context);
     const cached = cache.get(manifestFeature.key);
     if (cached) return cached;
@@ -53,33 +64,42 @@ export class RuntimeFeatureCatalog {
       return disabledFeature(manifestFeature);
     }
 
-    const resolved = await this.resolveOwnState(manifestFeature);
-    if (!resolved.enabled || !manifestFeature.dependencies?.length) {
-      cache.set(manifestFeature.key, resolved);
-      return resolved;
-    }
-
-    const nextVisiting = new Set(visiting);
-    nextVisiting.add(manifestFeature.key);
-    for (const dependencyKey of manifestFeature.dependencies) {
-      const dependency = this.definitions.get(dependencyKey);
-      if (!dependency) {
-        const disabled = disabledFeature(resolved);
-        cache.set(manifestFeature.key, disabled);
-        return disabled;
-      }
-      const dependencyState = await this.resolveInternal(
-        context,
-        dependency,
-        nextVisiting,
-      );
-      if (!dependencyState.enabled || dependencyState.visible !== "visible") {
-        const disabled = { ...resolved, enabled: false };
-        cache.set(manifestFeature.key, disabled);
-        return disabled;
+    const own = await this.resolveOwnState(manifestFeature);
+    // dependencies 来自 manifest；启用集合取运行时解析后的依赖状态，
+    // 最终判定统一交给 shared resolveFeatureState，避免第二套漂移逻辑。
+    const enabledDependencies = new Set<string>();
+    if (
+      own.enabled &&
+      own.visible === "visible" &&
+      manifestFeature.dependencies?.length
+    ) {
+      const nextVisiting = new Set(visiting);
+      nextVisiting.add(manifestFeature.key);
+      for (const dependencyKey of manifestFeature.dependencies) {
+        const dependency = this.definitions.get(dependencyKey);
+        if (!dependency) continue;
+        const dependencyState = await this.resolveInternal(
+          context,
+          dependency,
+          nextVisiting,
+        );
+        if (
+          dependencyState.enabled &&
+          dependencyState.visible === "visible" &&
+          isFeatureLicensedForContext(dependencyState, context)
+        ) {
+          enabledDependencies.add(dependencyKey);
+        }
       }
     }
 
+    const state = resolveFeatureState(own, enabledDependencies, true);
+    const resolved: ResolvedFeatureFlag = {
+      ...own,
+      enabled: state.enabled,
+      visible: state.visible,
+      ...(state.reason ? { disabledReason: state.reason } : {}),
+    };
     cache.set(manifestFeature.key, resolved);
     return resolved;
   }
@@ -108,7 +128,9 @@ export class RuntimeFeatureCatalog {
     }
   }
 
-  private cacheFor(context: object): Map<string, FeatureFlagDefinition> {
+  private cacheFor(
+    context: RequestGuardContext,
+  ): Map<string, ResolvedFeatureFlag> {
     let cache = this.requestCache.get(context);
     if (!cache) {
       cache = new Map();
@@ -118,6 +140,19 @@ export class RuntimeFeatureCatalog {
   }
 }
 
+function isFeatureLicensedForContext(
+  feature: FeatureFlagDefinition,
+  context: RequestGuardContext,
+): boolean {
+  return (
+    isLicenseVersionAllowed(feature, context.license?.versionKey) &&
+    (!feature.requiredEntitlement ||
+      Boolean(
+        context.license?.entitlements?.includes(feature.requiredEntitlement),
+      ))
+  );
+}
+
 function disabledFeature(
   feature: FeatureFlagDefinition,
 ): FeatureFlagDefinition {

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

@@ -273,6 +273,7 @@ describe("server runtime", () => {
     expect(await runtime.resolveFeature(context, capability)).toMatchObject({
       enabled: false,
       visible: "visible",
+      disabledReason: "dependency-missing",
     });
   });
 

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

@@ -25,11 +25,13 @@ import { developmentAdminActor } from "./runtime-development.js";
 import {
   RuntimeFeatureCatalog,
   type FeatureFlagRuntimeResolver,
+  type ResolvedFeatureFlag,
 } from "./runtime-feature.js";
 
 export type {
   FeatureFlagRuntimeResolver,
   FeatureFlagRuntimeState,
+  ResolvedFeatureFlag,
 } from "./runtime-feature.js";
 
 export interface SessionRecord {
@@ -230,7 +232,7 @@ export function createServerRuntime(
     async resolveFeature(
       context: ReturnType<typeof createRequestGuardContext>,
       manifestFeature: FeatureFlagDefinition,
-    ): Promise<FeatureFlagDefinition> {
+    ): Promise<ResolvedFeatureFlag> {
       return featureCatalog.resolve(context, manifestFeature);
     },
     recordDecisions(decisions: Array<GuardDecision | undefined>) {

package/template/apps/server/src/system/built-in-roles.ts

@@ -90,7 +90,7 @@ function role(
   };
 }
 
-function menuKeysForPermissions(
+export function menuKeysForPermissions(
   snapshot: FoundationSnapshot,
   permissions: string[],
 ): string[] {

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

@@ -1,12 +1,15 @@
 import { describe, expect, test } from "bun:test";
 import { featureKey } from "@southwind-ai/shared";
+import { validateCapabilityCatalogs } from "@southwind-ai/modules";
 import {
   createFoundationSnapshot,
   loadFoundationModules,
 } from "../foundation.js";
-import { createExampleModuleRuntime } from "../example-modules.js";
-import type { ManagedDepartment } from "../system/entities.js";
-import { InMemoryEntityRepository } from "../system/repository.js";
+import { createWorkOrderModule } from "../example-modules.js";
+import {
+  adaptModuleSearchProviders,
+  initializeModuleHosts,
+} from "../module-host.js";
 
 describe("平台模块 composition root", () => {
   test("默认安装平台能力模块与可删除的工单模块", () => {
@@ -47,6 +50,21 @@ describe("平台模块 composition root", () => {
     );
   });
 
+  test("示例工单的合法 Migration Bundle 通过启动校验", () => {
+    const modules = loadFoundationModules();
+    const workOrder = modules.find(({ name }) => name === "work-order");
+
+    expect(() => validateCapabilityCatalogs(modules)).not.toThrow();
+    expect(workOrder?.migrationBundle?.migrations.map(({ id }) => id)).toEqual([
+      "work-order.0001.create-work-orders",
+    ]);
+    expect(
+      workOrder?.migrationBundle?.migrations.every(({ checksum }) =>
+        checksum.startsWith("sha256:"),
+      ),
+    ).toBe(true);
+  });
+
   test("业务 API 的 package 依赖图不经过 Windy Web 或 Vue", async () => {
     const serverPackage = await packageJson(
       new URL("../../package.json", import.meta.url),
@@ -66,21 +84,23 @@ describe("平台模块 composition root", () => {
     });
     expect(serverPackage.dependencies).not.toHaveProperty("@southwind-ai/web");
     expect(serverPackage.dependencies).not.toHaveProperty("vue");
-    expect(businessPackage.dependencies).not.toHaveProperty("@southwind-ai/web");
+    expect(businessPackage.dependencies).not.toHaveProperty(
+      "@southwind-ai/web",
+    );
     expect(businessPackage.dependencies).not.toHaveProperty("vue");
     expect(webPackage.dependencies).not.toHaveProperty(
       "@southwind-ai/example-work-order",
     );
   });
 
-  test("示例模块运行时从同一 composition seam 提供搜索 Handler", () => {
-    const snapshot = createFoundationSnapshot();
-    const runtime = createExampleModuleRuntime({
-      features: snapshot.features,
-      departments: new InMemoryEntityRepository<ManagedDepartment>(),
+  test("示例模块经 Host 声明式装配提供搜索 Provider", async () => {
+    const module = createWorkOrderModule();
+    const hosts = await initializeModuleHosts({
+      modules: [module.manifest],
+      installations: [module],
     });
 
-    expect(runtime?.providers.map(({ key }) => key)).toEqual([
+    expect(adaptModuleSearchProviders(hosts).map(({ key }) => key)).toEqual([
       "work-order.ticket.search",
     ]);
   });

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

@@ -1,6 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import type { WorkOrder } from "@southwind-ai/example-work-order";
+import {
+  workOrderModule,
+  type WorkOrder,
+} from "@southwind-ai/example-work-order";
 import { licenseVersionKey } from "@southwind-ai/shared";
+import { initializeModuleHosts, installModuleRoutes } from "../module-host.js";
+import { createWorkOrderModule } from "../example-modules.js";
 import { InMemoryEntityRepository } from "../system/repository.js";
 import { InMemoryScopedEntityRepository } from "../data-access/scoped-repository.js";
 import { buildScopeContext } from "../data-access/context.js";
@@ -8,8 +13,6 @@ import type { ManagedDepartment } from "../system/entities.js";
 import { FakeRouteApp } from "../system/route-test-app.js";
 import { createServerRuntime } from "../runtime.js";
 import type { RequestActor } from "../guards.js";
-import { registerWorkOrderRoutes } from "./routes.js";
-import { WorkOrderService } from "./service.js";
 import { workOrderDataScopeBinding } from "./repository.js";
 
 describe("示例工单 routes", () => {
@@ -39,6 +42,9 @@ describe("示例工单 routes", () => {
     expect(await reason(rbacDenied.invoke("GET", "/work-orders"))).toBe(
       "missing-permission",
     );
+    expect(
+      rbacDenied.runtime.auditSink.list().map(({ action }) => action),
+    ).toContain("security.denied");
 
     const licenseDenied = await createFixture({ licenseVersion: "basic" });
     expect(await reason(licenseDenied.invoke("GET", "/work-orders"))).toBe(
@@ -100,23 +106,29 @@ async function createFixture(options: FixtureOptions = {}) {
       },
     },
   );
+  const module = createWorkOrderModule();
+  const hosts = await initializeModuleHosts({
+    modules: [module.manifest],
+    installations: [module],
+  });
+  module.attach({
+    departments: new InMemoryEntityRepository<ManagedDepartment>([
+      department("dept_a"),
+      department("dept_b"),
+    ]),
+    repository: new InMemoryScopedEntityRepository<WorkOrder>(
+      [
+        ticket("ticket_self", "user_self", "dept_a"),
+        ticket("ticket_other", "user_other", "dept_b"),
+      ],
+      workOrderDataScopeBinding,
+    ),
+  });
   const app = new FakeRouteApp();
-  const workOrders = new InMemoryScopedEntityRepository<WorkOrder>(
-    [
-      ticket("ticket_self", "user_self", "dept_a"),
-      ticket("ticket_other", "user_other", "dept_b"),
-    ],
-    workOrderDataScopeBinding,
-  );
-  const departments = new InMemoryEntityRepository<ManagedDepartment>([
-    department("dept_a"),
-    department("dept_b"),
-  ]);
-  registerWorkOrderRoutes(
-    app,
-    new WorkOrderService(workOrders, departments),
+  installModuleRoutes(hosts, app, {
     runtime,
-  );
+    features: workOrderModule().features,
+  });
   const guardContext = await runtime.createGuardContext(
     new Request("http://localhost/api/work-orders"),
   );

package/template/apps/server/src/work-order/routes.ts

@@ -1,141 +1,123 @@
 import {
   createWorkOrderSchema,
   updateWorkOrderSchema,
-  workOrderModule,
 } from "@southwind-ai/example-work-order";
-import type { ApiPermissionBinding } from "@southwind-ai/shared";
-import { recordMutationAudit } from "../audit/policy.js";
-import { accessCall } from "../system/resource-access-response.js";
-import { evaluateRouteGuards } from "../route-guards.js";
-import type { createServerRuntime } from "../runtime.js";
-import {
-  forbidden,
-  notFound,
-  resourceEvent,
-  routeContext,
-} from "../system/route-helpers.js";
-import type { RouteApp } from "../system/route-types.js";
+import type { ModuleRouteDefinition } from "@southwind-ai/server-sdk";
+import { searchAuditMetadata } from "../audit/search-summary.js";
+import { requestActorFromModule } from "../module-host/request-context.js";
 import { parsePagination } from "../pagination.js";
+import { accessCall } from "../system/resource-access-response.js";
+import { notFound } from "../system/route-helpers.js";
 import type { WorkOrderService } from "./service.js";
-import { searchAuditEvent } from "../audit/search-summary.js";
 
-type ServerRuntime = ReturnType<typeof createServerRuntime>;
-const manifest = workOrderModule();
-const feature = manifest.features[0];
-
-export function registerWorkOrderRoutes(
-  app: RouteApp,
-  service: WorkOrderService,
-  runtime: ServerRuntime,
-) {
-  app.get("/work-orders", (raw) =>
-    guarded(raw, binding("GET", "/api/work-orders"), runtime, async () => {
-      const context = routeContext(raw);
-      const pagination = parsePagination(context.query);
-      if (pagination instanceof Response) return pagination;
-      const result = await accessCall(() =>
-        service.list(
-          { ...pagination, q: context.query.q },
-          context.guardContext.actor,
-        ),
-      );
-      if (!(result instanceof Response) && context.query.q?.trim()) {
-        runtime.auditSink.recordEvent(
-          searchAuditEvent(
-            context.guardContext,
-            "work-order",
-            context.query.q,
-            result.total,
+/**
+ * 示例工单的 Guarded Route 定义。
+ *
+ * 只声明 method/path/permissionKey 与 Handler；Guard、审计上下文与受限 Port
+ * 由宿主在 installModuleRoutes 时统一绑定，不再手工查询 Manifest 绑定。
+ * `requireService` 延迟解析宿主装配完成后才存在的模块服务。
+ */
+export function createWorkOrderRouteDefinitions(
+  requireService: () => WorkOrderService,
+): ModuleRouteDefinition[] {
+  return [
+    {
+      method: "GET",
+      path: "/api/work-orders",
+      permissionKey: "work-order.ticket.read",
+      handler: async (context) => {
+        const pagination = parsePagination(context.query);
+        if (pagination instanceof Response) return pagination;
+        const result = await accessCall(() =>
+          requireService().list(
+            { ...pagination, q: context.query.q },
+            requestActorFromModule(context.actor),
           ),
         );
-      }
-      return result;
-    }),
-  );
-
-  app.get("/work-orders/:id", (raw) =>
-    guarded(raw, binding("GET", "/api/work-orders/:id"), runtime, async () => {
-      const context = routeContext(raw);
-      const id = context.params.id || "";
-      const item = await accessCall(() =>
-        service.get(id, context.guardContext.actor),
-      );
-      return item instanceof Response
-        ? item
-        : item || notFound("work-order", id);
-    }),
-  );
-
-  app.post("/work-orders", (raw) =>
-    guarded(raw, binding("POST", "/api/work-orders"), runtime, async () => {
-      const context = routeContext(raw);
-      const parsed = createWorkOrderSchema.safeParse(context.body);
-      if (!parsed.success) return invalid(parsed.error.issues[0]?.message);
-      const item = await accessCall(() =>
-        service.create(parsed.data, context.guardContext.actor),
-      );
-      if (item instanceof Response) return item;
-      await audit(runtime, context.guardContext, "crud.create", item.id);
-      return item;
-    }),
-  );
-
-  app.put("/work-orders/:id", (raw) =>
-    guarded(raw, binding("PUT", "/api/work-orders/:id"), runtime, async () => {
-      const context = routeContext(raw);
-      const id = context.params.id || "";
-      const parsed = updateWorkOrderSchema.safeParse(context.body);
-      if (!parsed.success) return invalid(parsed.error.issues[0]?.message);
-      const item = await accessCall(() =>
-        service.update(id, parsed.data, context.guardContext.actor),
-      );
-      if (item instanceof Response) return item;
-      if (!item) return notFound("work-order", id);
-      await audit(runtime, context.guardContext, "crud.update", id);
-      return item;
-    }),
-  );
-
-  app.delete("/work-orders/:id", (raw) =>
-    guarded(
-      raw,
-      binding("DELETE", "/api/work-orders/:id"),
-      runtime,
-      async () => {
-        const context = routeContext(raw);
+        if (!(result instanceof Response) && context.query.q?.trim()) {
+          await context.audit.emit("data.search", {
+            target: { type: "work-order" },
+            metadata: searchAuditMetadata(context.query.q, result.total),
+          });
+        }
+        return result;
+      },
+    },
+    {
+      method: "GET",
+      path: "/api/work-orders/:id",
+      permissionKey: "work-order.ticket.read",
+      handler: async (context) => {
         const id = context.params.id || "";
         const item = await accessCall(() =>
-          service.archive(id, context.guardContext.actor),
+          requireService().get(id, requestActorFromModule(context.actor)),
+        );
+        return item instanceof Response
+          ? item
+          : item || notFound("work-order", id);
+      },
+    },
+    {
+      method: "POST",
+      path: "/api/work-orders",
+      permissionKey: "work-order.ticket.create",
+      handler: async (context) => {
+        const parsed = createWorkOrderSchema.safeParse(context.body);
+        if (!parsed.success) return invalid(parsed.error.issues[0]?.message);
+        const item = await accessCall(() =>
+          requireService().create(
+            parsed.data,
+            requestActorFromModule(context.actor),
+          ),
+        );
+        if (item instanceof Response) return item;
+        await context.audit.emit("crud.create", {
+          target: { type: "work-order", id: item.id },
+        });
+        return item;
+      },
+    },
+    {
+      method: "PUT",
+      path: "/api/work-orders/:id",
+      permissionKey: "work-order.ticket.manage",
+      handler: async (context) => {
+        const id = context.params.id || "";
+        const parsed = updateWorkOrderSchema.safeParse(context.body);
+        if (!parsed.success) return invalid(parsed.error.issues[0]?.message);
+        const item = await accessCall(() =>
+          requireService().update(
+            id,
+            parsed.data,
+            requestActorFromModule(context.actor),
+          ),
         );
         if (item instanceof Response) return item;
         if (!item) return notFound("work-order", id);
-        await audit(runtime, context.guardContext, "crud.delete", id);
+        await context.audit.emit("crud.update", {
+          target: { type: "work-order", id },
+        });
         return item;
       },
-    ),
-  );
-}
-
-async function guarded(
-  raw: unknown,
-  permission: ApiPermissionBinding,
-  runtime: ServerRuntime,
-  handler: () => unknown,
-) {
-  const decision = await evaluateRouteGuards(
-    runtime,
-    routeContext(raw).guardContext,
-    { permission, feature },
-  );
-  return decision.allowed ? handler() : forbidden(decision.reason);
-}
-
-function binding(method: string, path: string): ApiPermissionBinding {
-  const result = manifest.apiPermissions.find(
-    (item) => item.method === method && item.path === path,
-  );
-  if (!result) throw new Error(`示例工单缺少 API 绑定：${method} ${path}`);
-  return result;
+    },
+    {
+      method: "DELETE",
+      path: "/api/work-orders/:id",
+      permissionKey: "work-order.ticket.manage",
+      handler: async (context) => {
+        const id = context.params.id || "";
+        const item = await accessCall(() =>
+          requireService().archive(id, requestActorFromModule(context.actor)),
+        );
+        if (item instanceof Response) return item;
+        if (!item) return notFound("work-order", id);
+        await context.audit.emit("crud.delete", {
+          target: { type: "work-order", id },
+        });
+        return item;
+      },
+    },
+  ];
 }
 
 function invalid(message = "工单内容无效") {
@@ -144,16 +126,3 @@ function invalid(message = "工单内容无效") {
     { status: 400 },
   );
 }
-
-function audit(
-  runtime: ServerRuntime,
-  context: ReturnType<typeof routeContext>["guardContext"],
-  action: "crud.create" | "crud.update" | "crud.delete",
-  id: string,
-) {
-  return recordMutationAudit(
-    runtime,
-    "work-orders",
-    resourceEvent(context, action, "work-order", id),
-  );
-}

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

@@ -1,6 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import { workOrderModule, type WorkOrder } from "@southwind-ai/example-work-order";
-import { systemFoundationModule, type ModuleManifest } from "@southwind-ai/modules";
+import {
+  workOrderModule,
+  type WorkOrder,
+} from "@southwind-ai/example-work-order";
+import {
+  systemFoundationModule,
+  type ModuleManifest,
+} from "@southwind-ai/modules";
 import { licenseVersionKey } from "@southwind-ai/shared";
 import { buildScopeContext } from "../data-access/context.js";
 import { InMemoryScopedEntityRepository } from "../data-access/scoped-repository.js";
@@ -11,6 +17,7 @@ import { searchTestContext } from "../search/test-support.js";
 import type { ManagedDepartment } from "../system/entities.js";
 import { InMemoryEntityRepository } from "../system/repository.js";
 import type { RouteApp } from "../system/route-types.js";
+import { adaptModuleSearchProvider } from "../module-host.js";
 import { workOrderDataScopeBinding } from "./repository.js";
 import { WorkOrderSearchProvider } from "./search-provider.js";
 import { WorkOrderService } from "./service.js";
@@ -45,7 +52,11 @@ describe("搜索 API 数据范围", () => {
     );
     const service = new SearchService(
       modules,
-      [new WorkOrderSearchProvider(workOrders)],
+      [
+        adaptModuleSearchProvider(
+          new WorkOrderSearchProvider(() => workOrders),
+        ),
+      ],
       runtime,
     );
     const context = searchTestContext([