create-windy 0.1.0

package/template/apps/server/src/bulk-data/types.ts

@@ -0,0 +1,73 @@
+import type { ArtifactRef } from "@windy/storage";
+
+export type BulkJobKind = "import" | "export";
+export type BulkJobStatus =
+  | "queued"
+  | "running"
+  | "retry-pending"
+  | "succeeded"
+  | "completed-with-errors"
+  | "failed";
+export type BulkArtifactKind = "source" | "result" | "failures";
+
+export interface BulkDataJob {
+  id: string;
+  kind: BulkJobKind;
+  resource: string;
+  mode?: "create" | "upsert";
+  status: BulkJobStatus;
+  idempotencyKey: string;
+  requestDigest: string;
+  requestedBy: string;
+  totalRows: number;
+  processedRows: number;
+  succeededRows: number;
+  failedRows: number;
+  attempt: number;
+  maxAttempts: number;
+  nextAttemptAt?: string;
+  error?: string;
+  durableJobId?: string;
+  createdAt: string;
+  startedAt?: string;
+  finishedAt?: string;
+  updatedAt: string;
+}
+
+export interface BulkDataArtifact {
+  id: string;
+  jobId: string;
+  kind: BulkArtifactKind;
+  filename: string;
+  contentType: string;
+  content?: string;
+  artifactRef?: ArtifactRef;
+  sha256: string;
+  byteSize: number;
+  createdAt: string;
+  expiresAt: string;
+}
+
+export interface NewBulkJob {
+  kind: BulkJobKind;
+  resource: string;
+  mode?: "create" | "upsert";
+  idempotencyKey: string;
+  requestDigest: string;
+  requestedBy: string;
+  totalRows: number;
+  maxAttempts: number;
+}
+
+export interface JobProgress {
+  processedRows: number;
+  succeededRows: number;
+  failedRows: number;
+}
+
+export interface BulkRowFailure {
+  line: number;
+  code: "INVALID_JSON" | "INVALID_ROW" | "IMPORT_FAILED";
+  message: string;
+  inputDigest: string;
+}

package/template/apps/server/src/configuration/bootstrap.ts

@@ -0,0 +1,59 @@
+import type { PlatformConfig } from "@windy/config";
+import type { FeatureFlagDefinition } from "@windy/shared";
+import type { FoundationSnapshot } from "../foundation.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { RouteApp } from "../system/route-types.js";
+import {
+  createRedisHealthProbe,
+  type RedisHealthProbe,
+} from "../system/redis-health.js";
+import { PlatformConfigApplyAdapter } from "./definition.js";
+import {
+  InMemoryModuleConfigVersionRepository,
+  type ModuleConfigVersionRepository,
+} from "./repository.js";
+import { ModuleConfigurationService } from "./service.js";
+import { registerModuleConfigurationRoutes } from "./routes.js";
+
+export async function bootstrapModuleConfiguration(
+  config: PlatformConfig,
+  repository?: ModuleConfigVersionRepository,
+): Promise<{
+  service: ModuleConfigurationService;
+  bindFoundation(snapshot: FoundationSnapshot): void;
+  redisHealthProbe: RedisHealthProbe;
+  register(
+    app: Pick<RouteApp, "get" | "post">,
+    runtime: ReturnType<typeof createServerRuntime>,
+    features: FeatureFlagDefinition[],
+  ): void;
+}> {
+  const adapter = new PlatformConfigApplyAdapter(config);
+  const service = new ModuleConfigurationService(
+    repository || new InMemoryModuleConfigVersionRepository(),
+    [adapter.definition()],
+  );
+  await service.initialize();
+  return {
+    service,
+    bindFoundation(snapshot) {
+      adapter.setListener({
+        applied(current) {
+          snapshot.platform.enableAI = current.enableAI;
+        },
+      });
+    },
+    redisHealthProbe: createLiveRedisHealthProbe(config),
+    register(app, runtime, features) {
+      registerModuleConfigurationRoutes(app, service, runtime, features);
+    },
+  };
+}
+
+export function createLiveRedisHealthProbe(config: PlatformConfig) {
+  return () =>
+    createRedisHealthProbe({
+      url: config.cache.redisUrl,
+      timeoutMs: config.cache.healthTimeoutMs,
+    })();
+}

package/template/apps/server/src/configuration/definition.ts

@@ -0,0 +1,89 @@
+import { platformConfigDefinition, type PlatformConfig } from "@windy/config";
+import type {
+  ModuleConfigFieldDescriptor,
+  ModuleConfigValues,
+} from "@windy/shared";
+import { z } from "zod";
+
+export interface ManagedModuleConfigDefinition {
+  moduleKey: string;
+  label: string;
+  fields: ModuleConfigFieldDescriptor[];
+  validate(values: unknown): ModuleConfigValues;
+  apply(values: ModuleConfigValues): Promise<void> | void;
+  baseValues(): ModuleConfigValues;
+}
+
+export interface PlatformConfigApplyListener {
+  applied(config: PlatformConfig): void;
+}
+
+const managedPaths = ["enableAI", "cache.healthTimeoutMs"] as const;
+const platformValuesSchema = z.strictObject({
+  enableAI: z.boolean(),
+  "cache.healthTimeoutMs": z.number().int().min(50).max(10_000),
+});
+
+export class PlatformConfigApplyAdapter {
+  private listener?: PlatformConfigApplyListener;
+
+  constructor(private readonly config: PlatformConfig) {
+    assertSafeManagedPaths();
+  }
+
+  setListener(listener: PlatformConfigApplyListener): void {
+    this.listener = listener;
+  }
+
+  definition(): ManagedModuleConfigDefinition {
+    return {
+      moduleKey: platformConfigDefinition.key,
+      label: platformConfigDefinition.label,
+      fields: [
+        {
+          path: "enableAI",
+          label: "AI 能力总开关",
+          description: "控制 foundation 快照中的平台 AI 能力声明。",
+          input: "boolean",
+        },
+        {
+          path: "cache.healthTimeoutMs",
+          label: "Redis 探活超时",
+          description: "控制运维总览单次 Redis 探活的总等待时间。",
+          input: "integer",
+          minimum: 50,
+          maximum: 10_000,
+        },
+      ],
+      validate: (values) => platformValuesSchema.parse(values),
+      apply: (values) => this.apply(values),
+      baseValues: () => this.values(),
+    };
+  }
+
+  private apply(values: ModuleConfigValues): void {
+    const parsed = platformValuesSchema.parse(values);
+    this.config.enableAI = parsed.enableAI;
+    this.config.cache.healthTimeoutMs = parsed["cache.healthTimeoutMs"];
+    this.listener?.applied(this.config);
+  }
+
+  private values(): ModuleConfigValues {
+    return {
+      enableAI: this.config.enableAI,
+      "cache.healthTimeoutMs": this.config.cache.healthTimeoutMs,
+    };
+  }
+}
+
+function assertSafeManagedPaths(): void {
+  const fields = new Map(
+    platformConfigDefinition.environment.map((field) => [field.path, field]),
+  );
+  for (const path of managedPaths) {
+    const field = fields.get(path);
+    if (!field)
+      throw new Error(`动态配置字段未在 ModuleConfigDefinition 注册：${path}`);
+    if (field.secret) throw new Error(`Secret 字段禁止进入动态配置：${path}`);
+  }
+}

package/template/apps/server/src/configuration/drizzle-repository.ts

@@ -0,0 +1,166 @@
+import { randomUUIDv7 } from "bun";
+import { moduleConfigVersions } from "@windy/database";
+import type { ModuleConfigVersion } from "@windy/shared";
+import { and, desc, eq, ne, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type {
+  BeginConfigVersionInput,
+  ModuleConfigVersionRepository,
+} from "./repository.js";
+import { isApplyStatus } from "./repository.js";
+
+export class DrizzleModuleConfigVersionRepository implements ModuleConfigVersionRepository {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async begin(input: BeginConfigVersionInput): Promise<ModuleConfigVersion> {
+    return this.db.transaction(async (tx) => {
+      await tx.execute(
+        sql`select pg_advisory_xact_lock(hashtext(${input.moduleKey}))`,
+      );
+      const [latest] = await tx
+        .select({ version: moduleConfigVersions.version })
+        .from(moduleConfigVersions)
+        .where(eq(moduleConfigVersions.moduleKey, input.moduleKey))
+        .orderBy(desc(moduleConfigVersions.version))
+        .limit(1);
+      const [created] = await tx
+        .insert(moduleConfigVersions)
+        .values({
+          id: randomUUIDv7(),
+          moduleKey: input.moduleKey,
+          version: (latest?.version || 0) + 1,
+          values: input.values,
+          diff: input.diff,
+          applyStatus: "applying",
+          rollbackOfVersion: input.rollbackOfVersion,
+          reason: input.reason,
+          createdBy: input.actorId,
+        })
+        .returning();
+      return mapRequired(created);
+    });
+  }
+
+  async markEffective(
+    id: string,
+    appliedAt: Date,
+  ): Promise<ModuleConfigVersion> {
+    return this.db.transaction(async (tx) => {
+      const [candidate] = await tx
+        .select()
+        .from(moduleConfigVersions)
+        .where(eq(moduleConfigVersions.id, id))
+        .limit(1);
+      if (!candidate) throw new Error("配置版本不存在");
+      await tx
+        .update(moduleConfigVersions)
+        .set({ applyStatus: "superseded" })
+        .where(
+          and(
+            eq(moduleConfigVersions.moduleKey, candidate.moduleKey),
+            eq(moduleConfigVersions.applyStatus, "effective"),
+            ne(moduleConfigVersions.id, id),
+          ),
+        );
+      const [updated] = await tx
+        .update(moduleConfigVersions)
+        .set({ applyStatus: "effective", applyError: null, appliedAt })
+        .where(eq(moduleConfigVersions.id, id))
+        .returning();
+      return mapRequired(updated);
+    });
+  }
+
+  async markFailed(
+    id: string,
+    applyError: string,
+    appliedAt: Date,
+  ): Promise<ModuleConfigVersion> {
+    const [updated] = await this.db
+      .update(moduleConfigVersions)
+      .set({ applyStatus: "failed", applyError, appliedAt })
+      .where(eq(moduleConfigVersions.id, id))
+      .returning();
+    return mapRequired(updated);
+  }
+
+  latest(moduleKey: string): Promise<ModuleConfigVersion | undefined> {
+    return this.first(moduleKey);
+  }
+
+  effective(moduleKey: string): Promise<ModuleConfigVersion | undefined> {
+    return this.first(moduleKey, "effective");
+  }
+
+  async find(
+    moduleKey: string,
+    version: number,
+  ): Promise<ModuleConfigVersion | undefined> {
+    const [row] = await this.db
+      .select()
+      .from(moduleConfigVersions)
+      .where(
+        and(
+          eq(moduleConfigVersions.moduleKey, moduleKey),
+          eq(moduleConfigVersions.version, version),
+        ),
+      )
+      .limit(1);
+    return row ? mapVersion(row) : undefined;
+  }
+
+  async list(moduleKey: string): Promise<ModuleConfigVersion[]> {
+    const rows = await this.db
+      .select()
+      .from(moduleConfigVersions)
+      .where(eq(moduleConfigVersions.moduleKey, moduleKey))
+      .orderBy(desc(moduleConfigVersions.version));
+    return rows.map(mapVersion);
+  }
+
+  private async first(
+    moduleKey: string,
+    status?: string,
+  ): Promise<ModuleConfigVersion | undefined> {
+    const where = status
+      ? and(
+          eq(moduleConfigVersions.moduleKey, moduleKey),
+          eq(moduleConfigVersions.applyStatus, status),
+        )
+      : eq(moduleConfigVersions.moduleKey, moduleKey);
+    const [row] = await this.db
+      .select()
+      .from(moduleConfigVersions)
+      .where(where)
+      .orderBy(desc(moduleConfigVersions.version))
+      .limit(1);
+    return row ? mapVersion(row) : undefined;
+  }
+}
+
+type ConfigVersionRow = typeof moduleConfigVersions.$inferSelect;
+
+function mapRequired(row: ConfigVersionRow | undefined): ModuleConfigVersion {
+  if (!row) throw new Error("配置版本写入失败");
+  return mapVersion(row);
+}
+
+function mapVersion(row: ConfigVersionRow): ModuleConfigVersion {
+  if (!isApplyStatus(row.applyStatus)) {
+    throw new Error(`配置版本状态无效：${row.applyStatus}`);
+  }
+  return {
+    id: row.id,
+    moduleKey: row.moduleKey,
+    version: row.version,
+    values: { ...row.values },
+    diff: row.diff.map((entry) => ({ ...entry })),
+    applyStatus: row.applyStatus,
+    applyError: row.applyError || undefined,
+    rollbackOfVersion: row.rollbackOfVersion || undefined,
+    reason: row.reason || undefined,
+    createdAt: row.createdAt.toISOString(),
+    createdBy: row.createdBy,
+    appliedAt: row.appliedAt?.toISOString(),
+  };
+}

package/template/apps/server/src/configuration/repository.ts

@@ -0,0 +1,138 @@
+import { randomUUIDv7 } from "bun";
+import type {
+  ModuleConfigApplyStatus,
+  ModuleConfigDiffEntry,
+  ModuleConfigValues,
+  ModuleConfigVersion,
+} from "@windy/shared";
+
+export interface BeginConfigVersionInput {
+  moduleKey: string;
+  values: ModuleConfigValues;
+  diff: ModuleConfigDiffEntry[];
+  rollbackOfVersion?: number;
+  reason?: string;
+  actorId: string;
+}
+
+export interface ModuleConfigVersionRepository {
+  begin(input: BeginConfigVersionInput): Promise<ModuleConfigVersion>;
+  markEffective(id: string, appliedAt: Date): Promise<ModuleConfigVersion>;
+  markFailed(
+    id: string,
+    applyError: string,
+    appliedAt: Date,
+  ): Promise<ModuleConfigVersion>;
+  latest(moduleKey: string): Promise<ModuleConfigVersion | undefined>;
+  effective(moduleKey: string): Promise<ModuleConfigVersion | undefined>;
+  find(
+    moduleKey: string,
+    version: number,
+  ): Promise<ModuleConfigVersion | undefined>;
+  list(moduleKey: string): Promise<ModuleConfigVersion[]>;
+}
+
+export class InMemoryModuleConfigVersionRepository implements ModuleConfigVersionRepository {
+  private readonly versions: ModuleConfigVersion[] = [];
+
+  async begin(input: BeginConfigVersionInput): Promise<ModuleConfigVersion> {
+    const latest = await this.latest(input.moduleKey);
+    const version: ModuleConfigVersion = {
+      id: randomUUIDv7(),
+      moduleKey: input.moduleKey,
+      version: (latest?.version || 0) + 1,
+      values: { ...input.values },
+      diff: input.diff.map((entry) => ({ ...entry })),
+      applyStatus: "applying",
+      rollbackOfVersion: input.rollbackOfVersion,
+      reason: input.reason,
+      createdAt: new Date().toISOString(),
+      createdBy: input.actorId,
+    };
+    this.versions.push(version);
+    return cloneVersion(version);
+  }
+
+  async markEffective(
+    id: string,
+    appliedAt: Date,
+  ): Promise<ModuleConfigVersion> {
+    const version = this.required(id);
+    for (const candidate of this.versions) {
+      if (
+        candidate.moduleKey === version.moduleKey &&
+        candidate.applyStatus === "effective"
+      ) {
+        candidate.applyStatus = "superseded";
+      }
+    }
+    version.applyStatus = "effective";
+    version.applyError = undefined;
+    version.appliedAt = appliedAt.toISOString();
+    return cloneVersion(version);
+  }
+
+  async markFailed(
+    id: string,
+    applyError: string,
+    appliedAt: Date,
+  ): Promise<ModuleConfigVersion> {
+    const version = this.required(id);
+    version.applyStatus = "failed";
+    version.applyError = applyError;
+    version.appliedAt = appliedAt.toISOString();
+    return cloneVersion(version);
+  }
+
+  async latest(moduleKey: string): Promise<ModuleConfigVersion | undefined> {
+    return this.sorted(moduleKey)[0];
+  }
+
+  async effective(moduleKey: string): Promise<ModuleConfigVersion | undefined> {
+    return this.sorted(moduleKey).find(
+      (version) => version.applyStatus === "effective",
+    );
+  }
+
+  async find(
+    moduleKey: string,
+    version: number,
+  ): Promise<ModuleConfigVersion | undefined> {
+    const found = this.versions.find(
+      (candidate) =>
+        candidate.moduleKey === moduleKey && candidate.version === version,
+    );
+    return found ? cloneVersion(found) : undefined;
+  }
+
+  async list(moduleKey: string): Promise<ModuleConfigVersion[]> {
+    return this.sorted(moduleKey);
+  }
+
+  private sorted(moduleKey: string): ModuleConfigVersion[] {
+    return this.versions
+      .filter((version) => version.moduleKey === moduleKey)
+      .sort((left, right) => right.version - left.version)
+      .map(cloneVersion);
+  }
+
+  private required(id: string): ModuleConfigVersion {
+    const version = this.versions.find((candidate) => candidate.id === id);
+    if (!version) throw new Error("配置版本不存在");
+    return version;
+  }
+}
+
+export function cloneVersion(
+  version: ModuleConfigVersion,
+): ModuleConfigVersion {
+  return {
+    ...version,
+    values: { ...version.values },
+    diff: version.diff.map((entry) => ({ ...entry })),
+  };
+}
+
+export function isApplyStatus(value: string): value is ModuleConfigApplyStatus {
+  return ["applying", "effective", "failed", "superseded"].includes(value);
+}

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

@@ -0,0 +1,178 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import type { RouteApp } from "../system/route-types.js";
+import type { ManagedModuleConfigDefinition } from "./definition.js";
+import { InMemoryModuleConfigVersionRepository } from "./repository.js";
+import { registerModuleConfigurationRoutes } from "./routes.js";
+import { ModuleConfigurationService } from "./service.js";
+
+class FakeRouteApp implements Pick<RouteApp, "get" | "post"> {
+  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);
+  }
+
+  invoke(method: "GET" | "POST", path: string, context: unknown): unknown {
+    const handler = this.handlers.get(`${method} ${path}`);
+    if (!handler) throw new Error(`未注册路由 ${method} ${path}`);
+    return handler(context);
+  }
+}
+
+describe("模块配置路由", () => {
+  test("读取与管理权限分别受 RBAC 和 Feature 保护", async () => {
+    const fixture = createFixture(readActor());
+    const readable = await fixture.app.invoke(
+      "GET",
+      "/system/configurations",
+      fixture.context,
+    );
+    const denied = (await fixture.app.invoke(
+      "POST",
+      "/system/configurations/:moduleKey/versions",
+      {
+        ...fixture.context,
+        body: { values: { enabled: true } },
+        params: { moduleKey: "test.runtime" },
+      },
+    )) as Response;
+
+    expect(readable).toEqual(expect.any(Array));
+    expect(denied.status).toBe(403);
+  });
+
+  test("变更和回滚只记录字段路径并创建新版本", async () => {
+    const fixture = createFixture(manageActor());
+    const createPath = "/system/configurations/:moduleKey/versions";
+    const first = await fixture.app.invoke("POST", createPath, {
+      ...fixture.context,
+      body: { values: { enabled: true }, reason: "启用受控测试能力" },
+      params: { moduleKey: "test.runtime" },
+    });
+    await fixture.app.invoke("POST", createPath, {
+      ...fixture.context,
+      body: { values: { enabled: false }, reason: "临时关闭测试能力" },
+      params: { moduleKey: "test.runtime" },
+    });
+    const rollback = await fixture.app.invoke(
+      "POST",
+      "/system/configurations/:moduleKey/versions/:version/rollback",
+      {
+        ...fixture.context,
+        body: { reason: "恢复已经验证的稳定版本" },
+        params: { moduleKey: "test.runtime", version: "1" },
+      },
+    );
+
+    expect(first).toMatchObject({ version: 1, values: { enabled: true } });
+    expect(rollback).toMatchObject({
+      version: 3,
+      rollbackOfVersion: 1,
+      values: { enabled: true },
+    });
+    const audit = JSON.stringify(fixture.runtime.auditSink.list());
+    expect(audit).toContain("changedPaths");
+    expect(audit).toContain("config.rollback");
+    expect(audit).not.toContain('"values"');
+    expect(audit).not.toContain("SecretRef");
+  });
+
+  test("未注册字段被 strict schema 拒绝且不进入版本记录", async () => {
+    const fixture = createFixture(manageActor());
+    const response = (await fixture.app.invoke(
+      "POST",
+      "/system/configurations/:moduleKey/versions",
+      {
+        ...fixture.context,
+        body: {
+          values: { enabled: true, databaseUrl: "secret-value-marker" },
+        },
+        params: { moduleKey: "test.runtime" },
+      },
+    )) as Response;
+
+    expect(response.status).toBe(400);
+    expect(await fixture.service.list("test.runtime")).toEqual([]);
+    expect(JSON.stringify(await response.json())).not.toContain(
+      "secret-value-marker",
+    );
+  });
+});
+
+function createFixture(actor: RequestActor) {
+  const app = new FakeRouteApp();
+  const runtime = createServerRuntime({ NODE_ENV: "test" });
+  const definition: ManagedModuleConfigDefinition = {
+    moduleKey: "test.runtime",
+    label: "测试配置",
+    fields: [
+      {
+        path: "enabled",
+        label: "启用",
+        description: "测试开关",
+        input: "boolean",
+      },
+    ],
+    validate(values) {
+      if (
+        !values ||
+        typeof values !== "object" ||
+        Array.isArray(values) ||
+        Object.keys(values).some((key) => key !== "enabled") ||
+        typeof (values as Record<string, unknown>).enabled !== "boolean"
+      ) {
+        throw new Error("INVALID_VALUES");
+      }
+      return { enabled: (values as Record<string, boolean>).enabled };
+    },
+    apply() {},
+    baseValues: () => ({ enabled: false }),
+  };
+  const service = new ModuleConfigurationService(
+    new InMemoryModuleConfigVersionRepository(),
+    [definition],
+  );
+  registerModuleConfigurationRoutes(
+    app,
+    service,
+    runtime,
+    createFoundationSnapshot().features,
+  );
+  const guardContext: RequestGuardContext = {
+    requestId: "request-config-test",
+    actor,
+    startedAt: new Date().toISOString(),
+  };
+  return {
+    app,
+    runtime,
+    service,
+    context: { guardContext, body: undefined, params: {}, query: {} },
+  };
+}
+
+function readActor(): RequestActor {
+  return {
+    id: "reader",
+    type: "user",
+    name: "配置查看员",
+    roleCodes: ["reader"],
+    permissionKeys: ["system.config.read"],
+  };
+}
+
+function manageActor(): RequestActor {
+  return {
+    ...readActor(),
+    id: "manager",
+    name: "配置管理员",
+    permissionKeys: ["system.config.read", "system.config.manage"],
+  };
+}