create-windy 0.1.0

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

@@ -0,0 +1,250 @@
+import { describe, expect, test } from "bun:test";
+import type { PlatformBrandingSettings } from "@windy/shared";
+import { createFoundationSnapshot } from "../foundation.js";
+import type { RequestActor } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import type { RouteApp } from "../system/route-types.js";
+import { InMemoryBrandingSettingsRepository } from "./repository.js";
+import { registerBrandingSettingsRoutes } from "./routes.js";
+
+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(): void {}
+
+  put(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(`PUT ${path}`, handler);
+  }
+
+  delete(): void {}
+
+  invoke(method: "GET" | "PUT", path: string, context: unknown = {}): unknown {
+    const handler = this.handlers.get(`${method} ${path}`);
+    if (!handler) throw new Error(`未注册路由 ${method} ${path}`);
+    return handler(context);
+  }
+}
+
+describe("全局品牌设置路由", () => {
+  test("公开端点无需登录即可读取默认品牌", async () => {
+    const fixture = await createFixture(anonymousActor());
+
+    const settings = (await fixture.app.invoke(
+      "GET",
+      "/platform/branding",
+    )) as PlatformBrandingSettings;
+
+    expect(settings).toEqual({ softwareName: "Windy Starter" });
+  });
+
+  test("具有管理权限的用户可更新品牌并写 config.update 审计", async () => {
+    const fixture = await createFixture(settingsActor(true));
+
+    const settings = (await fixture.app.invoke(
+      "PUT",
+      "/system/settings/branding",
+      {
+        guardContext: fixture.guardContext,
+        body: {
+          softwareName: "南风业务平台",
+          logoUrl: "https://assets.example.com/logo.svg",
+        },
+        params: {},
+        query: {},
+      },
+    )) as PlatformBrandingSettings;
+
+    expect(settings).toEqual({
+      softwareName: "南风业务平台",
+      logoUrl: "https://assets.example.com/logo.svg",
+    });
+    expect(await fixture.repository.get()).toEqual(settings);
+    expect(fixture.runtime.auditSink.list()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          action: "config.update",
+          target: { type: "platform-branding", id: "platform" },
+        }),
+      ]),
+    );
+  });
+
+  test("全局设置可以保存平台描述", async () => {
+    const fixture = await createFixture(settingsActor(true));
+
+    const settings = (await fixture.app.invoke(
+      "PUT",
+      "/system/settings/branding",
+      {
+        guardContext: fixture.guardContext,
+        body: {
+          softwareName: "南风业务平台",
+          description: "连接组织、权限与运营能力的企业工作台。",
+        },
+        params: {},
+        query: {},
+      },
+    )) as PlatformBrandingSettings;
+
+    expect(settings).toEqual({
+      softwareName: "南风业务平台",
+      description: "连接组织、权限与运营能力的企业工作台。",
+    });
+  });
+
+  test("只读权限可以访问管理读取端点但不能更新", async () => {
+    const fixture = await createFixture(settingsActor(false));
+
+    const readable = (await fixture.app.invoke(
+      "GET",
+      "/system/settings/branding",
+      { guardContext: fixture.guardContext, params: {}, query: {} },
+    )) as PlatformBrandingSettings;
+    const denied = (await fixture.app.invoke(
+      "PUT",
+      "/system/settings/branding",
+      {
+        guardContext: fixture.guardContext,
+        body: { softwareName: "禁止更新" },
+        params: {},
+        query: {},
+      },
+    )) as Response;
+
+    expect(readable.softwareName).toBe("Windy Starter");
+    expect(denied.status).toBe(403);
+    await expect(denied.json()).resolves.toMatchObject({
+      reason: "missing-permission",
+    });
+  });
+
+  test("Feature 关闭时管理端点返回 403", async () => {
+    const fixture = await createFixture(settingsActor(true), false);
+
+    const denied = (await fixture.app.invoke(
+      "GET",
+      "/system/settings/branding",
+      { guardContext: fixture.guardContext, params: {}, query: {} },
+    )) as Response;
+
+    expect(denied.status).toBe(403);
+    await expect(denied.json()).resolves.toMatchObject({
+      reason: "feature-disabled",
+    });
+  });
+
+  test("非法软件名返回 400 且不修改设置", async () => {
+    const fixture = await createFixture(settingsActor(true));
+
+    const response = (await fixture.app.invoke(
+      "PUT",
+      "/system/settings/branding",
+      {
+        guardContext: fixture.guardContext,
+        body: { softwareName: "   " },
+        params: {},
+        query: {},
+      },
+    )) as Response;
+
+    expect(response.status).toBe(400);
+    expect(await fixture.repository.get()).toEqual({
+      softwareName: "Windy Starter",
+    });
+    expect(
+      fixture.runtime.auditSink
+        .list()
+        .some((event) => event.action === "config.update"),
+    ).toBe(false);
+  });
+
+  test("拒绝可能执行脚本的 Logo 地址", async () => {
+    const fixture = await createFixture(settingsActor(true));
+
+    const response = (await fixture.app.invoke(
+      "PUT",
+      "/system/settings/branding",
+      {
+        guardContext: fixture.guardContext,
+        body: { softwareName: "Windy", logoUrl: "javascript:alert(1)" },
+        params: {},
+        query: {},
+      },
+    )) as Response;
+
+    expect(response.status).toBe(400);
+    expect(await fixture.repository.get()).toEqual({
+      softwareName: "Windy Starter",
+    });
+  });
+
+  test("接受受限大小的本地栅格 Logo 数据", async () => {
+    const fixture = await createFixture(settingsActor(true));
+    const logoUrl = `data:image/png;base64,${Buffer.from("png-logo").toString("base64")}`;
+
+    const settings = (await fixture.app.invoke(
+      "PUT",
+      "/system/settings/branding",
+      {
+        guardContext: fixture.guardContext,
+        body: { softwareName: "Windy", logoUrl },
+        params: {},
+        query: {},
+      },
+    )) as PlatformBrandingSettings;
+
+    expect(settings.logoUrl).toBe(logoUrl);
+  });
+});
+
+async function createFixture(actor: RequestActor, featureEnabled = true) {
+  const snapshot = createFoundationSnapshot();
+  const repository = new InMemoryBrandingSettingsRepository({
+    softwareName: "Windy Starter",
+  });
+  const runtime = createServerRuntime(
+    {},
+    {
+      actorResolver: { resolve: () => actor },
+      featureResolver: {
+        resolve: (key) => ({
+          key,
+          enabled: featureEnabled,
+          visible: "visible",
+        }),
+      },
+    },
+  );
+  const app = new FakeRouteApp();
+  registerBrandingSettingsRoutes(app, repository, runtime, snapshot.features);
+  const guardContext = await runtime.createGuardContext(
+    new Request("http://localhost/api/system/settings/branding"),
+  );
+  return { app, repository, runtime, guardContext };
+}
+
+function settingsActor(canManage: boolean): RequestActor {
+  return {
+    id: "user_settings",
+    type: "user",
+    name: "配置管理员",
+    roleCodes: ["admin"],
+    permissionKeys: ["system.settings.read"].concat(
+      canManage ? "system.settings.manage" : [],
+    ),
+  };
+}
+
+function anonymousActor(): RequestActor {
+  return {
+    id: "anonymous",
+    type: "anonymous",
+    name: "匿名用户",
+    roleCodes: [],
+    permissionKeys: [],
+  };
+}

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

@@ -0,0 +1,175 @@
+import type {
+  ApiPermissionBinding,
+  FeatureFlagDefinition,
+  PlatformBrandingSettings,
+} from "@windy/shared";
+import { evaluateRouteGuards, findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { RouteApp } from "../system/route-types.js";
+import { resourceEvent, routeContext } from "../system/route-helpers.js";
+import { recordMutationAudit } from "../audit/policy.js";
+import type { BrandingSettingsRepository } from "./repository.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+const READ_BINDING = brandingBinding("GET", "system.settings.read");
+const MANAGE_BINDING = brandingBinding("PUT", "system.settings.manage");
+const MAX_REMOTE_LOGO_URL_LENGTH = 2_048;
+const MAX_LOCAL_LOGO_URL_LENGTH = 1_398_128;
+
+export function registerBrandingSettingsRoutes(
+  app: RouteApp,
+  repository: BrandingSettingsRepository,
+  runtime: ServerRuntime,
+  features: FeatureFlagDefinition[],
+): void {
+  const feature = findFeature(features, "system.settings");
+
+  app.get("/platform/branding", () => repository.get());
+
+  app.get("/system/settings/branding", async (rawContext) => {
+    const { guardContext } = routeContext(rawContext);
+    const denied = await guard(runtime, guardContext, READ_BINDING, feature);
+    return denied || repository.get();
+  });
+
+  app.put("/system/settings/branding", async (rawContext) => {
+    const { body, guardContext } = routeContext(rawContext);
+    const denied = await guard(runtime, guardContext, MANAGE_BINDING, feature);
+    if (denied) return denied;
+
+    const parsed = parseBrandingSettings(body);
+    if (!parsed.ok) {
+      return Response.json(
+        { error: "INVALID_BRANDING_SETTINGS", message: parsed.message },
+        { status: 400 },
+      );
+    }
+
+    const updated = await repository.update(
+      parsed.value,
+      guardContext.actor.id,
+    );
+    await recordMutationAudit(
+      runtime,
+      "settings",
+      resourceEvent(
+        guardContext,
+        "config.update",
+        "platform-branding",
+        "platform",
+        { changedFields: changedFields(parsed.value) },
+      ),
+    );
+    return updated;
+  });
+}
+
+async function guard(
+  runtime: ServerRuntime,
+  context: ReturnType<typeof routeContext>["guardContext"],
+  permission: ApiPermissionBinding,
+  feature: FeatureFlagDefinition | undefined,
+): Promise<Response | undefined> {
+  const decision = await evaluateRouteGuards(runtime, context, {
+    permission,
+    feature,
+  });
+  if (decision.allowed) return undefined;
+  return Response.json(
+    { error: "FORBIDDEN", reason: decision.reason },
+    { status: 403 },
+  );
+}
+
+function brandingBinding(
+  method: "GET" | "PUT",
+  permissionKey: string,
+): ApiPermissionBinding {
+  return {
+    method,
+    path: "/api/system/settings/branding",
+    permissionKey,
+    featureKey: "system.settings",
+  };
+}
+
+type BrandingParseResult =
+  | { ok: true; value: PlatformBrandingSettings }
+  | { ok: false; message: string };
+
+function parseBrandingSettings(body: unknown): BrandingParseResult {
+  if (!body || typeof body !== "object") {
+    return { ok: false, message: "请求体必须是对象" };
+  }
+  const source = body as Record<string, unknown>;
+  if (typeof source.softwareName !== "string") {
+    return { ok: false, message: "软件名不能为空" };
+  }
+  const softwareName = source.softwareName.trim();
+  if (!softwareName || softwareName.length > 120) {
+    return { ok: false, message: "软件名长度必须为 1 到 120 个字符" };
+  }
+  if (
+    source.logoUrl !== undefined &&
+    source.logoUrl !== null &&
+    typeof source.logoUrl !== "string"
+  ) {
+    return { ok: false, message: "Logo 地址必须是字符串" };
+  }
+  const logoUrl =
+    typeof source.logoUrl === "string" ? source.logoUrl.trim() : "";
+  if (
+    logoUrl.length >
+    (logoUrl.startsWith("data:")
+      ? MAX_LOCAL_LOGO_URL_LENGTH
+      : MAX_REMOTE_LOGO_URL_LENGTH)
+  ) {
+    return { ok: false, message: "Logo 文件不能超过 1 MiB" };
+  }
+  if (logoUrl && !isAllowedLogoUrl(logoUrl)) {
+    return {
+      ok: false,
+      message: "Logo 地址必须使用 HTTP、HTTPS 或以 / 开头的站内路径",
+    };
+  }
+  if (
+    source.description !== undefined &&
+    source.description !== null &&
+    typeof source.description !== "string"
+  ) {
+    return { ok: false, message: "平台描述必须是字符串" };
+  }
+  const description =
+    typeof source.description === "string" ? source.description.trim() : "";
+  if (description.length > 500) {
+    return { ok: false, message: "平台描述不能超过 500 个字符" };
+  }
+  return {
+    ok: true,
+    value: {
+      softwareName,
+      logoUrl: logoUrl || undefined,
+      description: description || undefined,
+    },
+  };
+}
+
+function isAllowedLogoUrl(value: string): boolean {
+  if (/^data:image\/(png|jpeg|webp);base64,[a-z\d+/]+={0,2}$/i.test(value)) {
+    return true;
+  }
+  if (value.startsWith("/") && !value.startsWith("//")) return true;
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "https:" || parsed.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+function changedFields(settings: PlatformBrandingSettings): string[] {
+  return ["softwareName", "logoUrl", "description"].filter(
+    (field) => field === "softwareName" || Reflect.has(settings, field),
+  );
+}

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

@@ -0,0 +1,13 @@
+import type { PlatformBrandingSettings } from "@windy/shared";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { DrizzleBrandingSettingsRepository } from "./drizzle-repository.js";
+import { InMemoryBrandingSettingsRepository } from "./repository.js";
+
+export function createBrandingSettingsRepository(
+  db: NodePgDatabase | undefined,
+  defaults: PlatformBrandingSettings,
+) {
+  return db
+    ? new DrizzleBrandingSettingsRepository(db, defaults)
+    : new InMemoryBrandingSettingsRepository(defaults);
+}

package/template/apps/server/src/storage/blob-reference-registry.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { artifactRef } from "@windy/storage";
+import { collectActiveBlobRefs } from "./blob-reference-registry.js";
+
+describe("应用 Blob 引用注册表", () => {
+  test("合并 upload 之外的 durable 与 bulk 引用并去重", async () => {
+    const durable = artifactRef("blob_11111111111111111111111111111111");
+    const bulk = artifactRef("blob_22222222222222222222222222222222");
+    const now = new Date("2026-07-16T00:00:00.000Z");
+    const refs = await collectActiveBlobRefs(
+      [source(durable), source(durable, bulk)],
+      now,
+    );
+
+    expect([...refs]).toEqual([durable, bulk]);
+  });
+});
+
+function source(...refs: ReturnType<typeof artifactRef>[]) {
+  return {
+    async listActiveArtifactRefs() {
+      return refs;
+    },
+  };
+}

package/template/apps/server/src/storage/blob-reference-registry.ts

@@ -0,0 +1,15 @@
+import type { ArtifactRef } from "@windy/storage";
+
+export interface ActiveBlobReferenceSource {
+  listActiveArtifactRefs(now: Date): Promise<ArtifactRef[]>;
+}
+
+export async function collectActiveBlobRefs(
+  sources: readonly ActiveBlobReferenceSource[],
+  now: Date,
+): Promise<Set<ArtifactRef>> {
+  const refs = await Promise.all(
+    sources.map((source) => source.listActiveArtifactRefs(now)),
+  );
+  return new Set(refs.flat());
+}

package/template/apps/server/src/storage/drizzle-upload-repository.integration.test.ts

@@ -0,0 +1,136 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import {
+  MemoryBlobStore,
+  UploadService,
+  type UploadPolicy,
+} from "@windy/storage";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { Pool } from "pg";
+import { DrizzleUploadRepository } from "./drizzle-upload-repository.js";
+
+const databaseUrl = process.env.STORAGE_TEST_DATABASE_URL;
+const describePostgres = databaseUrl ? describe : describe.skip;
+const policy: UploadPolicy = {
+  purpose: "bulk-data",
+  maxByteSize: 64 * 1024 * 1024,
+  maxPartByteSize: 8 * 1024 * 1024,
+  sessionTtlMs: 60_000,
+  allowedTypes: { "application/x-ndjson": ["ndjson"] },
+  signature: "none",
+};
+let currentTime = new Date("2026-07-16T00:00:00.000Z");
+const blobStore = new MemoryBlobStore();
+
+describePostgres("PostgreSQL upload repository", () => {
+  let pool: Pool;
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: databaseUrl });
+    await migrate(drizzle(pool), {
+      migrationsFolder: resolve(
+        import.meta.dir,
+        "../../../../packages/database/drizzle",
+      ),
+      migrationsSchema: "public",
+      migrationsTable: "__storage_test_migrations",
+    });
+    await pool.query(
+      "truncate table file_upload_parts, file_metadata, file_upload_sessions",
+    );
+  });
+
+  afterAll(async () => {
+    await pool?.end();
+  });
+
+  test("并发分片 CAS、重启续传、完成和到期清理均持久化", async () => {
+    const repository = new DrizzleUploadRepository(drizzle(pool));
+    const service = uploadService(repository);
+    const body = new TextEncoder().encode('{"id":1}\n');
+    const session = await service.create({
+      ownerId: "user_pg",
+      purpose: "bulk-data",
+      filename: "source.ndjson",
+      mimeType: "application/x-ndjson",
+      expectedByteSize: body.byteLength,
+      expectedSha256: digest(body),
+      fileExpiresAt: new Date("2026-07-16T00:00:30.000Z"),
+    });
+
+    const results = await Promise.allSettled([
+      service.appendPart(part(session.id, body)),
+      service.appendPart(part(session.id, body)),
+    ]);
+    const fulfilled = results
+      .filter((result) => result.status === "fulfilled")
+      .map((result) => result.value);
+    expect(fulfilled.length).toBeGreaterThanOrEqual(1);
+    expect(new Set(fulfilled.map(({ artifactRef }) => artifactRef)).size).toBe(
+      1,
+    );
+    for (const result of results) {
+      if (result.status === "rejected") {
+        expect(result.reason).toMatchObject({ code: "CONCURRENT_UPLOAD" });
+      }
+    }
+    expect(blobStore.size).toBe(1);
+
+    const restartedRepository = new DrizzleUploadRepository(drizzle(pool));
+    expect(await restartedRepository.getSession(session.id)).toMatchObject({
+      receivedByteSize: body.byteLength,
+      nextPartNumber: 1,
+      status: "uploading",
+    });
+    const file = await uploadService(restartedRepository).complete(
+      session.id,
+      "user_pg",
+    );
+    expect(await restartedRepository.getFile(file.id)).toMatchObject({
+      ownerId: "user_pg",
+      byteSize: body.byteLength,
+      contentHash: { value: digest(body) },
+    });
+
+    currentTime = new Date("2026-07-16T00:00:30.000Z");
+    expect(await uploadService(restartedRepository).cleanupExpired()).toEqual({
+      sessions: 0,
+      files: 1,
+      blobs: 1,
+      orphans: 0,
+    });
+    expect(await restartedRepository.getFile(file.id)).toBeUndefined();
+  });
+});
+
+function uploadService(repository: DrizzleUploadRepository) {
+  return new UploadService({
+    repository,
+    blobStore,
+    policies: [policy],
+    now: () => currentTime,
+  });
+}
+
+function part(sessionId: string, body: Uint8Array) {
+  return {
+    sessionId,
+    ownerId: "user_pg",
+    partNumber: 0,
+    byteOffset: 0,
+    byteSize: body.byteLength,
+    sha256: digest(body),
+    body: new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(body);
+        controller.close();
+      },
+    }),
+  };
+}
+
+function digest(value: Uint8Array) {
+  return createHash("sha256").update(value).digest("hex");
+}