create-windy 0.2.33 → 0.3.0

package/template/apps/server/src/notification/smtp-adapter.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import type { Transporter } from "nodemailer";
+import {
+  NotificationChannelError,
+  type NotificationChannelMessage,
+} from "./channel-adapter.js";
+import { SmtpNotificationChannelAdapter } from "./smtp-adapter.js";
+
+describe("SmtpNotificationChannelAdapter", () => {
+  test("使用类型化 mail 配置发件且不向消息暴露 smtpUrl", async () => {
+    const sent: unknown[] = [];
+    const transporter = {
+      async sendMail(message: unknown) {
+        sent.push(message);
+        return { messageId: "mail-1" };
+      },
+    } as unknown as Transporter;
+    const adapter = new SmtpNotificationChannelAdapter(config, transporter);
+    expect(await adapter.deliver(message)).toEqual({
+      providerMessageId: "mail-1",
+    });
+    expect(sent[0]).toMatchObject({
+      from: "notify@example.com",
+      to: "user@example.com",
+      subject: "测试通知",
+      text: "正文",
+    });
+    expect(JSON.stringify(sent[0])).not.toContain("smtp://");
+  });
+
+  test("认证错误标记为不可重试且只保留标准化错误码", async () => {
+    const transporter = {
+      async sendMail() {
+        throw Object.assign(new Error("包含服务端敏感响应"), { code: "EAUTH" });
+      },
+    } as unknown as Transporter;
+    const adapter = new SmtpNotificationChannelAdapter(config, transporter);
+    try {
+      await adapter.deliver(message);
+      throw new Error("expected rejection");
+    } catch (error) {
+      expect(error).toBeInstanceOf(NotificationChannelError);
+      expect(error).toMatchObject({ code: "EAUTH", retryable: false });
+      expect(String(error)).not.toContain("敏感响应");
+    }
+  });
+});
+
+const config = {
+  enabled: true,
+  host: "smtp.example.com",
+  port: 587,
+  secure: false,
+  fromAddress: "notify@example.com",
+  connectTimeoutMs: 5_000,
+  smtpUrl: "smtp://secret@example.com",
+};
+
+const message: NotificationChannelMessage = {
+  deliveryId: "delivery-1",
+  userId: "user-1",
+  address: "user@example.com",
+  subject: "测试通知",
+  content: "正文",
+};

package/template/apps/server/src/notification/smtp-adapter.ts

@@ -0,0 +1,68 @@
+import nodemailer from "nodemailer";
+import type { Transporter } from "nodemailer";
+import type { PlatformConfig } from "@southwind-ai/config";
+import {
+  NotificationChannelError,
+  type NotificationChannelAdapter,
+  type NotificationChannelMessage,
+} from "./channel-adapter.js";
+
+export class SmtpNotificationChannelAdapter implements NotificationChannelAdapter {
+  readonly channel = "email" as const;
+  private readonly transporter: Transporter;
+
+  constructor(
+    private readonly config: PlatformConfig["mail"],
+    transporter?: Transporter,
+  ) {
+    if (!config.enabled || !config.fromAddress) {
+      throw new Error("SMTP 通知渠道未启用或未配置发件地址");
+    }
+    this.transporter =
+      transporter ||
+      nodemailer.createTransport(
+        config.smtpUrl || {
+          host: config.host,
+          port: config.port,
+          secure: config.secure,
+          connectionTimeout: config.connectTimeoutMs,
+        },
+      );
+  }
+
+  async deliver(message: NotificationChannelMessage) {
+    try {
+      const result = await this.transporter.sendMail({
+        from: this.config.fromAddress,
+        to: message.address,
+        subject: message.subject,
+        text: message.content,
+        headers: { "X-Windy-Delivery-Id": message.deliveryId },
+      });
+      return { providerMessageId: result.messageId || undefined };
+    } catch (error) {
+      const code = smtpErrorCode(error);
+      throw new NotificationChannelError(code, isRetryableSmtpError(error));
+    }
+  }
+}
+
+function smtpErrorCode(error: unknown) {
+  if (!error || typeof error !== "object") return "SMTP_DELIVERY_FAILED";
+  const value = error as { code?: unknown; responseCode?: unknown };
+  const code =
+    typeof value.code === "string" ? value.code.toUpperCase() : undefined;
+  const responseCode =
+    typeof value.responseCode === "number" ? value.responseCode : undefined;
+  return (
+    code || (responseCode ? `SMTP_${responseCode}` : "SMTP_DELIVERY_FAILED")
+  );
+}
+
+function isRetryableSmtpError(error: unknown) {
+  if (!error || typeof error !== "object") return true;
+  const value = error as { code?: unknown; responseCode?: unknown };
+  if (typeof value.responseCode === "number")
+    return value.responseCode >= 400 && value.responseCode < 500;
+  return !["EAUTH", "EENVELOPE", "EMESSAGE"].includes(String(value.code || ""));
+}

package/template/apps/server/src/persistence.integration.test.ts

@@ -4,7 +4,10 @@ import { resolve } from "node:path";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { migrate } from "drizzle-orm/node-postgres/migrator";
 import { Pool } from "pg";
-import { DrizzleAuditLogWriter } from "./audit/drizzle-log-store.js";
+import {
+  DrizzleAuditLogReader,
+  DrizzleAuditLogWriter,
+} from "./audit/drizzle-log-store.js";
 
 const databaseUrl = process.env.AUDIT_TEST_DATABASE_URL;
 const describePostgres = databaseUrl ? describe : describe.skip;
@@ -12,6 +15,7 @@ const describePostgres = databaseUrl ? describe : describe.skip;
 describePostgres("PostgreSQL audit writer", () => {
   let pool: Pool;
   let writer: DrizzleAuditLogWriter;
+  let reader: DrizzleAuditLogReader;
 
   beforeAll(async () => {
     pool = new Pool({ connectionString: databaseUrl });
@@ -25,10 +29,13 @@ describePostgres("PostgreSQL audit writer", () => {
       migrationsTable: "__audit01_test_migrations",
     });
     writer = new DrizzleAuditLogWriter(db);
+    reader = new DrizzleAuditLogReader(db);
   });
 
   afterAll(async () => {
-    await pool?.query("delete from audit_logs where id = 'audit_pg_1'");
+    await pool?.query(
+      "delete from audit_logs where id in ('audit_pg_1', 'audit_pg_search_1')",
+    );
     await pool?.end();
   });
 
@@ -51,4 +58,36 @@ describePostgres("PostgreSQL audit writer", () => {
     );
     expect(result.rows[0]?.count).toBe("1");
   });
+
+  test("关键字与分钟范围在 PostgreSQL Reader 中共同生效", async () => {
+    await writer.write({
+      id: "audit_pg_search_1",
+      action: "case.review",
+      outcome: "success",
+      actor: {
+        id: "user_1",
+        type: "user",
+        name: "审计员",
+        ip: "203.0.113.8",
+      },
+      target: { type: "case", id: "case_1", label: "案件甲" },
+      module: "case-workbench",
+      requestId: "request_pg_1",
+      message: "完成复核",
+      metadata: { note: "线索已确认" },
+      occurredAt: "2026-07-20T01:15:30.000Z",
+    });
+
+    const result = await reader.list({
+      page: 1,
+      pageSize: 10,
+      q: "案件甲",
+      actorId: "user_1",
+      action: "case.review",
+      occurredAfter: "2026-07-20T01:15:00.000Z",
+      occurredBefore: "2026-07-20T01:15:59.999Z",
+    });
+
+    expect(result.items.map(({ id }) => id)).toContain("audit_pg_search_1");
+  });
 });

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

@@ -44,6 +44,7 @@ export function systemFeatureKeyForResource(resourceName: string): string {
     audit: "system.audit",
     license: "system.license",
     ops: "system.ops",
+    notification: "system.notification",
     scheduler: "system.scheduler",
     settings: "system.settings",
   };

package/template/apps/server/src/runtime-audit-list.test.ts

@@ -95,4 +95,43 @@ describe("server runtime audit list", () => {
     expect(hidden.items.map(({ id }) => id)).toEqual(["audit_user"]);
     expect(included.total).toBe(2);
   });
+
+  test("无数据库时关键字覆盖动作、操作者、对象、IP 和已脱敏上下文", async () => {
+    const runtime = createServerRuntime();
+    runtime.auditSink.recordEvent({
+      id: "audit_keyword",
+      action: "case.review",
+      outcome: "success",
+      actor: {
+        id: "user_1",
+        type: "user",
+        name: "审计员",
+        ip: "203.0.113.8",
+      },
+      target: { type: "case", id: "case_1", label: "案件甲" },
+      module: "case-workbench",
+      requestId: "request_1",
+      message: "完成复核",
+      metadata: { note: "线索已确认", token: "[REDACTED]" },
+      occurredAt: "2026-07-14T01:00:00.000Z",
+    });
+
+    for (const q of [
+      "case.review",
+      "审计员",
+      "案件甲",
+      "203.0.113.8",
+      "完成复核",
+      "case-workbench",
+      "request_1",
+      "线索已确认",
+    ]) {
+      const result = await runtime.listAuditEvents({
+        page: 1,
+        pageSize: 10,
+        q,
+      });
+      expect(result.items.map(({ id }) => id)).toEqual(["audit_keyword"]);
+    }
+  });
 });

package/template/apps/server/src/runtime-development.ts

@@ -25,6 +25,7 @@ export function developmentAdminActor(): RequestActor {
       "system.menu.read",
       "system.user.read",
       "system.user.manage",
+      "system.user-directory.read",
       "system.role.read",
       "system.role.manage",
       "system.department.read",
@@ -51,6 +52,7 @@ export function developmentAdminActor(): RequestActor {
       "system.scheduler.read",
       "system.scheduler.manage",
       "system.notification.read",
+      "system.notification.update",
       "system.notification.manage",
       "system.bulk-data.manage",
       "system.storage.read",

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

@@ -7,6 +7,7 @@ import {
   type FeatureFlagDefinition,
 } from "@southwind-ai/shared";
 import { createFoundationSnapshot } from "./foundation.js";
+import { auditActor } from "./guards.js";
 import { createServerRuntime } from "./runtime.js";
 import { AuditWriteUnavailableError } from "./audit/contracts.js";
 
@@ -136,30 +137,43 @@ describe("server runtime", () => {
   });
 
   test("外部 actor resolver 优先提供数据库角色权限来源", async () => {
+    const sessionActor = {
+      id: "user_from_db",
+      type: "user" as const,
+      name: "数据库用户",
+      roleCodes: ["operator"],
+      permissionKeys: ["system.audit.read"],
+    };
     const runtime = createServerRuntime(
       { WINDY_DEV_ADMIN_TOKEN: "token_1" },
       {
         actorResolver: {
           async resolve() {
-            return {
-              id: "user_from_db",
-              type: "user",
-              name: "数据库用户",
-              roleCodes: ["operator"],
-              permissionKeys: ["system.audit.read"],
-            };
+            return sessionActor;
           },
         },
       },
     );
     const request = new Request("http://localhost/api/system/audit-logs", {
-      headers: { authorization: "Bearer token_1" },
+      headers: {
+        authorization: "Bearer token_1",
+        "user-agent": "Windy-Audit-Test/1.0",
+        "x-forwarded-for": "203.0.113.99",
+      },
     });
 
-    const context = await runtime.createGuardContext(request);
+    const context = await runtime.createGuardContext(request, {
+      clientIp: "198.51.100.10",
+    });
 
     expect(context.actor.id).toBe("user_from_db");
     expect(context.actor.permissionKeys).toEqual(["system.audit.read"]);
+    expect(auditActor(context)).toMatchObject({
+      ip: "198.51.100.10",
+      userAgent: "Windy-Audit-Test/1.0",
+    });
+    expect(sessionActor).not.toHaveProperty("ip");
+    expect(sessionActor).not.toHaveProperty("userAgent");
   });
 
   test("外部 license resolver 优先提供真实 License 授权状态", async () => {

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

@@ -27,6 +27,10 @@ import {
   type FeatureFlagRuntimeResolver,
   type ResolvedFeatureFlag,
 } from "./runtime-feature.js";
+import {
+  requestSourcePolicyFromEnv,
+  resolveRequestSource,
+} from "./http/request-source.js";
 
 export type {
   FeatureFlagRuntimeResolver,
@@ -53,6 +57,7 @@ export interface AuditEventWriter {
 export interface AuditEventListQuery {
   page: number;
   pageSize: number;
+  q?: string;
   actorId?: string;
   action?: string;
   resource?: string;
@@ -198,6 +203,7 @@ export function createServerRuntime(
     options.featureResolver,
     env.NODE_ENV === "production",
   );
+  const requestSourcePolicy = requestSourcePolicyFromEnv(env);
 
   return {
     auditSink,
@@ -205,13 +211,18 @@ export function createServerRuntime(
       request: Request,
       metadata: { clientIp?: string } = {},
     ) {
+      const requestSource = resolveRequestSource(
+        request,
+        metadata.clientIp,
+        requestSourcePolicy,
+      );
       const actor =
         (await options.actorResolver?.resolve(request)) ||
         sessionStore.resolve(request);
       const license =
         (await options.licenseResolver?.resolve()) || licenseStore.resolve();
       return createRequestGuardContext(request, {
-        clientIp: metadata.clientIp,
+        ...requestSource,
         resolveActor: () => actor,
         resolveLicense: () => license,
       });
@@ -221,10 +232,15 @@ export function createServerRuntime(
       actor: RequestActor,
       metadata: { clientIp?: string } = {},
     ) {
+      const requestSource = resolveRequestSource(
+        request,
+        metadata.clientIp,
+        requestSourcePolicy,
+      );
       const license =
         (await options.licenseResolver?.resolve()) || licenseStore.resolve();
       return createRequestGuardContext(request, {
-        clientIp: metadata.clientIp,
+        ...requestSource,
         resolveActor: () => actor,
         resolveLicense: () => license,
       });
@@ -268,6 +284,7 @@ function matchesAuditQuery(
   query: AuditEventListQuery,
 ): boolean {
   return (
+    (!query.q || matchesAuditKeyword(event, query.q)) &&
     (!query.actorId || event.actor.id === query.actorId) &&
     (!query.action || event.action === query.action) &&
     (!query.resource || event.target?.type === query.resource) &&
@@ -277,3 +294,23 @@ function matchesAuditQuery(
     (!query.occurredBefore || event.occurredAt <= query.occurredBefore)
   );
 }
+
+function matchesAuditKeyword(event: AuditEvent, query: string): boolean {
+  const keyword = query.toLowerCase();
+  const values = [
+    event.action,
+    event.actor.id,
+    event.actor.name,
+    event.target?.type,
+    event.target?.id,
+    event.target?.label,
+    event.actor.ip,
+    event.message,
+    event.module,
+    event.requestId,
+    event.metadata ? JSON.stringify(event.metadata) : undefined,
+  ];
+  return values.some((value) =>
+    value === undefined ? false : String(value).toLowerCase().includes(keyword),
+  );
+}

package/template/apps/server/src/scheduler/audit.ts

@@ -1,6 +1,6 @@
 import { randomUUIDv7 } from "bun";
 import type { AuditEvent } from "@southwind-ai/shared";
-import type { RequestActor, RequestGuardContext } from "../guards.js";
+import { auditActor, type RequestGuardContext } from "../guards.js";
 import type { ScheduledTaskRun } from "./types.js";
 
 export function schedulerAuditEvent(
@@ -14,7 +14,7 @@ export function schedulerAuditEvent(
     id: randomUUIDv7(),
     action,
     outcome,
-    actor: auditActor(context.actor),
+    actor: auditActor(context),
     target: { type: "scheduled-task", id: run.taskKey },
     requestId: context.requestId,
     metadata: {
@@ -27,12 +27,3 @@ export function schedulerAuditEvent(
     occurredAt: occurredAt.toISOString(),
   };
 }
-
-function auditActor(actor: RequestActor): AuditEvent["actor"] {
-  return {
-    id: actor.id,
-    type: actor.type === "anonymous" ? "user" : actor.type,
-    name: actor.name,
-    roleCodes: actor.roleCodes,
-  };
-}

package/template/apps/server/src/scheduler/definitions.test.ts

@@ -13,6 +13,7 @@ describe("平台任务 Manifest Adapter", () => {
         storageCleanup: () => ({ deleted: 0 }),
         workflowTimeoutDispatch: () => ({ claimed: false }),
         governedExportDispatch: () => ({ claimed: false }),
+        notificationDispatch: () => ({ claimed: false }),
       },
     );
 
@@ -31,5 +32,10 @@ describe("平台任务 Manifest Adapter", () => {
         .find(({ key }) => key === "system.governed-export.dispatch")
         ?.isIdleResult?.({ claimed: false }),
     ).toBe(true);
+    expect(
+      definitions
+        .find(({ key }) => key === "system.notification.dispatch")
+        ?.isIdleResult?.({ claimed: false }),
+    ).toBe(true);
   });
 });

package/template/apps/server/src/scheduler/definitions.ts

@@ -8,6 +8,7 @@ export interface PlatformTaskHandlers {
   storageCleanup?: ScheduledTaskDefinition["handler"];
   workflowTimeoutDispatch?: ScheduledTaskDefinition["handler"];
   governedExportDispatch?: ScheduledTaskDefinition["handler"];
+  notificationDispatch?: ScheduledTaskDefinition["handler"];
 }
 
 export function createPlatformTaskDefinitions(
@@ -33,6 +34,11 @@ export function createPlatformTaskDefinitions(
       "system.governed-export.dispatch",
       handlers.governedExportDispatch,
     );
+  if (handlers.notificationDispatch)
+    handlerByKey.set(
+      "system.notification.dispatch",
+      handlers.notificationDispatch,
+    );
 
   return systemModuleManifests()
     .flatMap((module) => module.tasks)
@@ -49,6 +55,7 @@ export function createPlatformTaskDefinitions(
           isIdleResult:
             task.key === "system.bulk-data.dispatch" ||
             task.key === "system.workflow.timeout-dispatch" ||
+            task.key === "system.notification.dispatch" ||
             task.key === "system.governed-export.dispatch"
               ? (value) => value?.claimed === false
               : undefined,

package/template/apps/server/src/scheduler/recovery-service.ts

@@ -1,7 +1,7 @@
 import { randomUUIDv7 } from "bun";
 import type { AuditEvent } from "@southwind-ai/shared";
 import { runGuardedBackgroundTask } from "../background/task-guard.js";
-import type { RequestActor, RequestGuardContext } from "../guards.js";
+import { auditActor, type RequestGuardContext } from "../guards.js";
 import type { createServerRuntime } from "../runtime.js";
 import type { SchedulerRepository } from "./repository.js";
 import { sanitizeRecoveryReason } from "./sensitive-text.js";
@@ -116,7 +116,7 @@ function auditEvent(
     id: randomUUIDv7(),
     action: "task.recover",
     outcome,
-    actor: auditActor(context.actor),
+    actor: auditActor(context),
     target: { type: "scheduled-task-run", id: recovery.runId },
     requestId: context.requestId,
     message: phase === "intent" ? "人工恢复意图已确认" : "人工恢复状态转换结果",
@@ -141,12 +141,3 @@ function policy(definition: ScheduledTaskDefinition) {
     feature: definition.feature,
   };
 }
-
-function auditActor(actor: RequestActor): AuditEvent["actor"] {
-  return {
-    id: actor.id,
-    type: actor.type === "anonymous" ? "user" : actor.type,
-    name: actor.name,
-    roleCodes: actor.roleCodes,
-  };
-}

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

@@ -4,7 +4,7 @@ import type {
   FeatureFlagDefinition,
   HttpMethod,
 } from "@southwind-ai/shared";
-import type { RequestGuardContext } from "../guards.js";
+import { auditActor, type RequestGuardContext } from "../guards.js";
 import { evaluateRouteGuards, findSystemFeature } from "../route-guards.js";
 import type { createServerRuntime } from "../runtime.js";
 import { routeContext } from "../system/route-helpers.js";
@@ -209,12 +209,7 @@ function readAudit(context: RequestGuardContext, resource: string): AuditEvent {
     id: randomUUIDv7(),
     action: "task.read",
     outcome: "success",
-    actor: {
-      id: context.actor.id,
-      type: context.actor.type === "anonymous" ? "user" : context.actor.type,
-      name: context.actor.name,
-      roleCodes: context.actor.roleCodes,
-    },
+    actor: auditActor(context),
     target: { type: resource },
     requestId: context.requestId,
     occurredAt: new Date().toISOString(),

package/template/apps/server/src/search/opensearch-client.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { OpenSearchClient, readOpenSearchConfig } from "./opensearch-client.js";
+
+describe("OpenSearch Client 配置", () => {
+  test("未配置 URL 时保持默认无外部搜索依赖", () => {
+    expect(readOpenSearchConfig({})).toBeUndefined();
+  });
+
+  test("拒绝 URL 内嵌凭据与不完整认证配置", () => {
+    const config = readOpenSearchConfig({
+      OPENSEARCH_URL: "http://user:secret@localhost:9200",
+    });
+    expect(() => new OpenSearchClient(config!)).toThrow("不含凭据、路径和参数");
+    expect(
+      () =>
+        new OpenSearchClient({
+          url: "http://localhost:9200",
+          username: "windy",
+          requestTimeoutMs: 1_000,
+        }),
+    ).toThrow("必须同时配置");
+  });
+
+  test("认证只进入 Server 到 OpenSearch 的请求头", async () => {
+    const requests: Request[] = [];
+    const client = new OpenSearchClient(
+      {
+        url: "http://opensearch:9200",
+        username: "windy",
+        password: "secret",
+        requestTimeoutMs: 1_000,
+      },
+      async (input, init) => {
+        requests.push(new Request(input, init));
+        return Response.json({ status: "green" });
+      },
+    );
+
+    expect(await client.health()).toEqual({ status: "green" });
+    expect(requests[0]?.url).toBe(
+      "http://opensearch:9200/_cluster/health?local=true",
+    );
+    expect(requests[0]?.headers.get("authorization")).toStartWith("Basic ");
+  });
+});