create-windy 0.2.19 → 0.2.21

package/template/apps/server/src/module-host/initialize.ts

@@ -0,0 +1,328 @@
+import {
+  DurableHandlerRegistry,
+  type DurableHandlerDefinition,
+} from "@southwind-ai/jobs";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import {
+  requireModuleNamespace,
+  type ModuleHost,
+  type ModuleRouteDefinition,
+  type ModuleUploadPolicy,
+} from "@southwind-ai/server-sdk";
+import type {
+  InitializedModuleHosts,
+  InitializeModuleHostsInput,
+  RegisteredModuleAiOperationHandler,
+  RegisteredModuleRolePreset,
+  RegisteredModuleRoute,
+  RegisteredModuleSearchProvider,
+  RegisteredModuleTaskHandler,
+  RegisteredModuleToolHandler,
+} from "./initialize-contracts.js";
+
+export type {
+  InitializedModuleHosts,
+  InitializeModuleHostsInput,
+  RegisteredModuleAiOperationHandler,
+  RegisteredModuleRolePreset,
+  RegisteredModuleRoute,
+  RegisteredModuleSearchProvider,
+  RegisteredModuleTaskHandler,
+  RegisteredModuleToolHandler,
+} from "./initialize-contracts.js";
+
+type HandlerInstaller = (registry: DurableHandlerRegistry) => void;
+
+export async function initializeModuleHosts(
+  input: InitializeModuleHostsInput,
+): Promise<InitializedModuleHosts> {
+  const manifests = new Map(
+    input.modules.map((module) => [module.name, module]),
+  );
+  const initializedNames = new Set<string>();
+  const uploadPolicies: ModuleUploadPolicy[] = [];
+  const uploadPurposes = new Set<string>();
+  for (const policy of input.baseUploadPolicies ?? []) {
+    if (uploadPurposes.has(policy.purpose)) {
+      throw new Error(`上传用途重复注册：${policy.purpose}`);
+    }
+    uploadPurposes.add(policy.purpose);
+    uploadPolicies.push(policy);
+  }
+  const state: HostCollections = {
+    uploadPolicies,
+    uploadPurposes,
+    modulePurposes: new Map<string, Set<string>>(),
+    handlerKeys: new Set<string>(),
+    handlerInstallers: [],
+    routes: [],
+    routeKeys: new Set<string>(),
+    taskHandlers: [],
+    taskKeys: new Set<string>(),
+    toolHandlers: [],
+    toolKeys: new Set<string>(),
+    aiOperationHandlers: [],
+    aiOperationKeys: new Set<string>(),
+    rolePresets: [],
+    rolePresetKeys: new Set<string>(),
+    searchProviders: [],
+    searchProviderKeys: new Set<string>(),
+  };
+
+  const installations = [
+    ...(input.installations ?? []).map((installation) => ({
+      moduleName: installation.manifest.name.trim(),
+      manifest: installation.manifest,
+      setup: installation.setup,
+      legacy: false,
+    })),
+    ...(input.initializers ?? []).map((initializer) => ({
+      moduleName: initializer.moduleName.trim(),
+      manifest: undefined,
+      setup: initializer.initialize,
+      legacy: true,
+    })),
+  ];
+  for (const installation of installations) {
+    const moduleName = installation.moduleName;
+    const manifest = manifests.get(moduleName);
+    if (!manifest) {
+      throw new Error(
+        installation.legacy
+          ? `模块初始化器与已安装模块不匹配：${moduleName}`
+          : `Server Module 与已安装模块不匹配：${moduleName}`,
+      );
+    }
+    if (initializedNames.has(moduleName)) {
+      throw new Error(`模块初始化器重复注册：${moduleName}`);
+    }
+    initializedNames.add(moduleName);
+    if (installation.manifest && installation.manifest !== manifest) {
+      throw new Error(
+        `Server Module Manifest 与能力目录不是同一声明：${moduleName}`,
+      );
+    }
+    await installation.setup(createScopedHost(manifest, state));
+  }
+
+  return {
+    manifests: input.modules,
+    uploadPolicies: [...state.uploadPolicies],
+    routes: [...state.routes],
+    taskHandlers: [...state.taskHandlers],
+    toolHandlers: [...state.toolHandlers],
+    aiOperationHandlers: [...state.aiOperationHandlers],
+    rolePresets: [...state.rolePresets],
+    searchProviders: [...state.searchProviders],
+    manifestOf(moduleName) {
+      const manifest = manifests.get(moduleName);
+      if (!manifest) throw new Error(`模块未安装：${moduleName}`);
+      return manifest;
+    },
+    uploadPurposesOf(moduleName) {
+      return state.modulePurposes.get(moduleName) ?? new Set<string>();
+    },
+    installDurableHandlers(registry) {
+      for (const install of state.handlerInstallers) install(registry);
+    },
+  };
+}
+
+interface HostCollections {
+  uploadPolicies: ModuleUploadPolicy[];
+  uploadPurposes: Set<string>;
+  modulePurposes: Map<string, Set<string>>;
+  handlerKeys: Set<string>;
+  handlerInstallers: HandlerInstaller[];
+  routes: RegisteredModuleRoute[];
+  routeKeys: Set<string>;
+  taskHandlers: RegisteredModuleTaskHandler[];
+  taskKeys: Set<string>;
+  toolHandlers: RegisteredModuleToolHandler[];
+  toolKeys: Set<string>;
+  aiOperationHandlers: RegisteredModuleAiOperationHandler[];
+  aiOperationKeys: Set<string>;
+  rolePresets: RegisteredModuleRolePreset[];
+  rolePresetKeys: Set<string>;
+  searchProviders: RegisteredModuleSearchProvider[];
+  searchProviderKeys: Set<string>;
+}
+
+function createScopedHost(
+  manifest: ModuleManifest,
+  state: HostCollections,
+): ModuleHost {
+  const moduleName = manifest.name;
+  return {
+    moduleName,
+    registerUploadPolicy(policy) {
+      requireModuleNamespace("上传用途", policy.purpose, moduleName);
+      if (state.uploadPurposes.has(policy.purpose)) {
+        throw new Error(`上传用途重复注册：${policy.purpose}`);
+      }
+      state.uploadPurposes.add(policy.purpose);
+      state.uploadPolicies.push(policy);
+      const purposes =
+        state.modulePurposes.get(moduleName) ?? new Set<string>();
+      purposes.add(policy.purpose);
+      state.modulePurposes.set(moduleName, purposes);
+    },
+    registerDurableHandler<T>(definition: DurableHandlerDefinition<T>) {
+      requireModuleNamespace("任务 handler", definition.key, moduleName);
+      if (state.handlerKeys.has(definition.key)) {
+        throw new Error(`任务 handler 重复注册：${definition.key}`);
+      }
+      state.handlerKeys.add(definition.key);
+      state.handlerInstallers.push((registry) => {
+        registry.register(definition);
+      });
+    },
+    registerRoutes(routes) {
+      for (const definition of routes) {
+        requireModuleNamespace(
+          "路由权限",
+          definition.permissionKey,
+          moduleName,
+        );
+        validateRouteDeclaration(manifest, definition);
+        const key = `${definition.method} ${definition.path}`;
+        if (state.routeKeys.has(key)) {
+          throw new Error(`模块路由重复注册：${key}`);
+        }
+        state.routeKeys.add(key);
+        state.routes.push({ moduleName, definition });
+      }
+    },
+    registerTaskHandlers(registrations) {
+      for (const registration of registrations) {
+        requireModuleNamespace("定时任务", registration.taskKey, moduleName);
+        if (!manifest.tasks.some(({ key }) => key === registration.taskKey)) {
+          throw new Error(
+            `定时任务 Handler 未在 Manifest 声明：${registration.taskKey}`,
+          );
+        }
+        if (state.taskKeys.has(registration.taskKey)) {
+          throw new Error(`定时任务 Handler 重复注册：${registration.taskKey}`);
+        }
+        state.taskKeys.add(registration.taskKey);
+        state.taskHandlers.push({ moduleName, registration });
+      }
+    },
+    registerToolHandlers(registrations) {
+      for (const registration of registrations) {
+        requireModuleNamespace("Agent Tool", registration.toolKey, moduleName);
+        if (!manifest.tools.some(({ key }) => key === registration.toolKey)) {
+          throw new Error(
+            `Agent Tool Handler 未在 Manifest 声明：${registration.toolKey}`,
+          );
+        }
+        if (state.toolKeys.has(registration.toolKey)) {
+          throw new Error(
+            `Agent Tool Handler 重复注册：${registration.toolKey}`,
+          );
+        }
+        state.toolKeys.add(registration.toolKey);
+        state.toolHandlers.push({ moduleName, registration });
+      }
+    },
+    registerAiOperationHandlers(registrations) {
+      for (const registration of registrations) {
+        requireModuleNamespace(
+          "AI Operation",
+          registration.operationKey,
+          moduleName,
+        );
+        if (
+          !manifest.aiOperations?.some(
+            ({ key }) => key === registration.operationKey,
+          )
+        ) {
+          throw new Error(
+            `AI Operation Handler 未在 Manifest 声明：${registration.operationKey}`,
+          );
+        }
+        if (state.aiOperationKeys.has(registration.operationKey)) {
+          throw new Error(
+            `AI Operation Handler 重复注册：${registration.operationKey}`,
+          );
+        }
+        state.aiOperationKeys.add(registration.operationKey);
+        state.aiOperationHandlers.push({ moduleName, registration });
+      }
+    },
+    registerRolePresets(presets) {
+      for (const preset of presets) {
+        requireModuleNamespace("角色预设", preset.key, moduleName);
+        if (state.rolePresetKeys.has(preset.key)) {
+          throw new Error(`角色预设重复注册：${preset.key}`);
+        }
+        for (const permissionKey of preset.permissionKeys) {
+          requireModuleNamespace("角色预设权限", permissionKey, moduleName);
+          if (!manifest.permissions.some(({ key }) => key === permissionKey)) {
+            throw new Error(
+              `角色预设引用了模块 ${moduleName} 未声明权限：${permissionKey}`,
+            );
+          }
+        }
+        state.rolePresetKeys.add(preset.key);
+        state.rolePresets.push({ moduleName, preset });
+      }
+    },
+    registerSearchProviders(providers) {
+      for (const provider of providers) {
+        requireModuleNamespace("搜索 Provider", provider.key, moduleName);
+        if (!manifest.providers.some(({ key }) => key === provider.key)) {
+          throw new Error(`搜索 Provider 未在 Manifest 声明：${provider.key}`);
+        }
+        if (state.searchProviderKeys.has(provider.key)) {
+          throw new Error(`搜索 Provider 重复注册：${provider.key}`);
+        }
+        state.searchProviderKeys.add(provider.key);
+        state.searchProviders.push({ moduleName, provider });
+      }
+    },
+  };
+}
+
+function validateRouteDeclaration(
+  manifest: ModuleManifest,
+  definition: ModuleRouteDefinition,
+): void {
+  const binding = manifest.apiPermissions.find(
+    (item) =>
+      item.method === definition.method && item.path === definition.path,
+  );
+  const route = `${definition.method} ${definition.path}`;
+  if (!binding) {
+    throw new Error(`模块路由未在 Manifest 声明：${route}`);
+  }
+  if (binding.permissionKey !== definition.permissionKey) {
+    throw new Error(`模块路由权限与 Manifest 声明不一致：${route}`);
+  }
+  if (
+    definition.featureKey !== undefined &&
+    binding.featureKey !== definition.featureKey
+  ) {
+    throw new Error(`模块路由 Feature 与 Manifest 声明不一致：${route}`);
+  }
+  if (
+    binding.featureKey &&
+    !manifest.features.some(({ key }) => key === binding.featureKey)
+  ) {
+    throw new Error(
+      `模块路由 Feature 未在 Manifest 注册：${binding.featureKey}`,
+    );
+  }
+  if (
+    definition.auditAction &&
+    !manifest.auditActions.some((action) =>
+      typeof action === "string"
+        ? action === definition.auditAction
+        : action.key === definition.auditAction,
+    )
+  ) {
+    throw new Error(
+      `模块路由审计动作未在 Manifest 注册：${definition.auditAction}`,
+    );
+  }
+}

package/template/apps/server/src/module-host/request-context.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import { buildScopeContext } from "../data-access/context.js";
+import type { RequestActor } from "../guards.js";
+import { requestActorFromModule, toModuleActor } from "./request-context.js";
+
+describe("模块 Actor 运行时边界", () => {
+  test("只下发 SDK 白名单字段并保留宿主内部身份映射", () => {
+    const requestActor: RequestActor = {
+      id: "user-1",
+      type: "user",
+      name: "测试用户",
+      username: "tester",
+      displayName: "测试用户",
+      email: "private@example.test",
+      phone: "13800000000",
+      credentialState: "active",
+      passwordChangedAt: "2026-07-25T00:00:00.000Z",
+      roleCodes: ["operator"],
+      permissionKeys: ["work-order.ticket.read"],
+      scopeContext: buildScopeContext("user-1", undefined, [
+        {
+          id: "role-1",
+          code: "operator",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    };
+
+    const actor = toModuleActor(requestActor);
+
+    expect(actor).toEqual({
+      id: "user-1",
+      type: "user",
+      name: "测试用户",
+      username: "tester",
+      displayName: "测试用户",
+      roleCodes: ["operator"],
+      permissionKeys: ["work-order.ticket.read"],
+    });
+    expect(Object.keys(actor).sort()).toEqual([
+      "displayName",
+      "id",
+      "name",
+      "permissionKeys",
+      "roleCodes",
+      "type",
+      "username",
+    ]);
+    expect(Object.isFrozen(actor)).toBe(true);
+    expect(Object.isFrozen(actor.roleCodes)).toBe(true);
+    expect(requestActorFromModule(actor)).toBe(requestActor);
+  });
+
+  test("拒绝业务模块自行构造的 Actor", () => {
+    expect(() =>
+      requestActorFromModule({
+        id: "forged",
+        type: "user",
+        name: "伪造用户",
+        roleCodes: [],
+        permissionKeys: [],
+      }),
+    ).toThrow("不是由当前宿主颁发");
+  });
+});

package/template/apps/server/src/module-host/request-context.ts

@@ -0,0 +1,156 @@
+import { randomUUIDv7 } from "bun";
+import type { DurableJobs } from "@southwind-ai/jobs";
+import type {
+  ModuleActor,
+  ModuleAuditEmitInput,
+  ModuleAuditEmitter,
+  ModuleJobSubmitter,
+  ModuleRequestContext,
+  ModuleStoragePort,
+} from "@southwind-ai/server-sdk";
+import { requireModuleNamespace } from "@southwind-ai/server-sdk";
+import type { AuditEvent } from "@southwind-ai/shared";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+const requestActorByModuleView = new WeakMap<object, RequestActor>();
+
+/**
+ * 收窄为模块 Actor 只读视图。只复制 SDK 明确公开的字段，避免凭据状态、
+ * 联系方式与数据范围令牌在运行时通过属性枚举泄漏给业务模块。
+ */
+export function toModuleActor(actor: RequestActor): ModuleActor {
+  const view: ModuleActor = Object.freeze({
+    id: actor.id,
+    type: actor.type,
+    name: actor.name,
+    ...(actor.username ? { username: actor.username } : {}),
+    ...(actor.displayName ? { displayName: actor.displayName } : {}),
+    roleCodes: Object.freeze([...actor.roleCodes]),
+    permissionKeys: Object.freeze([...actor.permissionKeys]),
+  });
+  requestActorByModuleView.set(view, actor);
+  return view;
+}
+
+/**
+ * Host 内部适配器通过对象身份恢复原始 Actor，使平台内置模块仍能复用宿主的数据
+ * 范围执行链；原始 Actor 不作为 SDK 字段下发，外部业务包也无法访问该映射。
+ */
+export function requestActorFromModule(actor: ModuleActor): RequestActor {
+  const requestActor = requestActorByModuleView.get(actor);
+  if (!requestActor) {
+    throw new Error("模块 Actor 不是由当前宿主颁发");
+  }
+  return requestActor;
+}
+
+export interface ModuleRequestContextInput {
+  moduleName: string;
+  manifest: ModuleManifest;
+  guardContext: RequestGuardContext;
+  params: Record<string, string | undefined>;
+  query: Record<string, string | undefined>;
+  body?: unknown;
+  runtime: ServerRuntime;
+  jobs?: DurableJobs;
+  storage?: ModuleStoragePort;
+}
+
+export function buildModuleRequestContext(
+  input: ModuleRequestContextInput,
+): ModuleRequestContext {
+  return {
+    requestId: input.guardContext.requestId,
+    actor: toModuleActor(input.guardContext.actor),
+    params: input.params,
+    query: input.query,
+    body: input.body,
+    audit: createModuleAuditEmitter(input),
+    jobs: createModuleJobSubmitter(input),
+    storage: input.storage ?? unavailableModuleStorage(input.moduleName),
+  };
+}
+
+function createModuleAuditEmitter(
+  input: ModuleRequestContextInput,
+): ModuleAuditEmitter {
+  const allowed = new Set(
+    input.manifest.auditActions.map((action) =>
+      typeof action === "string" ? action : action.key,
+    ),
+  );
+  return {
+    async emit(action: string, event: ModuleAuditEmitInput = {}) {
+      if (!allowed.has(action)) {
+        throw new Error(
+          `审计动作未在模块 ${input.moduleName} Manifest 注册：${action}`,
+        );
+      }
+      const auditEvent = buildAuditEvent(input.guardContext, action, event);
+      if (event.critical) {
+        await input.runtime.auditSink.recordCriticalEvent(auditEvent);
+        return;
+      }
+      input.runtime.auditSink.recordEvent(auditEvent);
+    },
+  };
+}
+
+function buildAuditEvent(
+  context: RequestGuardContext,
+  action: string,
+  input: ModuleAuditEmitInput,
+): AuditEvent {
+  return {
+    id: randomUUIDv7(),
+    action,
+    outcome: "success",
+    actor: {
+      id: context.actor.id,
+      type: context.actor.type === "anonymous" ? "user" : context.actor.type,
+      name: context.actor.name,
+    },
+    target: input.target,
+    requestId: context.requestId,
+    metadata: input.metadata,
+    occurredAt: new Date().toISOString(),
+  };
+}
+
+function createModuleJobSubmitter(
+  input: ModuleRequestContextInput,
+): ModuleJobSubmitter {
+  return {
+    async submit(job) {
+      requireModuleNamespace("任务 handler", job.handlerKey, input.moduleName);
+      if (!input.jobs) {
+        throw new Error("Durable Jobs 运行时未挂载");
+      }
+      const result = await input.jobs.submit({
+        ...job,
+        queue: input.moduleName,
+        requestedBy: input.guardContext.actor.id,
+      });
+      return { jobId: result.job.id, created: result.created };
+    },
+  };
+}
+
+/**
+ * 存储 Port 未挂载时的防御性实现：任何访问都以明确错误失败，
+ * 而不是让模块悄悄绕过 purpose / owner 约束。
+ */
+function unavailableModuleStorage(moduleName: string): ModuleStoragePort {
+  const fail = (): never => {
+    throw new Error(`模块 ${moduleName} 的存储 Port 未挂载`);
+  };
+  return {
+    createUploadSession: () => fail(),
+    openFile: () => fail(),
+    openPublicFile: () => fail(),
+  };
+}

package/template/apps/server/src/module-host/role-presets.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import type { ManagedRole } from "../system/entities.js";
+import { InMemoryEntityRepository } from "../system/repository.js";
+import type { RegisteredModuleRolePreset } from "./initialize.js";
+import {
+  moduleRolePresetId,
+  synchronizeModuleRolePresets,
+} from "./role-presets.js";
+
+describe("模块角色预设同步", () => {
+  test("预设落库为独立角色且重复同步幂等", async () => {
+    const roles = new InMemoryEntityRepository<ManagedRole>([]);
+    const snapshot = createFoundationSnapshot();
+
+    await synchronizeModuleRolePresets({ roles }, snapshot, [preset()]);
+    const created = await roles.get(moduleRolePresetId("shop.manager"));
+    expect(created).toMatchObject({
+      code: "shop.manager",
+      name: "店长",
+      dataScope: "department-and-children",
+      permissionKeys: ["shop.item.manage", "shop.item.read"],
+      status: "active",
+    });
+
+    await synchronizeModuleRolePresets({ roles }, snapshot, [preset()]);
+    const again = await roles.get(moduleRolePresetId("shop.manager"));
+    expect(again?.permissionKeys).toEqual(created?.permissionKeys);
+  });
+
+  test("已存在角色保留管理员手工追加的授权", async () => {
+    const roles = new InMemoryEntityRepository<ManagedRole>([]);
+    const snapshot = createFoundationSnapshot();
+    await synchronizeModuleRolePresets({ roles }, snapshot, [preset()]);
+
+    const id = moduleRolePresetId("shop.manager");
+    const existing = await roles.get(id);
+    if (!existing) throw new Error("角色预设未创建");
+    await roles.update(
+      id,
+      { permissionKeys: [...existing.permissionKeys, "system.menu.read"] },
+      actor,
+    );
+
+    await synchronizeModuleRolePresets({ roles }, snapshot, [preset()]);
+    const merged = await roles.get(id);
+    expect(merged?.permissionKeys).toContain("system.menu.read");
+    expect(merged?.permissionKeys).toContain("shop.item.manage");
+  });
+
+  test("预设 Code 与既有角色冲突时启动失败", async () => {
+    const roles = new InMemoryEntityRepository<ManagedRole>([
+      {
+        id: "role_custom",
+        code: "shop.manager",
+        name: "手工角色",
+        dataScope: "self",
+        permissionKeys: [],
+        menuKeys: [],
+        status: "active",
+        createdAt: "2026-07-16T00:00:00.000Z",
+        createdBy: "system",
+        updatedAt: "2026-07-16T00:00:00.000Z",
+        updatedBy: "system",
+      },
+    ]);
+
+    await expect(
+      synchronizeModuleRolePresets({ roles }, createFoundationSnapshot(), [
+        preset(),
+      ]),
+    ).rejects.toThrow("角色预设与既有角色冲突：shop.manager");
+  });
+});
+
+function preset(): RegisteredModuleRolePreset {
+  return {
+    moduleName: "shop",
+    preset: {
+      key: "shop.manager",
+      label: "店长",
+      dataScope: "department-and-children",
+      permissionKeys: ["shop.item.read", "shop.item.manage"],
+    },
+  };
+}
+
+const actor = {
+  id: "system_bootstrap",
+  type: "service" as const,
+  name: "平台初始化",
+  roleCodes: ["system"],
+  permissionKeys: ["system.role.manage"],
+};