create-windy 0.1.0

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

@@ -0,0 +1,396 @@
+import { describe, expect, test } from "vitest";
+import { createMemoryHistory } from "vue-router";
+import { systemFoundationModule } from "@windy/modules";
+import type { WebAccessSnapshot } from "@/layout/navigation";
+import type { PlatformLicenseSnapshot } from "@/services/license-api";
+import { ApiError } from "@/services/http";
+import { safeReturnTo } from "./auth-navigation";
+import { createAppRouter, routes } from "./index";
+
+describe("Manifest 菜单与 Router 契约", () => {
+  test("路由默认要求登录，只有显式 public 的页面允许匿名访问", () => {
+    const publicRoutes = routes.filter((route) => route.meta?.public === true);
+
+    expect(publicRoutes.map((route) => route.path)).toEqual(["/login"]);
+    expect(routes.find((route) => route.path === "/")?.meta?.public).not.toBe(
+      true,
+    );
+    expect(
+      routes.find((route) => route.path === "/admin")?.meta?.public,
+    ).not.toBe(true);
+  });
+
+  test("每个 Admin Route 都由真实页面实现且 Guard 来自 Manifest", () => {
+    const manifests = [systemFoundationModule()];
+    const definitions = manifests.flatMap((manifest) => manifest.adminRoutes);
+    const implementationByKey = new Map(
+      routes.flatMap((route) => {
+        const key = route.meta?.manifestRouteKey;
+        return typeof key === "string" ? [[key, route] as const] : [];
+      }),
+    );
+
+    expect([...implementationByKey.keys()].sort()).toEqual(
+      definitions.map(({ key }) => key).sort(),
+    );
+    for (const definition of definitions) {
+      const route = implementationByKey.get(definition.key);
+      expect(route?.path).toBe(definition.path);
+      expect(route?.meta?.title).toBe(definition.title);
+      if (definition.directAccess !== "authenticated") {
+        expect(route?.meta?.permissionKey).toBe(definition.permissionKey);
+        expect(route?.meta?.featureKey).toBe(definition.featureKey);
+      }
+    }
+    expect(definitions.some(({ path }) => path === "/admin/profile")).toBe(
+      true,
+    );
+    expect(definitions.some(({ path }) => path === "/work-orders")).toBe(false);
+    expect(routes.some(({ path }) => path === "/work-orders")).toBe(false);
+  });
+});
+
+describe("Web 路由强制访问", () => {
+  test("普通业务账号可进入首页且不会加载管理面或 License 快照", async () => {
+    let accessRefreshes = 0;
+    let licenseRefreshes = 0;
+    const router = createAppRouter(
+      createMemoryHistory(),
+      {
+        async refresh() {
+          accessRefreshes += 1;
+          throw new ApiError("admin access denied", 403);
+        },
+      },
+      {
+        async refresh() {
+          licenseRefreshes += 1;
+          return licenseSnapshot();
+        },
+      },
+      authProvider(),
+    );
+
+    await router.push("/");
+    await router.isReady();
+
+    expect(router.currentRoute.value.path).toBe("/");
+    expect(accessRefreshes).toBe(0);
+    expect(licenseRefreshes).toBe(0);
+  });
+
+  test("拥有管理面准入权限的管理员可进入管理后台", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      licenseProvider(),
+      authProvider(),
+    );
+
+    await router.push("/admin");
+    await router.isReady();
+
+    expect(router.currentRoute.value.path).toBe("/admin");
+  });
+
+  test("普通业务账号直访管理后台进入明确拒绝页", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      {
+        refresh: async () =>
+          Promise.reject(new ApiError("admin access denied", 403)),
+      },
+      licenseProvider(),
+      authProvider(),
+    );
+
+    await router.push("/admin");
+
+    expect(router.currentRoute.value.name).toBe("access-denied");
+    expect(router.currentRoute.value.query).toMatchObject({
+      reason: "admin-access-denied",
+      from: "/admin",
+    });
+  });
+
+  test("直接访问缺少权限的路由进入明确拒绝页", async () => {
+    const snapshot = accessSnapshot();
+    snapshot.actor.permissionKeys = [];
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(snapshot),
+      licenseProvider(),
+      authProvider(),
+    );
+
+    await router.push("/admin/system/features");
+    await router.isReady();
+
+    expect(router.currentRoute.value.name).toBe("access-denied");
+    expect(router.currentRoute.value.query).toMatchObject({
+      reason: "missing-permission",
+      from: "/admin/system/features",
+    });
+  });
+
+  test("Feature 关闭后拒绝直访，恢复后无需重建 Router", async () => {
+    const snapshot = accessSnapshot();
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(snapshot),
+      licenseProvider(),
+      authProvider(),
+    );
+    snapshot.features[0]!.allowed = false;
+    snapshot.features[0]!.enabled = false;
+
+    await router.push("/admin/system/audit");
+    expect(router.currentRoute.value.query.reason).toBe("feature-disabled");
+
+    snapshot.features[0]!.allowed = true;
+    snapshot.features[0]!.enabled = true;
+    await router.push("/admin/system/audit");
+
+    expect(router.currentRoute.value.path).toBe("/admin/system/audit");
+  });
+
+  test("RBAC Feature 关闭时仍可进入功能开关控制面恢复服务", async () => {
+    const snapshot = accessSnapshot();
+    snapshot.features[1]!.allowed = false;
+    snapshot.features[1]!.enabled = false;
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(snapshot),
+      licenseProvider(),
+      authProvider(),
+    );
+
+    await router.push("/admin/system/features");
+
+    expect(router.currentRoute.value.path).toBe("/admin/system/features");
+  });
+
+  test("个人设置路由同时受个人资料权限和 Feature 保护", async () => {
+    const snapshot = accessSnapshot();
+    snapshot.actor.permissionKeys.push("system.profile.read");
+    snapshot.features.push({
+      key: "system.profile",
+      enabled: true,
+      visible: "visible",
+      allowed: true,
+      reason: "allowed",
+    });
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(snapshot),
+      licenseProvider(),
+      authProvider(),
+    );
+
+    await router.push("/admin/profile");
+
+    expect(router.currentRoute.value.path).toBe("/admin/profile");
+  });
+
+  test("到期后任意业务页面都进入 License 更新页且不会重定向循环", async () => {
+    const snapshot = accessSnapshot();
+    let accessRefreshes = 0;
+    const router = createAppRouter(
+      createMemoryHistory(),
+      {
+        async refresh() {
+          accessRefreshes += 1;
+          return snapshot;
+        },
+      },
+      licenseProvider(true),
+      authProvider(),
+    );
+
+    await router.push("/admin/system/users");
+    await router.isReady();
+
+    expect(router.currentRoute.value.name).toBe("runtime-license");
+    expect(router.currentRoute.value.query).toMatchObject({
+      reason: "license-restricted",
+      from: "/admin/system/users",
+    });
+    expect(accessRefreshes).toBeGreaterThan(0);
+  });
+
+  test("管理面账号无需 License 管理权限也可查看状态页", async () => {
+    const snapshot = accessSnapshot();
+    snapshot.actor.permissionKeys = ["system.admin.access"];
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(snapshot),
+      licenseProvider(),
+      authProvider(),
+    );
+
+    await router.push("/admin/system/license");
+
+    expect(router.currentRoute.value.name).toBe("runtime-license");
+  });
+
+  test("未认证直访受保护页面会保存安全 returnTo 并进入登录页", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      licenseProvider(),
+      authProvider("anonymous"),
+    );
+
+    await router.push("/admin/system/users?page=2");
+
+    expect(router.currentRoute.value.name).toBe("login");
+    expect(router.currentRoute.value.query.returnTo).toBe(
+      "/admin/system/users?page=2",
+    );
+  });
+
+  test("已认证用户访问登录页只接受站内绝对 returnTo", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      licenseProvider(),
+      authProvider(),
+    );
+
+    await router.push({
+      name: "login",
+      query: { returnTo: "https://evil.test" },
+    });
+
+    expect(router.currentRoute.value.path).toBe("/");
+  });
+
+  test("管理员重置后的账号只能进入强制改密页且不会重定向循环", async () => {
+    const session = authProvider();
+    session.actor.credentialState = "must-change-password";
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      licenseProvider(),
+      session,
+    );
+
+    await router.push("/admin/system/users");
+    expect(router.currentRoute.value.name).toBe("change-password");
+
+    await router.push("/change-password");
+    expect(router.currentRoute.value.name).toBe("change-password");
+  });
+
+  test("会话服务异常不会被误判成未登录", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      licenseProvider(),
+      {
+        ensureInitialized: async () => Promise.reject(new Error("offline")),
+        clear() {},
+      },
+    );
+
+    await router.push("/admin/system/users");
+
+    expect(router.currentRoute.value.name).toBe("access-denied");
+    expect(router.currentRoute.value.query.reason).toBe("session-unavailable");
+  });
+
+  test("会话过期引发的 401 才会清退到登录页", async () => {
+    const router = createAppRouter(
+      createMemoryHistory(),
+      provider(accessSnapshot()),
+      { refresh: async () => Promise.reject(new ApiError("expired", 401)) },
+      authProvider(),
+    );
+
+    await router.push("/admin/system/license");
+
+    expect(router.currentRoute.value.name).toBe("login");
+    expect(router.currentRoute.value.query.returnTo).toBe(
+      "/admin/system/license",
+    );
+  });
+});
+
+describe("安全 returnTo", () => {
+  test("只接受应用内绝对路径并排除登录页自身", () => {
+    expect(safeReturnTo("/admin/system/users?tab=active#top")).toBe(
+      "/admin/system/users?tab=active#top",
+    );
+    expect(safeReturnTo("https://evil.test/admin/system/users")).toBe("/");
+    expect(safeReturnTo("//evil.test/admin/system/users")).toBe("/");
+    expect(safeReturnTo("/\\evil.test/admin/system/users")).toBe("/");
+    expect(safeReturnTo("/login?returnTo=/admin/system/users")).toBe("/");
+  });
+});
+
+function provider(snapshot: WebAccessSnapshot) {
+  return { refresh: async () => snapshot };
+}
+
+function licenseProvider(restricted = false) {
+  const snapshot = licenseSnapshot(restricted);
+  return { refresh: async () => snapshot };
+}
+
+function licenseSnapshot(restricted = false): PlatformLicenseSnapshot {
+  return {
+    status: restricted ? "expired" : "valid",
+    restricted,
+    reminder: { level: "none" },
+    canViewDetails: false,
+  };
+}
+
+function authProvider(phase: "authenticated" | "anonymous" = "authenticated") {
+  let currentPhase = phase;
+  const actor = accessSnapshot().actor;
+  return {
+    actor,
+    ensureInitialized: async () => ({
+      phase: currentPhase,
+      actor: currentPhase === "authenticated" ? actor : undefined,
+    }),
+    clear() {
+      currentPhase = "anonymous";
+    },
+  };
+}
+
+function accessSnapshot(): WebAccessSnapshot {
+  return {
+    actor: {
+      id: "user_1",
+      type: "user",
+      name: "审计员",
+      roleCodes: ["auditor"],
+      permissionKeys: [
+        "system.admin.access",
+        "system.audit.read",
+        "system.feature.read",
+      ],
+    },
+    menus: [],
+    permissions: [],
+    features: [
+      {
+        key: "system.audit",
+        enabled: true,
+        visible: "visible",
+        allowed: true,
+        reason: "allowed",
+      },
+      {
+        key: "system.rbac",
+        enabled: true,
+        visible: "visible",
+        allowed: true,
+        reason: "allowed",
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,59 @@
+import {
+  systemModuleManifests,
+  validateModuleComposition,
+  type ModuleAdminRouteDefinition,
+} from "@windy/modules";
+import type { Component } from "vue";
+import type { RouteRecordRaw } from "vue-router";
+
+export const webModuleManifests = systemModuleManifests();
+
+const adminRouteByKey = new Map(
+  webModuleManifests.flatMap((module) =>
+    module.adminRoutes.map((route) => [route.key, route] as const),
+  ),
+);
+
+export interface ManifestRouteImplementation {
+  component: Component;
+  name?: string;
+  props?: RouteRecordRaw["props"];
+}
+
+export function manifestAdminRoute(
+  key: string,
+  implementation: ManifestRouteImplementation,
+): RouteRecordRaw {
+  const definition = findAdminRoute(key);
+  const guarded = definition.directAccess !== "authenticated";
+  return {
+    path: definition.path,
+    name: implementation.name,
+    component: implementation.component,
+    props: implementation.props,
+    meta: {
+      title: definition.title,
+      layout: "admin",
+      manifestRouteKey: definition.key,
+      permissionKey: guarded ? definition.permissionKey : undefined,
+      featureKey: guarded ? definition.featureKey : undefined,
+    },
+  };
+}
+
+export function validateWebModuleComposition(
+  routes: readonly RouteRecordRaw[],
+): void {
+  validateModuleComposition(webModuleManifests, {
+    adminRoutes: routes.flatMap((route) => {
+      const key = route.meta?.manifestRouteKey;
+      return typeof key === "string" ? [key] : [];
+    }),
+  });
+}
+
+function findAdminRoute(key: string): ModuleAdminRouteDefinition {
+  const route = adminRouteByKey.get(key);
+  if (!route) throw new Error(`Admin Route 未声明：${key}`);
+  return route;
+}

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

@@ -0,0 +1,26 @@
+import type { MenuNode, PermissionDefinition } from "@windy/shared";
+import type {
+  WebAccessActor,
+  WebAccessSnapshot,
+  WebFeatureAccess,
+} from "@/layout/navigation";
+import { apiRequest } from "./http";
+
+interface FoundationResponse {
+  menus: MenuNode[];
+  permissions: PermissionDefinition[];
+  access: {
+    actor: WebAccessActor;
+    features: WebFeatureAccess[];
+  };
+}
+
+export async function loadAccessSnapshot(): Promise<WebAccessSnapshot> {
+  const foundation = await apiRequest<FoundationResponse>("/admin/bootstrap");
+  return {
+    actor: foundation.access.actor,
+    menus: foundation.menus,
+    features: foundation.access.features,
+    permissions: foundation.permissions,
+  };
+}

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

@@ -0,0 +1,72 @@
+import type { WebAccessActor } from "@/layout/navigation";
+import { apiRequest } from "./http";
+
+export interface LoginCredentials {
+  username: string;
+  password: string;
+}
+
+export interface PasswordChangeInput {
+  currentPassword: string;
+  newPassword: string;
+}
+
+interface LoginWireResponse {
+  expiresAt: string;
+  sessionId: string;
+  user: { id: string; username: string; displayName: string };
+}
+
+interface LoginResponse {
+  expiresAt: string;
+  sessionId: string;
+  user: LoginWireResponse["user"];
+}
+
+interface SessionResponse {
+  actor: WebAccessActor;
+}
+
+export async function loginWithPassword(
+  credentials: LoginCredentials,
+): Promise<LoginResponse> {
+  const response = await apiRequest<LoginWireResponse>(
+    "/auth/login",
+    { method: "POST", body: JSON.stringify(credentials) },
+    { omitDevelopmentAuth: true, suppressUnauthorizedHandler: true },
+  );
+  return {
+    expiresAt: response.expiresAt,
+    sessionId: response.sessionId,
+    user: response.user,
+  };
+}
+
+export async function loadCurrentSession(): Promise<WebAccessActor> {
+  const response = await apiRequest<SessionResponse>(
+    "/auth/session",
+    {},
+    { suppressUnauthorizedHandler: true },
+  );
+  return response.actor;
+}
+
+export function logoutCurrentSession(): Promise<{ success: true }> {
+  return apiRequest<{ success: true }>(
+    "/auth/logout",
+    { method: "POST" },
+    { suppressUnauthorizedHandler: true },
+  );
+}
+
+export function changeOwnPassword(input: PasswordChangeInput): Promise<{
+  success: true;
+  revokedSessions: number;
+  reauthenticationRequired: true;
+}> {
+  return apiRequest(
+    "/auth/password/change",
+    { method: "POST", body: JSON.stringify(input) },
+    { suppressUnauthorizedHandler: true },
+  );
+}

package/template/apps/web/src/services/bulk-data-api.ts

@@ -0,0 +1,105 @@
+import { apiRequest, apiResponse } from "./http";
+
+export const DICTIONARY_BULK_LIMITS = {
+  maxBytes: 10 * 1024 * 1024,
+  maxRows: 50_000,
+  maxLineBytes: 256 * 1024,
+} as const;
+
+export type BulkJobKind = "import" | "export";
+export type BulkJobStatus =
+  | "queued"
+  | "running"
+  | "retry-pending"
+  | "succeeded"
+  | "completed-with-errors"
+  | "failed";
+export type BulkArtifactKind = "result" | "failures";
+
+export interface BulkDataJob {
+  id: string;
+  kind: BulkJobKind;
+  resource: "dictionaries";
+  mode?: "create" | "upsert";
+  status: BulkJobStatus;
+  idempotencyKey: string;
+  requestedBy: string;
+  totalRows: number;
+  processedRows: number;
+  succeededRows: number;
+  failedRows: number;
+  attempt: number;
+  maxAttempts: number;
+  nextAttemptAt?: string;
+  error?: string;
+  createdAt: string;
+  startedAt?: string;
+  finishedAt?: string;
+  updatedAt: string;
+}
+
+export interface DictionaryImportRequest {
+  idempotencyKey: string;
+  mode: "create" | "upsert";
+  content: string;
+}
+
+export interface DownloadedBulkArtifact {
+  blob: Blob;
+  filename: string;
+}
+
+export function createDictionaryImport(input: DictionaryImportRequest) {
+  return apiRequest<BulkDataJob>("/system/bulk-data/dictionaries/import", {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+export function createDictionaryExport(idempotencyKey: string) {
+  return apiRequest<BulkDataJob>("/system/bulk-data/dictionaries/export", {
+    method: "POST",
+    body: JSON.stringify({ idempotencyKey }),
+  });
+}
+
+export function listDictionaryBulkJobs(limit = 50) {
+  const boundedLimit = Math.min(100, Math.max(1, Math.floor(limit)));
+  return apiRequest<BulkDataJob[]>(
+    `/system/bulk-data/jobs?limit=${boundedLimit}`,
+  );
+}
+
+export function getDictionaryBulkJob(id: string) {
+  return apiRequest<BulkDataJob>(
+    `/system/bulk-data/jobs/${encodeURIComponent(id)}`,
+  );
+}
+
+export async function downloadDictionaryBulkArtifact(
+  jobId: string,
+  kind: BulkArtifactKind,
+): Promise<DownloadedBulkArtifact> {
+  const response = await apiResponse(
+    `/system/bulk-data/jobs/${encodeURIComponent(jobId)}/artifacts/${kind}`,
+  );
+  return {
+    blob: await response.blob(),
+    filename:
+      contentDispositionFilename(response.headers.get("content-disposition")) ||
+      `dictionaries-${jobId}-${kind}.${kind === "failures" ? "ndjson" : "json"}`,
+  };
+}
+
+function contentDispositionFilename(value: string | null): string | undefined {
+  if (!value) return undefined;
+  const utf8 = value.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
+  const plain = value.match(/filename="?([^";]+)"?/i)?.[1];
+  const encoded = utf8 || plain;
+  if (!encoded) return undefined;
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return encoded;
+  }
+}

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

@@ -0,0 +1,43 @@
+import type {
+  ModuleConfigSummary,
+  ModuleConfigValues,
+  ModuleConfigVersion,
+} from "@windy/shared";
+import { apiRequest } from "./http";
+
+export function listModuleConfigurations(): Promise<ModuleConfigSummary[]> {
+  return apiRequest<ModuleConfigSummary[]>("/system/configurations");
+}
+
+export function listModuleConfigVersions(
+  moduleKey: string,
+): Promise<ModuleConfigVersion[]> {
+  return apiRequest<ModuleConfigVersion[]>(
+    `/system/configurations/${encodeURIComponent(moduleKey)}/versions`,
+  );
+}
+
+export function createModuleConfigVersion(
+  moduleKey: string,
+  values: ModuleConfigValues,
+  reason?: string,
+): Promise<ModuleConfigVersion> {
+  return apiRequest<ModuleConfigVersion>(
+    `/system/configurations/${encodeURIComponent(moduleKey)}/versions`,
+    {
+      method: "POST",
+      body: JSON.stringify({ values, reason }),
+    },
+  );
+}
+
+export function rollbackModuleConfigVersion(
+  moduleKey: string,
+  version: number,
+  reason: string,
+): Promise<ModuleConfigVersion> {
+  return apiRequest<ModuleConfigVersion>(
+    `/system/configurations/${encodeURIComponent(moduleKey)}/versions/${version}/rollback`,
+    { method: "POST", body: JSON.stringify({ reason }) },
+  );
+}