create-windy 0.3.2 → 0.3.5

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);
+  }
+}

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

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "vitest";
+import {
+  assertNoRouteCollisions,
+  materializeBusinessAdminRoutes,
+} from "./business-routes";
+
+describe("project-owned 业务路由接缝", () => {
+  test("统一生成带 Feature 与 RBAC Guard 的管理路由", () => {
+    const [route] = materializeBusinessAdminRoutes([
+      {
+        key: "case.record",
+        path: "/cases",
+        name: "case-records",
+        title: "案件",
+        component: {},
+        featureKey: "case.record",
+        permissionKey: "case.record.read",
+      },
+    ]);
+
+    expect(route).toMatchObject({
+      path: "/cases",
+      name: "case-records",
+      meta: {
+        title: "案件",
+        layout: "admin",
+        businessRouteKey: "case.record",
+        featureKey: "case.record",
+        permissionKey: "case.record.read",
+      },
+    });
+  });
+
+  test("拒绝空 Guard、重复 Key 与兜底路径", () => {
+    expect(() =>
+      materializeBusinessAdminRoutes([
+        {
+          key: "case.record",
+          path: "/cases",
+          title: "案件",
+          component: {},
+          featureKey: "",
+          permissionKey: "case.record.read",
+        },
+      ]),
+    ).toThrow("featureKey 不能为空");
+    expect(() =>
+      materializeBusinessAdminRoutes([
+        registration("/cases"),
+        registration("/other"),
+      ]),
+    ).toThrow("业务 Web Route Key 重复");
+    expect(() =>
+      materializeBusinessAdminRoutes([
+        registration("/:pathMatch(.*)*"),
+      ]),
+    ).toThrow("不能注册兜底路径");
+  });
+
+  test("组合时拒绝与平台路由重复的路径或名称", () => {
+    expect(() =>
+      assertNoRouteCollisions([
+        { path: "/admin", name: "admin-home", component: {} },
+        { path: "/admin", name: "business-home", component: {} },
+      ]),
+    ).toThrow("Web Route 路径重复：/admin");
+    expect(() =>
+      assertNoRouteCollisions([
+        { path: "/admin", name: "admin-home", component: {} },
+        { path: "/cases", name: "admin-home", component: {} },
+      ]),
+    ).toThrow("Web Route 名称重复：admin-home");
+  });
+});
+
+function registration(path: string) {
+  return {
+    key: "case.record",
+    path,
+    title: "案件",
+    component: {},
+    featureKey: "case.record",
+    permissionKey: "case.record.read",
+  };
+}

package/template/apps/web/src/router/index.ts

@@ -6,6 +6,7 @@ import {
 } from "vue-router";
 import DashboardPage from "@/pages/dashboard/DashboardPage.vue";
 import HomePage from "@/app/home/HomePage.vue";
+import { installedBusinessAdminRoutes } from "@/app/business-routes";
 import { loginPageComponent } from "@/app/auth/login-page";
 import { errorPageComponents } from "@/app/error-pages";
 import AccessDeniedPage from "@/pages/AccessDeniedPage.vue";
@@ -41,6 +42,10 @@ import { evaluateWebAccess, type WebAccessSnapshot } from "@/layout/navigation";
 import { isApiErrorStatus } from "@/services/http";
 import { loginRoute, safeReturnTo } from "./auth-navigation";
 import { safeErrorReturnTo } from "./error-navigation";
+import {
+  assertNoRouteCollisions,
+  materializeBusinessAdminRoutes,
+} from "./business-routes";
 import {
   manifestAdminRoute,
   validateWebModuleComposition,
@@ -195,6 +200,7 @@ export const routes: RouteRecordRaw[] = [
     component: ModuleConfigurationPage,
   }),
   // @windy-module system.configuration end
+  ...materializeBusinessAdminRoutes(installedBusinessAdminRoutes),
   {
     path: "/:pathMatch(.*)*",
     name: "not-found",
@@ -212,6 +218,7 @@ export const routes: RouteRecordRaw[] = [
   },
 ];
 
+assertNoRouteCollisions(routes);
 validateWebModuleComposition(routes);
 
 export function createAppRouter(

package/template/apps/web/src/router/shared-scaffold-neutrality.webtest.ts

@@ -25,6 +25,18 @@ describe("Router shared-scaffold 中性契约", () => {
     expect(routerSource).toContain("component: errorPageComponents.network");
   });
 
+  test("平台路由组合 project-owned 业务注册表且保持在兜底页之前", () => {
+    expect(routerSource).toContain(
+      'import { installedBusinessAdminRoutes } from "@/app/business-routes";',
+    );
+    const businessIndex = routerSource.indexOf(
+      "...materializeBusinessAdminRoutes(installedBusinessAdminRoutes)",
+    );
+    const fallbackIndex = routerSource.indexOf('path: "/:pathMatch(.*)*"');
+    expect(businessIndex).toBeGreaterThan(0);
+    expect(businessIndex).toBeLessThan(fallbackIndex);
+  });
+
   test("测试快照只从项目注入路由递归派生访问键", () => {
     expect(collectRouteAccess([])).toEqual({
       permissionKeys: [],

package/template/apps/web/src/services/access-api.ts

@@ -23,7 +23,11 @@ interface FoundationResponse {
 }
 
 export async function loadAccessSnapshot(): Promise<WebAccessSnapshot> {
-  const foundation = await apiRequest<FoundationResponse>("/admin/bootstrap");
+  const foundation = await apiRequest<FoundationResponse>(
+    "/admin/bootstrap",
+    {},
+    { suppressFailureHandler: true },
+  );
   return {
     actor: foundation.access.actor,
     menus: foundation.menus,

package/template/apps/web/src/services/access-api.webtest.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({ apiRequest: vi.fn() }));
+vi.mock("./http", () => mocks);
+
+import { loadAccessSnapshot } from "./access-api";
+
+describe("权限快照 API", () => {
+  test("由调用方处理刷新失败，避免全局错误页卸载编辑实例", async () => {
+    mocks.apiRequest.mockResolvedValue({
+      menus: [],
+      permissions: [],
+      auditActionCatalog: [],
+      licenseCatalog: [],
+      access: {
+        actor: {
+          id: "user_1",
+          type: "user",
+          name: "测试员",
+          roleCodes: [],
+          permissionKeys: [],
+        },
+        features: [],
+      },
+    });
+
+    await loadAccessSnapshot();
+
+    expect(mocks.apiRequest).toHaveBeenCalledWith(
+      "/admin/bootstrap",
+      {},
+      { suppressFailureHandler: true },
+    );
+  });
+});