create-windy 0.3.4 → 0.3.6

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

@@ -0,0 +1,334 @@
+import { createHash } from "node:crypto";
+import { randomUUIDv7 } from "bun";
+import type { DurableJobSnapshot, DurableJobs } from "@southwind-ai/jobs";
+import type {
+  ModuleJobPort,
+  ModuleJobView,
+} from "@southwind-ai/server-sdk";
+import {
+  ModuleJobControlError,
+  requireModuleNamespace,
+} from "@southwind-ai/server-sdk";
+import type { AuditEvent } from "@southwind-ai/shared";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  captureAuthorizationScope,
+  hashAuthorizationScope,
+} from "../data-access/scope-snapshot.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export interface ModuleJobControlRuntime {
+  readonly worker: {
+    controlCancel(input: {
+      jobId: string;
+      expectedStatus?: ModuleJobView["status"];
+      expectedVersion?: string;
+    }): Promise<{
+      outcome: "changed" | "unchanged" | "not-found" | "conflict";
+    }>;
+    recover(input: {
+      jobId: string;
+      requestedBy: string;
+      reason: string;
+      idempotencyKey: string;
+      expectedAttempt: number;
+      expectedStatus: ModuleJobView["status"];
+      expectedVersion: string;
+    }): Promise<unknown>;
+  };
+}
+
+export interface ModuleJobPortInput {
+  readonly moduleName: string;
+  readonly guardContext: RequestGuardContext;
+  readonly runtime: ServerRuntime;
+  readonly jobs?: DurableJobs;
+  readonly control?: ModuleJobControlRuntime;
+  readonly reauthorize?: () => Promise<boolean>;
+}
+
+export function createModuleJobPort(input: ModuleJobPortInput): ModuleJobPort {
+  return {
+    async submit(job) {
+      requireModuleNamespace("任务 handler", job.handlerKey, input.moduleName);
+      const jobs = requiredJobs(input);
+      const result = await jobs.submit({
+        ...job,
+        queue: input.moduleName,
+        requestedBy: input.guardContext.actor.id,
+        authorizationScope: currentScope(input),
+      });
+      return { jobId: result.job.id, created: result.created };
+    },
+    async get(jobId) {
+      return toAuthorizedView(input, jobId);
+    },
+    async cancel(request) {
+      const reason = sanitizeReason(request.reason);
+      const current = await requireAuthorizedSnapshot(input, request.jobId);
+      const control = requiredControl(input);
+      const result = await control.worker.controlCancel({
+        jobId: current.job.id,
+        expectedStatus: request.expectedStatus,
+        expectedVersion: request.expectedVersion,
+      });
+      if (result.outcome === "conflict" || result.outcome === "not-found") {
+        await auditControl(
+          input,
+          "cancel",
+          "failure",
+          current,
+          reason,
+          result.outcome,
+        );
+        throw conflict();
+      }
+      const updated = await requireAuthorizedSnapshot(input, request.jobId);
+      await auditControl(
+        input,
+        "cancel",
+        "success",
+        updated,
+        reason,
+        result.outcome,
+      );
+      return toView(updated);
+    },
+    async recover(request) {
+      const reason = sanitizeReason(request.reason);
+      const current = await requireAuthorizedSnapshot(input, request.jobId);
+      const control = requiredControl(input);
+      try {
+        await control.worker.recover({
+          jobId: current.job.id,
+          requestedBy: input.guardContext.actor.id,
+          reason,
+          idempotencyKey: recoveryKey(input, request),
+          expectedAttempt: request.expectedAttempt,
+          expectedStatus: request.expectedStatus,
+          expectedVersion: request.expectedVersion,
+        });
+      } catch {
+        await auditControl(
+          input,
+          "recover",
+          "failure",
+          current,
+          reason,
+          "conflict",
+        );
+        throw conflict();
+      }
+      const updated = await requireAuthorizedSnapshot(input, request.jobId);
+      await auditControl(input, "recover", "success", updated, reason, "changed");
+      return toView(updated);
+    },
+  };
+}
+
+async function toAuthorizedView(
+  input: ModuleJobPortInput,
+  jobId: string,
+): Promise<ModuleJobView | undefined> {
+  if (input.reauthorize && !(await input.reauthorize())) return undefined;
+  const snapshot = await requiredJobs(input).get(jobId);
+  return snapshot && authorized(input, snapshot) ? toView(snapshot) : undefined;
+}
+
+async function requireAuthorizedSnapshot(
+  input: ModuleJobPortInput,
+  jobId: string,
+) {
+  const snapshot = await toAuthorizedSnapshot(input, jobId);
+  if (snapshot) return snapshot;
+  await auditUnavailable(input, jobId);
+  throw new ModuleJobControlError("JOB_NOT_AVAILABLE", "任务不可用");
+}
+
+async function toAuthorizedSnapshot(
+  input: ModuleJobPortInput,
+  jobId: string,
+) {
+  if (input.reauthorize && !(await input.reauthorize())) return undefined;
+  const snapshot = await requiredJobs(input).get(jobId);
+  return snapshot && authorized(input, snapshot) ? snapshot : undefined;
+}
+
+function authorized(input: ModuleJobPortInput, snapshot: DurableJobSnapshot) {
+  const job = snapshot.job;
+  const submittedScope = job.authorizationScope;
+  return (
+    job.queue === input.moduleName &&
+    job.handlerKey.startsWith(`${input.moduleName}.`) &&
+    job.requestedBy === input.guardContext.actor.id &&
+    Boolean(submittedScope) &&
+    hashAuthorizationScope(submittedScope!) ===
+      hashAuthorizationScope(currentScope(input))
+  );
+}
+
+function toView(snapshot: DurableJobSnapshot): ModuleJobView {
+  const attempt = Math.max(
+    0,
+    ...snapshot.stages.map((stage) => stage.currentAttempt),
+  );
+  const latestProgress = snapshot.progress
+    .slice()
+    .sort(
+      (left, right) =>
+        left.recordedAt.localeCompare(right.recordedAt) ||
+        left.sequence - right.sequence,
+    )
+    .at(-1);
+  const latestFailure = snapshot.failures.at(-1);
+  const activeLease = snapshot.leases.some((lease) => lease.status === "active");
+  return {
+    jobId: snapshot.job.id,
+    handlerKey: snapshot.job.handlerKey,
+    status: snapshot.job.status,
+    progress: latestProgress
+      ? {
+          completedUnits: latestProgress.completedUnits,
+          totalUnits: latestProgress.totalUnits,
+        }
+      : undefined,
+    attempt,
+    maxAttempts: snapshot.job.maxAttempts,
+    createdAt: snapshot.job.createdAt,
+    startedAt: snapshot.job.startedAt,
+    finishedAt: snapshot.job.finishedAt,
+    failureCode: safeFailureCode(latestFailure?.code),
+    canCancel:
+      ["queued", "running"].includes(snapshot.job.status) &&
+      !snapshot.job.cancelRequestedAt,
+    canRecover:
+      ["failed", "cancelled"].includes(snapshot.job.status) && !activeLease,
+    version: snapshot.job.updatedAt,
+  };
+}
+
+function sanitizeReason(value: string) {
+  const reason = value
+    .trim()
+    .replace(/\s+/g, " ")
+    .replace(/[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}/g, "[邮箱]")
+    .replace(/\b\d{7,}\b/g, "[号码]")
+    .replace(/\b[A-Za-z0-9_-]{24,}\b/g, "[敏感内容]")
+    .slice(0, 200);
+  if (reason.length < 5) {
+    throw new ModuleJobControlError(
+      "JOB_REASON_INVALID",
+      "任务控制理由至少 5 个字符",
+    );
+  }
+  return reason;
+}
+
+function safeFailureCode(code: string | undefined) {
+  if (!code) return undefined;
+  return /^[A-Z][A-Z0-9_.-]{0,79}$/.test(code) ? code : "JOB_FAILED";
+}
+
+function currentScope(input: ModuleJobPortInput) {
+  return captureAuthorizationScope(
+    input.guardContext.actor.scopeContext,
+  ).snapshot;
+}
+
+function requiredJobs(input: ModuleJobPortInput) {
+  if (input.jobs) return input.jobs;
+  throw unavailable();
+}
+
+function requiredControl(input: ModuleJobPortInput) {
+  if (input.control) return input.control;
+  throw unavailable();
+}
+
+function unavailable() {
+  return new ModuleJobControlError(
+    "JOB_CONTROL_UNAVAILABLE",
+    "Durable Jobs 运行时未挂载",
+  );
+}
+
+function conflict() {
+  return new ModuleJobControlError("JOB_STATE_CONFLICT", "任务状态已变化");
+}
+
+function recoveryKey(
+  input: ModuleJobPortInput,
+  request: {
+    jobId: string;
+    expectedAttempt: number;
+    expectedStatus: string;
+    expectedVersion: string;
+  },
+) {
+  return createHash("sha256")
+    .update(
+      [
+        input.moduleName,
+        input.guardContext.actor.id,
+        request.jobId,
+        request.expectedAttempt,
+        request.expectedStatus,
+        request.expectedVersion,
+      ].join(":"),
+    )
+    .digest("hex");
+}
+
+async function auditUnavailable(input: ModuleJobPortInput, jobId: string) {
+  await input.runtime.auditSink.recordCriticalEvent(
+    auditEvent(input, "access", "denied", jobId),
+  );
+}
+
+async function auditControl(
+  input: ModuleJobPortInput,
+  operation: "cancel" | "recover",
+  outcome: "success" | "failure",
+  snapshot: DurableJobSnapshot,
+  reason: string,
+  result: string,
+) {
+  await input.runtime.auditSink.recordCriticalEvent({
+    ...auditEvent(input, operation, outcome, snapshot.job.id),
+    metadata: {
+      handlerKey: snapshot.job.handlerKey,
+      status: snapshot.job.status,
+      attempt: Math.max(
+        0,
+        ...snapshot.stages.map((stage) => stage.currentAttempt),
+      ),
+      attemptCount: snapshot.attempts.length,
+      failureCount: snapshot.failures.length,
+      failureCode: safeFailureCode(snapshot.failures.at(-1)?.code),
+      recoveryCount: snapshot.recoveries.length,
+      version: snapshot.job.updatedAt,
+      reason,
+      result,
+    },
+  });
+}
+
+function auditEvent(
+  input: ModuleJobPortInput,
+  operation: string,
+  outcome: AuditEvent["outcome"],
+  jobId: string,
+): AuditEvent {
+  return {
+    id: randomUUIDv7(),
+    action: `module.job.${operation}`,
+    outcome,
+    actor: auditActor(input.guardContext),
+    target: { type: "durable-job", id: jobId },
+    module: input.moduleName,
+    requestId: input.guardContext.requestId,
+    occurredAt: new Date().toISOString(),
+  };
+}

package/template/apps/server/src/module-host/request-context.ts

@@ -6,7 +6,6 @@ import type {
   ModuleAiOperationPort,
   ModuleAuditEmitInput,
   ModuleAuditEmitter,
-  ModuleJobSubmitter,
   ModuleRequestContext,
   ModuleStoragePort,
   ModuleUserDirectoryPort,
@@ -15,7 +14,6 @@ import {
   ModuleAiArtifactError,
   ModuleAiOperationError,
   ModuleUserDirectoryError,
-  requireModuleNamespace,
 } from "@southwind-ai/server-sdk";
 import type { AuditEvent } from "@southwind-ai/shared";
 import type { ModuleManifest } from "@southwind-ai/modules";
@@ -25,8 +23,11 @@ import {
   type RequestGuardContext,
 } from "../guards.js";
 import type { createServerRuntime } from "../runtime.js";
-import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
 import { unavailableModuleStoragePort } from "./storage-port.js";
+import {
+  createModuleJobPort,
+  type ModuleJobControlRuntime,
+} from "./job-port.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -71,6 +72,8 @@ export interface ModuleRequestContextInput {
   body?: unknown;
   runtime: ServerRuntime;
   jobs?: DurableJobs;
+  jobControl?: ModuleJobControlRuntime;
+  reauthorizeJobs?: () => Promise<boolean>;
   storage?: ModuleStoragePort;
   userDirectory?: ModuleUserDirectoryPort;
   aiArtifacts?: ModuleAiArtifactPort;
@@ -91,7 +94,14 @@ export function buildModuleRequestContext(
       input.aiArtifacts ?? unavailableModuleAiArtifactPort(input.moduleName),
     aiOperations:
       input.aiOperations ?? unavailableModuleAiOperationPort(input.moduleName),
-    jobs: createModuleJobSubmitter(input),
+    jobs: createModuleJobPort({
+      moduleName: input.moduleName,
+      guardContext: input.guardContext,
+      runtime: input.runtime,
+      jobs: input.jobs,
+      control: input.jobControl,
+      reauthorize: input.reauthorizeJobs,
+    }),
     storage: input.storage ?? unavailableModuleStoragePort(input.moduleName),
     userDirectory:
       input.userDirectory ?? unavailableModuleUserDirectory(input.moduleName),
@@ -184,25 +194,3 @@ function buildAuditEvent(
     occurredAt: new Date().toISOString(),
   };
 }
-
-function createModuleJobSubmitter(
-  input: ModuleRequestContextInput,
-): ModuleJobSubmitter {
-  return {
-    async submit(job) {
-      requireModuleNamespace("任务 handler", job.handlerKey, input.moduleName);
-      if (!input.jobs) {
-        throw new Error("Durable Jobs 运行时未挂载");
-      }
-      const result = await input.jobs.submit({
-        ...job,
-        queue: input.moduleName,
-        requestedBy: input.guardContext.actor.id,
-        authorizationScope: captureAuthorizationScope(
-          input.guardContext.actor.scopeContext,
-        ).snapshot,
-      });
-      return { jobId: result.job.id, created: result.created };
-    },
-  };
-}

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

@@ -19,6 +19,7 @@ import {
   type ModuleUserDirectoryServices,
 } from "./user-directory-port.js";
 import { createModuleStorageScope } from "./storage-scope.js";
+import type { ModuleJobControlRuntime } from "./job-port.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -28,6 +29,7 @@ export interface ModuleRouteInstallContext {
   runtime: ServerRuntime;
   features: readonly FeatureFlagDefinition[];
   jobs?: DurableJobs;
+  jobControl?: ModuleJobControlRuntime;
   /** 平台存储服务；提供后模块获得受限 Upload/BlobRead Port。 */
   storage?: ModuleStorageServices;
   /** 平台身份目录；Adapter 会绑定当前请求 Actor 与服务端数据范围。 */
@@ -98,6 +100,15 @@ export function installModuleRoutes(
           route.request.signal,
         ),
         jobs: context.jobs,
+        jobControl: context.jobControl,
+        reauthorizeJobs: async () =>
+          (
+            await evaluateRouteGuards(
+              context.runtime,
+              route.guardContext,
+              { permission: binding, feature },
+            )
+          ).allowed,
         storage: context.storage
           ? createModuleStoragePort(context.storage, {
               ...createModuleStorageScope({

package/template/apps/web/src/app/business-routes.ts

@@ -0,0 +1,22 @@
+import type { Component } from "vue";
+import type { RouteRecordRaw } from "vue-router";
+
+export interface BusinessAdminRouteRegistration {
+  readonly key: string;
+  readonly path: string;
+  readonly title: string;
+  readonly component: Component;
+  readonly featureKey: string;
+  readonly permissionKey: string;
+  readonly name?: string;
+  readonly props?: RouteRecordRaw["props"];
+}
+
+/**
+ * 客户拥有的 Web 业务路由注册表。
+ *
+ * 导航标题、路径、Feature 和 Permission 必须与业务 Module Manifest 保持一致。
+ * 平台 Router 会统一接入访问快照 Guard，业务项目不需要修改 shared-scaffold。
+ */
+export const installedBusinessAdminRoutes =
+  [] satisfies readonly BusinessAdminRouteRegistration[];

package/template/apps/web/src/components/common/AccessSnapshotBoundary.vue

@@ -0,0 +1,112 @@
+<script setup lang="ts">
+import { computed, nextTick, useTemplateRef, watch } from "vue";
+import { useRoute, useRouter } from "vue-router";
+import { useAccessSnapshot } from "@/composables/useAccessSnapshot";
+import { useAccessSnapshotMonitor } from "@/composables/useAccessSnapshotMonitor";
+import { evaluateWebAccess } from "@/layout/navigation";
+import AccessSnapshotNotice from "./AccessSnapshotNotice.vue";
+
+const route = useRoute();
+const router = useRouter();
+const access = useAccessSnapshot();
+const blocker = useTemplateRef<HTMLDivElement>("blocker");
+useAccessSnapshotMonitor();
+
+const routeRevoked = computed(() => {
+  const snapshot = access.snapshot.value;
+  if (!snapshot || route.meta.layout !== "admin") return false;
+  return !evaluateWebAccess(snapshot, {
+    permissionKey:
+      typeof route.meta.permissionKey === "string"
+        ? route.meta.permissionKey
+        : undefined,
+    featureKey:
+      typeof route.meta.featureKey === "string"
+        ? route.meta.featureKey
+        : undefined,
+  }).allowed;
+});
+
+const blockedReason = computed(() => {
+  if (routeRevoked.value) return "route-revoked" as const;
+  if (access.error.value) {
+    return access.failureReason.value || ("snapshot-unavailable" as const);
+  }
+  return undefined;
+});
+
+const blocked = computed(() => Boolean(blockedReason.value));
+const visibleChange = computed(() =>
+  blocked.value ? undefined : access.change.value,
+);
+
+watch(blocked, async (isBlocked) => {
+  if (!isBlocked) return;
+  await nextTick();
+  blocker.value?.focus();
+});
+
+async function retry(): Promise<void> {
+  try {
+    await access.refresh();
+  } catch {
+    // 失败详情保留在 access.error，由本边界继续安全降级。
+  }
+}
+
+function reload(): void {
+  window.location.reload();
+}
+
+async function returnHome(): Promise<void> {
+  await router.push({ name: "home" });
+}
+</script>
+
+<template>
+  <div class="contents">
+    <!-- 页面节点保留以维持表单基线、dirty 状态与 beforeunload 保护。 -->
+    <div
+      :inert="blocked"
+      :aria-hidden="blocked ? 'true' : undefined"
+      :class="{ 'pointer-events-none invisible': blocked }"
+      data-testid="access-protected-content"
+    >
+      <AccessSnapshotNotice
+        v-if="visibleChange"
+        class="fixed top-4 right-4 z-40 w-[min(32rem,calc(100vw-2rem))] bg-background shadow-lg"
+        :blocking="false"
+        :change-kind="visibleChange.kind"
+        :loading="access.loading.value"
+        :fingerprint="access.fingerprint.value"
+        @acknowledge="access.acknowledgeChange"
+        @reload="reload"
+        @retry="retry"
+        @return-home="returnHome"
+      />
+      <slot />
+    </div>
+    <div
+      v-if="blockedReason"
+      ref="blocker"
+      role="alertdialog"
+      aria-modal="true"
+      aria-label="访问状态已变化"
+      tabindex="-1"
+      class="fixed inset-0 z-40 flex items-start justify-center bg-background/95 p-6 pt-[15vh] outline-none backdrop-blur-sm"
+    >
+      <div class="w-full max-w-2xl">
+        <AccessSnapshotNotice
+          :blocking="true"
+          :reason="blockedReason"
+          :loading="access.loading.value"
+          :fingerprint="access.fingerprint.value"
+          @acknowledge="access.acknowledgeChange"
+          @reload="reload"
+          @retry="retry"
+          @return-home="returnHome"
+        />
+      </div>
+    </div>
+  </div>
+</template>

package/template/apps/web/src/components/common/AccessSnapshotBoundary.webtest.ts

@@ -0,0 +1,130 @@
+import { mount } from "@vue/test-utils";
+import { nextTick } from "vue";
+import {
+  createMemoryHistory,
+  createRouter,
+  type RouteRecordRaw,
+} from "vue-router";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import type { WebAccessSnapshot } from "@/layout/navigation";
+import AccessSnapshotBoundary from "./AccessSnapshotBoundary.vue";
+
+const mocks = vi.hoisted(() => ({ loadAccessSnapshot: vi.fn() }));
+vi.mock("@/services/access-api", () => mocks);
+vi.mock("@/composables/useAccessSnapshotMonitor", () => ({
+  useAccessSnapshotMonitor: vi.fn(),
+}));
+
+import {
+  resetAccessSnapshot,
+  useAccessSnapshot,
+} from "@/composables/useAccessSnapshot";
+
+describe("运行中权限快照边界", () => {
+  beforeEach(() => {
+    resetAccessSnapshot();
+    mocks.loadAccessSnapshot.mockReset();
+  });
+
+  test("当前路由权限撤销后隐藏但不卸载未保存页面", async () => {
+    mocks.loadAccessSnapshot
+      .mockResolvedValueOnce(snapshot(["system.user.read"]))
+      .mockResolvedValueOnce(snapshot([]));
+    const access = useAccessSnapshot();
+    await access.ensureLoaded();
+    const router = await testRouter();
+    const wrapper = mount(AccessSnapshotBoundary, {
+      slots: {
+        default:
+          '<input data-testid="draft" value="尚未保存的编辑内容" />',
+      },
+      global: { plugins: [router] },
+    });
+
+    await access.refresh();
+    await nextTick();
+
+    expect(wrapper.get('[data-testid="access-snapshot-blocker"]').text()).toContain(
+      "当前页面权限已被撤销",
+    );
+    expect(
+      wrapper.get('[data-testid="access-protected-content"]').classes(),
+    ).toContain("invisible");
+    expect(
+      wrapper.get<HTMLInputElement>('[data-testid="draft"]').element.value,
+    ).toBe("尚未保存的编辑内容");
+  });
+
+  test("刷新失败时 fail closed，成功重试后恢复原页面", async () => {
+    mocks.loadAccessSnapshot
+      .mockResolvedValueOnce(snapshot(["system.user.read"]))
+      .mockRejectedValueOnce(new Error("network unavailable"))
+      .mockResolvedValueOnce(snapshot(["system.user.read"]));
+    const access = useAccessSnapshot();
+    await access.ensureLoaded();
+    await expect(access.refresh()).rejects.toThrow("network unavailable");
+    const router = await testRouter();
+    const wrapper = mount(AccessSnapshotBoundary, {
+      slots: { default: '<p data-testid="content">用户列表</p>' },
+      global: { plugins: [router] },
+    });
+
+    await wrapper
+      .get('[data-testid="access-snapshot-blocker"] button')
+      .trigger("click");
+    await nextTick();
+
+    expect(mocks.loadAccessSnapshot).toHaveBeenCalledTimes(3);
+    expect(
+      wrapper.find('[data-testid="access-snapshot-blocker"]').exists(),
+    ).toBe(false);
+    expect(wrapper.get('[data-testid="content"]').text()).toBe("用户列表");
+  });
+});
+
+async function testRouter() {
+  const routes: RouteRecordRaw[] = [
+    {
+      path: "/users",
+      component: { template: "<div />" },
+      meta: {
+        layout: "admin",
+        permissionKey: "system.user.read",
+        featureKey: "system.user",
+      },
+    },
+    {
+      path: "/",
+      name: "home",
+      component: { template: "<div />" },
+      meta: { layout: "app" },
+    },
+  ];
+  const router = createRouter({ history: createMemoryHistory(), routes });
+  await router.push("/users");
+  await router.isReady();
+  return router;
+}
+
+function snapshot(permissionKeys: string[]): WebAccessSnapshot {
+  return {
+    actor: {
+      id: "user_1",
+      type: "user",
+      name: "平台用户",
+      roleCodes: ["member"],
+      permissionKeys,
+    },
+    menus: [],
+    permissions: [],
+    features: [
+      {
+        key: "system.user",
+        enabled: true,
+        visible: "visible",
+        allowed: true,
+        reason: "allowed",
+      },
+    ],
+  };
+}