create-windy 0.3.4 → 0.3.5

package/template/apps/server/src/module-host/governed-export-routes.test.ts

@@ -4,7 +4,10 @@ import type { ModuleGovernedResourceRegistration } from "@southwind-ai/server-sd
 import { featureKey, type PermissionDefinition } from "@southwind-ai/shared";
 import { captureGovernedExportScope } from "../data-governance/export/scope-snapshot.js";
 import { ModuleGovernedExportSource } from "../data-governance/export/source.js";
-import type { GovernedExportRequest } from "../data-governance/export/types.js";
+import {
+  legacyGovernedExportRendererSnapshot,
+  type GovernedExportRequest,
+} from "../data-governance/export/types.js";
 import { buildActorScopeContexts } from "../data-access/context.js";
 import type { RequestActor } from "../guards.js";
 import { createServerRuntime } from "../runtime.js";
@@ -314,6 +317,7 @@ function requestFixture(): GovernedExportRequest {
     scopeSnapshot: scope.snapshot,
     scopeHash: scope.hash,
     querySnapshot: { caseId: "case-1" },
+    renderer: legacyGovernedExportRendererSnapshot,
     status: "pending-approval",
     approvalRequired: true,
     expiresAt: "2099-01-01T00:00:00.000Z",

package/template/apps/server/src/module-host/governed-export-routes.ts

@@ -14,7 +14,6 @@ import {
 import type { InitializedModuleHosts } from "./initialize.js";
 import {
   exportTarget,
-  filename,
   knownError,
   optionalString,
   parseCreate,
@@ -194,7 +193,7 @@ function installDownloadRoute(
             headers: {
               "cache-control": "no-store",
               "content-type": opened.artifact.contentType,
-              "content-disposition": `attachment; filename="${filename(policy.resourceType)}"`,
+              "content-disposition": `attachment; filename="${opened.artifact.filename}"`,
               "x-content-sha256": opened.artifact.sha256,
             },
           });

package/template/apps/server/src/module-host/governed-renderer-registration.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  ModuleGovernedExportRegistration,
+  ModuleGovernedResourceRegistration,
+} from "@southwind-ai/server-sdk";
+import { featureKey } from "@southwind-ai/shared";
+import { initializeModuleHosts } from "./initialize.js";
+import { manifest } from "./test-fixtures.js";
+
+describe("业务模块治理导出 Renderer 注册", () => {
+  test("同一资源可注册 NDJSON、PDF、DOCX 与 XLSX", async () => {
+    const declared = exportManifest();
+    const hosts = await initializeModuleHosts({
+      modules: [declared],
+      installations: [
+        {
+          manifest: declared,
+          setup(host) {
+            host.registerGovernedResources([resource()]);
+          },
+        },
+      ],
+    });
+    expect(
+      hosts.governedResources[0]?.registration.export?.renderers?.map(
+        ({ formatKey }) => formatKey,
+      ),
+    ).toEqual(["ndjson", "pdf", "docx", "xlsx"]);
+  });
+
+  test("重复格式、未知 Schema 和越界 limits 在监听前 fail closed", async () => {
+    await expectInvalid(
+      (configured) => ({
+        ...configured,
+        renderers: [
+          configured.renderers![0]!,
+          { ...configured.renderers![0]!, templateVersion: "2" },
+        ],
+      }),
+      "formatKey 无效或重复",
+    );
+    await expectInvalid(
+      (configured) => ({
+        ...configured,
+        renderers: [
+          {
+            ...configured.renderers![0]!,
+            inputSchemaKey: "reports.missing.v1",
+          },
+        ],
+      }),
+      "未注册 JSON Schema",
+    );
+    await expectInvalid(
+      (configured) => ({
+        ...configured,
+        renderers: [
+          {
+            ...configured.renderers![0]!,
+            limits: {
+              ...configured.renderers![0]!.limits,
+              timeoutSeconds: 901,
+            },
+          },
+        ],
+      }),
+      "元数据或上限无效",
+    );
+  });
+});
+
+async function expectInvalid(
+  change: (
+    configured: ModuleGovernedExportRegistration,
+  ) => ModuleGovernedExportRegistration,
+  message: string,
+) {
+  const declared = exportManifest();
+  await expect(
+    initializeModuleHosts({
+      modules: [declared],
+      installations: [
+        {
+          manifest: declared,
+          setup(host) {
+            const base = resource();
+            host.registerGovernedResources([
+              { ...base, export: change(base.export!) },
+            ]);
+          },
+        },
+      ],
+    }),
+  ).rejects.toThrow(message);
+}
+
+function resource(): ModuleGovernedResourceRegistration {
+  return {
+    policyKey: "reports.official.fields",
+    readPath: "/api/reports/official/:id",
+    revealPath: "/api/reports/official/:id/plaintext",
+    revealAuditAction: "reports.official.reveal",
+    authorize: () => true,
+    read: () => undefined,
+    export: exportRegistration(),
+  };
+}
+
+function exportRegistration(): ModuleGovernedExportRegistration {
+  const formats = [
+    ["ndjson", "application/x-ndjson"],
+    ["pdf", "application/pdf"],
+    [
+      "docx",
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ],
+    [
+      "xlsx",
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ],
+  ] as const;
+  return {
+    basePath: "/api/reports/official/exports",
+    validateQuery: () => ({}),
+    readPage: () => ({ records: [] }),
+    renderers: formats.map(([formatKey, contentType]) => ({
+      formatKey,
+      templateKey: `reports.official.${formatKey}`,
+      templateVersion: "1.0.0",
+      inputSchemaKey: "reports.official.input.v1",
+      contentType,
+      filenameExtension: formatKey,
+      limits: {
+        maxRecords: 10_000,
+        maxOutputBytes: 20 * 1024 * 1024,
+        timeoutSeconds: 120,
+      },
+      render: () => ({ body: new ReadableStream<Uint8Array>() }),
+    })),
+  };
+}
+
+function exportManifest(): ModuleManifest {
+  const feature = featureKey("reports.official");
+  const declared = manifest("reports", {
+    permissions: [
+      permission("reports.official.read", "standard"),
+      permission("reports.official.reveal", "sensitive-disclosure"),
+      permission("reports.official.export", "governed-export"),
+    ],
+    features: [
+      {
+        key: feature,
+        label: "正式报告",
+        module: "reports",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    jsonSchemas: [
+      {
+        key: "reports.official.input.v1",
+        schema: { type: "object", properties: {} },
+      },
+    ],
+    dataPolicies: [
+      {
+        key: "reports.official.fields",
+        resourceType: "reports.official",
+        version: "1",
+        featureKey: feature,
+        readPermissionKey: "reports.official.read",
+        revealPermissionKey: "reports.official.reveal",
+        exportPermissionKey: "reports.official.export",
+        display: {
+          read: "masked",
+          reveal: "plaintext",
+          unauthorized: "hidden",
+        },
+        fields: [
+          {
+            fieldKey: "content",
+            classification: "sensitive",
+            mask: { kind: "redact" },
+          },
+        ],
+      },
+    ],
+    auditActions: ["reports.official.reveal"],
+  });
+  declared.apiPermissions = [
+    route("GET", "/api/reports/official/:id", "reports.official.read", feature),
+    route(
+      "POST",
+      "/api/reports/official/:id/plaintext",
+      "reports.official.reveal",
+      feature,
+    ),
+    ...(
+      [
+        ["POST", ""],
+        ["GET", "/:id"],
+        ["POST", "/:id/cancel"],
+        ["GET", "/:id/download"],
+      ] as const
+    ).map(([method, suffix]) => {
+      return route(
+        method,
+        `/api/reports/official/exports${suffix}`,
+        "reports.official.export",
+        feature,
+      );
+    }),
+  ];
+  return declared;
+}
+
+function permission(
+  key: string,
+  accessRisk: "standard" | "sensitive-disclosure" | "governed-export",
+) {
+  return {
+    key,
+    label: key,
+    module: "reports",
+    moduleLabel: "报告",
+    resource: "official",
+    resourceLabel: "正式报告",
+    action: key.endsWith(".read")
+      ? ("read" as const)
+      : key.endsWith(".reveal")
+        ? ("reveal" as const)
+        : ("export" as const),
+    accessRisk,
+  };
+}
+
+function route(
+  method: "GET" | "POST",
+  path: string,
+  permissionKey: string,
+  feature: ReturnType<typeof featureKey>,
+) {
+  return { method, path, permissionKey, featureKey: feature };
+}

package/template/apps/server/src/module-host/governed-resources.test.ts

@@ -122,6 +122,7 @@ describe("业务模块数据治理 Port", () => {
       }),
     ).rejects.toThrow("业务治理资源重复注册");
   });
+
 });
 
 interface SetupOptions {

package/template/apps/server/src/module-host/governed-resources.ts

@@ -94,6 +94,7 @@ function validateExportRegistration(
   ) {
     throw new Error(`业务治理导出保留时间无效：${registration.policyKey}`);
   }
+  validateRenderers(manifest, registration);
   for (const [method, suffix] of [
     ["POST", ""],
     ["GET", "/:id"],
@@ -112,6 +113,61 @@ function validateExportRegistration(
   }
 }
 
+function validateRenderers(
+  manifest: ModuleManifest,
+  registration: ModuleGovernedResourceRegistration,
+) {
+  const renderers = registration.export?.renderers;
+  if (!renderers) return;
+  if (renderers.length === 0) {
+    throw new Error(`业务治理导出 Renderer 列表不能为空：${registration.policyKey}`);
+  }
+  const formatKeys = new Set<string>();
+  const schemas = new Set(
+    (manifest.jsonSchemas ?? []).map(({ key }) => key),
+  );
+  for (const renderer of renderers) {
+    if (
+      !/^[a-z0-9][a-z0-9._-]{0,79}$/.test(renderer.formatKey) ||
+      formatKeys.has(renderer.formatKey)
+    ) {
+      throw new Error(
+        `业务治理导出 formatKey 无效或重复：${renderer.formatKey}`,
+      );
+    }
+    formatKeys.add(renderer.formatKey);
+    requireModuleNamespace("治理导出模板", renderer.templateKey, manifest.name);
+    if (!schemas.has(renderer.inputSchemaKey)) {
+      throw new Error(
+        `业务治理导出引用了未注册 JSON Schema：${renderer.inputSchemaKey}`,
+      );
+    }
+    if (
+      !renderer.templateVersion.trim() ||
+      renderer.templateVersion.length > 80 ||
+      !/^[a-z0-9][a-z0-9.+-]{0,79}$/i.test(renderer.templateVersion) ||
+      renderer.contentType.length > 120 ||
+      !/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i.test(
+        renderer.contentType,
+      ) ||
+      !/^[a-z0-9]{1,16}$/.test(renderer.filenameExtension) ||
+      !Number.isInteger(renderer.limits.maxRecords) ||
+      renderer.limits.maxRecords < 1 ||
+      renderer.limits.maxRecords > 1_000_000 ||
+      !Number.isInteger(renderer.limits.maxOutputBytes) ||
+      renderer.limits.maxOutputBytes < 1 ||
+      renderer.limits.maxOutputBytes > 1024 * 1024 * 1024 ||
+      !Number.isInteger(renderer.limits.timeoutSeconds) ||
+      renderer.limits.timeoutSeconds < 1 ||
+      renderer.limits.timeoutSeconds > 900
+    ) {
+      throw new Error(
+        `业务治理导出 Renderer 元数据或上限无效：${renderer.formatKey}`,
+      );
+    }
+  }
+}
+
 function validateRoute(
   manifest: ModuleManifest,
   state: GovernedResourceRegistrationState,

package/template/apps/server/src/module-host/http-runtime.ts

@@ -1,6 +1,7 @@
 import type { FeatureFlagDefinition } from "@southwind-ai/shared";
 // @windy-module system.scheduler begin
 import type { DurableJobService } from "../jobs/service.js";
+import type { DurableJobWorker } from "../jobs/worker.js";
 // @windy-module system.scheduler end
 import type { createServerRuntime } from "../runtime.js";
 // @windy-module system.storage begin
@@ -31,6 +32,7 @@ export function installModuleHttpRuntime(
     features: readonly FeatureFlagDefinition[];
     // @windy-module system.scheduler begin
     jobs: DurableJobService;
+    jobWorker: DurableJobWorker;
     // @windy-module system.scheduler end
     // @windy-module system.storage begin
     storage: ReturnType<typeof createStorageRuntime>;
@@ -55,6 +57,7 @@ export function installModuleHttpRuntime(
     features: context.features,
     // @windy-module system.scheduler begin
     jobs: context.jobs,
+    jobControl: { worker: context.jobWorker },
     // @windy-module system.scheduler end
     // @windy-module system.storage begin
     storage: {

package/template/apps/server/src/module-host/job-port.test.ts

@@ -0,0 +1,262 @@
+import { describe, expect, test } from "bun:test";
+import { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import { buildActorScopeContexts } from "../data-access/context.js";
+import type { RequestActor } from "../guards.js";
+import { InMemoryDurableExecutionRepository } from "../jobs/in-memory-execution.js";
+import { DurableJobService } from "../jobs/service.js";
+import { DurableJobWorker } from "../jobs/worker.js";
+import { createServerRuntime } from "../runtime.js";
+import { createModuleJobPort } from "./job-port.js";
+
+const now = new Date("2026-07-27T08:00:00.000Z");
+
+describe("Module Durable Job 受限控制 Port", () => {
+  test("最小投影限制在当前 Module、Actor、Scope 与当前授权", async () => {
+    const fixture = createFixture();
+    const submitted = await fixture.port.submit({
+      handlerKey: "evidence.analyze",
+      idempotencyKey: "analysis-1",
+      payload: { privateTranscript: "不得返回" },
+    });
+
+    expect(await fixture.port.get(submitted.jobId)).toEqual(
+      expect.objectContaining({
+        jobId: submitted.jobId,
+        handlerKey: "evidence.analyze",
+        status: "queued",
+        attempt: 0,
+        canCancel: true,
+      }),
+    );
+    expect(
+      JSON.stringify(await fixture.port.get(submitted.jobId)),
+    ).not.toContain("privateTranscript");
+    expect(
+      await createFixture({
+        facts: fixture.repository,
+        moduleName: "other",
+      }).port.get(submitted.jobId),
+    ).toBeUndefined();
+    expect(
+      await createFixture({
+        facts: fixture.repository,
+        actorId: "actor-b",
+      }).port.get(submitted.jobId),
+    ).toBeUndefined();
+    await expect(
+      createFixture({
+        facts: fixture.repository,
+        actorId: "actor-b",
+      }).port.cancel({
+        jobId: submitted.jobId,
+        reason: "尝试取消其他操作者任务",
+      }),
+    ).rejects.toMatchObject({ code: "JOB_NOT_AVAILABLE" });
+    await expect(
+      fixture.port.cancel({
+        jobId: "missing-job",
+        reason: "尝试取消不存在的任务",
+      }),
+    ).rejects.toMatchObject({ code: "JOB_NOT_AVAILABLE" });
+    expect(
+      await createFixture({
+        facts: fixture.repository,
+        departmentId: "dept-b",
+      }).port.get(submitted.jobId),
+    ).toBeUndefined();
+    fixture.authorized.value = false;
+    expect(await fixture.port.get(submitted.jobId)).toBeUndefined();
+  });
+
+  test("取消使用 CAS、重复调用幂等并将脱敏原因写入关键审计", async () => {
+    const fixture = createFixture();
+    const submitted = await fixture.port.submit({
+      handlerKey: "evidence.analyze",
+      idempotencyKey: "cancel-1",
+      payload: {},
+    });
+    const view = await fixture.port.get(submitted.jobId);
+    if (!view) throw new Error("任务未创建");
+
+    const cancelled = await fixture.port.cancel({
+      jobId: view.jobId,
+      reason: "申请人 test@example.com 要求停止 13800138000",
+      expectedStatus: view.status,
+      expectedVersion: view.version,
+    });
+    expect(cancelled.status).toBe("cancelled");
+    expect(
+      await fixture.port.cancel({
+        jobId: view.jobId,
+        reason: "申请人 test@example.com 要求停止 13800138000",
+        expectedStatus: view.status,
+        expectedVersion: view.version,
+      }),
+    ).toMatchObject({ status: "cancelled" });
+    expect(fixture.runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "module.job.cancel",
+        outcome: "success",
+        metadata: expect.objectContaining({
+          reason: "申请人 [邮箱] 要求停止 [号码]",
+        }),
+      }),
+    );
+  });
+
+  test("运行中取消立即传播 AbortSignal 并阻止成功完成", async () => {
+    const registry = new DurableHandlerRegistry();
+    let started: () => void = () => {};
+    const startedPromise = new Promise<void>((resolve) => {
+      started = () => resolve();
+    });
+    let observedReason: unknown;
+    registry.register(
+      {
+        key: "evidence.analyze",
+        payload: { parse: (value) => value as Record<string, unknown> },
+        execute: async (_, context) => {
+          started();
+          await new Promise<void>((_, reject) => {
+            context.signal.addEventListener(
+              "abort",
+              () => {
+                observedReason = context.signal.reason;
+                reject(new Error("aborted"));
+              },
+              { once: true },
+            );
+          });
+        },
+      },
+      { moduleName: "evidence" },
+    );
+    const fixture = createFixture({ registry });
+    const submitted = await fixture.port.submit({
+      handlerKey: "evidence.analyze",
+      idempotencyKey: "running-cancel-1",
+      payload: {},
+      maxAttempts: 1,
+    });
+    const running = fixture.worker.runNext("evidence", "worker-1");
+    await startedPromise;
+    const view = await fixture.port.get(submitted.jobId);
+    if (!view) throw new Error("运行中任务不可见");
+    await fixture.port.cancel({
+      jobId: view.jobId,
+      reason: "人工确认停止后台研判",
+      expectedStatus: view.status,
+      expectedVersion: view.version,
+    });
+
+    expect(await running).toEqual({
+      status: "cancelled",
+      jobId: submitted.jobId,
+    });
+    expect(observedReason).toBe("cancelled");
+    expect((await fixture.facts.get(submitted.jobId))?.job.status).toBe(
+      "cancelled",
+    );
+  });
+
+  test("人工恢复以 attempt/status/version CAS 保留失败与恢复事实", async () => {
+    const fixture = createFixture();
+    const submitted = await fixture.port.submit({
+      handlerKey: "evidence.analyze",
+      idempotencyKey: "recover-1",
+      payload: {},
+      maxAttempts: 1,
+    });
+    const claim = await fixture.repository.claim({
+      queue: "evidence",
+      workerId: "worker-1",
+      now,
+      leaseDurationMs: 30_000,
+    });
+    if (!claim) throw new Error("任务未领取");
+    await fixture.repository.fail(
+      claim,
+      { code: "MODEL_UNAVAILABLE", message: "模型不可用", retryable: false },
+      now,
+    );
+    const failed = await fixture.port.get(submitted.jobId);
+    if (!failed) throw new Error("失败任务不可见");
+    const request = {
+      jobId: failed.jobId,
+      reason: "人工确认依赖已经恢复",
+      expectedAttempt: failed.attempt,
+      expectedStatus: failed.status,
+      expectedVersion: failed.version,
+    } as const;
+
+    const recovered = await Promise.all([
+      fixture.port.recover(request),
+      fixture.port.recover(request),
+    ]);
+    expect(recovered).toEqual([
+      expect.objectContaining({ status: "queued", attempt: 1 }),
+      expect.objectContaining({ status: "queued", attempt: 1 }),
+    ]);
+    expect(await fixture.facts.get(submitted.jobId)).toMatchObject({
+      attempts: [{ status: "failed" }],
+      failures: [{ code: "MODEL_UNAVAILABLE" }],
+      recoveries: [
+        expect.objectContaining({
+          fromStatus: "failed",
+          reason: "人工确认依赖已经恢复",
+        }),
+      ],
+    });
+  });
+});
+
+function createFixture(
+  options: {
+    facts?: InMemoryDurableExecutionRepository;
+    registry?: DurableHandlerRegistry;
+    moduleName?: string;
+    actorId?: string;
+    departmentId?: string;
+  } = {},
+) {
+  const moduleName = options.moduleName || "evidence";
+  const actorId = options.actorId || "actor-a";
+  const departmentId = options.departmentId || "dept-a";
+  const repository = options.facts || new InMemoryDurableExecutionRepository();
+  const facts = new DurableJobService(repository, () => now);
+  const worker = new DurableJobWorker(
+    repository,
+    options.registry || new DurableHandlerRegistry(),
+    { now: () => now, leaseDurationMs: 60_000 },
+  );
+  const actor: RequestActor = {
+    id: actorId,
+    type: "user",
+    name: actorId,
+    roleCodes: ["analyst"],
+    permissionKeys: [`${moduleName}.analysis.manage`],
+    ...buildActorScopeContexts(actorId, departmentId, [
+      {
+        id: "role-analyst",
+        code: "analyst",
+        dataScope: "department",
+        departmentIds: [],
+      },
+    ]),
+  };
+  const runtime = createServerRuntime();
+  const authorized = { value: true };
+  const port = createModuleJobPort({
+    moduleName,
+    guardContext: {
+      requestId: `request-${actorId}`,
+      actor,
+      startedAt: now.toISOString(),
+    },
+    runtime,
+    jobs: facts,
+    control: { worker },
+    reauthorize: async () => authorized.value,
+  });
+  return { port, facts, repository, worker, runtime, authorized };
+}