create-windy 0.2.34 → 0.3.0

package/template/apps/web/src/router/error-navigation.webtest.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test, vi } from "vitest";
+import { createMemoryHistory, createRouter } from "vue-router";
+import { createApiClient } from "@/services/http";
+import {
+  installApiFailureNavigation,
+  installUnexpectedErrorNavigation,
+  safeErrorReturnTo,
+} from "./error-navigation";
+
+function testRouter() {
+  return createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: "/", name: "home", component: {} },
+      { path: "/records", name: "records", component: {} },
+      { path: "/fallback", name: "fallback", component: {} },
+      {
+        path: "/error/internal",
+        name: "internal-error",
+        component: {},
+        meta: { errorPage: true },
+      },
+      {
+        path: "/error/maintenance",
+        name: "maintenance",
+        component: {},
+        meta: { errorPage: true },
+      },
+      {
+        path: "/error/network",
+        name: "network-error",
+        component: {},
+        meta: { errorPage: true },
+      },
+    ],
+  });
+}
+
+describe("统一错误导航", () => {
+  test("HTTP 失败类型映射到对应页面并保留 Request ID", async () => {
+    const router = testRouter();
+    await router.push("/records");
+
+    installApiFailureNavigation(router)({
+      kind: "maintenance",
+      requestId: "req-maintenance-1",
+    });
+    await vi.waitFor(() => {
+      expect(router.currentRoute.value.name).toBe("maintenance");
+    });
+
+    expect(router.currentRoute.value.query).toEqual({
+      from: "/records",
+      requestId: "req-maintenance-1",
+    });
+  });
+
+  test("页面运行异常进入 500，错误页内不再递归跳转", async () => {
+    const router = testRouter();
+    await router.push("/records");
+    const navigate = installUnexpectedErrorNavigation(router);
+
+    navigate("/records");
+    await vi.waitFor(() => {
+      expect(router.currentRoute.value.name).toBe("internal-error");
+    });
+
+    installApiFailureNavigation(router)({ kind: "network" });
+    await Promise.resolve();
+    expect(router.currentRoute.value.name).toBe("internal-error");
+  });
+
+  test("错误页地址和外部地址不会成为重试目标", () => {
+    expect(safeErrorReturnTo("/error/network")).toBe("/");
+    expect(safeErrorReturnTo("https://example.com")).toBe("/");
+    expect(safeErrorReturnTo("/records")).toBe("/records");
+  });
+
+  test("路由 Guard 内的服务失败最终进入全局维护页", async () => {
+    const router = testRouter();
+    const client = createApiClient({
+      apiBase: "/api",
+      fetcher: async () =>
+        Response.json(
+          { error: "MAINTENANCE" },
+          { status: 503, headers: { "x-request-id": "req-guard-1" } },
+        ),
+    });
+    client.setFailureHandler(installApiFailureNavigation(router));
+    router.beforeEach(async (to) => {
+      if (to.name !== "records") return true;
+      try {
+        await client.request("/guard");
+        return true;
+      } catch {
+        return { name: "fallback" };
+      }
+    });
+
+    await router.push("/records");
+
+    await vi.waitFor(() => {
+      expect(router.currentRoute.value.name).toBe("maintenance");
+    });
+  });
+});

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

@@ -7,6 +7,7 @@ import {
 import DashboardPage from "@/pages/dashboard/DashboardPage.vue";
 import HomePage from "@/app/home/HomePage.vue";
 import { loginPageComponent } from "@/app/auth/login-page";
+import { errorPageComponents } from "@/app/error-pages";
 import AccessDeniedPage from "@/pages/AccessDeniedPage.vue";
 import ServiceUnavailablePage from "@/pages/ServiceUnavailablePage.vue";
 import ChangePasswordPage from "@/pages/auth/ChangePasswordPage.vue";
@@ -39,6 +40,7 @@ import { useLicenseRuntime } from "@/composables/useLicenseRuntime";
 import { evaluateWebAccess, type WebAccessSnapshot } from "@/layout/navigation";
 import { isApiErrorStatus } from "@/services/http";
 import { loginRoute, safeReturnTo } from "./auth-navigation";
+import { safeErrorReturnTo } from "./error-navigation";
 import {
   manifestAdminRoute,
   validateWebModuleComposition,
@@ -117,6 +119,54 @@ export const routes: RouteRecordRaw[] = [
     }),
     meta: { title: "服务暂不可用", layout: "auth", public: true },
   },
+  {
+    path: "/error/internal",
+    name: "internal-error",
+    component: errorPageComponents.internal,
+    props: (route) => ({
+      kind: "internal",
+      from: safeErrorReturnTo(String(route.query.from || "/")),
+      requestId: requestIdFrom(route.query.requestId),
+    }),
+    meta: {
+      title: "页面运行异常",
+      layout: "auth",
+      public: true,
+      errorPage: true,
+    },
+  },
+  {
+    path: "/error/maintenance",
+    name: "maintenance",
+    component: errorPageComponents.maintenance,
+    props: (route) => ({
+      kind: "maintenance",
+      from: safeErrorReturnTo(String(route.query.from || "/")),
+      requestId: requestIdFrom(route.query.requestId),
+    }),
+    meta: {
+      title: "服务维护中",
+      layout: "auth",
+      public: true,
+      errorPage: true,
+    },
+  },
+  {
+    path: "/error/network",
+    name: "network-error",
+    component: errorPageComponents.network,
+    props: (route) => ({
+      kind: "network",
+      from: safeErrorReturnTo(String(route.query.from || "/")),
+      requestId: requestIdFrom(route.query.requestId),
+    }),
+    meta: {
+      title: "网络异常",
+      layout: "auth",
+      public: true,
+      errorPage: true,
+    },
+  },
   systemRoute("system.user", "users"),
   systemRoute("system.role", "roles"),
   systemRoute("system.department", "departments"),
@@ -145,6 +195,21 @@ export const routes: RouteRecordRaw[] = [
     component: ModuleConfigurationPage,
   }),
   // @windy-module system.configuration end
+  {
+    path: "/:pathMatch(.*)*",
+    name: "not-found",
+    component: errorPageComponents.notFound,
+    props: (route) => ({
+      kind: "not-found",
+      from: route.fullPath,
+    }),
+    meta: {
+      title: "页面不存在",
+      layout: "auth",
+      public: true,
+      errorPage: true,
+    },
+  },
 ];
 
 validateWebModuleComposition(routes);
@@ -257,4 +322,10 @@ function serviceUnavailableRoute(from: string, reason: string) {
   };
 }
 
+function requestIdFrom(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const requestId = value.trim();
+  return requestId && requestId.length <= 128 ? requestId : undefined;
+}
+
 export const router = createAppRouter();

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

@@ -13,6 +13,35 @@ import {
 } from "./router-test-fixtures";
 
 describe("Web 路由强制访问", () => {
+  test("未知地址无需权限快照即可进入统一 404", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      {
+        async refresh() {
+          throw new Error("404 不应读取权限快照");
+        },
+      },
+      // @windy-module system.license begin
+      {
+        async refresh() {
+          throw new Error("404 不应读取 License 快照");
+        },
+      },
+      // @windy-module system.license end
+      authProvider(),
+    );
+
+    await router.push("/unknown/business/page");
+    await router.isReady();
+
+    expect(router.currentRoute.value.name).toBe("not-found");
+    expect(router.currentRoute.value.params.pathMatch).toEqual([
+      "unknown",
+      "business",
+      "page",
+    ]);
+  });
+
   // @windy-module system.license begin
   test("普通业务账号可进入首页且不会加载管理面或 License 快照", async () => {
     let accessRefreshes = 0;

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

@@ -9,6 +9,10 @@ describe("Manifest 菜单与 Router 契约", () => {
     expect(publicRoutes.map((route) => route.path)).toEqual([
       "/login",
       "/service-unavailable",
+      "/error/internal",
+      "/error/maintenance",
+      "/error/network",
+      "/:pathMatch(.*)*",
     ]);
     expect(routes.find((route) => route.path === "/")?.meta?.public).not.toBe(
       true,

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

@@ -13,6 +13,18 @@ describe("Router shared-scaffold 中性契约", () => {
     expect(fixtureSource).toContain("collectRouteAccess");
   });
 
+  test("平台错误路由使用 project-owned 业务选择 seam", () => {
+    expect(routerSource).toContain(
+      'import { errorPageComponents } from "@/app/error-pages";',
+    );
+    expect(routerSource).toContain("component: errorPageComponents.notFound");
+    expect(routerSource).toContain("component: errorPageComponents.internal");
+    expect(routerSource).toContain(
+      "component: errorPageComponents.maintenance",
+    );
+    expect(routerSource).toContain("component: errorPageComponents.network");
+  });
+
   test("测试快照只从项目注入路由递归派生访问键", () => {
     expect(collectRouteAccess([])).toEqual({
       permissionKeys: [],

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

@@ -1,4 +1,5 @@
 import type { WebAccessActor } from "@/layout/navigation";
+import type { PasswordPolicy } from "@southwind-ai/shared";
 import { apiRequest } from "./http";
 
 export interface LoginCredentials {
@@ -70,3 +71,7 @@ export function changeOwnPassword(input: PasswordChangeInput): Promise<{
     { suppressUnauthorizedHandler: true },
   );
 }
+
+export function loadPasswordPolicy(): Promise<PasswordPolicy> {
+  return apiRequest<PasswordPolicy>("/auth/password/policy");
+}

package/template/apps/web/src/services/http.ts

@@ -8,6 +8,7 @@ export interface ApiPage<T> {
 export interface ApiRequestPolicy {
   omitDevelopmentAuth?: boolean;
   suppressUnauthorizedHandler?: boolean;
+  suppressFailureHandler?: boolean;
 }
 
 export interface DevelopmentAuthStatus {
@@ -21,12 +22,18 @@ export interface ApiClientOptions {
   developmentToken?: string;
 }
 
+export interface ApiFailure {
+  kind: "internal" | "maintenance" | "network";
+  requestId?: string;
+}
+
 export class ApiError extends Error {
   constructor(
     message: string,
     readonly status: number,
     readonly code?: string,
     readonly reason?: string,
+    readonly requestId?: string,
   ) {
     super(message);
     this.name = "ApiError";
@@ -38,6 +45,7 @@ export function createApiClient(options: ApiClientOptions) {
   const configuredToken = options.developmentToken?.trim() || undefined;
   let developmentAuthActive = Boolean(configuredToken);
   let unauthorizedHandler: (() => void) | undefined;
+  let failureHandler: ((failure: ApiFailure) => void) | undefined;
 
   async function response(
     path: string,
@@ -56,17 +64,31 @@ export function createApiClient(options: ApiClientOptions) {
     ) {
       headers.set("authorization", `Bearer ${configuredToken}`);
     }
-    const result = await fetcher(`${options.apiBase}${path}`, {
-      ...init,
-      credentials: init.credentials || "same-origin",
-      headers,
-    });
+    let result: Response;
+    try {
+      result = await fetcher(`${options.apiBase}${path}`, {
+        ...init,
+        credentials: init.credentials || "same-origin",
+        headers,
+      });
+    } catch (error) {
+      if (!policy.suppressFailureHandler && !isAbortError(error)) {
+        failureHandler?.({ kind: "network" });
+      }
+      throw error;
+    }
 
     if (!result.ok) {
       const error = await readApiError(result);
       if (result.status === 401 && !policy.suppressUnauthorizedHandler) {
         unauthorizedHandler?.();
       }
+      if (!policy.suppressFailureHandler && result.status >= 500) {
+        failureHandler?.({
+          kind: result.status === 503 ? "maintenance" : "internal",
+          requestId: error.requestId,
+        });
+      }
       throw error;
     }
     return result;
@@ -88,6 +110,9 @@ export function createApiClient(options: ApiClientOptions) {
     setUnauthorizedHandler(handler: (() => void) | undefined) {
       unauthorizedHandler = handler;
     },
+    setFailureHandler(handler: ((failure: ApiFailure) => void) | undefined) {
+      failureHandler = handler;
+    },
     developmentAuthStatus(): DevelopmentAuthStatus {
       return {
         configured: Boolean(configuredToken),
@@ -116,9 +141,16 @@ async function readApiError(response: Response): Promise<ApiError> {
       response.status,
       payload.error,
       payload.reason,
+      response.headers.get("x-request-id") || undefined,
     );
   } catch {
-    return new ApiError(response.statusText || "请求失败", response.status);
+    return new ApiError(
+      response.statusText || "请求失败",
+      response.status,
+      undefined,
+      undefined,
+      response.headers.get("x-request-id") || undefined,
+    );
   }
 }
 
@@ -137,9 +169,14 @@ const client = createApiClient({
 export const apiRequest = client.request;
 export const apiResponse = client.response;
 export const setUnauthorizedHandler = client.setUnauthorizedHandler;
+export const setApiFailureHandler = client.setFailureHandler;
 export const developmentAuthStatus = client.developmentAuthStatus;
 export const suspendDevelopmentAuth = client.suspendDevelopmentAuth;
 
 export function isApiErrorStatus(error: unknown, status: number): boolean {
   return error instanceof ApiError && error.status === status;
 }
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === "AbortError";
+}

package/template/apps/web/src/services/http.webtest.ts

@@ -70,4 +70,74 @@ describe("Web HTTP 会话策略", () => {
     });
     expect(unauthorized).toHaveBeenCalledTimes(1);
   });
+
+  test("5xx 映射统一错误类型并保留响应 Request ID", async () => {
+    const failures = vi.fn();
+    const fetcher = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(
+        Response.json(
+          { error: "INTERNAL_ERROR" },
+          {
+            status: 500,
+            headers: { "x-request-id": "req-internal-1" },
+          },
+        ),
+      )
+      .mockResolvedValueOnce(
+        Response.json(
+          { error: "MAINTENANCE" },
+          {
+            status: 503,
+            headers: { "x-request-id": "req-maintenance-1" },
+          },
+        ),
+      );
+    const client = createApiClient({ apiBase: "/api", fetcher });
+    client.setFailureHandler(failures);
+
+    await expect(client.request("/first")).rejects.toMatchObject({
+      status: 500,
+      requestId: "req-internal-1",
+    });
+    await expect(client.request("/second")).rejects.toMatchObject({
+      status: 503,
+      requestId: "req-maintenance-1",
+    });
+    expect(failures.mock.calls).toEqual([
+      [{ kind: "internal", requestId: "req-internal-1" }],
+      [{ kind: "maintenance", requestId: "req-maintenance-1" }],
+    ]);
+  });
+
+  test("传输失败进入网络异常，调用方可显式抑制全局错误页", async () => {
+    const failures = vi.fn();
+    const fetcher = vi.fn<typeof fetch>(async () => {
+      throw new TypeError("Failed to fetch");
+    });
+    const client = createApiClient({ apiBase: "/api", fetcher });
+    client.setFailureHandler(failures);
+
+    await expect(client.request("/first")).rejects.toThrow("Failed to fetch");
+    await expect(
+      client.request("/second", {}, { suppressFailureHandler: true }),
+    ).rejects.toThrow("Failed to fetch");
+
+    expect(failures).toHaveBeenCalledTimes(1);
+    expect(failures).toHaveBeenCalledWith({ kind: "network" });
+  });
+
+  test("调用方主动取消请求不会误跳网络异常页", async () => {
+    const failures = vi.fn();
+    const fetcher = vi.fn<typeof fetch>(async () => {
+      throw new DOMException("aborted", "AbortError");
+    });
+    const client = createApiClient({ apiBase: "/api", fetcher });
+    client.setFailureHandler(failures);
+
+    await expect(client.request("/cancelled")).rejects.toMatchObject({
+      name: "AbortError",
+    });
+    expect(failures).not.toHaveBeenCalled();
+  });
 });

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

@@ -1,16 +1,39 @@
 import type {
   MarkNotificationReadResult,
+  NotificationInboxFilters,
   NotificationInboxItem,
+  NotificationAudienceOptions,
+  NotificationDelivery,
+  NotificationPreference,
+  NotificationRevision,
   PageResult,
   PlatformNotification,
   PublishNotificationInput,
+  SetNotificationFavoriteResult,
+  UpdateNotificationInput,
+  UpdateNotificationPreferenceInput,
+  UpdateNotificationResult,
 } from "@southwind-ai/shared";
 import { DEFAULT_PAGE_SIZE } from "@southwind-ai/shared";
 import { apiRequest } from "./http";
 
-export function listNotifications(page = 1, pageSize = DEFAULT_PAGE_SIZE) {
+export function listNotifications(
+  page = 1,
+  pageSize = DEFAULT_PAGE_SIZE,
+  filters: NotificationInboxFilters = {},
+) {
+  const params = new URLSearchParams({
+    page: String(page),
+    pageSize: String(pageSize),
+  });
+  if (filters.q) params.set("q", filters.q);
+  if (filters.category) params.set("category", filters.category);
+  if (filters.read) params.set("read", filters.read);
+  if (filters.favorite !== undefined) {
+    params.set("favorite", String(filters.favorite));
+  }
   return apiRequest<PageResult<NotificationInboxItem>>(
-    `/notifications?page=${page}&pageSize=${pageSize}`,
+    `/notifications?${params.toString()}`,
   );
 }
 
@@ -21,6 +44,20 @@ export function markNotificationRead(id: string) {
   );
 }
 
+export function favoriteNotification(id: string) {
+  return apiRequest<SetNotificationFavoriteResult>(
+    `/notifications/${encodeURIComponent(id)}/favorite`,
+    { method: "PUT" },
+  );
+}
+
+export function unfavoriteNotification(id: string) {
+  return apiRequest<SetNotificationFavoriteResult>(
+    `/notifications/${encodeURIComponent(id)}/favorite`,
+    { method: "DELETE" },
+  );
+}
+
 export function listManagedNotifications(
   page = 1,
   pageSize = DEFAULT_PAGE_SIZE,
@@ -43,6 +80,52 @@ export function publishNotification(input: PublishNotificationInput) {
   });
 }
 
+export function getNotificationPreference() {
+  return apiRequest<NotificationPreference>("/notifications/preferences");
+}
+
+export function updateNotificationPreference(
+  input: UpdateNotificationPreferenceInput,
+) {
+  return apiRequest<NotificationPreference>("/notifications/preferences", {
+    method: "PUT",
+    body: JSON.stringify(input),
+  });
+}
+
+export function getNotificationAudienceOptions() {
+  return apiRequest<NotificationAudienceOptions>(
+    "/system/notifications/audience-options",
+  );
+}
+
+export function listNotificationDeliveries(id: string) {
+  return apiRequest<NotificationDelivery[]>(
+    `/system/notifications/${encodeURIComponent(id)}/deliveries`,
+  );
+}
+
+export function updateNotification(id: string, input: UpdateNotificationInput) {
+  return apiRequest<UpdateNotificationResult>(
+    `/system/notifications/${encodeURIComponent(id)}`,
+    { method: "PUT", body: JSON.stringify(input) },
+  );
+}
+
+export function listNotificationRevisions(
+  id: string,
+  page = 1,
+  pageSize = DEFAULT_PAGE_SIZE,
+) {
+  const params = new URLSearchParams({
+    page: String(page),
+    pageSize: String(pageSize),
+  });
+  return apiRequest<PageResult<NotificationRevision>>(
+    `/system/notifications/${encodeURIComponent(id)}/revisions?${params.toString()}`,
+  );
+}
+
 export function archiveNotification(id: string) {
   return apiRequest<PlatformNotification>(
     `/system/notifications/${encodeURIComponent(id)}`,