create-windy 0.3.4 → 0.3.6

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

package/template/apps/web/src/composables/useAccessSnapshot.ts

@@ -1,22 +1,35 @@
 import { readonly, shallowReadonly, shallowRef } from "vue";
 import type { WebAccessSnapshot } from "@/layout/navigation";
 import { loadAccessSnapshot } from "@/services/access-api";
+import { isApiErrorStatus } from "@/services/http";
+import {
+  accessSnapshotIdentity,
+  describeAccessSnapshotChange,
+  type AccessSnapshotChange,
+} from "./access-snapshot-change";
 
 const snapshot = shallowRef<WebAccessSnapshot>();
 const loading = shallowRef(false);
 const error = shallowRef("");
+const failureReason = shallowRef<
+  "admin-access-revoked" | "snapshot-unavailable" | undefined
+>();
+const fingerprint = shallowRef("");
+const version = shallowRef(0);
+const change = shallowRef<AccessSnapshotChange>();
 let pending: Promise<WebAccessSnapshot> | undefined;
 let generation = 0;
+let identity: ReturnType<typeof accessSnapshotIdentity> | undefined;
 
 async function load(force = false): Promise<WebAccessSnapshot> {
   if (pending) return pending;
   if (snapshot.value && !force) return snapshot.value;
   loading.value = true;
-  error.value = "";
+  if (!snapshot.value) error.value = "";
   const requestGeneration = generation;
   const operation = loadAccessSnapshot()
     .then((result) => {
-      if (requestGeneration === generation) snapshot.value = result;
+      if (requestGeneration === generation) acceptSnapshot(result);
       return result;
     })
     .catch((currentError: unknown) => {
@@ -25,6 +38,9 @@ async function load(force = false): Promise<WebAccessSnapshot> {
           currentError instanceof Error
             ? currentError.message
             : String(currentError);
+        failureReason.value = isApiErrorStatus(currentError, 403)
+          ? "admin-access-revoked"
+          : "snapshot-unavailable";
       }
       throw currentError;
     })
@@ -36,11 +52,34 @@ async function load(force = false): Promise<WebAccessSnapshot> {
   return operation;
 }
 
+function acceptSnapshot(result: WebAccessSnapshot): void {
+  const nextIdentity = accessSnapshotIdentity(result);
+  const nextChange = identity
+    ? describeAccessSnapshotChange(identity, nextIdentity)
+    : undefined;
+  snapshot.value = result;
+  error.value = "";
+  failureReason.value = undefined;
+  fingerprint.value = nextIdentity.fingerprint;
+  if (nextChange) {
+    version.value += 1;
+    change.value = nextChange;
+  } else if (!identity) {
+    version.value = 1;
+  }
+  identity = nextIdentity;
+}
+
 export function resetAccessSnapshot(): void {
   generation += 1;
   snapshot.value = undefined;
   loading.value = false;
   error.value = "";
+  failureReason.value = undefined;
+  fingerprint.value = "";
+  version.value = 0;
+  change.value = undefined;
+  identity = undefined;
   pending = undefined;
 }
 
@@ -49,7 +88,14 @@ export function useAccessSnapshot() {
     snapshot: shallowReadonly(snapshot),
     loading: readonly(loading),
     error: readonly(error),
+    failureReason: readonly(failureReason),
+    fingerprint: readonly(fingerprint),
+    version: readonly(version),
+    change: shallowReadonly(change),
     ensureLoaded: () => load(false),
     refresh: () => load(true),
+    acknowledgeChange: () => {
+      change.value = undefined;
+    },
   };
 }

package/template/apps/web/src/composables/useAccessSnapshot.webtest.ts

@@ -36,4 +36,58 @@ describe("权限快照 single-flight", () => {
     expect(first).toEqual(snapshot);
     expect(second).toEqual(snapshot);
   });
+
+  test("运行中快照变化保留版本、指纹和能力收紧事实", async () => {
+    const initial = accessSnapshot(["system.user.read"]);
+    const reduced = accessSnapshot([]);
+    mocks.loadAccessSnapshot
+      .mockResolvedValueOnce(initial)
+      .mockResolvedValueOnce(reduced);
+    const access = useAccessSnapshot();
+
+    await access.ensureLoaded();
+    const initialFingerprint = access.fingerprint.value;
+    await access.refresh();
+
+    expect(access.version.value).toBe(2);
+    expect(access.fingerprint.value).not.toBe(initialFingerprint);
+    expect(access.change.value).toMatchObject({
+      kind: "reduced",
+      previousFingerprint: initialFingerprint,
+      currentFingerprint: access.fingerprint.value,
+      removedCapabilities: ["permission:system.user.read"],
+    });
+
+    access.acknowledgeChange();
+    expect(access.change.value).toBeUndefined();
+  });
+
+  test("刷新失败时保留旧快照并进入显式安全降级状态", async () => {
+    const initial = accessSnapshot(["system.user.read"]);
+    mocks.loadAccessSnapshot
+      .mockResolvedValueOnce(initial)
+      .mockRejectedValueOnce(new Error("network unavailable"));
+    const access = useAccessSnapshot();
+    await access.ensureLoaded();
+
+    await expect(access.refresh()).rejects.toThrow("network unavailable");
+
+    expect(access.snapshot.value).toEqual(initial);
+    expect(access.error.value).toBe("network unavailable");
+  });
 });
+
+function accessSnapshot(permissionKeys: string[]) {
+  return {
+    actor: {
+      id: "user_1",
+      type: "user" as const,
+      name: "测试员",
+      roleCodes: ["member"],
+      permissionKeys,
+    },
+    menus: [],
+    permissions: [],
+    features: [],
+  };
+}

package/template/apps/web/src/composables/useAccessSnapshotMonitor.ts

@@ -0,0 +1,42 @@
+import { onBeforeUnmount, onMounted } from "vue";
+import { useAccessSnapshot } from "./useAccessSnapshot";
+
+const refreshIntervalMilliseconds = 60_000;
+const eventRefreshCooldownMilliseconds = 5_000;
+
+export function useAccessSnapshotMonitor(): void {
+  const access = useAccessSnapshot();
+  let interval: ReturnType<typeof setInterval> | undefined;
+  let lastEventRefresh = 0;
+
+  function refresh(): void {
+    void access.refresh().catch(() => {
+      // 失败状态由权限快照统一边界展示，事件处理器不产生未处理拒绝。
+    });
+  }
+
+  function refreshAfterBrowserEvent(): void {
+    const now = Date.now();
+    if (now - lastEventRefresh < eventRefreshCooldownMilliseconds) return;
+    lastEventRefresh = now;
+    refresh();
+  }
+
+  function refreshWhenVisible(): void {
+    if (document.visibilityState === "visible") refreshAfterBrowserEvent();
+  }
+
+  onMounted(() => {
+    interval = setInterval(refresh, refreshIntervalMilliseconds);
+    window.addEventListener("focus", refreshAfterBrowserEvent);
+    window.addEventListener("online", refreshAfterBrowserEvent);
+    document.addEventListener("visibilitychange", refreshWhenVisible);
+  });
+
+  onBeforeUnmount(() => {
+    if (interval) clearInterval(interval);
+    window.removeEventListener("focus", refreshAfterBrowserEvent);
+    window.removeEventListener("online", refreshAfterBrowserEvent);
+    document.removeEventListener("visibilitychange", refreshWhenVisible);
+  });
+}

package/template/apps/web/src/layout/AppShell.vue

@@ -3,6 +3,7 @@ import { Toaster } from "@/components/ui/sonner";
 import { SidebarInset, SidebarProvider } from "@/components/ui/sidebar";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import DevelopmentAuthWarning from "@/components/auth/DevelopmentAuthWarning.vue";
+import AccessSnapshotBoundary from "@/components/common/AccessSnapshotBoundary.vue";
 // @windy-module system.license begin
 import LicenseExpiryBanner from "@/components/license/LicenseExpiryBanner.vue";
 import { useLicenseReminderRefresh } from "@/composables/useLicenseReminderRefresh";
@@ -24,32 +25,34 @@ useLicenseReminderRefresh(licenseRuntime.refresh);
 
 <template>
   <TooltipProvider :delay-duration="0">
-    <SidebarProvider class="h-svh min-h-0 overflow-hidden">
-      <AppSidebar />
-      <SidebarInset class="h-svh min-w-0 overflow-hidden">
-        <AppHeader />
-        <div
-          data-testid="app-content-scroll"
-          class="min-h-0 flex-1 overflow-y-auto overscroll-contain"
-        >
-          <div v-if="developmentAuth.configured" class="px-6 pt-4">
-            <DevelopmentAuthWarning />
+    <AccessSnapshotBoundary>
+      <SidebarProvider class="h-svh min-h-0 overflow-hidden">
+        <AppSidebar />
+        <SidebarInset class="h-svh min-w-0 overflow-hidden">
+          <AppHeader />
+          <div
+            data-testid="app-content-scroll"
+            class="min-h-0 flex-1 overflow-y-auto overscroll-contain"
+          >
+            <div v-if="developmentAuth.configured" class="px-6 pt-4">
+              <DevelopmentAuthWarning />
+            </div>
+            <!-- @windy-module system.license begin -->
+            <LicenseExpiryBanner
+              v-if="licenseRuntime.snapshot.value"
+              :snapshot="licenseRuntime.snapshot.value"
+            />
+            <!-- @windy-module system.license end -->
+            <main class="p-6">
+              <slot />
+            </main>
           </div>
-          <!-- @windy-module system.license begin -->
-          <LicenseExpiryBanner
-            v-if="licenseRuntime.snapshot.value"
-            :snapshot="licenseRuntime.snapshot.value"
-          />
-          <!-- @windy-module system.license end -->
-          <main class="p-6">
-            <slot />
-          </main>
-        </div>
-      </SidebarInset>
-    </SidebarProvider>
-    <!-- @windy-module system.settings begin -->
-    <GlobalWatermark />
-    <!-- @windy-module system.settings end -->
+        </SidebarInset>
+      </SidebarProvider>
+      <!-- @windy-module system.settings begin -->
+      <GlobalWatermark />
+      <!-- @windy-module system.settings end -->
+    </AccessSnapshotBoundary>
     <Toaster />
   </TooltipProvider>
 </template>

package/template/apps/web/src/layout/AppShell.webtest.ts

@@ -35,6 +35,7 @@ describe("AppShell", () => {
         stubs: {
           AppHeader: { template: '<header data-testid="app-header" />' },
           AppSidebar: { template: '<aside data-testid="app-sidebar" />' },
+          AccessSnapshotBoundary: passthroughStub("access-snapshot-boundary"),
           DevelopmentAuthWarning: true,
           GlobalWatermark: true,
           // @windy-module system.license begin

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

@@ -0,0 +1,68 @@
+import type { RouteRecordRaw } from "vue-router";
+import type { BusinessAdminRouteRegistration } from "@/app/business-routes";
+
+export function materializeBusinessAdminRoutes(
+  registrations: readonly BusinessAdminRouteRegistration[],
+): RouteRecordRaw[] {
+  assertBusinessAdminRouteRegistrations(registrations);
+  return registrations.map((registration) => ({
+    path: registration.path,
+    name: registration.name,
+    component: registration.component,
+    props: registration.props,
+    meta: {
+      title: registration.title,
+      layout: "admin",
+      businessRouteKey: registration.key,
+      featureKey: registration.featureKey,
+      permissionKey: registration.permissionKey,
+    },
+  }));
+}
+
+export function assertNoRouteCollisions(
+  routes: readonly RouteRecordRaw[],
+): void {
+  const paths = new Set<string>();
+  const names = new Set<string>();
+  for (const route of routes) {
+    if (paths.has(route.path)) {
+      throw new Error(`Web Route 路径重复：${route.path}`);
+    }
+    paths.add(route.path);
+    if (typeof route.name !== "string") continue;
+    if (names.has(route.name)) {
+      throw new Error(`Web Route 名称重复：${route.name}`);
+    }
+    names.add(route.name);
+  }
+}
+
+function assertBusinessAdminRouteRegistrations(
+  registrations: readonly BusinessAdminRouteRegistration[],
+): void {
+  const keys = new Set<string>();
+  for (const registration of registrations) {
+    for (const [field, value] of [
+      ["key", registration.key],
+      ["path", registration.path],
+      ["title", registration.title],
+      ["featureKey", registration.featureKey],
+      ["permissionKey", registration.permissionKey],
+    ] as const) {
+      if (!value.trim()) {
+        throw new Error(`业务 Web Route 的 ${field} 不能为空`);
+      }
+    }
+    if (!registration.path.startsWith("/")) {
+      throw new Error(`业务 Web Route 必须使用绝对路径：${registration.path}`);
+    }
+    if (registration.path.includes(":pathMatch")) {
+      throw new Error(`业务 Web Route 不能注册兜底路径：${registration.path}`);
+    }
+    if (keys.has(registration.key)) {
+      throw new Error(`业务 Web Route Key 重复：${registration.key}`);
+    }
+    keys.add(registration.key);
+  }
+}