create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,327 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { ModuleGovernedResourceRegistration } from "@southwind-ai/server-sdk";
+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 {
+  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";
+import { FakeRouteApp } from "../system/route-test-app.js";
+import { installModuleGovernedExportRoutes } from "./governed-export-routes.js";
+import { initializeModuleHosts } from "./initialize.js";
+
+describe("业务模块治理导出 Port", () => {
+  test("导出入口由 Manifest Guard 绑定，客户端不能选择策略与字段", async () => {
+    const manifest = peopleManifest();
+    const registrationValue = registration();
+    const hosts = await initializeModuleHosts({
+      modules: [manifest],
+      installations: [
+        {
+          manifest,
+          setup(host) {
+            host.registerGovernedResources([registrationValue]);
+          },
+        },
+      ],
+    });
+    const runtime = createServerRuntime(
+      {},
+      {
+        actorResolver: { resolve: () => actor() },
+        featureCatalog: manifest.features,
+      },
+    );
+    const guardContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/people/persons/exports"),
+    );
+    let captured: unknown;
+    const app = new FakeRouteApp();
+    installModuleGovernedExportRoutes(hosts, app, {
+      runtime,
+      features: manifest.features,
+      service: {
+        async request(input, _context, target) {
+          captured = { input, target };
+          return requestFixture();
+        },
+        async status() {
+          return requestFixture();
+        },
+        async cancel() {
+          return requestFixture();
+        },
+        async download() {
+          throw new Error("not used");
+        },
+      },
+    });
+
+    const response = (await app.invoke("POST", "/people/persons/exports", {
+      guardContext,
+      params: {},
+      query: {},
+      body: {
+        idempotencyKey: "people-export-1",
+        reason: "案件复核需要导出人员字段",
+        query: { caseId: "case-1" },
+      },
+    })) as Response;
+
+    expect(response.status).toBe(202);
+    expect(captured).toEqual({
+      input: {
+        idempotencyKey: "people-export-1",
+        reason: "案件复核需要导出人员字段",
+        query: { caseId: "case-1" },
+      },
+      target: {
+        resourceType: "people.person",
+        policyKey: "people.person.fields",
+        policyVersion: "1",
+        fieldKeys: ["phone"],
+        approvalRequired: true,
+        retentionSeconds: 3_600,
+      },
+    });
+  });
+
+  test("后台分页源只获得当前 Actor、受限查询和不透明游标", async () => {
+    const seen: unknown[] = [];
+    const registrationValue = registration({
+      export: {
+        basePath: "/api/people/persons/exports",
+        approvalRequired: true,
+        retentionSeconds: 3_600,
+        validateQuery: () => ({ caseId: "case-1" }),
+        readPage(input, context) {
+          seen.push({ input, actor: context.actor });
+          return input.cursor
+            ? { records: [{ id: "person-2", phone: "13900000000" }] }
+            : {
+                records: [{ id: "person-1", phone: "13800000000" }],
+                nextCursor: "cursor-2",
+              };
+        },
+      },
+    });
+    const source = new ModuleGovernedExportSource(
+      registrationValue,
+      peopleManifest().dataPolicies![0]!,
+      async () => actor(),
+    );
+    const pages: unknown[] = [];
+    for await (const page of source.pages(requestFixture())) pages.push(page);
+
+    expect(pages).toEqual([
+      [{ id: "person-1", phone: "13800000000" }],
+      [{ id: "person-2", phone: "13900000000" }],
+    ]);
+    expect(seen).toEqual([
+      {
+        input: { query: { caseId: "case-1" }, cursor: undefined, limit: 100 },
+        actor: expect.objectContaining({
+          id: "user-reviewer",
+          permissionKeys: ["people.person.export"],
+        }),
+      },
+      {
+        input: {
+          query: { caseId: "case-1" },
+          cursor: "cursor-2",
+          limit: 100,
+        },
+        actor: expect.objectContaining({ id: "user-reviewer" }),
+      },
+    ]);
+  });
+});
+
+function registration(
+  overrides: Partial<ModuleGovernedResourceRegistration> = {},
+): ModuleGovernedResourceRegistration {
+  return {
+    policyKey: "people.person.fields",
+    readPath: "/api/people/persons/:id",
+    revealPath: "/api/people/persons/:id/plaintext",
+    revealAuditAction: "people.phone.reveal",
+    authorize: () => true,
+    read: () => ({
+      id: "person-1",
+      publicFields: { name: "张三" },
+      governedFields: { phone: "13800000000" },
+    }),
+    export: {
+      basePath: "/api/people/persons/exports",
+      approvalRequired: true,
+      retentionSeconds: 3_600,
+      validateQuery(query) {
+        if (
+          !query ||
+          typeof query !== "object" ||
+          Array.isArray(query) ||
+          typeof (query as Record<string, unknown>).caseId !== "string"
+        ) {
+          throw new Error("caseId required");
+        }
+        return { caseId: (query as { caseId: string }).caseId };
+      },
+      readPage: () => ({ records: [] }),
+    },
+    ...overrides,
+  };
+}
+
+function peopleManifest(): ModuleManifest {
+  const feature = featureKey("people.person");
+  const exportBase = "/api/people/persons/exports";
+  return {
+    name: "people",
+    version: "0.1.0",
+    label: "人员",
+    description: "人员主档",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      permission("people.person.read", "read"),
+      permission("people.person.reveal", "reveal", "sensitive-disclosure"),
+      permission("people.person.export", "export", "governed-export"),
+    ],
+    apiPermissions: [
+      binding("GET", "/api/people/persons/:id", "people.person.read", feature),
+      binding(
+        "POST",
+        "/api/people/persons/:id/plaintext",
+        "people.person.reveal",
+        feature,
+      ),
+      binding("POST", exportBase, "people.person.export", feature),
+      binding("GET", `${exportBase}/:id`, "people.person.export", feature),
+      binding(
+        "POST",
+        `${exportBase}/:id/cancel`,
+        "people.person.export",
+        feature,
+      ),
+      binding(
+        "GET",
+        `${exportBase}/:id/download`,
+        "people.person.export",
+        feature,
+      ),
+    ],
+    features: [
+      {
+        key: feature,
+        label: "人员主档",
+        module: "people",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    dataPolicies: [
+      {
+        key: "people.person.fields",
+        resourceType: "people.person",
+        version: "1",
+        featureKey: feature,
+        readPermissionKey: "people.person.read",
+        revealPermissionKey: "people.person.reveal",
+        exportPermissionKey: "people.person.export",
+        display: {
+          read: "masked",
+          reveal: "plaintext",
+          unauthorized: "hidden",
+        },
+        fields: [
+          {
+            fieldKey: "phone",
+            classification: "sensitive",
+            mask: { kind: "partial", prefix: 3, suffix: 4 },
+          },
+        ],
+      },
+    ],
+    auditActions: ["people.phone.reveal"],
+  };
+}
+
+function binding(
+  method: "GET" | "POST",
+  path: string,
+  permissionKey: string,
+  feature: ReturnType<typeof featureKey>,
+) {
+  return { method, path, permissionKey, featureKey: feature };
+}
+
+function permission(
+  key: string,
+  action: PermissionDefinition["action"],
+  accessRisk?: PermissionDefinition["accessRisk"],
+): PermissionDefinition {
+  return {
+    key,
+    label: key,
+    module: "people",
+    moduleLabel: "人员",
+    resource: "person",
+    resourceLabel: "人员",
+    action,
+    accessRisk,
+  };
+}
+
+function actor(): RequestActor {
+  return {
+    id: "user-reviewer",
+    type: "user",
+    name: "复核员",
+    roleCodes: ["reviewer"],
+    permissionKeys: ["people.person.export"],
+    ...buildActorScopeContexts("user-reviewer", "dept-case", [
+      {
+        id: "role-reviewer",
+        code: "reviewer",
+        dataScope: "department",
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+function requestFixture(): GovernedExportRequest {
+  const scope = captureGovernedExportScope(actor().scopeContext);
+  return {
+    id: "export-1",
+    resourceType: "people.person",
+    policyKey: "people.person.fields",
+    policyVersion: "1",
+    fieldKeys: ["phone"],
+    requesterId: "user-reviewer",
+    requesterName: "复核员",
+    idempotencyKey: "people-export-1",
+    requestFingerprint: "a".repeat(64),
+    reason: "案件复核需要导出人员字段",
+    scopeSnapshot: scope.snapshot,
+    scopeHash: scope.hash,
+    querySnapshot: { caseId: "case-1" },
+    renderer: legacyGovernedExportRendererSnapshot,
+    status: "pending-approval",
+    approvalRequired: true,
+    expiresAt: "2099-01-01T00:00:00.000Z",
+    createdAt: "2026-07-27T00:00:00.000Z",
+    updatedAt: "2026-07-27T00:00:00.000Z",
+  };
+}

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

@@ -0,0 +1,238 @@
+import type {
+  DataGovernancePolicyDefinition,
+  FeatureFlagDefinition,
+} from "@southwind-ai/shared";
+import type { ModuleGovernedResourceRegistration } from "@southwind-ai/server-sdk";
+import { evaluateRouteGuards, findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { routeContext } from "../system/route-helpers.js";
+import type { RouteApp } from "../system/route-types.js";
+import {
+  type GovernedExportService,
+  type GovernedExportTarget,
+} from "../data-governance/export/service.js";
+import type { InitializedModuleHosts } from "./initialize.js";
+import {
+  exportTarget,
+  knownError,
+  optionalString,
+  parseCreate,
+  project,
+  requirePolicy,
+  required,
+  strictObject,
+  stripApiPrefix,
+} from "./governed-export-route-support.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+type GovernedExportApi = Pick<
+  GovernedExportService,
+  "request" | "status" | "cancel" | "download"
+>;
+
+export function installModuleGovernedExportRoutes(
+  hosts: InitializedModuleHosts,
+  app: RouteApp,
+  context: {
+    readonly runtime: ServerRuntime;
+    readonly features: readonly FeatureFlagDefinition[];
+    readonly service: GovernedExportApi;
+  },
+) {
+  for (const { moduleName, registration } of hosts.governedResources) {
+    if (!registration.export) continue;
+    const policy = requirePolicy(hosts, moduleName, registration.policyKey);
+    installRoutes(app, registration, policy, context);
+  }
+}
+
+function installRoutes(
+  app: RouteApp,
+  registration: ModuleGovernedResourceRegistration,
+  policy: DataGovernancePolicyDefinition,
+  context: {
+    runtime: ServerRuntime;
+    features: readonly FeatureFlagDefinition[];
+    service: GovernedExportApi;
+  },
+) {
+  const source = registration.export;
+  if (!source) return;
+  const target = exportTarget(registration, policy);
+  const feature = findFeature([...context.features], policy.featureKey);
+  const base = source.basePath;
+
+  app.post(stripApiPrefix(base), async (raw) => {
+    const route = routeContext(raw);
+    return guarded(
+      context.runtime,
+      route.guardContext,
+      feature,
+      "POST",
+      base,
+      policy,
+      async () => {
+        try {
+          const input = parseCreate(route.body, registration);
+          return Response.json(
+            project(
+              await context.service.request(input, route.guardContext, target),
+            ),
+            { status: 202 },
+          );
+        } catch (error) {
+          return knownError(error);
+        }
+      },
+    );
+  });
+
+  installStatusRoute(app, context, feature, policy, target, base);
+  installCancelRoute(app, context, feature, policy, target, base);
+  installDownloadRoute(app, context, feature, policy, target, base);
+}
+
+function installStatusRoute(
+  app: RouteApp,
+  context: RouteInstallContext,
+  feature: FeatureFlagDefinition | undefined,
+  policy: DataGovernancePolicyDefinition,
+  target: GovernedExportTarget,
+  base: string,
+) {
+  const path = `${base}/:id`;
+  app.get(stripApiPrefix(path), async (raw) => {
+    const route = routeContext(raw);
+    return guarded(
+      context.runtime,
+      route.guardContext,
+      feature,
+      "GET",
+      path,
+      policy,
+      async () => {
+        try {
+          return project(
+            await context.service.status(
+              required(route.params.id),
+              route.guardContext,
+              target,
+            ),
+          );
+        } catch (error) {
+          return knownError(error);
+        }
+      },
+    );
+  });
+}
+
+function installCancelRoute(
+  app: RouteApp,
+  context: RouteInstallContext,
+  feature: FeatureFlagDefinition | undefined,
+  policy: DataGovernancePolicyDefinition,
+  target: GovernedExportTarget,
+  base: string,
+) {
+  const path = `${base}/:id/cancel`;
+  app.post(stripApiPrefix(path), async (raw) => {
+    const route = routeContext(raw);
+    return guarded(
+      context.runtime,
+      route.guardContext,
+      feature,
+      "POST",
+      path,
+      policy,
+      async () => {
+        try {
+          const body = strictObject(route.body ?? {}, ["reason"]);
+          return project(
+            await context.service.cancel(
+              required(route.params.id),
+              route.guardContext,
+              optionalString(body.reason) || "用户取消治理导出申请",
+              target,
+            ),
+          );
+        } catch (error) {
+          return knownError(error);
+        }
+      },
+    );
+  });
+}
+
+function installDownloadRoute(
+  app: RouteApp,
+  context: RouteInstallContext,
+  feature: FeatureFlagDefinition | undefined,
+  policy: DataGovernancePolicyDefinition,
+  target: GovernedExportTarget,
+  base: string,
+) {
+  const path = `${base}/:id/download`;
+  app.get(stripApiPrefix(path), async (raw) => {
+    const route = routeContext(raw);
+    return guarded(
+      context.runtime,
+      route.guardContext,
+      feature,
+      "GET",
+      path,
+      policy,
+      async () => {
+        try {
+          const opened = await context.service.download(
+            required(route.params.id),
+            route.guardContext,
+            target,
+          );
+          return new Response(opened.body, {
+            headers: {
+              "cache-control": "no-store",
+              "content-type": opened.artifact.contentType,
+              "content-disposition": `attachment; filename="${opened.artifact.filename}"`,
+              "x-content-sha256": opened.artifact.sha256,
+            },
+          });
+        } catch (error) {
+          return knownError(error);
+        }
+      },
+    );
+  });
+}
+
+interface RouteInstallContext {
+  runtime: ServerRuntime;
+  service: GovernedExportApi;
+}
+
+async function guarded<T>(
+  runtime: ServerRuntime,
+  guardContext: ReturnType<typeof routeContext>["guardContext"],
+  feature: FeatureFlagDefinition | undefined,
+  method: "GET" | "POST",
+  path: string,
+  policy: DataGovernancePolicyDefinition,
+  handler: () => Promise<T>,
+) {
+  const decision = await evaluateRouteGuards(runtime, guardContext, {
+    permission: {
+      method,
+      path,
+      permissionKey: policy.exportPermissionKey,
+      featureKey: policy.featureKey,
+    },
+    feature,
+    restrictedModeAccess: "backup-export",
+  });
+  return decision.allowed
+    ? handler()
+    : Response.json(
+        { error: "FORBIDDEN", reason: decision.reason },
+        { status: 403 },
+      );
+}