create-windy 0.2.18 → 0.2.20

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-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),
-  }));
-}