create-windy 0.1.0

package/template/apps/server/src/storage/routes.ts

@@ -0,0 +1,297 @@
+import type { FeatureFlagDefinition, HttpMethod } from "@windy/shared";
+import {
+  UploadError,
+  type FileService,
+  type UploadService,
+} from "@windy/storage";
+import { evaluateRouteGuards, findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { resourceEvent, routeContext } from "../system/route-helpers.js";
+import type { RouteApp } from "../system/route-types.js";
+import {
+  downloadResponse,
+  integer,
+  nonNegativeInteger,
+  object,
+  optionalDate,
+  optionalString,
+  publicImageResponse,
+  string,
+  uploadError,
+} from "./route-support.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export interface StorageRouteServices {
+  uploads: UploadService;
+  files: FileService;
+  isPublicBrandingFile?: (fileId: string) => Promise<boolean>;
+}
+
+export function registerStorageRoutes(
+  app: RouteApp,
+  services: StorageRouteServices,
+  runtime: ServerRuntime,
+  features: FeatureFlagDefinition[],
+) {
+  const feature = findFeature(features, "system.storage");
+  const settingsFeature = findFeature(features, "system.settings");
+
+  app.post("/system/storage/uploads", async (rawContext) => {
+    const { body, guardContext } = routeContext(rawContext);
+    return guarded(
+      runtime,
+      guardContext,
+      feature,
+      "POST",
+      "system.storage.create",
+      async () => {
+        try {
+          const payload = object(body);
+          const session = await services.uploads.create({
+            ownerId: guardContext.actor.id,
+            purpose: string(payload.purpose),
+            filename: string(payload.filename),
+            mimeType: string(payload.mimeType),
+            expectedByteSize: integer(payload.expectedByteSize),
+            expectedSha256: optionalString(payload.expectedSha256),
+            fileExpiresAt: optionalDate(payload.fileExpiresAt),
+          });
+          record(runtime, guardContext, "file.upload.create", session.id, {
+            purpose: session.purpose,
+            byteSize: session.expectedByteSize,
+          });
+          return Response.json(session, { status: 201 });
+        } catch (error) {
+          return uploadError(error);
+        }
+      },
+    );
+  });
+
+  app.get("/system/storage/uploads/:id", async (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    return guarded(
+      runtime,
+      guardContext,
+      feature,
+      "GET",
+      "system.storage.create",
+      async () => {
+        try {
+          return await services.uploads.getSession(
+            string(params.id),
+            guardContext.actor.id,
+          );
+        } catch (error) {
+          return uploadError(error);
+        }
+      },
+    );
+  });
+
+  app.put(
+    "/system/storage/uploads/:id/parts/:partNumber",
+    async (rawContext) => {
+      const context = streamingContext(rawContext);
+      return guarded(
+        runtime,
+        context.guardContext,
+        feature,
+        "PUT",
+        "system.storage.create",
+        async () => {
+          try {
+            if (!context.request.body) {
+              throw new UploadError("INVALID_UPLOAD", "分片请求体不能为空");
+            }
+            const part = await services.uploads.appendPart({
+              sessionId: string(context.params.id),
+              ownerId: context.guardContext.actor.id,
+              partNumber: nonNegativeInteger(context.params.partNumber),
+              byteOffset: nonNegativeInteger(
+                context.request.headers.get("x-upload-offset"),
+              ),
+              byteSize: nonNegativeInteger(
+                context.request.headers.get("content-length"),
+              ),
+              sha256: context.request.headers.get("x-content-sha256") || "",
+              body: context.request.body,
+            });
+            return Response.json({
+              partNumber: part.partNumber,
+              receivedByteSize: part.byteOffset + part.byteSize,
+              sha256: part.contentHash.value,
+            });
+          } catch (error) {
+            return uploadError(error);
+          }
+        },
+      );
+    },
+    { parse: "none" },
+  );
+
+  app.post("/system/storage/uploads/:id/complete", async (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    return guarded(
+      runtime,
+      guardContext,
+      feature,
+      "POST",
+      "system.storage.create",
+      async () => {
+        try {
+          const file = await services.uploads.complete(
+            string(params.id),
+            guardContext.actor.id,
+          );
+          record(runtime, guardContext, "file.upload.complete", file.id, {
+            purpose: file.purpose,
+            byteSize: file.byteSize,
+            sha256: file.contentHash.value,
+          });
+          return Response.json(file, { status: 201 });
+        } catch (error) {
+          return uploadError(error);
+        }
+      },
+    );
+  });
+
+  app.delete("/system/storage/uploads/:id", async (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    return guarded(
+      runtime,
+      guardContext,
+      feature,
+      "DELETE",
+      "system.storage.create",
+      async () => {
+        try {
+          const id = string(params.id);
+          await services.uploads.abort(id, guardContext.actor.id);
+          record(runtime, guardContext, "file.upload.abort", id, {});
+          return new Response(null, { status: 204 });
+        } catch (error) {
+          return uploadError(error);
+        }
+      },
+    );
+  });
+
+  app.get("/system/storage/files/:id", async (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    return guarded(
+      runtime,
+      guardContext,
+      feature,
+      "GET",
+      "system.storage.read",
+      async () => {
+        const id = string(params.id);
+        try {
+          const file = await services.files.open(
+            id,
+            guardContext.actor.id,
+            guardContext.actor.permissionKeys.includes("system.storage.manage"),
+          );
+          record(runtime, guardContext, "file.download", file.id, {
+            purpose: file.purpose,
+            byteSize: file.byteSize,
+            sha256: file.contentHash.value,
+          });
+          return downloadResponse(file);
+        } catch (error) {
+          if (
+            error instanceof UploadError &&
+            error.code === "UPLOAD_FORBIDDEN"
+          ) {
+            runtime.auditSink.recordEvent(
+              resourceEvent(
+                guardContext,
+                "security.denied",
+                "file-storage",
+                id,
+                { reason: "owner-mismatch" },
+              ),
+            );
+          }
+          return uploadError(error);
+        }
+      },
+    );
+  });
+
+  app.get("/platform/files/:id", async (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    return guarded(
+      runtime,
+      guardContext,
+      settingsFeature,
+      "GET",
+      "system.settings.read",
+      async () => {
+        try {
+          const id = string(params.id);
+          if (!(await services.isPublicBrandingFile?.(id))) {
+            throw new UploadError("FILE_NOT_FOUND", "文件不存在");
+          }
+          const file = await services.files.openPublic(id, "branding-logo");
+          return publicImageResponse(file);
+        } catch (error) {
+          return uploadError(error);
+        }
+      },
+      true,
+    );
+  });
+
+  return app;
+}
+
+async function guarded<T>(
+  runtime: ServerRuntime,
+  context: ReturnType<typeof routeContext>["guardContext"],
+  feature: FeatureFlagDefinition | undefined,
+  method: HttpMethod,
+  permissionKey: string,
+  handler: () => T | Promise<T>,
+  anonymous = false,
+) {
+  const result = await evaluateRouteGuards(runtime, context, {
+    permission: {
+      method,
+      path: "/api/system/storage",
+      permissionKey,
+      anonymous,
+    },
+    feature,
+  });
+  return result.allowed
+    ? handler()
+    : Response.json(
+        { error: "FORBIDDEN", reason: result.reason },
+        { status: 403 },
+      );
+}
+
+function record(
+  runtime: ServerRuntime,
+  context: ReturnType<typeof routeContext>["guardContext"],
+  action:
+    | "file.upload.create"
+    | "file.upload.complete"
+    | "file.upload.abort"
+    | "file.download",
+  id: string,
+  metadata: Record<string, unknown>,
+) {
+  runtime.auditSink.recordEvent(
+    resourceEvent(context, action, "file-storage", id, metadata),
+  );
+}
+
+function streamingContext(value: unknown) {
+  return value as ReturnType<typeof routeContext> & { request: Request };
+}

package/template/apps/server/src/storage/runtime.ts

@@ -0,0 +1,86 @@
+import { resolve } from "node:path";
+import {
+  FileService,
+  InMemoryUploadRepository,
+  LocalFileBlobMaintenance,
+  LocalFileBlobStore,
+  MemoryBlobStore,
+  UploadService,
+  type BlobStore,
+  type BlobStoreMaintenance,
+  type UploadPolicy,
+  type UploadRepository,
+} from "@windy/storage";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { DrizzleUploadRepository } from "./drizzle-upload-repository.js";
+
+export interface StorageRuntime {
+  blobStore: BlobStore;
+  repository: UploadRepository;
+  uploads: UploadService;
+  files: FileService;
+}
+
+export const platformUploadPolicies: UploadPolicy[] = [
+  {
+    purpose: "bulk-data",
+    maxByteSize: 512 * 1024 * 1024,
+    maxPartByteSize: 8 * 1024 * 1024,
+    sessionTtlMs: 24 * 60 * 60_000,
+    allowedTypes: {
+      "application/x-ndjson": ["ndjson"],
+      "application/json": ["json"],
+    },
+    signature: "none",
+  },
+  {
+    purpose: "branding-logo",
+    maxByteSize: 5 * 1024 * 1024,
+    maxPartByteSize: 1024 * 1024,
+    sessionTtlMs: 60 * 60_000,
+    allowedTypes: {
+      "image/png": ["png"],
+      "image/jpeg": ["jpg", "jpeg"],
+      "image/webp": ["webp"],
+    },
+    signature: "image",
+  },
+];
+
+export function createStorageRuntime(
+  env: Record<string, string | undefined>,
+  db?: NodePgDatabase,
+): StorageRuntime {
+  if (!db) {
+    const repository = new InMemoryUploadRepository();
+    const blobStore = new MemoryBlobStore();
+    return createRuntime(repository, blobStore);
+  }
+  const driver = env.WINDY_BLOB_DRIVER || "local";
+  if (driver !== "local") {
+    throw new Error(`未安装 BlobStore Adapter：${driver}`);
+  }
+  const root = resolve(env.WINDY_STORAGE_ROOT || ".data/storage");
+  const repository = new DrizzleUploadRepository(db);
+  const blobStore = new LocalFileBlobStore({ root });
+  const maintenance = new LocalFileBlobMaintenance(root);
+  return createRuntime(repository, blobStore, maintenance);
+}
+
+function createRuntime(
+  repository: UploadRepository,
+  blobStore: BlobStore,
+  maintenance?: BlobStoreMaintenance,
+): StorageRuntime {
+  return {
+    repository,
+    blobStore,
+    uploads: new UploadService({
+      repository,
+      blobStore,
+      maintenance,
+      policies: platformUploadPolicies,
+    }),
+    files: new FileService(repository, blobStore),
+  };
+}

package/template/apps/server/src/system/audit-query.ts

@@ -0,0 +1,17 @@
+export function validateAuditTimeRange(
+  query: Record<string, string | undefined>,
+) {
+  for (const key of ["occurredAfter", "occurredBefore"] as const) {
+    const value = query[key];
+    if (value && Number.isNaN(Date.parse(value))) {
+      return Response.json(
+        {
+          error: "INVALID_AUDIT_TIME_RANGE",
+          message: `${key} 必须是有效的 ISO 时间。`,
+        },
+        { status: 400 },
+      );
+    }
+  }
+  return undefined;
+}

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

@@ -0,0 +1,139 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import {
+  createServerRuntime,
+  type AuditEventListQuery,
+} from "../runtime.js";
+import { FakeRouteApp } from "./route-test-app.js";
+import { registerSystemRoutes } from "./routes.js";
+import { createSystemRepositories } from "./seed.js";
+
+async function auditFixture() {
+  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/api/system/audit-logs", {
+      headers: { authorization: "Bearer token_1" },
+    }),
+  );
+  return { app, runtime, guardContext };
+}
+
+describe("audit routes", () => {
+  test("配置 reader 后从持久化查询", async () => {
+    let receivedAuditQuery: AuditEventListQuery | undefined;
+    const runtime = createServerRuntime(
+      { WINDY_DEV_ADMIN_TOKEN: "token_1" },
+      {
+        auditReader: {
+          async list(query) {
+            receivedAuditQuery = query;
+            return {
+              items: [
+                {
+                  id: "audit_from_db",
+                  action: "crud.create",
+                  outcome: "success",
+                  actor: {
+                    id: query.actorId || "user_1",
+                    type: "user",
+                    name: "审计员",
+                  },
+                  target: { type: query.resource || "users" },
+                  occurredAt: "2026-07-10T00:00:00.000Z",
+                },
+              ],
+              total: 1,
+              page: query.page,
+              pageSize: query.pageSize,
+            };
+          },
+        },
+      },
+    );
+    const app = new FakeRouteApp();
+    registerSystemRoutes(
+      app,
+      createSystemRepositories(createFoundationSnapshot()),
+      runtime,
+    );
+    const guardContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/audit-logs", {
+        headers: { authorization: "Bearer token_1" },
+      }),
+    );
+
+    const result = (await app.invoke("GET", "/system/audit-logs", {
+      guardContext,
+      params: {},
+      query: {
+        pageSize: "5",
+        actorId: "user_1",
+        resource: "users",
+        occurredAfter: "2026-07-01T00:00:00.000Z",
+      },
+    })) as { total: number; pageSize: number; items: Array<{ id: string }> };
+
+    expect(result.total).toBe(1);
+    expect(result.pageSize).toBe(5);
+    expect(result.items[0]?.id).toBe("audit_from_db");
+    expect(receivedAuditQuery).toMatchObject({
+      occurredAfter: "2026-07-01T00:00:00.000Z",
+      includeScheduler: false,
+    });
+  });
+
+  test("列表固定排除调度器，导出可显式包含", async () => {
+    const { app, runtime, guardContext } = await auditFixture();
+    const event = {
+      outcome: "success",
+      target: { type: "scheduled-task", id: "system.scheduler.health" },
+      occurredAt: "2026-07-14T01:00:00.000Z",
+    } as const;
+    runtime.auditSink.recordEvent({
+      ...event,
+      id: "audit_scheduler",
+      action: "task.execute",
+      actor: {
+        id: "system_scheduler",
+        type: "service",
+        name: "平台定时任务执行器",
+      },
+    });
+    runtime.auditSink.recordEvent({
+      ...event,
+      id: "audit_user",
+      action: "task.trigger",
+      actor: { id: "user_1", type: "user", name: "管理员" },
+    });
+
+    const listed = (await app.invoke("GET", "/system/audit-logs", {
+      guardContext,
+      params: {},
+      query: { includeScheduler: "true" },
+    })) as { items: Array<{ id: string }> };
+    const defaultExport = (await app.invoke(
+      "GET",
+      "/system/audit-logs/export",
+      { guardContext, params: {}, query: {} },
+    )) as Response;
+    const completeExport = (await app.invoke(
+      "GET",
+      "/system/audit-logs/export",
+      {
+        guardContext,
+        params: {},
+        query: { includeScheduler: "true" },
+      },
+    )) as Response;
+
+    expect(listed.items.map(({ id }) => id)).toEqual(["audit_user"]);
+    await expect(defaultExport.json()).resolves.toMatchObject({ total: 1 });
+    await expect(completeExport.json()).resolves.toMatchObject({ total: 3 });
+  });
+});

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

@@ -0,0 +1,113 @@
+import type { AuditEvent, FeatureFlagDefinition } from "@windy/shared";
+import { findSystemFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { parsePagination } from "../pagination.js";
+import { resourceEvent, routeContext } from "./route-helpers.js";
+import type { RouteApp } from "./route-types.js";
+import { withPermission } from "./resource-route-support.js";
+import { validateAuditTimeRange } from "./audit-query.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export function registerAuditRoutes(
+  app: RouteApp,
+  runtime: ServerRuntime,
+  features: FeatureFlagDefinition[],
+) {
+  const feature = findSystemFeature(features, "audit");
+  app.get("/system/audit-logs", (rawContext) => {
+    const { guardContext, query } = routeContext(rawContext);
+    return withPermission(
+      runtime,
+      guardContext,
+      "GET",
+      "audit",
+      "read",
+      feature,
+      async () => {
+        const pagination = parsePagination(query);
+        if (pagination instanceof Response) return pagination;
+        const invalidTimeRange = validateAuditTimeRange(query);
+        if (invalidTimeRange) return invalidTimeRange;
+        return runtime.listAuditEvents({
+          ...pagination,
+          ...auditFilters(query),
+          includeScheduler: false,
+        });
+      },
+    );
+  });
+
+  app.get("/system/audit-logs/export", (rawContext) => {
+    const { guardContext, query } = routeContext(rawContext);
+    return withPermission(
+      runtime,
+      guardContext,
+      "GET",
+      "audit",
+      "read",
+      feature,
+      async () => {
+        const invalidTimeRange = validateAuditTimeRange(query);
+        if (invalidTimeRange) return invalidTimeRange;
+        const includeScheduler = query.includeScheduler === "true";
+        const items = await listAll(runtime, {
+          ...auditFilters(query),
+          includeScheduler,
+        });
+        runtime.auditSink.recordEvent(
+          resourceEvent(guardContext, "data.export", "audit-logs", undefined, {
+            total: items.length,
+            includeScheduler,
+          }),
+        );
+        return Response.json(
+          {
+            resource: "audit-logs",
+            exportedAt: new Date().toISOString(),
+            total: items.length,
+            items,
+          },
+          {
+            headers: {
+              "content-disposition": 'attachment; filename="audit-logs.json"',
+            },
+          },
+        );
+      },
+      "backup-export",
+    );
+  });
+}
+
+function auditFilters(query: Record<string, string | undefined>) {
+  return {
+    actorId: query.actorId,
+    action: query.action,
+    resource: query.resource,
+    resourceId: query.resourceId,
+    occurredAfter: query.occurredAfter,
+    occurredBefore: query.occurredBefore,
+  };
+}
+
+async function listAll(
+  runtime: ServerRuntime,
+  filters: Omit<
+    Parameters<ServerRuntime["listAuditEvents"]>[0],
+    "page" | "pageSize"
+  >,
+): Promise<AuditEvent[]> {
+  const items: AuditEvent[] = [];
+  let page = 1;
+  while (true) {
+    const result = await runtime.listAuditEvents({
+      ...filters,
+      page,
+      pageSize: 100,
+    });
+    items.push(...result.items);
+    if (items.length >= result.total) return items;
+    page += 1;
+  }
+}