create-windy 0.3.2 → 0.3.5

package/template/apps/server/src/data-governance/export/renderer-job-runtime.test.ts

@@ -0,0 +1,235 @@
+import { describe, expect, test } from "bun:test";
+import { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import type { ModuleGovernedExportRendererRegistration } from "@southwind-ai/server-sdk";
+import { MemoryBlobStore } from "@southwind-ai/storage";
+import { buildScopeContext } from "../../data-access/context.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 { GovernedExportJobRuntime } from "./job-runtime.js";
+import { InMemoryGovernedExportRepository } from "./repository.js";
+import { captureGovernedExportScope } from "./scope-snapshot.js";
+import type { GovernedExportSource } from "./source.js";
+import type { GovernedExportRendererSnapshot } from "./types.js";
+
+const now = new Date("2026-07-27T01:00:00.000Z");
+
+describe("governed export renderer runtime", () => {
+  test("Renderer 消费逐页记录与水印并发布受控格式、模板和内容元数据", async () => {
+    for (const [formatKey, contentType] of formats) {
+      const renderer = reportRenderer(formatKey, contentType, 1024);
+      const fixture = await setup(renderer, true);
+      const job = await fixture.runtime.submit(fixture.request);
+
+      expect(await fixture.runtime.runNext(`${formatKey}-worker`)).toMatchObject({
+        status: "succeeded",
+      });
+      const artifact = (await fixture.jobs.get(job.id))?.artifacts[0];
+      if (!artifact) throw new Error("Renderer artifact 未发布");
+      expect(artifact).toMatchObject({
+        filename: `governed-people-report.${formatKey}`,
+        contentType,
+        metadata: {
+          formatKey,
+          templateKey: `reports.official.${formatKey}`,
+          templateVersion: "2026.07",
+          inputSchemaKey: "reports.official.input.v1",
+          contentMetadata: { sourceCount: 2 },
+        },
+      });
+      const blob = await fixture.blobs.open(artifact.artifactRef);
+      if (!blob) throw new Error("Renderer Blob 不存在");
+      const content = await new Response(blob.body).text();
+      expect(content).toContain("source:evidence-1");
+      expect(content).toContain(fixture.request.scopeHash);
+      expect(content).toContain(job.id);
+      expect(fixture.authorizationChecks()).toBe(4);
+    }
+  });
+
+  test("未绑定 Renderer 与输出超限 fail closed 且不保留半成品", async () => {
+    const renderer = reportRenderer("pdf", "application/pdf", 4);
+    for (const registered of [false, true]) {
+      const fixture = await setup(renderer, registered);
+      const job = await fixture.runtime.submit(fixture.request);
+      expect(await fixture.runtime.runNext("failed-renderer-worker")).toMatchObject(
+        { status: "failed" },
+      );
+      expect(fixture.blobs.size).toBe(0);
+      expect((await fixture.jobs.get(job.id))?.artifacts).toEqual([]);
+    }
+  });
+
+  test("Durable Job 取消经 heartbeat 传播到 Renderer AbortSignal", async () => {
+    let enter: () => void = () => undefined;
+    let resume: () => void = () => undefined;
+    const entered = new Promise<void>((resolve) => {
+      enter = resolve;
+    });
+    const resumed = new Promise<void>((resolve) => {
+      resume = resolve;
+    });
+    let aborted = false;
+    const renderer: ModuleGovernedExportRendererRegistration = {
+      ...reportRenderer("pdf", "application/pdf", 1024),
+      async render(_input, context) {
+        enter();
+        await resumed;
+        try {
+          await context.heartbeat();
+        } catch (error) {
+          aborted = context.signal.aborted;
+          throw error;
+        }
+        throw new Error("取消未传播");
+      },
+    };
+    const fixture = await setup(renderer, true);
+    const job = await fixture.runtime.submit(fixture.request);
+    const running = fixture.runtime.runNext("cancel-renderer-worker");
+    await entered;
+    await fixture.runtime.cancel(job.id);
+    resume();
+
+    expect(await running).toMatchObject({ status: "cancelled" });
+    expect(aborted).toBe(true);
+    expect(fixture.blobs.size).toBe(0);
+    expect((await fixture.jobs.get(job.id))?.artifacts).toEqual([]);
+  });
+});
+
+async function setup(
+  renderer: ModuleGovernedExportRendererRegistration,
+  registered: boolean,
+) {
+  const requests = new InMemoryGovernedExportRepository();
+  const facts = new InMemoryDurableExecutionRepository();
+  const jobs = new DurableJobService(facts, () => now);
+  const registry = new DurableHandlerRegistry();
+  const worker = new DurableJobWorker(facts, registry, { now: () => now });
+  const blobs = new MemoryBlobStore();
+  const server = createServerRuntime();
+  let authorizationChecks = 0;
+  const source: GovernedExportSource = {
+    resourceType: "people.report",
+    async *pages() {
+      yield [{ id: "evidence-1", reference: "source-a" }];
+      yield [{ id: "evidence-2", reference: "source-b" }];
+    },
+  };
+  const scope = captureGovernedExportScope(
+    buildScopeContext("reviewer-1", "dept-1", [
+      {
+        id: "role-reviewer",
+        code: "reviewer",
+        dataScope: "department",
+        departmentIds: [],
+      },
+    ]),
+  );
+  const created = await requests.create(
+    {
+      id: Bun.randomUUIDv7(),
+      resourceType: "people.report",
+      policyKey: "people.report.fields",
+      policyVersion: "1",
+      fieldKeys: ["content"],
+      requesterId: "reviewer-1",
+      requesterName: "复核员",
+      idempotencyKey: Bun.randomUUIDv7(),
+      requestFingerprint: "a".repeat(64),
+      reason: "生成正式复核报告",
+      scopeSnapshot: scope.snapshot,
+      scopeHash: scope.hash,
+      querySnapshot: {},
+      renderer: snapshot(renderer),
+      approvalRequired: true,
+      approvalId: "approval-1",
+      expiresAt: "2026-07-28T01:00:00.000Z",
+    },
+    now,
+  );
+  return {
+    request: created.request,
+    runtime: new GovernedExportJobRuntime(
+      requests,
+      jobs,
+      worker,
+      registry,
+      blobs,
+      server.auditSink,
+      [source],
+      async () => true,
+      {
+        evaluate: async () => {
+          authorizationChecks += 1;
+          return { allowed: true };
+        },
+      },
+      () => now,
+      registered ? [{ resourceType: source.resourceType, renderer }] : [],
+    ),
+    jobs,
+    blobs,
+    authorizationChecks: () => authorizationChecks,
+  };
+}
+
+function reportRenderer(
+  formatKey: string,
+  contentType: string,
+  maxOutputBytes: number,
+): ModuleGovernedExportRendererRegistration {
+  return {
+    formatKey,
+    templateKey: `reports.official.${formatKey}`,
+    templateVersion: "2026.07",
+    inputSchemaKey: "reports.official.input.v1",
+    contentType,
+    filenameExtension: formatKey,
+    limits: { maxRecords: 10, maxOutputBytes, timeoutSeconds: 10 },
+    async render(input) {
+      const sources: string[] = [];
+      for await (const record of input.records) {
+        sources.push(`source:${String(record.id)}`);
+      }
+      return {
+        body: new Response(
+          [
+            `watermark:${input.watermark.scopeHash}:${input.watermark.jobId}`,
+            ...sources,
+          ].join("\n"),
+        ).body!,
+        contentMetadata: { sourceCount: sources.length },
+      };
+    },
+  };
+}
+
+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;
+
+function snapshot(
+  renderer: ModuleGovernedExportRendererRegistration,
+): GovernedExportRendererSnapshot {
+  return {
+    formatKey: renderer.formatKey,
+    templateKey: renderer.templateKey,
+    templateVersion: renderer.templateVersion,
+    inputSchemaKey: renderer.inputSchemaKey,
+    contentType: renderer.contentType,
+    filenameExtension: renderer.filenameExtension,
+    ...renderer.limits,
+  };
+}

package/template/apps/server/src/data-governance/export/renderer-runtime.ts

@@ -0,0 +1,293 @@
+import type {
+  GovernedExportRenderedArtifact,
+  GovernedExportWatermarkContext,
+  ModuleGovernedExportRendererRegistration,
+} from "@southwind-ai/server-sdk";
+import type { JsonValue } from "@southwind-ai/shared";
+import type { GovernedExportSource } from "./source.js";
+import { createWatermarkedNdjsonStream } from "./ndjson-stream.js";
+import type {
+  GovernedExportRendererSnapshot,
+  GovernedExportRequest,
+} from "./types.js";
+
+export interface GovernedExportRendererBinding {
+  readonly resourceType: string;
+  readonly renderer: ModuleGovernedExportRendererRegistration;
+}
+
+interface RenderContext {
+  readonly request: GovernedExportRequest;
+  readonly source: GovernedExportSource;
+  readonly jobId: string;
+  readonly generatedAt: string;
+  readonly signal: AbortSignal;
+  readonly heartbeat: () => Promise<void>;
+  readonly beforePage: () => Promise<void>;
+  readonly pageCompleted: (completed: number) => Promise<void>;
+}
+
+export interface GovernedExportRenderSession {
+  readonly body: ReadableStream<Uint8Array>;
+  readonly contentMetadata?: Readonly<Record<string, JsonValue>>;
+  assertRecordsConsumed(): void;
+  dispose(): void;
+}
+
+export async function createGovernedExportRenderSession(
+  input: RenderContext,
+  bindings: readonly GovernedExportRendererBinding[],
+): Promise<GovernedExportRenderSession> {
+  const watermark = watermarkOf(input);
+  const binding = bindings.find(
+    ({ resourceType, renderer }) =>
+      resourceType === input.request.resourceType &&
+      renderer.formatKey === input.request.renderer.formatKey,
+  );
+  if (!binding) {
+    if (!isLegacyNdjson(input.request.renderer)) {
+      throw new Error("EXPORT_RENDERER_NOT_REGISTERED");
+    }
+    const body = createWatermarkedNdjsonStream({
+      ...input,
+      watermark,
+      maxRecords: input.request.renderer.maxRecords,
+    });
+    return {
+      body: limitOutput(
+        body,
+        input.request.renderer.maxOutputBytes,
+        input.signal,
+      ),
+      assertRecordsConsumed() {},
+      dispose() {},
+    };
+  }
+  assertRendererSnapshot(binding.renderer, input.request.renderer);
+  const abort = linkedAbort(
+    input.signal,
+    binding.renderer.limits.timeoutSeconds,
+  );
+  const records = governedRecords(
+    input,
+    binding.renderer.limits.maxRecords,
+    abort.signal,
+  );
+  let artifact: GovernedExportRenderedArtifact;
+  let body: ReadableStream<Uint8Array>;
+  try {
+    artifact = await raceAbort(
+      Promise.resolve(
+        binding.renderer.render(
+          { records: records.iterable, watermark },
+          { signal: abort.signal, heartbeat: input.heartbeat },
+        ),
+      ),
+      abort.signal,
+    );
+    validateContentMetadata(artifact.contentMetadata);
+    body = limitOutput(
+      artifact.body,
+      binding.renderer.limits.maxOutputBytes,
+      abort.signal,
+    );
+  } catch (error) {
+    abort.dispose();
+    throw error;
+  }
+  return {
+    body,
+    contentMetadata: artifact.contentMetadata,
+    assertRecordsConsumed() {
+      if (!records.consumed()) throw new Error("EXPORT_RECORDS_NOT_CONSUMED");
+    },
+    dispose: abort.dispose,
+  };
+}
+
+function governedRecords(
+  input: RenderContext,
+  maxRecords: number,
+  signal: AbortSignal,
+) {
+  let completed = 0;
+  let finished = false;
+  async function* stream() {
+    const pageStream = input.source.pages(input.request, signal);
+    const pages = pageStream[Symbol.asyncIterator]();
+    try {
+      while (true) {
+        throwIfAborted(signal);
+        await input.beforePage();
+        const page = await raceAbort(pages.next(), signal);
+        if (page.done) {
+          finished = true;
+          return;
+        }
+        for (const record of page.value) {
+          completed += 1;
+          if (completed > maxRecords) {
+            throw new Error("EXPORT_RECORD_LIMIT_EXCEEDED");
+          }
+          yield record as Readonly<Record<string, JsonValue>>;
+        }
+        await input.pageCompleted(completed);
+      }
+    } finally {
+      await pages.return?.();
+    }
+  }
+  return { iterable: stream(), consumed: () => finished };
+}
+
+function limitOutput(
+  body: ReadableStream<Uint8Array>,
+  maxBytes: number,
+  signal: AbortSignal,
+) {
+  const reader = body.getReader();
+  let bytes = 0;
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await raceAbort(reader.read(), signal);
+        if (result.done) return controller.close();
+        bytes += result.value.byteLength;
+        if (bytes > maxBytes) throw new Error("EXPORT_OUTPUT_LIMIT_EXCEEDED");
+        controller.enqueue(result.value);
+      } catch (error) {
+        await reader.cancel(error).catch(() => undefined);
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
+}
+
+function linkedAbort(parent: AbortSignal, timeoutSeconds: number) {
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(parent.reason ?? "cancelled");
+  parent.addEventListener("abort", onAbort, { once: true });
+  if (parent.aborted) onAbort();
+  const timeout = setTimeout(
+    () => controller.abort("renderer-timeout"),
+    timeoutSeconds * 1_000,
+  );
+  return {
+    signal: controller.signal,
+    dispose() {
+      clearTimeout(timeout);
+      parent.removeEventListener("abort", onAbort);
+    },
+  };
+}
+
+function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  throwIfAborted(signal);
+  return new Promise<T>((resolve, reject) => {
+    const aborted = () => reject(new Error("EXPORT_RENDERER_ABORTED"));
+    signal.addEventListener("abort", aborted, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", aborted);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", aborted);
+        reject(error);
+      },
+    );
+  });
+}
+
+function throwIfAborted(signal: AbortSignal) {
+  if (signal.aborted) throw new Error("EXPORT_RENDERER_ABORTED");
+}
+
+function assertRendererSnapshot(
+  renderer: ModuleGovernedExportRendererRegistration,
+  snapshot: GovernedExportRendererSnapshot,
+) {
+  if (
+    snapshot.formatKey !== renderer.formatKey ||
+    snapshot.templateKey !== renderer.templateKey ||
+    snapshot.templateVersion !== renderer.templateVersion ||
+    snapshot.inputSchemaKey !== renderer.inputSchemaKey ||
+    snapshot.contentType !== renderer.contentType ||
+    snapshot.filenameExtension !== renderer.filenameExtension ||
+    snapshot.maxRecords !== renderer.limits.maxRecords ||
+    snapshot.maxOutputBytes !== renderer.limits.maxOutputBytes ||
+    snapshot.timeoutSeconds !== renderer.limits.timeoutSeconds
+  ) {
+    throw new Error("EXPORT_RENDERER_VERSION_DRIFT");
+  }
+}
+
+function isLegacyNdjson(snapshot: GovernedExportRendererSnapshot) {
+  return (
+    snapshot.formatKey === "ndjson" &&
+    snapshot.templateKey === "system.governed-export.ndjson" &&
+    snapshot.templateVersion === "1" &&
+    snapshot.inputSchemaKey === "system.governed-export.record.v1" &&
+    snapshot.contentType === "application/x-ndjson" &&
+    snapshot.filenameExtension === "ndjson" &&
+    snapshot.maxRecords === 50_000 &&
+    snapshot.maxOutputBytes === 10 * 1024 * 1024 &&
+    snapshot.timeoutSeconds === 900
+  );
+}
+
+function validateContentMetadata(
+  metadata: Readonly<Record<string, JsonValue>> | undefined,
+) {
+  if (
+    metadata &&
+    (!isJsonObject(metadata) || JSON.stringify(metadata).length > 16_000)
+  ) {
+    throw new Error("EXPORT_CONTENT_METADATA_TOO_LARGE");
+  }
+}
+
+function isJsonObject(value: unknown, depth = 0): boolean {
+  if (
+    depth > 8 ||
+    !value ||
+    Array.isArray(value) ||
+    typeof value !== "object"
+  ) {
+    return false;
+  }
+  return Object.entries(value).every(
+    ([key, item]) => key.length <= 160 && isJson(item, depth + 1),
+  );
+}
+
+function isJson(value: unknown, depth: number): boolean {
+  if (depth > 8) return false;
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return true;
+  }
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) {
+    return (
+      value.length <= 1_000 && value.every((item) => isJson(item, depth + 1))
+    );
+  }
+  return isJsonObject(value, depth);
+}
+
+function watermarkOf(input: RenderContext): GovernedExportWatermarkContext {
+  return {
+    actorId: input.request.requesterId,
+    generatedAt: input.generatedAt,
+    scopeHash: input.request.scopeHash,
+    jobId: input.jobId,
+    requestId: input.request.id,
+  };
+}

package/template/apps/server/src/data-governance/export/renderer-selection.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import {
+  GovernedExportServiceError,
+  legacyNdjsonRenderer,
+  selectRenderer,
+  type CreateGovernedExportInput,
+  type GovernedExportTarget,
+} from "./service-support.js";
+
+const input: CreateGovernedExportInput = {
+  idempotencyKey: "request-1",
+  reason: "生成正式治理报告",
+  query: {},
+};
+const target: GovernedExportTarget = {
+  resourceType: "reports.official",
+  policyKey: "reports.official.fields",
+  policyVersion: "1",
+  fieldKeys: ["content"],
+};
+
+describe("governed export renderer selection", () => {
+  test("未声明 Renderer 的资源保持 NDJSON 兼容", () => {
+    expect(selectRenderer(input, target)).toEqual(legacyNdjsonRenderer);
+    expect(
+      selectRenderer({ ...input, formatKey: "ndjson" }, target),
+    ).toEqual(legacyNdjsonRenderer);
+  });
+
+  test("声明 Renderer 后必须显式选择已注册格式", () => {
+    const configured = {
+      ...target,
+      renderers: [
+        {
+          formatKey: "pdf",
+          templateKey: "reports.official.pdf",
+          templateVersion: "1",
+          inputSchemaKey: "reports.official.input.v1",
+          contentType: "application/pdf",
+          filenameExtension: "pdf",
+          maxRecords: 100,
+          maxOutputBytes: 1_000_000,
+          timeoutSeconds: 60,
+        },
+      ],
+    };
+    expectSelectionError(configured, undefined, "EXPORT_FORMAT_REQUIRED");
+    expectSelectionError(configured, "docx", "EXPORT_FORMAT_NOT_REGISTERED");
+    expect(selectRenderer({ ...input, formatKey: "pdf" }, configured)).toEqual(
+      configured.renderers[0],
+    );
+  });
+});
+
+function expectSelectionError(
+  configured: GovernedExportTarget,
+  formatKey: string | undefined,
+  code: string,
+) {
+  try {
+    selectRenderer({ ...input, formatKey }, configured);
+    throw new Error("应拒绝 Renderer 选择");
+  } catch (error) {
+    expect(error).toBeInstanceOf(GovernedExportServiceError);
+    expect((error as GovernedExportServiceError).code).toBe(code);
+  }
+}

package/template/apps/server/src/data-governance/export/repository.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { InMemoryGovernedExportRepository } from "./repository.js";
+import { legacyGovernedExportRendererSnapshot } from "./types.js";
 
 const now = new Date("2026-07-16T01:00:00.000Z");
 
@@ -25,6 +26,7 @@ describe("governed export repository", () => {
       },
       scopeHash: "a".repeat(64),
       querySnapshot: { includeDeleted: false },
+      renderer: legacyGovernedExportRendererSnapshot,
       approvalRequired: true,
       expiresAt: "2026-07-17T01:00:00.000Z",
     } satisfies Parameters<typeof repository.create>[0];

package/template/apps/server/src/data-governance/export/request-fingerprint.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { fingerprintGovernedExportRequest } from "./request-fingerprint.js";
+import { legacyGovernedExportRendererSnapshot } from "./types.js";
 
 const request = {
   resourceType: "system.user",
@@ -10,6 +11,7 @@ const request = {
   reason: "合规复核用户字段",
   scopeHash: "a".repeat(64),
   querySnapshot: { includeDeleted: false, q: "审计" },
+  renderer: legacyGovernedExportRendererSnapshot,
   approvalRequired: true,
 };
 
@@ -29,6 +31,17 @@ describe("governed export request fingerprint", () => {
         reason: "另一项合规复核用途",
       }),
     ).not.toBe(first);
+    expect(
+      fingerprintGovernedExportRequest({
+        ...request,
+        renderer: {
+          ...legacyGovernedExportRendererSnapshot,
+          formatKey: "pdf",
+          contentType: "application/pdf",
+          filenameExtension: "pdf",
+        },
+      }),
+    ).not.toBe(first);
   });
 
   test("数据库标识和到期时间不参与同一业务请求的摘要", () => {

package/template/apps/server/src/data-governance/export/request-fingerprint.ts

@@ -11,6 +11,7 @@ type FingerprintedRequest = Pick<
   | "reason"
   | "scopeHash"
   | "querySnapshot"
+  | "renderer"
   | "approvalRequired"
 >;
 
@@ -26,6 +27,7 @@ export function fingerprintGovernedExportRequest(
     reason: request.reason,
     scopeHash: request.scopeHash,
     querySnapshot: request.querySnapshot,
+    renderer: request.renderer,
     approvalRequired: request.approvalRequired,
   };
   return createHash("sha256").update(stableJson(payload)).digest("hex");

package/template/apps/server/src/data-governance/export/routes.ts

@@ -112,7 +112,12 @@ async function guarded<T>(
 }
 
 function parseCreate(body: unknown) {
-  const value = strictObject(body, ["idempotencyKey", "reason", "query"]);
+  const value = strictObject(body, [
+    "idempotencyKey",
+    "reason",
+    "query",
+    "formatKey",
+  ]);
   const query = strictObject(value.query || {}, [
     "q",
     "status",
@@ -126,9 +131,11 @@ function parseCreate(body: unknown) {
   ) {
     throw new GovernedExportServiceError("EXPORT_QUERY_INVALID", 400);
   }
+  const formatKey = optionalString(value.formatKey);
   return {
     idempotencyKey: requiredString(value.idempotencyKey),
     reason: requiredString(value.reason),
+    ...(formatKey === undefined ? {} : { formatKey }),
     query: {
       q: optionalString(query.q),
       status: status as LifecycleStatus | undefined,
@@ -200,6 +207,9 @@ function project(request: GovernedExportRequest) {
     expiresAt: request.expiresAt,
     createdAt: request.createdAt,
     updatedAt: request.updatedAt,
+    formatKey: request.renderer.formatKey,
+    templateKey: request.renderer.templateKey,
+    templateVersion: request.renderer.templateVersion,
   };
 }