create-windy 0.2.34 → 0.3.1

package/template/apps/server/src/system/resource-routes.ts

@@ -0,0 +1,270 @@
+import { recordMutationAudit } from "../audit/policy.js";
+import { searchAuditEvent } from "../audit/search-summary.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { ManagedEntity } from "./entities.js";
+import {
+  asPartial,
+  notFound,
+  parseImportPayload,
+  parseListQuery,
+  requiredId,
+  resourceEvent,
+  routeContext,
+} from "./route-helpers.js";
+import type { ResourceRouteConfig, RouteApp } from "./route-types.js";
+import { withPermission } from "./resource-route-support.js";
+import {
+  accessCall,
+  importNotSupported,
+  readAccessible,
+  resourceConflict,
+} from "./resource-access-response.js";
+import { runResourceMutation } from "./mutation-runner.js";
+import { registerResourceExportRoute } from "./resource-export-route.js";
+import {
+  projectEntity,
+  projectEntities,
+  projectImportResult,
+} from "./response-projection.js";
+
+export function registerResourceRoutes<T extends ManagedEntity>(
+  app: RouteApp,
+  config: ResourceRouteConfig<T>,
+  runtime: ReturnType<typeof createServerRuntime>,
+) {
+  app.get(`/system/${config.path}`, (rawContext) => {
+    const { guardContext, query } = routeContext(rawContext);
+    return withPermission(
+      runtime,
+      guardContext,
+      "GET",
+      config.permissionResource,
+      "read",
+      config.feature,
+      async () => {
+        const listQuery = parseListQuery(query);
+        if (listQuery instanceof Response) return listQuery;
+        const result = await accessCall(() =>
+          config.dataAccess.mode === "request"
+            ? config.dataAccess.access.list(
+                listQuery,
+                config.searchFields,
+                guardContext.actor,
+              )
+            : config.repository.list(listQuery, config.searchFields),
+        );
+        if (result instanceof Response) return result;
+        const search = listQuery.q?.trim();
+        if (search) {
+          runtime.auditSink.recordEvent(
+            searchAuditEvent(guardContext, config.path, search, result.total),
+          );
+        }
+        return { ...result, items: projectEntities(config, result.items) };
+      },
+    );
+  });
+
+  if (config.backupExport !== false) {
+    registerResourceExportRoute(app, config, runtime);
+  }
+
+  app.get(`/system/${config.path}/:id`, (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    return withPermission(
+      runtime,
+      guardContext,
+      "GET",
+      config.permissionResource,
+      "read",
+      config.feature,
+      async () => {
+        const item = await readAccessible(
+          config,
+          requiredId(params),
+          guardContext.actor,
+        );
+        if (item instanceof Response) return item;
+        return item
+          ? projectEntity(config, item)
+          : notFound(config.path, requiredId(params));
+      },
+    );
+  });
+
+  if (config.readonly) {
+    return;
+  }
+
+  app.post(`/system/${config.path}/import`, (rawContext) => {
+    const { guardContext, body } = routeContext(rawContext);
+    return withPermission(
+      runtime,
+      guardContext,
+      "POST",
+      config.permissionResource,
+      "manage",
+      config.feature,
+      async () => {
+        if (config.importable === false) {
+          return importNotSupported();
+        }
+        const payload = parseImportPayload<T>(body);
+        const result = await accessCall(() =>
+          config.dataAccess.mode === "request"
+            ? config.dataAccess.access.importMany(
+                payload.items,
+                guardContext.actor,
+                payload.mode,
+              )
+            : config.repository.importMany(
+                payload.items,
+                guardContext.actor,
+                payload.mode,
+              ),
+        );
+        if (result instanceof Response) return result;
+        await recordMutationAudit(
+          runtime,
+          config.path,
+          resourceEvent(guardContext, "data.import", config.path, undefined, {
+            created: result.created,
+            updated: result.updated,
+            skipped: result.skipped,
+            total: payload.items.length,
+          }),
+        );
+        return {
+          ...projectImportResult(config, result),
+          total: payload.items.length,
+        };
+      },
+    );
+  });
+
+  app.post(`/system/${config.path}`, (rawContext) => {
+    const { guardContext, body } = routeContext(rawContext);
+    return withPermission(
+      runtime,
+      guardContext,
+      "POST",
+      config.permissionResource,
+      "manage",
+      config.feature,
+      async () =>
+        runResourceMutation(config, async () => {
+          const input = asPartial<T>(body);
+          const validationError = await config.validateInput?.(input);
+          if (validationError) return invalidResource(validationError);
+          const policyError = await config.beforeCreate?.(input);
+          if (policyError) return resourceConflict(policyError);
+          const item = await accessCall(() =>
+            config.dataAccess.mode === "request"
+              ? config.dataAccess.access.create(input, guardContext.actor)
+              : config.repository.create(input, guardContext.actor),
+          );
+          if (item instanceof Response) return item;
+          await recordMutationAudit(
+            runtime,
+            config.path,
+            resourceEvent(guardContext, "crud.create", config.path, item.id),
+          );
+          return projectEntity(config, item);
+        }),
+    );
+  });
+
+  app.put(`/system/${config.path}/:id`, (rawContext) => {
+    const { guardContext, params, body } = routeContext(rawContext);
+    return withPermission(
+      runtime,
+      guardContext,
+      "PUT",
+      config.permissionResource,
+      "manage",
+      config.feature,
+      async () =>
+        runResourceMutation(config, async () => {
+          const id = requiredId(params);
+          const input = asPartial<T>(body);
+          const current = await readAccessible(config, id, guardContext.actor);
+          if (current instanceof Response) return current;
+          if (!current) return notFound(config.path, id);
+          const validationError = await config.validateInput?.(input, current);
+          if (validationError) return invalidResource(validationError);
+          const policyError = await config.beforeUpdate?.(current, input);
+          if (policyError) return resourceConflict(policyError);
+          const item = await accessCall(() =>
+            config.dataAccess.mode === "request"
+              ? config.dataAccess.access.update(id, input, guardContext.actor)
+              : config.repository.update(id, input, guardContext.actor),
+          );
+          if (item instanceof Response) return item;
+          if (!item) {
+            return notFound(config.path, id);
+          }
+          await config.afterUpdate?.(current, item, guardContext.actor);
+          await recordMutationAudit(
+            runtime,
+            config.path,
+            resourceEvent(guardContext, "crud.update", config.path, id),
+          );
+          return projectEntity(config, item);
+        }),
+    );
+  });
+
+  app.delete(`/system/${config.path}/:id`, (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    return withPermission(
+      runtime,
+      guardContext,
+      "DELETE",
+      config.permissionResource,
+      "manage",
+      config.feature,
+      async () =>
+        runResourceMutation(config, async () => {
+          const id = requiredId(params);
+          const current = await readAccessible(config, id, guardContext.actor);
+          if (current instanceof Response) return current;
+          if (!current) return notFound(config.path, id);
+          const policyError = await config.beforeDelete?.(current);
+          if (policyError) return resourceConflict(policyError);
+          const item = await accessCall(() =>
+            config.dataAccess.mode === "request"
+              ? config.dataAccess.access.softDelete(id, guardContext.actor)
+              : config.repository.softDelete(id, guardContext.actor),
+          );
+          if (item instanceof Response) return item;
+          if (!item) {
+            return notFound(config.path, id);
+          }
+          await config.afterDelete?.(item, guardContext.actor);
+          await recordMutationAudit(
+            runtime,
+            config.path,
+            resourceEvent(guardContext, "crud.delete", config.path, id),
+          );
+          return projectEntity(config, item);
+        }),
+    );
+  });
+}
+
+function invalidResource(
+  error: NonNullable<
+    Awaited<
+      ReturnType<
+        NonNullable<ResourceRouteConfig<ManagedEntity>["validateInput"]>
+      >
+    >
+  >,
+): Response {
+  return Response.json(
+    typeof error === "string"
+      ? { error: "INVALID_RESOURCE", message: error }
+      : error,
+    { status: 400 },
+  );
+}

package/template/apps/server/src/system/role-department-scope-policy.ts

@@ -0,0 +1,55 @@
+import type { ManagedDepartment, ManagedRole } from "./entities.js";
+import type { EntityRepository } from "./repository.js";
+import type {
+  ResourcePolicyError,
+  ResourcePolicyResult,
+} from "./route-types.js";
+
+export class RoleDepartmentScopePolicy {
+  constructor(
+    private readonly departments: EntityRepository<ManagedDepartment>,
+  ) {}
+
+  async validate(
+    input: Partial<ManagedRole>,
+    current?: ManagedRole,
+  ): Promise<ResourcePolicyResult> {
+    const dataScope = input.dataScope ?? current?.dataScope;
+    const departmentIds = input.departmentIds ?? current?.departmentIds ?? [];
+    if (dataScope === "custom" && departmentIds.length === 0) {
+      return invalid(
+        "CUSTOM_DEPARTMENT_SCOPE_REQUIRED",
+        "自定义部门数据权限至少需要选择一个启用部门",
+      );
+    }
+    if (input.departmentIds === undefined && dataScope !== "custom") {
+      return undefined;
+    }
+    if (!Array.isArray(departmentIds) || departmentIds.some((id) => !id)) {
+      return invalid(
+        "INVALID_ROLE_DEPARTMENT_SCOPE",
+        "角色自定义部门范围必须是非空部门 ID 数组",
+      );
+    }
+    const departments = new Map(
+      (await this.departments.all()).map((item) => [item.id, item]),
+    );
+    const invalidIds = unique(departmentIds).filter(
+      (id) => departments.get(id)?.status !== "active",
+    );
+    return invalidIds.length
+      ? invalid(
+          "INVALID_ROLE_DEPARTMENT_SCOPE",
+          `角色数据权限引用了不存在或未启用的部门：${invalidIds.join(", ")}`,
+        )
+      : undefined;
+  }
+}
+
+function invalid(error: string, message: string): ResourcePolicyError {
+  return { error, message };
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}

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

@@ -1,6 +1,7 @@
 import { randomUUIDv7 } from "bun";
 import type { AuditEvent, LifecycleStatus } from "@southwind-ai/shared";
 import type { RequestGuardContext } from "../guards.js";
+import { auditActor } from "../guards.js";
 import type { ManagedEntity } from "./entities.js";
 import { parsePagination } from "../pagination.js";
 
@@ -88,11 +89,7 @@ export function resourceEvent(
     id: randomUUIDv7(),
     action,
     outcome: "success",
-    actor: {
-      id: context.actor.id,
-      type: context.actor.type === "anonymous" ? "user" : context.actor.type,
-      name: context.actor.name,
-    },
+    actor: auditActor(context),
     target: {
       type: resourceName,
       id,

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

@@ -5,6 +5,14 @@ import type { ScopedResourceAccess } from "../data-access/scoped-resource.js";
 import type { RequestActor } from "../guards.js";
 import type { MutationRunner } from "./mutation-runner.js";
 
+export interface ResourcePolicyError {
+  error: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export type ResourcePolicyResult = string | ResourcePolicyError | undefined;
+
 export interface RouteApp {
   get(path: string, handler: (context: unknown) => unknown): unknown;
   post(
@@ -33,16 +41,17 @@ export interface ResourceRouteConfig<T extends ManagedEntity> {
   validateInput?: (
     input: Partial<T>,
     current?: T,
-  ) => MaybePromise<string | undefined>;
+  ) => MaybePromise<ResourcePolicyResult>;
   dataAccess:
     | { readonly mode: "platform" }
     | { readonly mode: "request"; readonly access: ScopedResourceAccess<T> };
   projectResponse?: (entity: T) => Record<string, unknown>;
+  beforeCreate?: (input: Partial<T>) => MaybePromise<ResourcePolicyResult>;
   beforeUpdate?: (
     current: T,
     input: Partial<T>,
-  ) => MaybePromise<string | undefined>;
-  beforeDelete?: (current: T) => MaybePromise<string | undefined>;
+  ) => MaybePromise<ResourcePolicyResult>;
+  beforeDelete?: (current: T) => MaybePromise<ResourcePolicyResult>;
   afterUpdate?: (
     current: T,
     updated: T,

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

@@ -41,6 +41,32 @@ describe("system route query validation", () => {
       error: "INVALID_AUDIT_TIME_RANGE",
     });
   });
+
+  test("审计日志拒绝反向时间范围和过长关键字", async () => {
+    const fixture = await createFixture("/api/system/audit-logs");
+    const reversed = (await fixture.app.invoke("GET", "/system/audit-logs", {
+      guardContext: fixture.guardContext,
+      params: {},
+      query: {
+        occurredAfter: "2026-07-20T09:16:00.000Z",
+        occurredBefore: "2026-07-20T09:15:59.999Z",
+      },
+    })) as Response;
+    expect(reversed.status).toBe(400);
+    await expect(reversed.json()).resolves.toMatchObject({
+      error: "INVALID_AUDIT_TIME_RANGE",
+    });
+
+    const tooLong = (await fixture.app.invoke("GET", "/system/audit-logs", {
+      guardContext: fixture.guardContext,
+      params: {},
+      query: { q: "审".repeat(121) },
+    })) as Response;
+    expect(tooLong.status).toBe(400);
+    await expect(tooLong.json()).resolves.toMatchObject({
+      error: "INVALID_AUDIT_QUERY",
+    });
+  });
   // @windy-module system.audit end
 });
 

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

@@ -223,7 +223,11 @@ describe("system routes", () => {
       guardContext,
       params: {},
       query: {},
-      body: { code: "dept-security", name: "安全部" },
+      body: {
+        code: "dept-security",
+        name: "安全部",
+        parentId: "dept_platform",
+      },
     });
 
     expect(policies).toEqual(["critical", "ordinary"]);
@@ -255,7 +259,11 @@ describe("system routes", () => {
         guardContext,
         params: {},
         query: {},
-        body: { code: "dept-available", name: "可用部门" },
+        body: {
+          code: "dept-available",
+          name: "可用部门",
+          parentId: "dept_platform",
+        },
       }),
     ).resolves.toMatchObject({ code: "dept-available" });
     await Bun.sleep(0);