create-windy 0.2.34 → 0.3.0

package/template/apps/server/src/module-host/storage-scope.ts

@@ -6,7 +6,7 @@ import type {
 } from "@southwind-ai/server-sdk";
 import { evaluateAccessGuards } from "../access-guards.js";
 import { isServerScopeContext } from "../data-access/context.js";
-import type { RequestGuardContext } from "../guards.js";
+import { auditActor, type RequestGuardContext } from "../guards.js";
 import type { createServerRuntime } from "../runtime.js";
 import { findFeature } from "../route-guards.js";
 import type { ModuleStorageScope } from "./storage-port.js";
@@ -73,14 +73,7 @@ function resourceFileEvent(
     id: randomUUIDv7(),
     action: policy.auditAction,
     outcome,
-    actor: {
-      id: input.guardContext.actor.id,
-      type:
-        input.guardContext.actor.type === "anonymous"
-          ? ("user" as const)
-          : input.guardContext.actor.type,
-      name: input.guardContext.actor.name,
-    },
+    actor: auditActor(input.guardContext),
     target: {
       type: request.resourceType,
       id: request.resourceId,

package/template/apps/server/src/module-host/user-directory-port.ts

@@ -8,7 +8,7 @@ import {
 import type { AuditEvent, FeatureFlagDefinition } from "@southwind-ai/shared";
 import { DataScopedResourceService } from "../data-access/scoped-resource.js";
 import { departmentDescendantResolver } from "../data-access/department-tree.js";
-import type { RequestGuardContext } from "../guards.js";
+import { auditActor, type RequestGuardContext } from "../guards.js";
 import { evaluateRouteGuards, findFeature } from "../route-guards.js";
 import type { createServerRuntime } from "../runtime.js";
 import type { SystemRepositories } from "../system/seed.js";
@@ -125,11 +125,7 @@ function queryAuditEvent(
     id: randomUUIDv7(),
     action: auditAction,
     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-directory", id: "enabled-users" },
     requestId: context.requestId,
     metadata: {

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

@@ -0,0 +1,46 @@
+import type { ExternalNotificationChannel } from "@southwind-ai/shared";
+
+export interface NotificationChannelMessage {
+  deliveryId: string;
+  userId: string;
+  address: string;
+  subject: string;
+  content: string;
+}
+
+export interface NotificationChannelResult {
+  providerMessageId?: string;
+}
+
+export interface NotificationChannelAdapter {
+  readonly channel: ExternalNotificationChannel;
+  deliver(
+    message: NotificationChannelMessage,
+  ): Promise<NotificationChannelResult>;
+}
+
+export class NotificationChannelError extends Error {
+  constructor(
+    readonly code: string,
+    readonly retryable: boolean,
+    message = code,
+  ) {
+    super(message);
+    this.name = "NotificationChannelError";
+  }
+}
+
+export class NotificationChannelRegistry {
+  private readonly adapters = new Map<
+    ExternalNotificationChannel,
+    NotificationChannelAdapter
+  >();
+
+  constructor(adapters: NotificationChannelAdapter[] = []) {
+    for (const adapter of adapters) this.adapters.set(adapter.channel, adapter);
+  }
+
+  get(channel: ExternalNotificationChannel) {
+    return this.adapters.get(channel);
+  }
+}

package/template/apps/server/src/notification/delivery-policy.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { mergeExternalDeliveryPolicy } from "./delivery-policy.js";
+
+describe("mergeExternalDeliveryPolicy", () => {
+  test("未设置偏好时，普通类别只保留站内通知", () => {
+    expect(
+      mergeExternalDeliveryPolicy({
+        category: "运营",
+        requestedChannels: ["email", "sms"],
+        mandatoryCategories: new Set(),
+      }),
+    ).toEqual([]);
+  });
+
+  test("普通类别先应用类别退订，再取请求渠道与启用渠道交集", () => {
+    const preference = {
+      userId: "u1",
+      enabledChannels: ["email"] as const,
+      disabledCategories: ["营销"],
+    };
+    expect(
+      mergeExternalDeliveryPolicy({
+        category: "营销",
+        requestedChannels: ["email"],
+        preference: {
+          ...preference,
+          enabledChannels: [...preference.enabledChannels],
+        },
+        mandatoryCategories: new Set(),
+      }),
+    ).toEqual([]);
+    expect(
+      mergeExternalDeliveryPolicy({
+        category: "运营",
+        requestedChannels: ["email", "sms"],
+        preference: {
+          ...preference,
+          enabledChannels: [...preference.enabledChannels],
+        },
+        mandatoryCategories: new Set(),
+      }),
+    ).toEqual(["email"]);
+  });
+
+  test("强制类别绕过用户外部偏好，但不增加未请求渠道", () => {
+    expect(
+      mergeExternalDeliveryPolicy({
+        category: "安全",
+        requestedChannels: ["sms", "sms"],
+        preference: {
+          userId: "u1",
+          enabledChannels: [],
+          disabledCategories: ["安全"],
+        },
+        mandatoryCategories: new Set(["安全"]),
+      }),
+    ).toEqual(["sms"]);
+  });
+});

package/template/apps/server/src/notification/delivery-policy.ts

@@ -0,0 +1,37 @@
+import type {
+  ExternalNotificationChannel,
+  NotificationPreference,
+} from "@southwind-ai/shared";
+
+export interface NotificationDeliveryPolicyInput {
+  category: string;
+  requestedChannels: ExternalNotificationChannel[];
+  preference?: NotificationPreference;
+  mandatoryCategories: ReadonlySet<string>;
+}
+
+/**
+ * 站内通知始终可见，此函数只决定外部渠道：
+ * 强制类别 > 类别退订 > 渠道启用；未保存偏好时外部渠道默认关闭。
+ */
+export function mergeExternalDeliveryPolicy(
+  input: NotificationDeliveryPolicyInput,
+): ExternalNotificationChannel[] {
+  if (input.mandatoryCategories.has(input.category)) {
+    return unique(input.requestedChannels);
+  }
+  if (
+    !input.preference ||
+    input.preference.disabledCategories.includes(input.category)
+  ) {
+    return [];
+  }
+  const enabled = new Set(input.preference.enabledChannels);
+  return unique(input.requestedChannels).filter((channel) =>
+    enabled.has(channel),
+  );
+}
+
+function unique<T>(values: T[]) {
+  return [...new Set(values)];
+}

package/template/apps/server/src/notification/delivery-repository.ts

@@ -0,0 +1,198 @@
+import { notificationDeliveryOutbox } from "@southwind-ai/database";
+import type {
+  ExternalNotificationChannel,
+  NotificationDelivery,
+} from "@southwind-ai/shared";
+import { and, asc, eq, inArray, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+
+export interface NotificationDeliveryDraft {
+  notificationId: string;
+  userId: string;
+  channel: ExternalNotificationChannel;
+  subject: string;
+  content: string;
+}
+
+export interface ClaimedNotificationDelivery extends NotificationDeliveryDraft {
+  id: string;
+  attemptCount: number;
+  leaseToken: string;
+}
+
+export interface NotificationDeliveryRepository {
+  enqueue(drafts: NotificationDeliveryDraft[]): Promise<number>;
+  claim(now: Date, limit: number): Promise<ClaimedNotificationDelivery[]>;
+  complete(
+    id: string,
+    leaseToken: string,
+    providerMessageId?: string,
+  ): Promise<boolean>;
+  fail(
+    id: string,
+    leaseToken: string,
+    code: string,
+    retryAt?: Date,
+  ): Promise<boolean>;
+  list(notificationId: string): Promise<NotificationDelivery[]>;
+}
+
+export class DrizzleNotificationDeliveryRepository implements NotificationDeliveryRepository {
+  constructor(
+    private readonly db: NodePgDatabase,
+    private readonly leaseMs = 30_000,
+  ) {}
+
+  async enqueue(drafts: NotificationDeliveryDraft[]) {
+    if (drafts.length === 0) return 0;
+    const now = new Date();
+    return (
+      await this.db
+        .insert(notificationDeliveryOutbox)
+        .values(
+          drafts.map((draft) => ({
+            id: Bun.randomUUIDv7(),
+            ...draft,
+            status: "pending" as const,
+            nextAttemptAt: now,
+            createdAt: now,
+            updatedAt: now,
+          })),
+        )
+        .onConflictDoNothing()
+        .returning({ id: notificationDeliveryOutbox.id })
+    ).length;
+  }
+
+  async claim(now: Date, limit: number) {
+    const leaseToken = Bun.randomUUIDv7();
+    const leaseExpiresAt = new Date(now.getTime() + this.leaseMs);
+    return this.db.transaction(async (tx) => {
+      const rows = await tx.execute<{
+        id: string;
+        notification_id: string;
+        user_id: string;
+        channel: ExternalNotificationChannel;
+        subject: string;
+        content: string;
+        attempt_count: number;
+      }>(sql`
+        select id, notification_id, user_id, channel, subject, content,
+               attempt_count
+          from notification_delivery_outbox
+         where (
+           status in ('pending', 'retrying')
+           and next_attempt_at <= ${now}
+         ) or (
+           status = 'processing'
+           and lease_expires_at <= ${now}
+         )
+         order by next_attempt_at asc
+         limit ${limit}
+         for update skip locked
+      `);
+      const claimed = rows.rows;
+      if (claimed.length === 0) return [];
+      await tx
+        .update(notificationDeliveryOutbox)
+        .set({
+          status: "processing",
+          leaseToken,
+          leaseExpiresAt,
+          updatedAt: now,
+          attemptCount: sql`${notificationDeliveryOutbox.attemptCount} + 1`,
+        })
+        .where(
+          inArray(
+            notificationDeliveryOutbox.id,
+            claimed.map((row) => row.id),
+          ),
+        );
+      return claimed.map((row) => ({
+        id: row.id,
+        notificationId: row.notification_id,
+        userId: row.user_id,
+        channel: row.channel,
+        subject: row.subject,
+        content: row.content,
+        attemptCount: row.attempt_count + 1,
+        leaseToken,
+      }));
+    });
+  }
+
+  async complete(id: string, leaseToken: string, providerMessageId?: string) {
+    const now = new Date();
+    return Boolean(
+      (
+        await this.db
+          .update(notificationDeliveryOutbox)
+          .set({
+            status: "delivered",
+            deliveredAt: now,
+            providerMessageId,
+            leaseToken: null,
+            leaseExpiresAt: null,
+            lastErrorCode: null,
+            updatedAt: now,
+          })
+          .where(activeLease(id, leaseToken))
+          .returning({ id: notificationDeliveryOutbox.id })
+      )[0],
+    );
+  }
+
+  async fail(id: string, leaseToken: string, code: string, retryAt?: Date) {
+    return Boolean(
+      (
+        await this.db
+          .update(notificationDeliveryOutbox)
+          .set({
+            status: retryAt ? "retrying" : "dead",
+            nextAttemptAt: retryAt || new Date(),
+            leaseToken: null,
+            leaseExpiresAt: null,
+            lastErrorCode: code,
+            updatedAt: new Date(),
+          })
+          .where(activeLease(id, leaseToken))
+          .returning({ id: notificationDeliveryOutbox.id })
+      )[0],
+    );
+  }
+
+  async list(notificationId: string) {
+    const rows = await this.db
+      .select()
+      .from(notificationDeliveryOutbox)
+      .where(eq(notificationDeliveryOutbox.notificationId, notificationId))
+      .orderBy(asc(notificationDeliveryOutbox.createdAt));
+    return rows.map(toDelivery);
+  }
+}
+
+function activeLease(id: string, leaseToken: string) {
+  return and(
+    eq(notificationDeliveryOutbox.id, id),
+    eq(notificationDeliveryOutbox.status, "processing"),
+    eq(notificationDeliveryOutbox.leaseToken, leaseToken),
+  );
+}
+
+function toDelivery(
+  row: typeof notificationDeliveryOutbox.$inferSelect,
+): NotificationDelivery {
+  return {
+    id: row.id,
+    notificationId: row.notificationId,
+    userId: row.userId,
+    channel: row.channel,
+    status: row.status,
+    attemptCount: row.attemptCount,
+    nextAttemptAt: row.nextAttemptAt.toISOString(),
+    deliveredAt: row.deliveredAt?.toISOString(),
+    lastErrorCode: row.lastErrorCode || undefined,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}

package/template/apps/server/src/notification/delivery-worker.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import {
+  NotificationChannelError,
+  NotificationChannelRegistry,
+} from "./channel-adapter.js";
+import { InMemoryNotificationDeliveryRepository } from "./memory-delivery-repository.js";
+import { NotificationDeliveryWorker } from "./delivery-worker.js";
+import type { NotificationRecipientDirectory } from "./recipient-directory.js";
+
+const directory: NotificationRecipientDirectory = {
+  async options() {
+    return { users: [], roles: [], departments: [] };
+  },
+  async resolve() {
+    return [];
+  },
+  async address(_userId, channel) {
+    return channel === "email" ? "user@example.com" : "13800000000";
+  },
+};
+
+describe("NotificationDeliveryWorker", () => {
+  test("成功投递后完成 outbox", async () => {
+    const repository = new InMemoryNotificationDeliveryRepository();
+    await repository.enqueue([draft("email")]);
+    const worker = new NotificationDeliveryWorker(
+      repository,
+      directory,
+      new NotificationChannelRegistry([
+        {
+          channel: "email",
+          async deliver() {
+            return { providerMessageId: "smtp-1" };
+          },
+        },
+      ]),
+    );
+    expect(await worker.runNext(new Date("2030-01-01T00:00:00.000Z"))).toEqual({
+      claimed: 1,
+      delivered: 1,
+      retrying: 0,
+      dead: 0,
+    });
+    expect((await repository.list("n1"))[0]?.status).toBe("delivered");
+  });
+
+  test("可重试错误进入退避，未配置短信明确进入 dead", async () => {
+    const repository = new InMemoryNotificationDeliveryRepository();
+    await repository.enqueue([draft("email"), draft("sms")]);
+    const worker = new NotificationDeliveryWorker(
+      repository,
+      directory,
+      new NotificationChannelRegistry([
+        {
+          channel: "email",
+          async deliver() {
+            throw new NotificationChannelError("SMTP_TEMPORARY", true);
+          },
+        },
+      ]),
+      { retryBaseMs: 1_000 },
+    );
+    expect(await worker.runNext(new Date("2030-01-01T00:00:00.000Z"))).toEqual({
+      claimed: 2,
+      delivered: 0,
+      retrying: 1,
+      dead: 1,
+    });
+    const items = await repository.list("n1");
+    expect(items.find((item) => item.channel === "email")?.status).toBe(
+      "retrying",
+    );
+    expect(items.find((item) => item.channel === "sms")?.lastErrorCode).toBe(
+      "CHANNEL_NOT_CONFIGURED",
+    );
+  });
+});
+
+function draft(channel: "email" | "sms") {
+  return {
+    notificationId: "n1",
+    userId: "u1",
+    channel,
+    subject: "测试通知",
+    content: "正文",
+  };
+}

package/template/apps/server/src/notification/delivery-worker.ts

@@ -0,0 +1,88 @@
+import {
+  NotificationChannelError,
+  NotificationChannelRegistry,
+} from "./channel-adapter.js";
+import type { NotificationDeliveryRepository } from "./delivery-repository.js";
+import type { NotificationRecipientDirectory } from "./recipient-directory.js";
+
+export interface NotificationDeliveryWorkerOptions {
+  batchSize?: number;
+  maxAttempts?: number;
+  retryBaseMs?: number;
+}
+
+export class NotificationDeliveryWorker {
+  private readonly batchSize: number;
+  private readonly maxAttempts: number;
+  private readonly retryBaseMs: number;
+
+  constructor(
+    private readonly repository: NotificationDeliveryRepository,
+    private readonly recipients: NotificationRecipientDirectory,
+    private readonly channels: NotificationChannelRegistry,
+    options: NotificationDeliveryWorkerOptions = {},
+  ) {
+    this.batchSize = options.batchSize || 20;
+    this.maxAttempts = options.maxAttempts || 5;
+    this.retryBaseMs = options.retryBaseMs || 5_000;
+  }
+
+  async runNext(now = new Date()) {
+    const deliveries = await this.repository.claim(now, this.batchSize);
+    let delivered = 0;
+    let retrying = 0;
+    let dead = 0;
+    for (const delivery of deliveries) {
+      const adapter = this.channels.get(delivery.channel);
+      const address = await this.recipients.address(
+        delivery.userId,
+        delivery.channel,
+      );
+      if (!adapter || !address) {
+        await this.repository.fail(
+          delivery.id,
+          delivery.leaseToken,
+          adapter ? "RECIPIENT_ADDRESS_MISSING" : "CHANNEL_NOT_CONFIGURED",
+        );
+        dead += 1;
+        continue;
+      }
+      try {
+        const result = await adapter.deliver({
+          deliveryId: delivery.id,
+          userId: delivery.userId,
+          address,
+          subject: delivery.subject,
+          content: delivery.content,
+        });
+        await this.repository.complete(
+          delivery.id,
+          delivery.leaseToken,
+          result.providerMessageId,
+        );
+        delivered += 1;
+      } catch (error) {
+        const channelError =
+          error instanceof NotificationChannelError
+            ? error
+            : new NotificationChannelError("CHANNEL_DELIVERY_FAILED", true);
+        const retry =
+          channelError.retryable && delivery.attemptCount < this.maxAttempts;
+        await this.repository.fail(
+          delivery.id,
+          delivery.leaseToken,
+          channelError.code,
+          retry ? this.retryAt(now, delivery.attemptCount) : undefined,
+        );
+        if (retry) retrying += 1;
+        else dead += 1;
+      }
+    }
+    return { claimed: deliveries.length, delivered, retrying, dead };
+  }
+
+  private retryAt(now: Date, attempt: number) {
+    const delay = this.retryBaseMs * 2 ** Math.max(0, attempt - 1);
+    return new Date(now.getTime() + Math.min(delay, 60 * 60 * 1_000));
+  }
+}