create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/module-host/route-installer.test.ts

@@ -1,24 +1,14 @@
 import { describe, expect, test } from "bun:test";
-import type { DurableJobs, SubmitDurableJob } from "@southwind-ai/jobs";
-import type { ModuleManifest } from "@southwind-ai/modules";
-import type {
-  ModuleInitializer,
-  ModuleRequestContext,
+import {
+  requireModuleSecretPort,
+  requireModuleStorageWritePortV1,
 } from "@southwind-ai/server-sdk";
-import { featureKey, licenseVersionKey } from "@southwind-ai/shared";
-import { buildScopeContext } from "../data-access/context.js";
-import type { RequestActor } from "../guards.js";
-import { createServerRuntime } from "../runtime.js";
-import { createStorageRuntime } from "../storage/runtime.js";
-import { FakeRouteApp } from "../system/route-test-app.js";
-import { initializeModuleHosts } from "./initialize.js";
-import { installModuleRoutes } from "./route-installer.js";
+import { createRouteInstallerFixture as createFixture } from "./route-installer.test-fixture.js";
 
 describe("模块 Guarded Route 安装", () => {
   test("无权限拒绝并写入 security.denied 审计", async () => {
     const fixture = await createFixture({ permissionKeys: [] });
     const response = (await fixture.invoke("GET", "/shop/items")) as Response;
-
     expect(response.status).toBe(403);
     await expect(response.json()).resolves.toMatchObject({
       reason: "missing-permission",
@@ -35,7 +25,6 @@ describe("模块 Guarded Route 安装", () => {
   test("Feature 停用时拒绝且不进入 Handler", async () => {
     const fixture = await createFixture({ featureEnabled: false });
     const response = (await fixture.invoke("GET", "/shop/items")) as Response;
-
     expect(response.status).toBe(403);
     await expect(response.json()).resolves.toMatchObject({
       reason: "feature-disabled",
@@ -48,7 +37,6 @@ describe("模块 Guarded Route 安装", () => {
     const result = (await fixture.invoke("POST", "/shop/items", {}, {})) as {
       ok: boolean;
     };
-
     expect(result).toEqual({ ok: true });
     expect(fixture.handled).toBe(true);
     expect(fixture.runtime.auditSink.list()).toContainEqual(
@@ -79,6 +67,7 @@ describe("模块 Guarded Route 安装", () => {
     await fixture.invoke("GET", "/shop/items");
     const context = fixture.context;
     if (!context) throw new Error("缺少请求上下文");
+    expect(requireModuleSecretPort(context)).toBeDefined();
 
     await expect(context.audit.emit("data.search")).rejects.toThrow(
       "审计动作未在模块 shop Manifest 注册：data.search",
@@ -103,9 +92,9 @@ describe("模块 Guarded Route 安装", () => {
       requestedBy: "user_admin",
     });
 
-    expect(() => context.storage.createUploadSession({} as never)).toThrow(
-      "模块 shop 的存储 Port 未挂载",
-    );
+    await expect(
+      requireModuleStorageWritePortV1(context).createUploadSession({} as never),
+    ).rejects.toThrow("模块 shop 的存储 Writer 未挂载");
   });
 
   test("未挂载 Durable Jobs 时提交以明确错误失败", async () => {
@@ -133,6 +122,10 @@ describe("模块 Guarded Route 安装", () => {
       expectedByteSize: 3,
     });
     expect(session.ownerId).toBe("user_admin");
+    if (!fixture.storage) throw new Error("缺少存储运行时");
+    await expect(
+      fixture.storage.uploads.inspectSession(session.id, "user_admin"),
+    ).resolves.toMatchObject({ ownerId: "user_admin" });
 
     await expect(
       context.storage.createUploadSession({
@@ -141,200 +134,43 @@ describe("模块 Guarded Route 安装", () => {
         mimeType: "text/plain",
         expectedByteSize: 3,
       }),
-    ).rejects.toThrow("上传用途不属于模块 shop：bulk-data");
+    ).rejects.toMatchObject({
+      code: "UPLOAD_FORBIDDEN",
+      message: "上传用途不属于模块 shop：bulk-data",
+    });
   });
-});
 
-interface FixtureOptions {
-  permissionKeys?: string[];
-  featureEnabled?: boolean;
-  withJobs?: boolean;
-  withStorage?: boolean;
-}
+  test("报告 Port 每次读取重新解析当前 Actor 与 Route Guard", async () => {
+    const fixture = await createFixture({
+      withStorage: true,
+      withReportStaging: true,
+    });
+    await fixture.invoke("GET", "/shop/items");
+    const port = fixture.context?.reportStaging;
+    if (!port) throw new Error("缺少报告暂存 Port");
 
-async function createFixture(options: FixtureOptions = {}) {
-  const state: {
-    handled: boolean;
-    context?: ModuleRequestContext;
-    submittedJob?: SubmitDurableJob;
-  } = { handled: false };
-  const initializer: ModuleInitializer = {
-    moduleName: "shop",
-    initialize(host) {
-      host.registerUploadPolicy({
-        purpose: "shop.attachment",
-        maxByteSize: 1024,
-        maxPartByteSize: 512,
-        sessionTtlMs: 60_000,
-        allowedTypes: { "text/plain": ["txt"] },
-        signature: "none",
-      });
-      host.registerRoutes([
-        {
-          method: "GET",
-          path: "/api/shop/items",
-          permissionKey: "shop.item.read",
-          handler: (context) => {
-            state.handled = true;
-            state.context = context;
-            return { items: [] };
-          },
-        },
-        {
-          method: "POST",
-          path: "/api/shop/items",
-          permissionKey: "shop.item.manage",
-          handler: () => {
-            state.handled = true;
-            state.context = undefined;
-            return { ok: true };
-          },
-        },
-      ]);
-    },
-  };
-  const hosts = await initializeModuleHosts({
-    modules: [shopManifest()],
-    initializers: [initializer],
-  });
-  const runtime = createServerRuntime(
-    {},
-    {
-      actorResolver: { resolve: () => actor(options.permissionKeys) },
-      licenseResolver: {
-        resolve: () => ({ versionKey: licenseVersionKey("standard") }),
-      },
-      featureResolver: {
-        resolve: (key) => ({
-          key,
-          enabled: options.featureEnabled ?? true,
-          visible: "visible",
-        }),
-      },
-    },
-  );
-  const jobs = options.withJobs
-    ? ({
-        submit: (input: SubmitDurableJob) => {
-          state.submittedJob = input;
-          return Promise.resolve({
-            job: { id: "job_1" },
-            created: true,
-          });
-        },
-      } as unknown as DurableJobs)
-    : undefined;
-  const app = new FakeRouteApp();
-  const storage = options.withStorage
-    ? createStorageRuntime({}, undefined, hosts.uploadPolicies)
-    : undefined;
-  installModuleRoutes(hosts, app, {
-    runtime,
-    features: shopManifest().features,
-    jobs,
-    storage: storage
-      ? { uploads: storage.uploads, files: storage.files }
-      : undefined,
+    await expect(
+      port.inspect("rsg_11111111111111111111111111111111"),
+    ).rejects.toMatchObject({ code: "REPORT_STAGING_FORBIDDEN" });
+    fixture.setPermissions([]);
+    await expect(
+      port.inspect("rsg_11111111111111111111111111111111"),
+    ).rejects.toMatchObject({ code: "REPORT_STAGING_FORBIDDEN" });
+    expect(fixture.runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "report.staging.access",
+        outcome: "denied",
+      }),
+    );
   });
-  const guardContext = await runtime.createGuardContext(
-    new Request("http://localhost/api/shop/items"),
-  );
-  return {
-    runtime,
-    get handled() {
-      return state.handled;
-    },
-    get context() {
-      return state.context;
-    },
-    get submittedJob() {
-      return state.submittedJob;
-    },
-    invoke(method: string, path: string, params = {}, body?: unknown) {
-      return app.invoke(method, path, {
-        guardContext,
-        request: new Request(`http://localhost${path}`),
-        params,
-        query: {},
-        body,
-      });
-    },
-  };
-}
 
-function actor(
-  permissionKeys = ["shop.item.read", "shop.item.manage"],
-): RequestActor {
-  return {
-    id: "user_admin",
-    type: "user",
-    name: "测试管理员",
-    roleCodes: ["developer"],
-    permissionKeys,
-    scopeContext: buildScopeContext("user_admin", undefined, [
-      {
-        id: "developer",
-        code: "developer",
-        dataScope: "self",
-        departmentIds: [],
-      },
-    ]),
-  };
-}
-
-function shopManifest(): ModuleManifest {
-  return {
-    name: "shop",
-    version: "0.1.0",
-    label: "商店",
-    description: "测试模块",
-    menus: [],
-    adminRoutes: [],
-    permissions: [permission("shop.item.read"), permission("shop.item.manage")],
-    apiPermissions: [
-      {
-        method: "GET",
-        path: "/api/shop/items",
-        permissionKey: "shop.item.read",
-        featureKey: "shop.feature",
-        auditAction: "data.read",
-      },
-      {
-        method: "POST",
-        path: "/api/shop/items",
-        permissionKey: "shop.item.manage",
-        featureKey: "shop.feature",
-        auditAction: "crud.create",
-      },
-    ],
-    features: [
-      {
-        key: featureKey("shop.feature"),
-        label: "商店",
-        module: "shop",
-        description: "测试 Feature",
-        visible: "visible",
-        enabled: true,
-        stage: "stable",
-      },
-    ],
-    migrations: [],
-    schemaExports: [],
-    tasks: [],
-    tools: [],
-    providers: [],
-    auditActions: ["crud.create", "data.read"],
-  };
-}
-
-function permission(key: string) {
-  return {
-    key,
-    label: key,
-    module: "shop",
-    moduleLabel: "商店",
-    resource: "item",
-    resourceLabel: "商品",
-    action: key.endsWith("read") ? ("read" as const) : ("manage" as const),
-  };
-}
+  test("production 无 PostgreSQL 时 RequestContext 不挂载临时报告 Port", async () => {
+    const fixture = await createFixture({
+      withStorage: true,
+      withReportStaging: true,
+      productionWithoutDb: true,
+    });
+    await fixture.invoke("GET", "/shop/items");
+    expect(fixture.context?.reportStaging).toBeUndefined();
+  });
+});

package/template/apps/server/src/module-host/route-installer.ts

@@ -6,9 +6,15 @@ import type { RouteApp } from "../system/route-types.js";
 import type { createServerRuntime } from "../runtime.js";
 import type { InitializedModuleHosts } from "./initialize.js";
 import type {
+  ModuleAiArtifactRef,
   ModuleAiArtifactPort,
   ModuleAiOperationPort,
+  ModuleAiOperationReadinessPortV1,
+  ModuleAiScreenshotIntakePortV1,
 } from "@southwind-ai/server-sdk";
+// @windy-module system.storage begin
+import { ModuleReportStagingError } from "@southwind-ai/server-sdk";
+// @windy-module system.storage end
 import { buildModuleRequestContext } from "./request-context.js";
 import {
   createModuleStoragePort,
@@ -19,7 +25,15 @@ import {
   type ModuleUserDirectoryServices,
 } from "./user-directory-port.js";
 import { createModuleStorageScope } from "./storage-scope.js";
+import { createModuleStorageWritePort } from "./storage-write-port.js";
 import type { ModuleJobControlRuntime } from "./job-port.js";
+import { createModuleSecretPort } from "./module-secret-port.js";
+import { createGovernedModuleScreenshotIntakePort } from "./screenshot-intake-port.js";
+import { ScreenshotIntakePlanStore } from "./screenshot-intake-store.js";
+// @windy-module system.storage begin
+import type { ReportStagingService } from "../report-staging/service.js";
+import { createModuleReportStagingPort } from "./report-staging-port.js";
+// @windy-module system.storage end
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -32,6 +46,10 @@ export interface ModuleRouteInstallContext {
   jobControl?: ModuleJobControlRuntime;
   /** 平台存储服务；提供后模块获得受限 Upload/BlobRead Port。 */
   storage?: ModuleStorageServices;
+  // @windy-module system.storage begin
+  /** Host 持有的大报告暂存生命周期；模块只获得作用域 Port。 */
+  reportStaging?: ReportStagingService;
+  // @windy-module system.storage end
   /** 平台身份目录；Adapter 会绑定当前请求 Actor 与服务端数据范围。 */
   userDirectory?: Omit<ModuleUserDirectoryServices, "runtime" | "features">;
   aiArtifacts?: (
@@ -39,11 +57,26 @@ export interface ModuleRouteInstallContext {
     guardContext: ReturnType<typeof routeContext>["guardContext"],
     signal: AbortSignal,
   ) => ModuleAiArtifactPort;
+  validateAiArtifact?: (
+    reference: ModuleAiArtifactRef,
+    moduleName: string,
+    guardContext: ReturnType<typeof routeContext>["guardContext"],
+  ) => ModuleAiArtifactRef;
   aiOperations?: (
     moduleName: string,
     guardContext: ReturnType<typeof routeContext>["guardContext"],
     signal: AbortSignal,
   ) => ModuleAiOperationPort;
+  aiReadiness?: (
+    moduleName: string,
+    guardContext: ReturnType<typeof routeContext>["guardContext"],
+    signal: AbortSignal,
+  ) => ModuleAiOperationReadinessPortV1;
+  screenshots?: (
+    moduleName: string,
+    guardContext: ReturnType<typeof routeContext>["guardContext"],
+    signal: AbortSignal,
+  ) => ModuleAiScreenshotIntakePortV1;
 }
 
 /**
@@ -56,6 +89,7 @@ export function installModuleRoutes(
   app: RouteApp,
   context: ModuleRouteInstallContext,
 ): void {
+  const screenshotStores = new Map<string, ScreenshotIntakePlanStore>();
   for (const { moduleName, definition } of hosts.routes) {
     const manifest = hosts.manifestOf(moduleName);
     const binding = manifest.apiPermissions.find(
@@ -73,22 +107,82 @@ export function installModuleRoutes(
       : undefined;
     const path = stripApiPrefix(definition.path);
     const method = definition.method.toLowerCase() as RouteMethod;
-    app[method](path, async (raw: unknown) => {
+    const handler = async (raw: unknown) => {
       const route = routeContext(raw);
       const decision = await evaluateRouteGuards(
         context.runtime,
         route.guardContext,
         { permission: binding, feature },
       );
-      if (!decision.allowed) return forbidden(decision.reason);
+      if (!decision.allowed) {
+        if (definition.bodyMode === "stream") {
+          await route.request.body
+            ?.cancel("module-route-guard-denied")
+            .catch(() => undefined);
+        }
+        return forbidden(decision.reason);
+      }
       const emittedAuditActions = new Set<string>();
+      const screenshotProducer = context.screenshots?.(
+        moduleName,
+        route.guardContext,
+        route.request.signal,
+      );
+      let screenshotStore = screenshotStores.get(moduleName);
+      if (screenshotProducer && !screenshotStore) {
+        screenshotStore = new ScreenshotIntakePlanStore();
+        screenshotStores.set(moduleName, screenshotStore);
+      }
+      const createStorageScopeFor = (guardContext: typeof route.guardContext) =>
+        createModuleStorageScope({
+          moduleName,
+          purposes: hosts.uploadPurposesOf(moduleName),
+          uploadPolicies: hosts.uploadPoliciesOf(moduleName),
+          resourceFileAccessPolicies:
+            hosts.resourceFileAccessPoliciesOf(moduleName),
+          guardContext,
+          runtime: context.runtime,
+          features: context.features,
+          signal: route.request.signal,
+        });
+      const storageScope = context.storage
+        ? createStorageScopeFor(route.guardContext)
+        : undefined;
+      // @windy-module system.storage begin
+      const resolveCurrentReportScope = async () => {
+        if (!storageScope) return undefined;
+        const currentGuard = await context.runtime.createGuardContext(
+          route.request,
+        );
+        const currentScope = createStorageScopeFor(currentGuard);
+        if (
+          currentScope.ownerId !== storageScope.ownerId ||
+          currentScope.authorizationBinding?.scopeHash !==
+            storageScope.authorizationBinding?.scopeHash ||
+          !(
+            await evaluateRouteGuards(context.runtime, currentGuard, {
+              permission: binding,
+              feature,
+            })
+          ).allowed
+        ) {
+          return undefined;
+        }
+        return currentScope;
+      };
+      // @windy-module system.storage end
       const requestContext = buildModuleRequestContext({
         moduleName,
         manifest,
         guardContext: route.guardContext,
         params: route.params,
         query: route.query,
-        body: route.body,
+        body: definition.bodyMode === "stream" ? undefined : route.body,
+        bodyStream:
+          definition.bodyMode === "stream"
+            ? (route.request.body ?? undefined)
+            : undefined,
+        signal: route.request.signal,
         runtime: context.runtime,
         aiArtifacts: context.aiArtifacts?.(
           moduleName,
@@ -100,30 +194,83 @@ export function installModuleRoutes(
           route.guardContext,
           route.request.signal,
         ),
+        aiReadiness: context.aiReadiness?.(
+          moduleName,
+          route.guardContext,
+          route.request.signal,
+        ),
+        screenshots:
+          screenshotProducer && screenshotStore && context.validateAiArtifact
+            ? createGovernedModuleScreenshotIntakePort({
+                moduleName,
+                manifest,
+                guardContext: route.guardContext,
+                signal: route.request.signal,
+                runtime: context.runtime,
+                producer: screenshotProducer,
+                store: screenshotStore,
+                validateArtifact: (reference) =>
+                  context.validateAiArtifact!(
+                    reference,
+                    moduleName,
+                    route.guardContext,
+                  ),
+              })
+            : undefined,
         jobs: context.jobs,
         jobControl: context.jobControl,
         reauthorizeJobs: async () =>
           (
-            await evaluateRouteGuards(
-              context.runtime,
-              route.guardContext,
-              { permission: binding, feature },
-            )
+            await evaluateRouteGuards(context.runtime, route.guardContext, {
+              permission: binding,
+              feature,
+            })
           ).allowed,
-        storage: context.storage
-          ? createModuleStoragePort(context.storage, {
-              ...createModuleStorageScope({
-                moduleName,
-                purposes: hosts.uploadPurposesOf(moduleName),
-                resourceFileAccessPolicies:
-                  hosts.resourceFileAccessPoliciesOf(moduleName),
+        secrets: createModuleSecretPort({
+          moduleName,
+          declarations: hosts.secretDeclarationsOf(moduleName),
+          bindings: hosts.secretBindingsOf(moduleName),
+          guardContext: route.guardContext,
+          runtime: context.runtime,
+          features: context.features,
+        }),
+        storage:
+          context.storage && storageScope
+            ? createModuleStoragePort(context.storage, storageScope)
+            : undefined,
+        storageWriter:
+          context.storage && storageScope
+            ? createModuleStorageWritePort(context.storage, storageScope)
+            : undefined,
+        // @windy-module system.storage begin
+        reportStaging:
+          context.reportStaging && context.storage && storageScope
+            ? createModuleReportStagingPort({
+                service: context.reportStaging,
+                policies: hosts.reportStagingPoliciesOf(moduleName),
+                storage: {
+                  async open(request) {
+                    const currentScope = await resolveCurrentReportScope();
+                    if (!currentScope) {
+                      throw new ModuleReportStagingError(
+                        "REPORT_STAGING_FORBIDDEN",
+                        "报告源文件访问未授权",
+                      );
+                    }
+                    return createModuleStoragePort(
+                      context.storage!,
+                      currentScope,
+                    ).openResourceFile(request);
+                  },
+                },
+                storageScope,
                 guardContext: route.guardContext,
                 runtime: context.runtime,
-                features: context.features,
-                signal: route.request.signal,
-              }),
-            })
-          : undefined,
+                reauthorize: async () =>
+                  Boolean(await resolveCurrentReportScope()),
+              })
+            : undefined,
+        // @windy-module system.storage end
         userDirectory: context.userDirectory
           ? createModuleUserDirectoryPort(
               {
@@ -150,8 +297,32 @@ export function installModuleRoutes(
         });
       }
       return result;
-    });
+    };
+    registerModuleRoute(app, method, path, handler, definition.bodyMode);
+  }
+}
+
+function registerModuleRoute(
+  app: RouteApp,
+  method: RouteMethod,
+  path: string,
+  handler: (context: unknown) => unknown,
+  bodyMode: "stream" | undefined,
+): void {
+  if (bodyMode === "stream") {
+    if (method === "post") {
+      app.post(path, handler, { parse: "none" });
+      return;
+    }
+    if (method === "put") {
+      app.put(path, handler, { parse: "none" });
+      return;
+    }
+    throw new Error(
+      `模块流式路由仅支持 POST/PUT：${method.toUpperCase()} ${path}`,
+    );
   }
+  app[method](path, handler);
 }
 
 function isSuccessfulResult(value: unknown): boolean {

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

@@ -81,10 +81,10 @@ describe("模块路由注册", () => {
             apiPermissions: [
               {
                 method: "GET",
-          path: "/api/known/items",
-          permissionKey: "known.item.read",
-          featureKey: featureKey("known.item"),
-          auditAction: "data.read",
+                path: "/api/known/items",
+                permissionKey: "known.item.read",
+                featureKey: featureKey("known.item"),
+                auditAction: "data.read",
               },
             ],
           }),
@@ -137,6 +137,46 @@ describe("模块路由注册", () => {
       "模块路由审计动作与 Manifest 声明不一致：GET /api/known/items",
     );
   });
+
+  test("流式请求体只允许 Manifest 已声明的 POST/PUT 路由", async () => {
+    const readable = manifest("known", {
+      apiPermissions: [
+        {
+          method: "GET",
+          path: "/api/known/items",
+          permissionKey: "known.item.read",
+          auditAction: "data.read",
+        },
+      ],
+      auditActions: ["data.read"],
+    });
+    await expect(
+      registerRoutes(readable, [{ ...route(), bodyMode: "stream" }]),
+    ).rejects.toThrow("模块流式路由仅支持 POST/PUT：GET /api/known/items");
+
+    const writable = manifest("known", {
+      apiPermissions: [
+        {
+          method: "PUT",
+          path: "/api/known/uploads/:id",
+          permissionKey: "known.item.read",
+          auditAction: "data.read",
+        },
+      ],
+      auditActions: ["data.read"],
+    });
+    await expect(
+      registerRoutes(writable, [
+        {
+          method: "PUT",
+          path: "/api/known/uploads/:id",
+          permissionKey: "known.item.read",
+          bodyMode: "stream",
+          handler: () => ({}),
+        },
+      ]),
+    ).resolves.toBeDefined();
+  });
 });
 
 function initializer(

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

@@ -20,6 +20,8 @@ const compatibleModules = mergeLegacyAndProjectModules(
 );
 
 export const runtimeBusinessModules = compatibleModules.modules;
+export const runtimeModuleSecretBindings =
+  serverCompositionDeclaration.secretBindings ?? [];
 
 export async function attachRuntimeBusinessModules(
   runtime: Parameters<typeof attachInstalledBusinessModules>[0],