create-windy 0.3.2 → 0.3.5

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",
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,117 @@
+<script setup lang="ts">
+import {
+  CircleAlertIcon,
+  LoaderCircleIcon,
+  RefreshCwIcon,
+  RotateCwIcon,
+} from "@lucide/vue";
+import { computed } from "vue";
+import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
+import { Button } from "@/components/ui/button";
+import type { AccessSnapshotChangeKind } from "@/composables/access-snapshot-change";
+
+const props = defineProps<{
+  blocking: boolean;
+  reason?:
+    | "route-revoked"
+    | "admin-access-revoked"
+    | "snapshot-unavailable";
+  changeKind?: AccessSnapshotChangeKind;
+  loading: boolean;
+  fingerprint: string;
+}>();
+
+const emit = defineEmits<{
+  acknowledge: [];
+  reload: [];
+  retry: [];
+  returnHome: [];
+}>();
+
+const title = computed(() => {
+  if (props.reason === "route-revoked") return "当前页面权限已被撤销";
+  if (props.reason === "admin-access-revoked") {
+    return "管理后台访问权限已被撤销";
+  }
+  if (props.reason === "snapshot-unavailable") return "暂时无法确认最新权限";
+  if (props.changeKind === "reduced") return "访问权限已收紧";
+  if (props.changeKind === "expanded") return "访问权限已增加";
+  return "访问权限已更新";
+});
+
+const description = computed(() => {
+  if (props.reason === "route-revoked") {
+    return "页面内容和操作已停止展示。未保存编辑仍保留在当前页面实例中；返回首页时会继续执行原有的未保存确认流程。";
+  }
+  if (props.reason === "admin-access-revoked") {
+    return "管理端内容和操作已停止展示。未保存编辑仍保留在当前页面实例中，可以重新检查权限或返回业务首页。";
+  }
+  if (props.reason === "snapshot-unavailable") {
+    return "为避免继续使用可能已撤销的能力，页面内容已临时隐藏。网络恢复后可重新检查。";
+  }
+  if (props.changeKind === "reduced") {
+    return "已撤销的入口和操作已立即隐藏。当前页面仍符合最新访问策略。";
+  }
+  if (props.changeKind === "expanded") {
+    return "入口和操作已按最新权限更新；如需重新加载页面数据，可以安全刷新。";
+  }
+  return "角色、功能或菜单策略已更新，当前界面已同步最新访问状态。";
+});
+</script>
+
+<template>
+  <Alert
+    :variant="blocking ? 'destructive' : 'default'"
+    :data-testid="
+      blocking ? 'access-snapshot-blocker' : 'access-snapshot-notice'
+    "
+  >
+    <CircleAlertIcon aria-hidden="true" />
+    <AlertTitle>{{ title }}</AlertTitle>
+    <AlertDescription class="space-y-3">
+      <p>{{ description }}</p>
+      <p v-if="fingerprint" class="font-mono text-[11px]">
+        快照：{{ fingerprint }}
+      </p>
+      <div class="flex flex-wrap gap-2">
+        <Button
+          v-if="blocking"
+          size="sm"
+          :disabled="loading"
+          @click="emit('retry')"
+        >
+          <LoaderCircleIcon v-if="loading" class="animate-spin" />
+          <RefreshCwIcon v-else />
+          {{ loading ? "正在检查…" : "重新检查" }}
+        </Button>
+        <Button
+          v-if="
+            reason === 'route-revoked' || reason === 'admin-access-revoked'
+          "
+          size="sm"
+          variant="outline"
+          @click="emit('returnHome')"
+        >
+          返回首页
+        </Button>
+        <Button
+          v-if="!blocking"
+          size="sm"
+          variant="outline"
+          @click="emit('reload')"
+        >
+          <RotateCwIcon />
+          安全刷新
+        </Button>
+        <Button
+          v-if="!blocking"
+          size="sm"
+          variant="ghost"
+          @click="emit('acknowledge')"
+        >
+          知道了
+        </Button>
+      </div>
+    </AlertDescription>
+  </Alert>
+</template>

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

@@ -52,6 +52,10 @@ function handleInteractOutside(event: { preventDefault(): void }) {
   if (props.preventOutsideClose) event.preventDefault();
 }
 
+function handleEscape(event: { preventDefault(): void }) {
+  if (props.preventOutsideClose) event.preventDefault();
+}
+
 async function handleOpenChange(value: boolean) {
   if (value) {
     open.value = true;
@@ -69,6 +73,8 @@ async function canClose() {
   <Dialog :open="open" @update:open="handleOpenChange">
     <DialogContent
       :class="contentClass"
+      :show-close-button="!preventOutsideClose"
+      @escape-key-down="handleEscape"
       @interact-outside="handleInteractOutside"
     >
       <DialogHeader>

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

@@ -52,6 +52,19 @@ describe("Modal 布局", () => {
     expect(preventDefault).toHaveBeenCalledTimes(1);
   });
 
+  test("禁止非显式取消时同时阻止 Escape 并隐藏关闭按钮", async () => {
+    const wrapper = mount(FormDialog, {
+      props: { open: true, preventOutsideClose: true },
+    });
+    const preventDefault = vi.fn();
+    const content = wrapper.getComponent(DialogContent);
+
+    content.vm.$emit("escapeKeyDown", { preventDefault });
+
+    expect(preventDefault).toHaveBeenCalledTimes(1);
+    expect(content.props("showCloseButton")).toBe(false);
+  });
+
   test("关闭前置检查拒绝时保持打开，通过后才通知父组件关闭", async () => {
     const beforeClose = vi
       .fn<() => boolean | Promise<boolean>>()

package/template/apps/web/src/composables/access-snapshot-change.ts

@@ -0,0 +1,131 @@
+import type { MenuNode } from "@southwind-ai/shared";
+import type { WebAccessSnapshot } from "@/layout/navigation";
+
+export type AccessSnapshotChangeKind = "reduced" | "expanded" | "changed";
+
+export interface AccessSnapshotChange {
+  readonly kind: AccessSnapshotChangeKind;
+  readonly previousFingerprint: string;
+  readonly currentFingerprint: string;
+  readonly removedCapabilities: readonly string[];
+  readonly addedCapabilities: readonly string[];
+}
+
+interface AccessSnapshotIdentity {
+  readonly signature: string;
+  readonly fingerprint: string;
+  readonly capabilities: ReadonlySet<string>;
+}
+
+export function accessSnapshotIdentity(
+  snapshot: WebAccessSnapshot,
+): AccessSnapshotIdentity {
+  const capabilities = collectCapabilities(snapshot);
+  const signature = JSON.stringify({
+    actor: {
+      id: snapshot.actor.id,
+      type: snapshot.actor.type,
+      roles: sorted(snapshot.actor.roleCodes),
+      permissions: sorted(snapshot.actor.permissionKeys),
+    },
+    features: [...snapshot.features]
+      .map(({ key, enabled, visible, allowed, reason }) => ({
+        key,
+        enabled,
+        visible,
+        allowed,
+        reason,
+      }))
+      .sort(byKey),
+    menus: normalizeMenus(snapshot.menus),
+  });
+  return {
+    signature,
+    fingerprint: `access-v1-${fnv1a(signature)}`,
+    capabilities,
+  };
+}
+
+export function describeAccessSnapshotChange(
+  previous: AccessSnapshotIdentity,
+  current: AccessSnapshotIdentity,
+): AccessSnapshotChange | undefined {
+  if (previous.signature === current.signature) return undefined;
+  const removedCapabilities = difference(
+    previous.capabilities,
+    current.capabilities,
+  );
+  const addedCapabilities = difference(
+    current.capabilities,
+    previous.capabilities,
+  );
+  return {
+    kind: removedCapabilities.length
+      ? "reduced"
+      : addedCapabilities.length
+        ? "expanded"
+        : "changed",
+    previousFingerprint: previous.fingerprint,
+    currentFingerprint: current.fingerprint,
+    removedCapabilities,
+    addedCapabilities,
+  };
+}
+
+function collectCapabilities(snapshot: WebAccessSnapshot): ReadonlySet<string> {
+  const capabilities = new Set(
+    snapshot.actor.permissionKeys.map((key) => `permission:${key}`),
+  );
+  for (const feature of snapshot.features) {
+    if (feature.allowed) capabilities.add(`feature:${feature.key}`);
+  }
+  collectMenuCapabilities(snapshot.menus, capabilities);
+  return capabilities;
+}
+
+function collectMenuCapabilities(
+  menus: readonly MenuNode[],
+  capabilities: Set<string>,
+): void {
+  for (const menu of menus) {
+    if (menu.visible) capabilities.add(`menu:${menu.key}`);
+    collectMenuCapabilities(menu.children || [], capabilities);
+  }
+}
+
+function normalizeMenus(menus: readonly MenuNode[]): object[] {
+  return [...menus]
+    .map((menu) => ({
+      key: menu.key,
+      path: menu.path || "",
+      visible: menu.visible,
+      permissionKey: menu.permissionKey || "",
+      featureKey: menu.featureKey || "",
+      children: normalizeMenus(menu.children || []),
+    }))
+    .sort(byKey);
+}
+
+function difference(
+  left: ReadonlySet<string>,
+  right: ReadonlySet<string>,
+): string[] {
+  return [...left].filter((item) => !right.has(item)).sort();
+}
+
+function sorted(values: readonly string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+function byKey(left: { key: string }, right: { key: string }): number {
+  return left.key.localeCompare(right.key);
+}
+
+function fnv1a(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}

package/template/apps/web/src/composables/access-snapshot-change.webtest.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "vitest";
+import type { WebAccessSnapshot } from "@/layout/navigation";
+import {
+  accessSnapshotIdentity,
+  describeAccessSnapshotChange,
+} from "./access-snapshot-change";
+
+describe("权限快照变化", () => {
+  test("不同返回顺序生成相同稳定指纹", () => {
+    const first = snapshot();
+    const second = snapshot();
+    second.actor.permissionKeys.reverse();
+    second.actor.roleCodes.reverse();
+    second.features.reverse();
+    second.menus.reverse();
+
+    expect(accessSnapshotIdentity(first).fingerprint).toBe(
+      accessSnapshotIdentity(second).fingerprint,
+    );
+  });
+
+  test("权限或已授权 Feature 被移除时归类为收紧", () => {
+    const previous = accessSnapshotIdentity(snapshot());
+    const currentSnapshot = snapshot();
+    currentSnapshot.actor.permissionKeys =
+      currentSnapshot.actor.permissionKeys.filter(
+        (key) => key !== "system.user.manage",
+      );
+    currentSnapshot.features[0]!.allowed = false;
+    const change = describeAccessSnapshotChange(
+      previous,
+      accessSnapshotIdentity(currentSnapshot),
+    );
+
+    expect(change?.kind).toBe("reduced");
+    expect(change?.removedCapabilities).toEqual([
+      "feature:system.user",
+      "permission:system.user.manage",
+    ]);
+  });
+
+  test("只有新增能力时归类为扩展", () => {
+    const previousSnapshot = snapshot();
+    previousSnapshot.actor.permissionKeys = ["system.user.read"];
+    const currentSnapshot = snapshot();
+    const change = describeAccessSnapshotChange(
+      accessSnapshotIdentity(previousSnapshot),
+      accessSnapshotIdentity(currentSnapshot),
+    );
+
+    expect(change?.kind).toBe("expanded");
+    expect(change?.addedCapabilities).toContain(
+      "permission:system.user.manage",
+    );
+  });
+});
+
+function snapshot(): WebAccessSnapshot {
+  return {
+    actor: {
+      id: "user_1",
+      type: "user",
+      name: "平台管理员",
+      roleCodes: ["operator", "admin"],
+      permissionKeys: ["system.user.read", "system.user.manage"],
+    },
+    menus: [
+      {
+        key: "system.role",
+        title: "角色",
+        type: "menu",
+        order: 2,
+        visible: true,
+        path: "/admin/system/roles",
+      },
+      {
+        key: "system.user",
+        title: "用户",
+        type: "menu",
+        order: 1,
+        visible: true,
+        path: "/admin/system/users",
+      },
+    ],
+    permissions: [],
+    features: [
+      {
+        key: "system.user",
+        enabled: true,
+        visible: "visible",
+        allowed: true,
+        reason: "allowed",
+      },
+      {
+        key: "system.role",
+        enabled: true,
+        visible: "visible",
+        allowed: true,
+        reason: "allowed",
+      },
+    ],
+  };
+}