create-windy 0.1.0

package/template/apps/server/src/system/route-helpers.ts

@@ -0,0 +1,104 @@
+import { randomUUIDv7 } from "bun";
+import type { AuditEvent, LifecycleStatus } from "@windy/shared";
+import type { RequestGuardContext } from "../guards.js";
+import type { ManagedEntity } from "./entities.js";
+import { parsePagination } from "../pagination.js";
+
+export type RouteContext = {
+  body?: unknown;
+  guardContext: RequestGuardContext;
+  params: Record<string, string | undefined>;
+  query: Record<string, string | undefined>;
+};
+
+export function parseListQuery(query: RouteContext["query"]) {
+  const pagination = parsePagination(query);
+  if (pagination instanceof Response) return pagination;
+  return {
+    ...pagination,
+    q: query.q,
+    status: query.status as LifecycleStatus | undefined,
+    includeDeleted: query.includeDeleted === "true",
+    sort: query.sort
+      ? query.sort.split(",").map((field) => ({
+          field: field.startsWith("-") ? field.slice(1) : field,
+          order: field.startsWith("-") ? ("desc" as const) : ("asc" as const),
+        }))
+      : undefined,
+  };
+}
+
+export function toPositiveInt(
+  value: string | undefined,
+  fallback: number,
+): number {
+  const parsed = value ? Number.parseInt(value, 10) : fallback;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export function asPartial<T>(body: unknown): Partial<T> {
+  return body && typeof body === "object" ? (body as Partial<T>) : {};
+}
+
+export function parseImportPayload<T extends ManagedEntity>(body: unknown) {
+  const payload =
+    body && typeof body === "object"
+      ? (body as { items?: Array<Partial<T>>; mode?: string })
+      : {};
+  const items = Array.isArray(body)
+    ? (body as Array<Partial<T>>)
+    : payload.items;
+  return {
+    items: items?.filter((item) => item && typeof item === "object") || [],
+    mode: payload.mode === "upsert" ? ("upsert" as const) : ("create" as const),
+  };
+}
+
+export function routeContext(context: unknown): RouteContext {
+  return context as RouteContext;
+}
+
+export function requiredId(params: RouteContext["params"]): string {
+  const id = params.id;
+  if (!id) {
+    throw new Error("缺少资源 ID");
+  }
+  return id;
+}
+
+export function forbidden(reason: string) {
+  return Response.json({ error: "FORBIDDEN", reason }, { status: 403 });
+}
+
+export function notFound(resourceName: string, id: string) {
+  return Response.json(
+    { error: "NOT_FOUND", resource: resourceName, id },
+    { status: 404 },
+  );
+}
+
+export function resourceEvent(
+  context: RequestGuardContext,
+  action: AuditEvent["action"],
+  resourceName: string,
+  id?: string,
+  metadata?: Record<string, unknown>,
+): AuditEvent {
+  return {
+    id: randomUUIDv7(),
+    action,
+    outcome: "success",
+    actor: {
+      id: context.actor.id,
+      type: context.actor.type === "anonymous" ? "user" : context.actor.type,
+      name: context.actor.name,
+    },
+    target: {
+      type: resourceName,
+      id,
+    },
+    requestId: context.requestId,
+    metadata,
+    occurredAt: new Date().toISOString(),
+  };
+}

package/template/apps/server/src/system/route-test-app.ts

@@ -0,0 +1,27 @@
+import type { RouteApp } from "./routes.js";
+
+export class FakeRouteApp implements RouteApp {
+  readonly handlers = new Map<string, (context: unknown) => unknown>();
+
+  get(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(`GET ${path}`, handler);
+  }
+
+  post(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(`POST ${path}`, handler);
+  }
+
+  put(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(`PUT ${path}`, handler);
+  }
+
+  delete(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(`DELETE ${path}`, handler);
+  }
+
+  invoke(method: string, path: string, context: unknown): unknown {
+    const handler = this.handlers.get(`${method} ${path}`);
+    if (!handler) throw new Error(`未注册路由 ${method} ${path}`);
+    return handler(context);
+  }
+}

package/template/apps/server/src/system/route-types.ts

@@ -0,0 +1,52 @@
+import type { FeatureFlagDefinition } from "@windy/shared";
+import type { ManagedEntity } from "./entities.js";
+import type { EntityRepository, MaybePromise } from "./repository.js";
+import type { ScopedResourceAccess } from "../data-access/scoped-resource.js";
+import type { RequestActor } from "../guards.js";
+import type { MutationRunner } from "./mutation-runner.js";
+
+export interface RouteApp {
+  get(path: string, handler: (context: unknown) => unknown): unknown;
+  post(
+    path: string,
+    handler: (context: unknown) => unknown,
+    options?: { parse?: "none" },
+  ): unknown;
+  put(
+    path: string,
+    handler: (context: unknown) => unknown,
+    options?: { parse?: "none" },
+  ): unknown;
+  delete(path: string, handler: (context: unknown) => unknown): unknown;
+}
+
+export interface ResourceRouteConfig<T extends ManagedEntity> {
+  path: string;
+  permissionResource: string;
+  repository: EntityRepository<T>;
+  searchFields: Array<keyof T>;
+  feature?: FeatureFlagDefinition;
+  readonly?: boolean;
+  importable?: boolean;
+  backupExport?: boolean;
+  mutationRunner?: MutationRunner;
+  validateInput?: (
+    input: Partial<T>,
+    current?: T,
+  ) => MaybePromise<string | undefined>;
+  dataAccess:
+    | { readonly mode: "platform" }
+    | { readonly mode: "request"; readonly access: ScopedResourceAccess<T> };
+  projectResponse?: (entity: T) => Record<string, unknown>;
+  beforeUpdate?: (
+    current: T,
+    input: Partial<T>,
+  ) => MaybePromise<string | undefined>;
+  beforeDelete?: (current: T) => MaybePromise<string | undefined>;
+  afterUpdate?: (
+    current: T,
+    updated: T,
+    actor: RequestActor,
+  ) => MaybePromise<void>;
+  afterDelete?: (deleted: T, actor: RequestActor) => MaybePromise<void>;
+}

package/template/apps/server/src/system/routes-validation.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import { FakeRouteApp } from "./route-test-app.js";
+import { registerSystemRoutes } from "./routes.js";
+import { createSystemRepositories } from "./seed.js";
+
+describe("system route query validation", () => {
+  test("列表默认每页 10 条并透明拒绝超过 100 的页大小", async () => {
+    const fixture = await createFixture("/api/system/users");
+    const listed = (await fixture.app.invoke("GET", "/system/users", {
+      guardContext: fixture.guardContext,
+      params: {},
+      query: {},
+    })) as { page: number; pageSize: number };
+    expect(listed).toMatchObject({ page: 1, pageSize: 10 });
+
+    const response = (await fixture.app.invoke("GET", "/system/users", {
+      guardContext: fixture.guardContext,
+      params: {},
+      query: { pageSize: "101" },
+    })) as Response;
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toMatchObject({
+      error: "INVALID_PAGINATION",
+      maxPageSize: 100,
+    });
+  });
+
+  // @windy-module system.audit begin
+  test("审计日志拒绝非法时间筛选值", async () => {
+    const fixture = await createFixture("/api/system/audit-logs");
+    const response = (await fixture.app.invoke("GET", "/system/audit-logs", {
+      guardContext: fixture.guardContext,
+      params: {},
+      query: { occurredAfter: "昨天" },
+    })) as Response;
+
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toMatchObject({
+      error: "INVALID_AUDIT_TIME_RANGE",
+    });
+  });
+  // @windy-module system.audit end
+});
+
+async function createFixture(path: string) {
+  const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token_1" });
+  const app = new FakeRouteApp();
+  registerSystemRoutes(
+    app,
+    createSystemRepositories(createFoundationSnapshot()),
+    runtime,
+  );
+  const guardContext = await runtime.createGuardContext(
+    new Request(`http://localhost${path}`, {
+      headers: { authorization: "Bearer token_1" },
+    }),
+  );
+  return { app, guardContext };
+}

package/template/apps/server/src/system/routes.test.ts

@@ -0,0 +1,311 @@
+import { describe, expect, test } from "bun:test";
+import { entitlementKey, type FeatureFlagDefinition } from "@windy/shared";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime, type AuditEventWriter } from "../runtime.js";
+import { FakeRouteApp } from "./route-test-app.js";
+import { registerSystemRoutes } from "./routes.js";
+import { createSystemRepositories } from "./seed.js";
+
+async function routeFixture(
+  features: FeatureFlagDefinition[] = [],
+  auditWriter?: AuditEventWriter,
+) {
+  const runtime = createServerRuntime(
+    { WINDY_DEV_ADMIN_TOKEN: "token_1" },
+    { auditWriter },
+  );
+  const app = new FakeRouteApp();
+  registerSystemRoutes(
+    app,
+    createSystemRepositories(createFoundationSnapshot()),
+    runtime,
+    features,
+  );
+  const guardContext = await runtime.createGuardContext(
+    new Request("http://localhost/api/system/users", {
+      headers: { authorization: "Bearer token_1" },
+    }),
+  );
+  return { app, runtime, guardContext };
+}
+
+describe("system routes", () => {
+  test("注册基础模块 CRUD 路由并记录审计事件", async () => {
+    const { app, runtime, guardContext } = await routeFixture();
+
+    const created = (await app.invoke("POST", "/system/users", {
+      guardContext,
+      params: {},
+      query: {},
+      body: {
+        username: "tester",
+        displayName: "测试员",
+        roleIds: ["role_user"],
+        departmentId: "dept_platform",
+      },
+    })) as { id: string; username: string };
+    const listed = (await app.invoke("GET", "/system/users", {
+      guardContext,
+      params: {},
+      query: { q: "tester" },
+    })) as { total: number; pageSize: number; items: Array<{ id: string }> };
+    const deleted = (await app.invoke("DELETE", "/system/users/:id", {
+      guardContext,
+      params: { id: created.id },
+      query: {},
+    })) as { id: string; deletedAt?: string };
+
+    expect(created.username).toBe("tester");
+    expect(listed.total).toBe(1);
+    expect(deleted.deletedAt).toBeString();
+    expect(runtime.auditSink.list().map((event) => event.action)).toEqual([
+      "crud.create",
+      "data.search",
+      "crud.delete",
+    ]);
+    expect(runtime.auditSink.list()[1]?.metadata).toEqual({
+      queryDigest: new Bun.CryptoHasher("sha256")
+        .update("tester")
+        .digest("hex"),
+      queryLength: 6,
+      matched: 1,
+    });
+  });
+
+  test("缺少权限时返回 403 Response 并记录 security.denied", async () => {
+    const runtime = createServerRuntime();
+    const app = new FakeRouteApp();
+    registerSystemRoutes(
+      app,
+      createSystemRepositories(createFoundationSnapshot()),
+      runtime,
+    );
+    const guardContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/users"),
+    );
+
+    const response = (await app.invoke("GET", "/system/users", {
+      guardContext,
+      params: {},
+      query: {},
+    })) as Response;
+
+    expect(response.status).toBe(403);
+    await expect(response.json()).resolves.toMatchObject({
+      error: "FORBIDDEN",
+    });
+    expect(runtime.auditSink.list()[0]?.action).toBe("security.denied");
+  });
+
+  test("用户同步备份导出入口已移除，其他资源备份导出保留", async () => {
+    const { app } = await routeFixture();
+
+    expect(app.handlers.has("GET /system/users/export")).toBe(false);
+    expect(app.handlers.has("GET /system/roles/export")).toBe(true);
+    expect(app.handlers.has("GET /system/dictionaries/export")).toBe(true);
+  });
+
+  test("资源路由会执行 Entitlement 与 Feature Guard", async () => {
+    const snapshot = createFoundationSnapshot();
+    const hiddenRbac = snapshot.features.map((feature) =>
+      feature.key === "system.rbac"
+        ? { ...feature, visible: "hidden" as const }
+        : feature,
+    );
+    const { app, guardContext } = await routeFixture(hiddenRbac);
+
+    const hiddenResponse = (await app.invoke("GET", "/system/users", {
+      guardContext,
+      params: {},
+      query: {},
+    })) as Response;
+
+    expect(hiddenResponse.status).toBe(403);
+    await expect(hiddenResponse.json()).resolves.toMatchObject({
+      reason: "feature-disabled",
+    });
+
+    // @windy-module system.license begin
+    const commercialFeature = snapshot.features.map((feature) =>
+      feature.key === "system.license"
+        ? {
+            ...feature,
+            requiredEntitlement: entitlementKey("capability.license"),
+          }
+        : feature,
+    );
+    const licenseFixture = await routeFixture(commercialFeature);
+    const licenseResponse = (await licenseFixture.app.invoke(
+      "GET",
+      "/system/licenses",
+      {
+        guardContext: licenseFixture.guardContext,
+        params: {},
+        query: {},
+      },
+    )) as Response;
+
+    expect(licenseResponse.status).toBe(403);
+    await expect(licenseResponse.json()).resolves.toMatchObject({
+      reason: "entitlement-not-granted",
+    });
+    // @windy-module system.license end
+  });
+
+  test("导入和导出系统资源并记录审计事件", async () => {
+    const { app, runtime, guardContext } = await routeFixture();
+
+    const identityImport = (await app.invoke("POST", "/system/roles/import", {
+      guardContext,
+      params: {},
+      query: {},
+      body: { mode: "upsert", items: [] },
+    })) as Response;
+    expect(identityImport.status).toBe(405);
+
+    const imported = (await app.invoke("POST", "/system/dictionaries/import", {
+      guardContext,
+      params: {},
+      query: {},
+      body: {
+        mode: "upsert",
+        items: [
+          {
+            id: "dict-imported",
+            code: "audit_result",
+            name: "审计结果",
+            items: [],
+          },
+        ],
+      },
+    })) as { created: number; updated: number; total: number };
+    const exportedResponse = (await app.invoke(
+      "GET",
+      "/system/dictionaries/export",
+      {
+        guardContext,
+        params: {},
+        query: { q: "audit_result" },
+      },
+    )) as Response;
+    const exported = (await exportedResponse.json()) as {
+      total: number;
+      items: Array<{ id: string }>;
+    };
+
+    expect(imported).toMatchObject({ created: 1, updated: 0, total: 1 });
+    expect(exported.total).toBe(1);
+    expect(exported.items[0]?.id).toBe("dict-imported");
+    expect(runtime.auditSink.list().map((event) => event.action)).toEqual([
+      "data.import",
+      "data.export",
+    ]);
+  });
+
+  test("用户与角色变更使用关键策略，普通资源变更保持降级可用", async () => {
+    const policies: string[] = [];
+    const { app, guardContext } = await routeFixture([], {
+      write: async (_event, policy) => void policies.push(policy || "ordinary"),
+    });
+
+    await app.invoke("POST", "/system/roles", {
+      guardContext,
+      params: {},
+      query: {},
+      body: { code: "security", name: "安全角色" },
+    });
+    await app.invoke("POST", "/system/departments", {
+      guardContext,
+      params: {},
+      query: {},
+      body: { code: "dept-security", name: "安全部" },
+    });
+
+    expect(policies).toEqual(["critical", "ordinary"]);
+  });
+
+  test("关键资源审计失败会拒绝请求，普通资源仍完成并报告降级", async () => {
+    const { app, runtime, guardContext } = await routeFixture([], {
+      write: async () => {
+        throw new Error("audit persistence unavailable");
+      },
+    });
+
+    await expect(
+      app.invoke("POST", "/system/users", {
+        guardContext,
+        params: {},
+        query: {},
+        body: {
+          username: "security-user",
+          displayName: "安全用户",
+          roleIds: ["role_user"],
+          departmentId: "dept_platform",
+        },
+      }),
+    ).rejects.toThrow("audit persistence unavailable");
+
+    await expect(
+      app.invoke("POST", "/system/departments", {
+        guardContext,
+        params: {},
+        query: {},
+        body: { code: "dept-available", name: "可用部门" },
+      }),
+    ).resolves.toMatchObject({ code: "dept-available" });
+    await Bun.sleep(0);
+
+    expect(runtime.auditSink.status()).toMatchObject({
+      state: "degraded",
+      failedAttempts: 2,
+      dropped: 2,
+    });
+  });
+
+  test("Feature API 只允许修改状态并让下一请求读取新运行态", async () => {
+    const snapshot = createFoundationSnapshot();
+    const repositories = createSystemRepositories(snapshot);
+    await repositories.features.syncManifest(snapshot.features);
+    const runtime = createServerRuntime(
+      { WINDY_DEV_ADMIN_TOKEN: "token_1" },
+      { featureResolver: repositories.features },
+    );
+    const app = new FakeRouteApp();
+    registerSystemRoutes(app, repositories, runtime, snapshot.features);
+    const context = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/features/system.rbac", {
+        headers: { authorization: "Bearer token_1" },
+      }),
+    );
+
+    const disabled = (await app.invoke("PUT", "/system/features/:id", {
+      guardContext: context,
+      params: { id: "system.rbac" },
+      query: {},
+      body: { enabled: false, label: "不能篡改的名称", module: "unknown" },
+    })) as { enabled: boolean; label: string; module: string };
+    const nextContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/users", {
+        headers: { authorization: "Bearer token_1" },
+      }),
+    );
+    const denied = (await app.invoke("GET", "/system/users", {
+      guardContext: nextContext,
+      params: {},
+      query: {},
+    })) as Response;
+
+    expect(disabled).toMatchObject({
+      enabled: false,
+      label: "RBAC 权限链路",
+      module: "system.identity",
+    });
+    expect(denied.status).toBe(403);
+    await expect(denied.json()).resolves.toMatchObject({
+      reason: "feature-disabled",
+    });
+    expect(app.handlers.has("POST /system/features")).toBe(false);
+    expect(app.handlers.has("POST /system/features/import")).toBe(false);
+    expect(app.handlers.has("DELETE /system/features/:id")).toBe(false);
+  });
+});