create-windy 0.2.34 → 0.3.0

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

@@ -81,6 +81,106 @@ describe("模块配置版本服务", () => {
     expect(serialized).not.toContain("secret-value-marker");
     expect(serialized).not.toContain("SecretRef");
   });
+
+  test("重启字段保存为等待状态并在下一次启动提升为生效版本", async () => {
+    const repository = new InMemoryModuleConfigVersionRepository();
+    const current = { host: "old.smtp.local" };
+    const definition: ManagedModuleConfigDefinition = {
+      moduleKey: "mail.runtime",
+      label: "邮件传输配置",
+      fields: [
+        {
+          path: "host",
+          label: "SMTP 主机",
+          description: "重启后应用",
+          input: "text",
+          applyMode: "restart",
+        },
+      ],
+      validate(values) {
+        const input = values as Record<string, unknown>;
+        return { host: String(input.host || current.host) };
+      },
+      apply(values) {
+        current.host = values.host as string;
+      },
+      baseValues: () => ({ ...current }),
+    };
+    const service = new ModuleConfigurationService(repository, [definition]);
+
+    const created = await service.create(
+      "mail.runtime",
+      { host: "new.smtp.local" },
+      "user-1",
+    );
+
+    expect(created).toMatchObject({
+      ok: true,
+      version: { applyStatus: "pending-restart" },
+    });
+    expect(current.host).toBe("old.smtp.local");
+
+    const replacement = await service.create(
+      "mail.runtime",
+      { host: "corrected.smtp.local" },
+      "user-1",
+    );
+    expect(replacement).toMatchObject({
+      ok: true,
+      version: { version: 2, applyStatus: "pending-restart" },
+    });
+    expect((await service.summaries())[0]?.pendingValues).toEqual({
+      host: "corrected.smtp.local",
+    });
+    expect(
+      (await service.list("mail.runtime"))?.map((item) => item.applyStatus),
+    ).toEqual(["pending-restart", "superseded"]);
+
+    await new ModuleConfigurationService(repository, [definition]).initialize();
+
+    expect(current.host).toBe("corrected.smtp.local");
+    expect((await repository.latest("mail.runtime"))?.applyStatus).toBe(
+      "effective",
+    );
+  });
+
+  test("旧版本缺少新增字段时使用当前基线补齐", async () => {
+    const current = { enabled: false, timeoutMs: 300 };
+    const schema = z.strictObject({
+      enabled: z.boolean(),
+      timeoutMs: z.number().int(),
+    });
+    const definition: ManagedModuleConfigDefinition = {
+      moduleKey: "compatible.runtime",
+      label: "兼容配置",
+      fields: [],
+      validate(values) {
+        return schema.parse({
+          ...current,
+          ...(values as Record<string, unknown>),
+        });
+      },
+      apply(values) {
+        current.enabled = values.enabled as boolean;
+        current.timeoutMs = values.timeoutMs as number;
+      },
+      baseValues: () => ({ ...current }),
+    };
+    const repository = new InMemoryModuleConfigVersionRepository();
+    const version = await repository.begin({
+      moduleKey: definition.moduleKey,
+      values: { enabled: true },
+      diff: [],
+      actorId: "legacy",
+    });
+    await repository.markEffective(version.id, new Date());
+    const service = new ModuleConfigurationService(repository, [definition]);
+
+    await service.initialize();
+
+    expect(current).toEqual({ enabled: true, timeoutMs: 300 });
+    expect((await service.summaries())[0]?.effectiveValues).toEqual(current);
+  });
 });
 
 function createFixture(failApply = false) {

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

@@ -36,14 +36,21 @@ export class ModuleConfigurationService {
 
   async initialize(): Promise<void> {
     for (const definition of this.definitions.values()) {
-      const effective = await this.repository.effective(definition.moduleKey);
-      if (!effective) continue;
+      const latest = await this.repository.latest(definition.moduleKey);
+      const candidate =
+        latest?.applyStatus === "pending-restart"
+          ? latest
+          : await this.repository.effective(definition.moduleKey);
+      if (!candidate) continue;
       try {
-        const values = definition.validate(effective.values);
+        const values = definition.validate(candidate.values);
         await definition.apply(values);
+        if (candidate.applyStatus === "pending-restart") {
+          await this.repository.markEffective(candidate.id, new Date());
+        }
       } catch (error) {
         await this.repository.markFailed(
-          effective.id,
+          candidate.id,
           sanitizeApplyError(error),
           new Date(),
         );
@@ -62,9 +69,13 @@ export class ModuleConfigurationService {
           moduleKey: definition.moduleKey,
           label: definition.label,
           fields: definition.fields.map((field) => ({ ...field })),
-          effectiveValues: {
-            ...(effective?.values || definition.baseValues()),
-          },
+          effectiveValues: definition.validate(
+            effective?.values || definition.baseValues(),
+          ),
+          pendingValues:
+            latest?.applyStatus === "pending-restart"
+              ? definition.validate(latest.values)
+              : undefined,
           effectiveSource: effective ? "version" : "environment",
           effectiveVersion: effective?.version,
           latestVersion: latest?.version,
@@ -129,16 +140,33 @@ export class ModuleConfigurationService {
     reason?: string,
     rollbackOfVersion?: number,
   ): Promise<ConfigVersionResult> {
-    const effective = await this.repository.effective(definition.moduleKey);
-    const before = effective?.values || definition.baseValues();
+    const [effective, latest] = await Promise.all([
+      this.repository.effective(definition.moduleKey),
+      this.repository.latest(definition.moduleKey),
+    ]);
+    const before = definition.validate(
+      latest?.applyStatus === "pending-restart"
+        ? latest.values
+        : effective?.values || definition.baseValues(),
+    );
+    const diff = configDiff(before, values);
     const version = await this.repository.begin({
       moduleKey: definition.moduleKey,
       values,
-      diff: configDiff(before, values),
+      diff,
       rollbackOfVersion,
       reason,
       actorId,
     });
+    if (
+      latest?.applyStatus === "pending-restart" ||
+      requiresRestart(definition, diff)
+    ) {
+      return {
+        ok: true,
+        version: await this.repository.markPendingRestart(version.id),
+      };
+    }
     try {
       await definition.apply(values);
       return {
@@ -158,6 +186,18 @@ export class ModuleConfigurationService {
   }
 }
 
+function requiresRestart(
+  definition: ManagedModuleConfigDefinition,
+  diff: ModuleConfigDiffEntry[],
+): boolean {
+  const restartPaths = new Set(
+    definition.fields
+      .filter((field) => field.applyMode === "restart")
+      .map((field) => field.path),
+  );
+  return diff.some((entry) => restartPaths.has(entry.path));
+}
+
 export function configDiff(
   before: ModuleConfigValues,
   after: ModuleConfigValues,

package/template/apps/server/src/data-access/scoped-repository.integration.test.ts

@@ -133,9 +133,10 @@ function createRepositories(pool: Pool) {
 async function seedDepartments(
   repository: ReturnType<typeof createRepositories>["departments"],
 ) {
-  await repository.create(department("dept_a"), setupActor);
+  await repository.create(department("org_root"), setupActor);
+  await repository.create(department("dept_a", "org_root"), setupActor);
   await repository.create(department("dept_a_child", "dept_a"), setupActor);
-  await repository.create(department("dept_b"), setupActor);
+  await repository.create(department("dept_b", "org_root"), setupActor);
 }
 
 async function seedUsers(

package/template/apps/server/src/data-governance/export/service.ts

@@ -1,6 +1,6 @@
 import type { GovernedExportQuerySnapshot } from "@southwind-ai/database";
 import type { AuditEvent } from "@southwind-ai/shared";
-import type { RequestGuardContext } from "../../guards.js";
+import { auditActor, type RequestGuardContext } from "../../guards.js";
 import {
   DurableArtifactError,
   type DurableArtifactService,
@@ -310,11 +310,7 @@ function event(
     id: Bun.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: "system.user.governed-export", id },
     requestId: context.requestId,
     metadata,

package/template/apps/server/src/example-modules.ts

@@ -17,6 +17,7 @@ import { createWorkOrderRepository } from "./work-order/repository.js";
 import { createDrizzleWorkOrderRepository } from "./work-order/drizzle-repository.js";
 import { createWorkOrderRouteDefinitions } from "./work-order/routes.js";
 import { WorkOrderSearchProvider } from "./work-order/search-provider.js";
+import { createWorkOrderOpenSearchIndex } from "./work-order/opensearch-index.js";
 import { WorkOrderService } from "./work-order/service.js";
 
 export interface WorkOrderModuleDependencies {
@@ -42,6 +43,7 @@ export interface WorkOrderModule {
  */
 export function createWorkOrderModule(): WorkOrderModule {
   let service: WorkOrderService | undefined;
+  const searchIndex = createWorkOrderOpenSearchIndex(process.env);
   const requireService = () => {
     if (!service) throw new Error("示例工单模块尚未挂载");
     return service;
@@ -52,7 +54,7 @@ export function createWorkOrderModule(): WorkOrderModule {
       requireService().operationalSnapshot(
         platformDataActor("task_work_order_snapshot", "工单运营快照任务"),
       ),
-    searchProvider: new WorkOrderSearchProvider(requireService),
+    searchProvider: new WorkOrderSearchProvider(requireService, searchIndex),
   });
   return {
     ...serverModule,
@@ -67,6 +69,7 @@ export function createWorkOrderModule(): WorkOrderModule {
             ? createDrizzleWorkOrderRepository(dependencies.db)
             : createWorkOrderRepository()),
         dependencies.departments,
+        searchIndex,
       );
     },
   };

package/template/apps/server/src/guards.ts

@@ -1,5 +1,6 @@
 import type {
   ApiPermissionBinding,
+  AuditActor,
   AuditEvent,
   EntitlementKey,
   FeatureFlagDefinition,
@@ -33,6 +34,7 @@ export interface RequestGuardContext {
   actor: RequestActor;
   startedAt: string;
   clientIp?: string;
+  userAgent?: string;
   license?: {
     versionKey?: LicenseVersionKey;
     /** V1 兼容字段。新 License 不再包含 Entitlement。 */
@@ -61,6 +63,7 @@ export interface GuardDecision {
 
 export interface RequestGuardContextOptions {
   clientIp?: string;
+  userAgent?: string;
   resolveActor?: (request: Request) => RequestActor | undefined;
   resolveLicense?: (
     request: Request,
@@ -86,10 +89,24 @@ export function createRequestGuardContext(
     actor: options.resolveActor?.(request) || anonymousActor(),
     startedAt: new Date().toISOString(),
     clientIp: options.clientIp,
+    userAgent: options.userAgent,
     license: options.resolveLicense?.(request),
   };
 }
 
+export function auditActor(
+  context: Pick<RequestGuardContext, "actor" | "clientIp" | "userAgent">,
+): AuditActor {
+  return {
+    id: context.actor.id,
+    type: context.actor.type === "anonymous" ? "user" : context.actor.type,
+    name: context.actor.name,
+    roleCodes: context.actor.roleCodes,
+    ip: context.clientIp,
+    userAgent: context.userAgent,
+  };
+}
+
 export function evaluatePermissionGuard(
   context: RequestGuardContext,
   binding: PermissionGuardRequirement,
@@ -207,11 +224,7 @@ function deniedDecision(
       id: randomUUIDv7(),
       action: "security.denied",
       outcome: "denied",
-      actor: {
-        id: context.actor.id,
-        type: context.actor.type === "anonymous" ? "user" : context.actor.type,
-        name: context.actor.name,
-      },
+      actor: auditActor(context),
       target: {
         type: "guard",
         id: targetId,

package/template/apps/server/src/http/request-source.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import {
+  requestSourcePolicyFromEnv,
+  resolveRequestSource,
+} from "./request-source.js";
+
+describe("平台请求来源信任边界", () => {
+  test("默认使用直接对端并忽略客户端伪造的转发头", () => {
+    const source = resolveRequestSource(
+      request("203.0.113.66"),
+      "198.51.100.10",
+      requestSourcePolicyFromEnv({}),
+    );
+
+    expect(source).toEqual({
+      clientIp: "198.51.100.10",
+      userAgent: "Windy-Test/1.0",
+    });
+  });
+
+  test("仅显式启用且直接对端受信时采用单一合法转发来源", () => {
+    const policy = requestSourcePolicyFromEnv({
+      WINDY_TRUST_PROXY: "true",
+      WINDY_TRUSTED_PROXY_IPS: "10.0.0.8",
+    });
+
+    expect(
+      resolveRequestSource(request("203.0.113.66"), "::1", policy).clientIp,
+    ).toBe("203.0.113.66");
+    expect(
+      resolveRequestSource(request("203.0.113.67"), "10.0.0.8", policy)
+        .clientIp,
+    ).toBe("203.0.113.67");
+    expect(
+      resolveRequestSource(request("203.0.113.68"), "10.0.0.9", policy)
+        .clientIp,
+    ).toBe("10.0.0.9");
+  });
+
+  test("多段或非法转发来源退回直接对端", () => {
+    const policy = requestSourcePolicyFromEnv({
+      WINDY_TRUST_PROXY: "true",
+    });
+    for (const forwardedFor of [
+      "203.0.113.66, 198.51.100.9",
+      "not-an-ip",
+      "203.0.113.66:443",
+    ]) {
+      expect(
+        resolveRequestSource(request(forwardedFor), "127.0.0.1", policy)
+          .clientIp,
+      ).toBe("127.0.0.1");
+    }
+  });
+
+  test("代理配置默认关闭且错误配置 fail closed", () => {
+    expect(requestSourcePolicyFromEnv({})).toEqual({
+      trustProxy: false,
+      trustedProxyIps: [],
+    });
+    expect(() =>
+      requestSourcePolicyFromEnv({
+        WINDY_TRUSTED_PROXY_IPS: "10.0.0.8",
+      }),
+    ).toThrow("WINDY_TRUST_PROXY=true");
+    expect(() =>
+      requestSourcePolicyFromEnv({ WINDY_TRUST_PROXY: "yes" }),
+    ).toThrow("只允许 true 或 false");
+    expect(() =>
+      requestSourcePolicyFromEnv({
+        WINDY_TRUST_PROXY: "true",
+        WINDY_TRUSTED_PROXY_IPS: "10.0.0.999",
+      }),
+    ).toThrow("无效 IP");
+  });
+});
+
+function request(forwardedFor: string): Request {
+  return new Request("https://windy.example.test/api/system/users", {
+    headers: {
+      "user-agent": "Windy-Test/1.0",
+      "x-forwarded-for": forwardedFor,
+    },
+  });
+}

package/template/apps/server/src/http/request-source.ts

@@ -0,0 +1,90 @@
+import { isIP } from "node:net";
+
+export interface RequestSourcePolicy {
+  trustProxy: boolean;
+  trustedProxyIps: readonly string[];
+}
+
+export interface RequestSource {
+  clientIp?: string;
+  userAgent?: string;
+}
+
+export function requestSourcePolicyFromEnv(
+  env: Record<string, string | undefined>,
+): RequestSourcePolicy {
+  const trustProxy = readBoolean(env.WINDY_TRUST_PROXY);
+  const configuredIps = (env.WINDY_TRUSTED_PROXY_IPS || "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (!trustProxy && configuredIps.length) {
+    throw new Error(
+      "配置 WINDY_TRUSTED_PROXY_IPS 时必须显式设置 WINDY_TRUST_PROXY=true",
+    );
+  }
+  return {
+    trustProxy,
+    trustedProxyIps: configuredIps.map((value) => {
+      const normalized = normalizeIp(value);
+      if (!normalized) {
+        throw new Error(`WINDY_TRUSTED_PROXY_IPS 包含无效 IP：${value}`);
+      }
+      return normalized;
+    }),
+  };
+}
+
+export function resolveRequestSource(
+  request: Request,
+  peerIp: string | undefined,
+  policy: RequestSourcePolicy,
+): RequestSource {
+  const normalizedPeerIp = normalizeIp(peerIp);
+  const forwardedIp = resolveForwardedIp(request, normalizedPeerIp, policy);
+  return {
+    clientIp: forwardedIp || normalizedPeerIp,
+    userAgent: normalizeUserAgent(request.headers.get("user-agent")),
+  };
+}
+
+function resolveForwardedIp(
+  request: Request,
+  peerIp: string | undefined,
+  policy: RequestSourcePolicy,
+): string | undefined {
+  if (!policy.trustProxy || !peerIp || !isTrustedProxy(peerIp, policy)) {
+    return undefined;
+  }
+  const header = request.headers.get("x-forwarded-for")?.trim();
+  if (!header || header.includes(",")) return undefined;
+  return normalizeIp(header);
+}
+
+function isTrustedProxy(peerIp: string, policy: RequestSourcePolicy): boolean {
+  if (isLoopback(peerIp)) return true;
+  return policy.trustedProxyIps.some((value) => normalizeIp(value) === peerIp);
+}
+
+function isLoopback(ip: string): boolean {
+  return ip === "::1" || (isIP(ip) === 4 && ip.startsWith("127."));
+}
+
+function normalizeIp(value: string | undefined): string | undefined {
+  const candidate = value?.trim().toLowerCase();
+  if (!candidate) return undefined;
+  const mapped = candidate.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)?.[1];
+  const normalized = mapped && isIP(mapped) === 4 ? mapped : candidate;
+  return isIP(normalized) ? normalized : undefined;
+}
+
+function normalizeUserAgent(value: string | null): string | undefined {
+  const normalized = value?.trim();
+  return normalized ? normalized.slice(0, 1_024) : undefined;
+}
+
+function readBoolean(value: string | undefined): boolean {
+  if (value === undefined || value === "" || value === "false") return false;
+  if (value === "true") return true;
+  throw new Error("WINDY_TRUST_PROXY 只允许 true 或 false");
+}

package/template/apps/server/src/index.ts

@@ -141,7 +141,11 @@ platformLicenseRuntime.setAuditSink(runtime.auditSink);
 // @windy-module system.license end
 const { authRepository, authService } = createAuthRuntime({
   repository: persistence?.authRepository,
-  sessionTtlSeconds: platformConfig.security.sessionTtlSeconds,
+  sessionTtlSeconds: () => platformConfig.security.sessionTtlSeconds,
+  passwordPolicy: () => ({
+    minLength: platformConfig.security.passwordMinLength,
+    maxLength: platformConfig.security.passwordMaxLength,
+  }),
   auditWriter: (event) => runtime.auditSink.recordCriticalEvent(event),
   // @windy-module system.audit begin
   auditReader: persistence?.auditReader,
@@ -153,12 +157,17 @@ const storageRuntime = createStorageRuntime(
   persistence?.db,
   moduleHosts.uploadPolicies,
 );
+configurationRuntime.bindStorage(storageRuntime.uploads);
 // @windy-module system.storage end
 // @windy-module system.settings begin
-const platformSettings = createPlatformSettingsRuntime(persistence?.db, {
-  softwareName: platformConfig.name,
-  logoUrl: platformConfig.logoUrl,
-});
+const platformSettings = createPlatformSettingsRuntime(
+  persistence?.db,
+  {
+    softwareName: platformConfig.name,
+    logoUrl: platformConfig.logoUrl,
+  },
+  () => ({ timeZone: platformConfig.regional.timeZone }),
+);
 // @windy-module system.settings end
 // @windy-module system.search begin
 const searchHost = createSearchHost(
@@ -177,6 +186,7 @@ const {
   scheduler,
   taskDefinitions: scheduledTaskDefinitions,
   notifications: notificationRepository,
+  notificationService,
   workflow: workflowService,
   governedExportService,
   durable: durableJobRuntime,
@@ -188,6 +198,7 @@ const {
   storage: storageRuntime,
   moduleTasks: moduleTaskDefinitions,
   bulkRetentionDays: readPositiveInt(process.env.BULK_DATA_RETENTION_DAYS, 7),
+  mailConfig: platformConfig.mail,
   installModuleDurableHandlers: moduleHosts.installDurableHandlers,
 });
 const schedulerWorker = new SchedulerWorker(
@@ -220,7 +231,13 @@ registerPlatformLicenseRoutes(app, platformLicenseRuntime);
 platformSettings.register(app, runtime, features);
 // @windy-module system.settings end
 // @windy-module system.notification begin
-registerNotificationRoutes(app, notificationRepository, runtime, features);
+registerNotificationRoutes(
+  app,
+  notificationRepository,
+  runtime,
+  features,
+  notificationService,
+);
 // @windy-module system.notification end
 // @windy-module system.workflow begin
 registerWorkflowRoutes(app, workflowService, runtime);

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

@@ -52,6 +52,8 @@ export function registerPlatformLicenseRoutes(
       const installed = await licenseRuntime.install(rawLicense, {
         actor: context.guardContext.actor,
         requestId: context.guardContext.requestId,
+        clientIp: context.guardContext.clientIp,
+        userAgent: context.guardContext.userAgent,
       });
       if (installed.result.status === "rejected") {
         return Response.json(

package/template/apps/server/src/license/runtime-service.ts

@@ -17,7 +17,11 @@ import type {
   LicenseFailureReason,
   SignedLicense,
 } from "@southwind-ai/shared";
-import type { RequestActor } from "../guards.js";
+import {
+  auditActor,
+  type RequestActor,
+  type RequestGuardContext,
+} from "../guards.js";
 import type { InMemoryAuditSink } from "../runtime.js";
 import type {
   LicenseEntitlementResolver,
@@ -57,10 +61,10 @@ export interface PlatformLicenseRuntimeOptions {
   now?: () => Date;
 }
 
-export interface LicenseInstallActorContext {
-  actor: RequestActor;
-  requestId: string;
-}
+export type LicenseInstallActorContext = Pick<
+  RequestGuardContext,
+  "actor" | "requestId" | "clientIp" | "userAgent"
+>;
 
 export class PlatformLicenseRuntime implements LicenseEntitlementResolver {
   private readonly stateStorage: LicenseStorage;
@@ -285,12 +289,7 @@ function installAuditEvent(
     id: crypto.randomUUID(),
     action: "license.update",
     outcome: success ? "success" : "failure",
-    actor: {
-      id: context.actor.id,
-      type: "user",
-      name: context.actor.name,
-      roleCodes: context.actor.roleCodes,
-    },
+    actor: auditActor(context),
     target: {
       type: "runtime-license",
       id: result.license?.claims.licenseId || candidate?.claims.licenseId,

package/template/apps/server/src/module-bootstrap.ts

@@ -17,7 +17,7 @@ import {
 } from "./module-host.js";
 import type { ServerPersistence } from "./persistence.js";
 // @windy-module system.storage begin
-import { platformUploadPolicies } from "./storage/runtime.js";
+import { createPlatformUploadPolicies } from "./storage/runtime.js";
 // @windy-module system.storage end
 import {
   createSystemRepositories,
@@ -51,7 +51,7 @@ export async function bootstrapServerModules(
     installations: installedBusinessModules,
     baseUploadPolicies: [
       // @windy-module system.storage begin
-      ...platformUploadPolicies,
+      ...createPlatformUploadPolicies(platformConfig),
       // @windy-module system.storage end
     ],
   });

package/template/apps/server/src/module-host/request-context.ts

@@ -15,7 +15,11 @@ import {
 } from "@southwind-ai/server-sdk";
 import type { AuditEvent } from "@southwind-ai/shared";
 import type { ModuleManifest } from "@southwind-ai/modules";
-import type { RequestActor, RequestGuardContext } from "../guards.js";
+import {
+  auditActor,
+  type RequestActor,
+  type RequestGuardContext,
+} from "../guards.js";
 import type { createServerRuntime } from "../runtime.js";
 import { unavailableModuleStoragePort } from "./storage-port.js";
 
@@ -130,11 +134,7 @@ function buildAuditEvent(
     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: input.target,
     requestId: context.requestId,
     metadata: input.metadata,