create-windy 0.2.19 → 0.2.21

package/template/packages/server-sdk/src/module-host.ts

@@ -1,4 +1,10 @@
 import type { DurableHandlerDefinition } from "@southwind-ai/jobs";
+import type { ModuleAiOperationHandlerRegistration } from "./ai-operation-registration.js";
+import type { ModuleRolePreset } from "./role-preset.js";
+import type { ModuleRouteDefinition } from "./route-definition.js";
+import type { ModuleSearchProvider } from "./search-provider-port.js";
+import type { ModuleTaskHandlerRegistration } from "./task-registration.js";
+import type { ModuleToolHandlerRegistration } from "./tool-registration.js";
 
 export interface ModuleUploadPolicy {
   purpose: string;
@@ -10,20 +16,54 @@ export interface ModuleUploadPolicy {
 }
 
 /**
- * 模块作用域 Host。注册的任务 Key 与上传用途必须使用初始化器模块名作为命名空间。
+ * 模块作用域 Host。注册的所有 Key（上传用途、任务、工具、角色预设、Provider）
+ * 必须使用初始化器模块名作为命名空间，越界或重复注册在 Server 监听前抛错。
+ *
+ * 模块只获得受限 Port（Guarded Route、Actor 视图、Audit、Durable Submit、
+ * 受限 Upload/BlobRead）；Worker 与 Repository 始终由宿主持有。
  */
 export interface ModuleHost {
   readonly moduleName: string;
   registerUploadPolicy(policy: ModuleUploadPolicy): void;
   registerDurableHandler<T>(definition: DurableHandlerDefinition<T>): void;
+  /** 注册 Guarded API 路由；须与 Manifest `apiPermissions` 声明一致。 */
+  registerRoutes(routes: readonly ModuleRouteDefinition[]): void;
+  /** 注册 Manifest `tasks` 已声明定时任务的执行体。 */
+  registerTaskHandlers(
+    registrations: readonly ModuleTaskHandlerRegistration[],
+  ): void;
+  /** 注册 Manifest `tools` 已声明 Agent Tool 的执行体。 */
+  registerToolHandlers(
+    registrations: readonly ModuleToolHandlerRegistration[],
+  ): void;
+  /** 注册 Manifest `aiOperations` 已声明的模型无关 Operation 执行计划。 */
+  registerAiOperationHandlers(
+    registrations: readonly ModuleAiOperationHandlerRegistration[],
+  ): void;
+  /** 注册角色预设；permissionKeys 须属于本模块 Manifest 权限声明。 */
+  registerRolePresets(presets: readonly ModuleRolePreset[]): void;
+  /** 注册 Manifest `providers` 已声明的搜索 Provider。 */
+  registerSearchProviders(providers: readonly ModuleSearchProvider[]): void;
 }
 
 /**
  * 已安装模块的 Server 初始化入口。
  *
  * 初始化器在 Storage 与 Durable Job 运行时创建前顺序执行；这里只注册定义，不启动 Worker。
+ * 路由、任务、工具与 Provider 的实现体可延迟绑定宿主运行时创建的服务。
  */
 export interface ModuleInitializer {
   readonly moduleName: string;
   initialize(host: ModuleHost): Promise<void> | void;
 }
+
+/**
+ * 可安装业务模块的完整 Server 契约。
+ *
+ * Manifest 与 setup 必须由同一安装单元贡献，避免宿主分别维护声明工厂和初始化器。
+ * TManifest 由能力目录包提供，SDK 因而不依赖具体 Manifest 实现。
+ */
+export interface InstallableServerModule<TManifest> {
+  readonly manifest: TManifest;
+  setup(host: ModuleHost): Promise<void> | void;
+}

package/template/packages/server-sdk/src/namespace.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { requireModuleNamespace } from "./namespace.js";
+
+describe("模块命名空间约束", () => {
+  test("模块名自身或点分前缀视为模块内 Key", () => {
+    expect(() =>
+      requireModuleNamespace("任务", "work-order", "work-order"),
+    ).not.toThrow();
+    expect(() =>
+      requireModuleNamespace(
+        "任务",
+        "work-order.ticket.snapshot",
+        "work-order",
+      ),
+    ).not.toThrow();
+  });
+
+  test("越界 Key 抛出中文错误", () => {
+    expect(() =>
+      requireModuleNamespace("上传用途", "other.attachment", "work-order"),
+    ).toThrow("上传用途不属于模块 work-order：other.attachment");
+    expect(() =>
+      requireModuleNamespace("角色预设", "work-orderx.role", "work-order"),
+    ).toThrow("角色预设不属于模块 work-order：work-orderx.role");
+  });
+});

package/template/packages/server-sdk/src/namespace.ts

@@ -0,0 +1,13 @@
+/**
+ * 模块命名空间约束：注册的 Key 必须等于模块名，或以 `<moduleName>.` 开头。
+ * 宿主在所有注册入口统一调用，越界注册在 Server 监听前抛错。
+ */
+export function requireModuleNamespace(
+  kind: string,
+  value: string,
+  moduleName: string,
+): void {
+  if (value !== moduleName && !value.startsWith(`${moduleName}.`)) {
+    throw new Error(`${kind}不属于模块 ${moduleName}：${value}`);
+  }
+}

package/template/packages/server-sdk/src/request-context.ts

@@ -0,0 +1,21 @@
+import type { ModuleActor } from "./actor.js";
+import type { ModuleAuditEmitter } from "./audit-port.js";
+import type { ModuleJobSubmitter } from "./jobs-port.js";
+import type { ModuleStoragePort } from "./storage-port.js";
+
+/**
+ * 模块路由 Handler 的受限请求上下文。
+ *
+ * 不暴露 Elysia 内部对象、数据库连接或任何 Repository；
+ * 模块只能经由 Actor 视图与受限 Port（Audit / Jobs / Storage）与平台交互。
+ */
+export interface ModuleRequestContext {
+  readonly requestId: string;
+  readonly actor: ModuleActor;
+  readonly params: Record<string, string | undefined>;
+  readonly query: Record<string, string | undefined>;
+  readonly body?: unknown;
+  readonly audit: ModuleAuditEmitter;
+  readonly jobs: ModuleJobSubmitter;
+  readonly storage: ModuleStoragePort;
+}

package/template/packages/server-sdk/src/role-preset.ts

@@ -0,0 +1,18 @@
+/**
+ * 模块贡献的角色预设。
+ *
+ * `key` 作为角色 Code，必须使用模块命名空间；`permissionKeys` 必须全部属于
+ * 本模块 Manifest `permissions` 声明（宿主在启动时校验）。预设随内置角色一起
+ * 同步入库：不存在则创建，权限或菜单漂移则收敛，不改变 4 个内置角色语义。
+ */
+export interface ModuleRolePreset {
+  readonly key: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly dataScope?:
+    | "all"
+    | "department"
+    | "department-and-children"
+    | "self";
+  readonly permissionKeys: readonly string[];
+}

package/template/packages/server-sdk/src/route-definition.ts

@@ -0,0 +1,26 @@
+import type { ModuleRequestContext } from "./request-context.js";
+
+export type ModuleRouteMethod = "GET" | "POST" | "PUT" | "DELETE";
+
+export type ModuleRouteHandler = (
+  context: ModuleRequestContext,
+) => Promise<unknown> | unknown;
+
+/**
+ * 模块贡献的 API 路由定义。
+ *
+ * `method` + `path` 必须与本模块 Manifest `apiPermissions` 中的声明一致
+ * （path 含 `/api` 前缀）；宿主据此绑定 Guard（权限 / Feature / License），
+ * 无需模块手工接线。`permissionKey` 必须与 Manifest 绑定一致并属于本模块命名空间。
+ *
+ * 声明 `auditAction` 时，宿主在 Handler 成功返回后自动写入一条该动作的审计事件；
+ * 动作必须是本模块 Manifest `auditActions` 已注册的动作。
+ */
+export interface ModuleRouteDefinition {
+  readonly method: ModuleRouteMethod;
+  readonly path: string;
+  readonly permissionKey: string;
+  readonly featureKey?: string;
+  readonly auditAction?: string;
+  readonly handler: ModuleRouteHandler;
+}

package/template/packages/server-sdk/src/search-provider-port.ts

@@ -0,0 +1,48 @@
+import type { ModuleActor } from "./actor.js";
+
+export interface ModuleSearchQuery {
+  readonly text: string;
+  readonly limit: number;
+  readonly cursor?: string;
+  readonly signal: AbortSignal;
+}
+
+export interface ModuleSearchContext {
+  readonly actor: ModuleActor;
+  readonly requestId: string;
+}
+
+export interface ModuleSearchHit {
+  readonly id: string;
+  readonly resourceType: string;
+  readonly maskedTitle: string;
+  readonly maskedExcerpt?: string;
+  readonly score?: number;
+}
+
+export interface ModuleSearchPage {
+  readonly hits: ModuleSearchHit[];
+  readonly nextCursor?: string;
+}
+
+export interface ModuleSearchHealth {
+  readonly status: "healthy" | "degraded" | "unavailable";
+  readonly checkedAt: string;
+  readonly message?: string;
+}
+
+/**
+ * 模块搜索 Provider。
+ *
+ * `key` 必须在本模块 Manifest `providers` 中声明；返回的标题与摘要必须是
+ * 已脱敏文本，明文访问与导出由目标资源与治理导出走各自 Guard。
+ */
+export interface ModuleSearchProvider {
+  readonly key: string;
+  readonly providerVersion: string;
+  search(
+    query: ModuleSearchQuery,
+    context: ModuleSearchContext,
+  ): Promise<ModuleSearchPage>;
+  health(signal: AbortSignal): Promise<ModuleSearchHealth>;
+}

package/template/packages/server-sdk/src/storage-port.ts

@@ -0,0 +1,25 @@
+import type { OpenedFile, UploadSession } from "@southwind-ai/storage";
+
+export interface ModuleUploadSessionInput {
+  readonly purpose: string;
+  readonly filename: string;
+  readonly mimeType: string;
+  readonly expectedByteSize: number;
+  readonly expectedSha256?: string;
+  readonly fileExpiresAt?: Date;
+}
+
+/**
+ * 模块受限 Upload / BlobRead Port。
+ *
+ * - `createUploadSession` 的 purpose 必须是本模块经 Host 注册的 Upload Policy，
+ *   跨模块或平台用途一律拒绝；Owner 由宿主以当前 Actor 身份补齐。
+ * - `openFile` 走 FileService 的 Owner 约束，且文件用途必须属于本模块。
+ * - `openPublicFile` 走 FileService 的 Purpose 约束，用途同样必须属于本模块。
+ * - 模块不允许直接接触 BlobStore 或 Upload Repository。
+ */
+export interface ModuleStoragePort {
+  createUploadSession(input: ModuleUploadSessionInput): Promise<UploadSession>;
+  openFile(fileId: string): Promise<OpenedFile>;
+  openPublicFile(fileId: string, purpose: string): Promise<OpenedFile>;
+}

package/template/packages/server-sdk/src/task-registration.ts

@@ -0,0 +1,18 @@
+export type ModuleTaskResult = Record<string, unknown> | void;
+
+export type ModuleTaskHandler = () =>
+  | Promise<ModuleTaskResult>
+  | ModuleTaskResult;
+
+/**
+ * 模块定时任务的 Handler 注册。
+ *
+ * `taskKey` 必须在本模块 Manifest `tasks` 中声明；调度元数据（间隔、重试、
+ * Feature、权限）一律以 Manifest 为准，这里只提供执行体。
+ */
+export interface ModuleTaskHandlerRegistration {
+  readonly taskKey: string;
+  readonly handler: ModuleTaskHandler;
+  /** 判断执行结果是否为空转（用于调度指标统计），与平台任务语义一致。 */
+  readonly isIdleResult?: (value: ModuleTaskResult) => boolean;
+}

package/template/packages/server-sdk/src/tool-host-port.ts

@@ -0,0 +1,22 @@
+import type { ModuleAiJsonValue } from "./ai-operation-registration.js";
+
+export interface ModuleAgentToolInvocation {
+  readonly runId: string;
+  readonly toolCallId: string;
+  readonly toolKey: string;
+  readonly arguments: Readonly<Record<string, ModuleAiJsonValue>>;
+}
+
+export interface ModuleAgentToolResult {
+  readonly value: ModuleAiJsonValue;
+}
+
+/**
+ * 宿主创建并绑定 Operation、Actor 与 Scope 的受限 Tool Host Port。
+ * 调用方不能传 Permission、Feature、License 或数据范围作为授权事实。
+ */
+export interface ModuleAgentToolHostPort {
+  execute(
+    invocation: ModuleAgentToolInvocation,
+  ): Promise<ModuleAgentToolResult>;
+}

package/template/packages/server-sdk/src/tool-registration.ts

@@ -0,0 +1,29 @@
+import type { ModuleActor } from "./actor.js";
+
+export interface ModuleToolContext {
+  readonly actor: ModuleActor;
+  readonly requestId: string;
+}
+
+export interface ModuleToolResult {
+  readonly items: unknown[];
+  readonly total: number;
+  readonly page: number;
+  readonly pageSize: number;
+}
+
+/**
+ * 模块 Agent Tool 的 Handler 注册。
+ *
+ * `toolKey` 必须在本模块 Manifest `tools` 中声明；Guard（权限 / Feature /
+ * 数据范围）由宿主在 Agent 路由层统一执行。`scopeMode: "request"` 的 Handler
+ * 只会在持有服务端数据范围上下文的 Actor 下执行。
+ */
+export interface ModuleToolHandlerRegistration {
+  readonly toolKey: string;
+  readonly scopeMode: "platform" | "request";
+  execute(
+    query: Record<string, string | undefined>,
+    context: ModuleToolContext,
+  ): Promise<ModuleToolResult> | ModuleToolResult;
+}

package/template/packages/shared/index.ts

@@ -5,6 +5,7 @@ export * from "./src/feature.js";
 export * from "./src/license.js";
 export * from "./src/license-catalog.js";
 export * from "./src/migration.js";
+export * from "./src/migration-bundle-validation.js";
 export * from "./src/module-configuration.js";
 export * from "./src/correlation.js";
 export * from "./src/notification.js";

package/template/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/shared",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/shared/src/license-catalog.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, test } from "bun:test";
-import { LICENSE_CATALOG } from "./license-catalog.js";
+import {
+  LICENSE_CATALOG,
+  parseLicenseCatalog,
+  parseLicenseCatalogJson,
+  resolveLicenseCatalog,
+  validateLicenseCatalog,
+  type LicenseCatalogDefinition,
+} from "./license-catalog.js";
+import { licenseVersionKey } from "./license.js";
 
 describe("License Catalog", () => {
   test("提供稳定且有序的默认产品版本", () => {
@@ -14,4 +22,68 @@ describe("License Catalog", () => {
       ),
     ).toBe(true);
   });
+
+  test("默认目录自身通过校验", () => {
+    expect(() => validateLicenseCatalog(LICENSE_CATALOG)).not.toThrow();
+  });
+
+  test("重复 Key 或重复 order 时校验报错", () => {
+    const duplicatedKey: LicenseCatalogDefinition[] = [
+      entry("basic", 10),
+      entry("basic", 20),
+    ];
+    const duplicatedOrder: LicenseCatalogDefinition[] = [
+      entry("basic", 10),
+      entry("pro", 10),
+    ];
+
+    expect(() => validateLicenseCatalog(duplicatedKey)).toThrow(
+      "License 版本目录 Key 重复：basic",
+    );
+    expect(() => validateLicenseCatalog(duplicatedOrder)).toThrow(
+      "License 版本目录 order 重复：10",
+    );
+    expect(() => validateLicenseCatalog([])).toThrow(
+      "License 版本目录不能为空",
+    );
+    expect(() => validateLicenseCatalog([entry("", 10)])).toThrow(
+      "License 版本目录的 Key 与名称不能为空",
+    );
+  });
+
+  test("resolveLicenseCatalog 未配置时回退默认目录，配置后校验并返回", () => {
+    expect(resolveLicenseCatalog()).toBe(LICENSE_CATALOG);
+
+    const custom = [entry("oem-basic", 10), entry("oem-pro", 20)];
+    expect(resolveLicenseCatalog(custom)).toBe(custom);
+    expect(() =>
+      resolveLicenseCatalog([entry("dup", 1), entry("dup", 2)]),
+    ).toThrow("License 版本目录 Key 重复：dup");
+  });
+
+  test("共享解析器统一归一化字段并拒绝结构漂移", () => {
+    expect(
+      parseLicenseCatalog([{ key: " oem ", label: " OEM 版 ", order: 10 }]),
+    ).toEqual([{ key: "oem", label: "OEM 版", description: "", order: 10 }]);
+    expect(() =>
+      parseLicenseCatalog([{ key: "oem", label: "OEM", order: 1.5 }]),
+    ).toThrow("order 必须是安全整数");
+    expect(() =>
+      parseLicenseCatalog([
+        { key: "oem", label: "OEM", order: 10, legacy: true },
+      ]),
+    ).toThrow("License 版本目录包含未知字段：legacy");
+    expect(() => parseLicenseCatalogJson("invalid", "宿主目录")).toThrow(
+      "宿主目录 必须是合法 JSON 数组",
+    );
+  });
 });
+
+function entry(key: string, order: number): LicenseCatalogDefinition {
+  return {
+    key: licenseVersionKey(key),
+    label: key || "占位",
+    description: `${key} 版本`,
+    order,
+  };
+}

package/template/packages/shared/src/license-catalog.ts

@@ -7,6 +7,8 @@ export interface LicenseCatalogDefinition {
   order: number;
 }
 
+const licenseCatalogFields = new Set(["key", "label", "description", "order"]);
+
 export const LICENSE_CATALOG = [
   {
     key: licenseVersionKey("free-trial"),
@@ -31,3 +33,96 @@ export const LICENSE_CATALOG = [
 export function licenseCatalogKeys(): ReadonlySet<LicenseVersionKey> {
   return new Set(LICENSE_CATALOG.map(({ key }) => key));
 }
+
+/** 校验宿主配置的 License 版本目录：Key 与 order 均唯一，目录非空。 */
+export function validateLicenseCatalog(
+  definitions: readonly LicenseCatalogDefinition[],
+): void {
+  if (definitions.length === 0) {
+    throw new Error("License 版本目录不能为空");
+  }
+  const keys = new Set<string>();
+  const orders = new Set<number>();
+  for (const definition of definitions) {
+    if (!definition.key.trim() || !definition.label.trim()) {
+      throw new Error("License 版本目录的 Key 与名称不能为空");
+    }
+    if (!Number.isSafeInteger(definition.order)) {
+      throw new Error(`License 版本 ${definition.key} 的 order 必须是安全整数`);
+    }
+    if (keys.has(definition.key)) {
+      throw new Error(`License 版本目录 Key 重复：${definition.key}`);
+    }
+    if (orders.has(definition.order)) {
+      throw new Error(
+        `License 版本目录 order 重复：${definition.order}（${definition.key}）`,
+      );
+    }
+    keys.add(definition.key);
+    orders.add(definition.order);
+  }
+}
+
+/** 从未知输入解析并归一化宿主 License 版本目录。 */
+export function parseLicenseCatalog(
+  input: unknown,
+): LicenseCatalogDefinition[] {
+  if (!Array.isArray(input)) {
+    throw new Error("License 版本目录必须是数组");
+  }
+  const catalog = input.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`License 版本目录第 ${index + 1} 项必须是对象`);
+    }
+    const record = entry as Record<string, unknown>;
+    const unknownField = Object.keys(record).find(
+      (key) => !licenseCatalogFields.has(key),
+    );
+    if (unknownField) {
+      throw new Error(`License 版本目录包含未知字段：${unknownField}`);
+    }
+    if (
+      typeof record.key !== "string" ||
+      typeof record.label !== "string" ||
+      (record.description !== undefined &&
+        typeof record.description !== "string") ||
+      typeof record.order !== "number"
+    ) {
+      throw new Error(`License 版本目录第 ${index + 1} 项字段类型无效`);
+    }
+    return {
+      key: licenseVersionKey(record.key.trim()),
+      label: record.label.trim(),
+      description: record.description?.trim() ?? "",
+      order: record.order,
+    };
+  });
+  validateLicenseCatalog(catalog);
+  return catalog;
+}
+
+/** 解析环境变量 JSON，错误消息不包含原始配置内容。 */
+export function parseLicenseCatalogJson(
+  raw: string,
+  source = "License 版本目录",
+): LicenseCatalogDefinition[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${source} 必须是合法 JSON 数组`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${source} 必须是合法 JSON 数组`);
+  }
+  return parseLicenseCatalog(parsed);
+}
+
+/** 有宿主配置时校验并返回，未配置时回退平台默认三级目录。 */
+export function resolveLicenseCatalog(
+  configured?: readonly LicenseCatalogDefinition[],
+): readonly LicenseCatalogDefinition[] {
+  if (!configured) return LICENSE_CATALOG;
+  validateLicenseCatalog(configured);
+  return configured;
+}

package/template/packages/{database/src/bundle-validation.ts → shared/src/migration-bundle-validation.ts}

@@ -4,7 +4,7 @@ import {
   type MigrationBundle,
   type MigrationDefinition,
   type MigrationManifestSource,
-} from "@southwind-ai/shared";
+} from "./migration.js";
 
 export function normalizeManifestBundles(
   modules: readonly MigrationManifestSource[],
@@ -126,6 +126,7 @@ export function validateAndOrderBundles(
       }
     }
     validateMigrationDependencies(bundle, migrationOwner);
+    orderBundleMigrations(bundle);
   }
   return topologicalBundles(byModule);
 }

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

@@ -1,30 +0,0 @@
-import { workOrderModule } from "@southwind-ai/example-work-order";
-import type { FeatureFlagDefinition } from "@southwind-ai/shared";
-import type { ScheduledTaskDefinition } from "../scheduler/types.js";
-import type { WorkOrderService } from "./service.js";
-import { platformDataActor } from "../data-access/platform-actor.js";
-
-export function createWorkOrderTaskDefinitions(
-  features: FeatureFlagDefinition[],
-  service: WorkOrderService,
-): ScheduledTaskDefinition[] {
-  const manifest = workOrderModule();
-  const feature = features.find(({ key }) => key === "work-order.ticket");
-  if (!feature) return [];
-  const actor = platformDataActor(
-    "task_work_order_snapshot",
-    "工单运营快照任务",
-  );
-
-  return manifest.tasks.map((task) => ({
-    key: task.key,
-    label: task.label,
-    description: task.description,
-    intervalSeconds: task.intervalSeconds,
-    maxAttempts: task.maxAttempts,
-    retryDelaySeconds: task.retryDelaySeconds,
-    permissionKey: task.permissionKey,
-    feature,
-    handler: () => service.operationalSnapshot(actor),
-  }));
-}