create-windy 0.2.34 → 0.3.1

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));
+  }
+}

package/template/apps/server/src/notification/drizzle-management.ts

@@ -0,0 +1,180 @@
+import {
+  notificationRevisions,
+  platformNotifications,
+} from "@southwind-ai/database";
+import type {
+  NotificationRevision,
+  PageResult,
+  PublishNotificationInput,
+  UpdateNotificationInput,
+} from "@southwind-ai/shared";
+import { and, desc, eq, inArray, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { RequestActor } from "../guards.js";
+import { toNotification, toRevision } from "./drizzle-query.js";
+
+export function publishNotification(
+  db: NodePgDatabase,
+  input: PublishNotificationInput,
+  actor: RequestActor,
+) {
+  return db.transaction(async (tx) => {
+    const now = new Date();
+    const [row] = await tx
+      .insert(platformNotifications)
+      .values({
+        id: Bun.randomUUIDv7(),
+        ...input,
+        scheduledFor: input.scheduledFor
+          ? new Date(input.scheduledFor)
+          : undefined,
+        status: input.scheduledFor ? "scheduled" : "published",
+        publishedAt: input.scheduledFor ? new Date(input.scheduledFor) : now,
+        createdAt: now,
+        createdBy: actor.id,
+        updatedAt: now,
+        updatedBy: actor.id,
+        revision: 1,
+      })
+      .onConflictDoNothing()
+      .returning();
+    if (!row && input.sourceKey) {
+      const [existing] = await tx
+        .select()
+        .from(platformNotifications)
+        .where(eq(platformNotifications.sourceKey, input.sourceKey))
+        .limit(1);
+      if (existing) return toNotification(existing);
+    }
+    if (!row) throw new Error("通知发布未返回记录");
+    await tx.insert(notificationRevisions).values({
+      notificationId: row.id,
+      revision: row.revision,
+      title: row.title,
+      summary: row.summary,
+      content: row.content,
+      category: row.category,
+      editedAt: now,
+      editedBy: actor.id,
+    });
+    return toNotification(row);
+  });
+}
+
+export function updateNotification(
+  db: NodePgDatabase,
+  notificationId: string,
+  input: UpdateNotificationInput,
+  actor: RequestActor,
+) {
+  return db.transaction(async (tx) => {
+    const [current] = await tx
+      .select()
+      .from(platformNotifications)
+      .where(
+        and(
+          eq(platformNotifications.id, notificationId),
+          eq(platformNotifications.status, "published"),
+        ),
+      )
+      .for("update")
+      .limit(1);
+    if (!current) return undefined;
+    if (sameContent(current, input)) {
+      return { notification: toNotification(current), changed: false };
+    }
+    const editedAt = new Date();
+    const [updated] = await tx
+      .update(platformNotifications)
+      .set({
+        ...input,
+        revision: sql`${platformNotifications.revision} + 1`,
+        updatedAt: editedAt,
+        updatedBy: actor.id,
+      })
+      .where(eq(platformNotifications.id, notificationId))
+      .returning();
+    if (!updated) throw new Error("通知更新未返回记录");
+    await tx.insert(notificationRevisions).values({
+      notificationId,
+      revision: updated.revision,
+      title: updated.title,
+      summary: updated.summary,
+      content: updated.content,
+      category: updated.category,
+      editedAt,
+      editedBy: actor.id,
+    });
+    return { notification: toNotification(updated), changed: true };
+  });
+}
+
+export async function listNotificationRevisions(
+  db: NodePgDatabase,
+  notificationId: string,
+  page: number,
+  pageSize: number,
+): Promise<PageResult<NotificationRevision> | undefined> {
+  const [notification] = await db
+    .select({ id: platformNotifications.id })
+    .from(platformNotifications)
+    .where(eq(platformNotifications.id, notificationId))
+    .limit(1);
+  if (!notification) return undefined;
+  const [rows, [{ count = 0 } = { count: 0 }]] = await Promise.all([
+    db
+      .select()
+      .from(notificationRevisions)
+      .where(eq(notificationRevisions.notificationId, notificationId))
+      .orderBy(desc(notificationRevisions.revision))
+      .limit(pageSize)
+      .offset((page - 1) * pageSize),
+    db
+      .select({ count: sql<number>`count(*)::int` })
+      .from(notificationRevisions)
+      .where(eq(notificationRevisions.notificationId, notificationId)),
+  ]);
+  return {
+    items: rows.map(toRevision),
+    total: count,
+    page,
+    pageSize,
+  };
+}
+
+export async function archiveNotification(
+  db: NodePgDatabase,
+  notificationId: string,
+  actor: RequestActor,
+) {
+  const now = new Date();
+  const [row] = await db
+    .update(platformNotifications)
+    .set({
+      status: "archived",
+      archivedAt: now,
+      archivedBy: actor.id,
+      updatedAt: now,
+      updatedBy: actor.id,
+    })
+    .where(
+      and(
+        eq(platformNotifications.id, notificationId),
+        inArray(platformNotifications.status, ["published", "scheduled"]),
+      ),
+    )
+    .returning();
+  return row ? toNotification(row) : undefined;
+}
+
+function sameContent(
+  current: typeof platformNotifications.$inferSelect,
+  input: UpdateNotificationInput,
+) {
+  return (
+    current.title === input.title &&
+    current.summary === input.summary &&
+    current.content === input.content &&
+    current.category === input.category
+  );
+}