create-windy 0.2.33 → 0.3.0

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

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

@@ -0,0 +1,160 @@
+import {
+  notificationFavorites,
+  notificationReads,
+  notificationRevisions,
+  platformNotifications,
+} from "@southwind-ai/database";
+import type {
+  NotificationInboxFilters,
+  NotificationRevision,
+  PlatformNotification,
+} from "@southwind-ai/shared";
+import {
+  and,
+  eq,
+  ilike,
+  isNotNull,
+  isNull,
+  or,
+  sql,
+  type SQL,
+} from "drizzle-orm";
+import type { RequestActor } from "../guards.js";
+
+export function toNotification(
+  row: typeof platformNotifications.$inferSelect,
+): PlatformNotification {
+  return {
+    id: row.id,
+    title: row.title,
+    summary: row.summary,
+    content: row.content,
+    category: row.category,
+    status: row.status as PlatformNotification["status"],
+    publishedAt: row.publishedAt.toISOString(),
+    scheduledFor: row.scheduledFor?.toISOString(),
+    createdAt: row.createdAt.toISOString(),
+    createdBy: row.createdBy,
+    updatedAt: row.updatedAt.toISOString(),
+    updatedBy: row.updatedBy,
+    archivedAt: row.archivedAt?.toISOString(),
+    archivedBy: row.archivedBy || undefined,
+    target: row.target || undefined,
+    recipientUserId: row.recipientUserId || undefined,
+    recipientUserIds: row.recipientUserIds,
+    recipientRoleCodes: row.recipientRoleCodes,
+    recipientDepartmentIds: row.recipientDepartmentIds,
+    includeChildDepartments: row.includeChildDepartments,
+    deliveryChannels: row.deliveryChannels,
+    sourceKey: row.sourceKey || undefined,
+    revision: row.revision,
+  };
+}
+
+export function toRevision(
+  row: typeof notificationRevisions.$inferSelect,
+): NotificationRevision {
+  return {
+    notificationId: row.notificationId,
+    revision: row.revision,
+    title: row.title,
+    summary: row.summary,
+    content: row.content,
+    category: row.category,
+    editedAt: row.editedAt.toISOString(),
+    editedBy: row.editedBy,
+  };
+}
+
+export function audienceWhere(
+  actor: Pick<RequestActor, "id" | "roleCodes" | "scopeContext">,
+): SQL {
+  const roleClauses = actor.roleCodes.map(
+    (role) =>
+      sql`${platformNotifications.recipientRoleCodes} @> ${JSON.stringify([role])}::jsonb`,
+  );
+  return or(
+    and(
+      isNull(platformNotifications.recipientUserId),
+      sql`jsonb_array_length(${platformNotifications.recipientUserIds}) = 0`,
+      sql`jsonb_array_length(${platformNotifications.recipientRoleCodes}) = 0`,
+      sql`jsonb_array_length(${platformNotifications.recipientDepartmentIds}) = 0`,
+    ),
+    eq(platformNotifications.recipientUserId, actor.id),
+    sql`${platformNotifications.recipientUserIds} @> ${JSON.stringify([actor.id])}::jsonb`,
+    ...(actor.scopeContext?.departmentId
+      ? [
+          sql`(
+            ${platformNotifications.recipientDepartmentIds} @>
+              ${JSON.stringify([actor.scopeContext.departmentId])}::jsonb
+            or (
+              ${platformNotifications.includeChildDepartments} = true
+              and exists (
+                with recursive ancestors as (
+                  select id, parent_id from departments
+                   where id = ${actor.scopeContext.departmentId}
+                  union all
+                  select department.id, department.parent_id
+                    from departments department
+                    join ancestors child on child.parent_id = department.id
+                )
+                select 1 from ancestors
+                 where ${platformNotifications.recipientDepartmentIds} @>
+                   jsonb_build_array(ancestors.id)
+              )
+            )
+          )`,
+        ]
+      : []),
+    ...roleClauses,
+  )!;
+}
+
+export function inboxWhere(
+  actor: Pick<RequestActor, "id" | "roleCodes" | "scopeContext">,
+  filters: NotificationInboxFilters,
+): SQL {
+  const conditions: SQL[] = [
+    eq(platformNotifications.status, "published"),
+    audienceWhere(actor),
+  ];
+  const keyword = filters.q?.trim();
+  if (keyword) {
+    conditions.push(
+      or(
+        ilike(platformNotifications.title, `%${keyword}%`),
+        ilike(platformNotifications.summary, `%${keyword}%`),
+        ilike(platformNotifications.content, `%${keyword}%`),
+        ilike(platformNotifications.category, `%${keyword}%`),
+      )!,
+    );
+  }
+  const category = filters.category?.trim();
+  if (category) conditions.push(eq(platformNotifications.category, category));
+  if (filters.read !== undefined) {
+    conditions.push(
+      filters.read === "read"
+        ? isNotNull(notificationReads.readAt)
+        : isNull(notificationReads.readAt),
+    );
+  }
+  if (filters.favorite !== undefined) {
+    conditions.push(
+      filters.favorite
+        ? isNotNull(notificationFavorites.favoritedAt)
+        : isNull(notificationFavorites.favoritedAt),
+    );
+  }
+  return and(...conditions)!;
+}
+
+export function searchWhere(query?: string): SQL | undefined {
+  const keyword = query?.trim();
+  return keyword
+    ? or(
+        ilike(platformNotifications.title, `%${keyword}%`),
+        ilike(platformNotifications.summary, `%${keyword}%`),
+        ilike(platformNotifications.category, `%${keyword}%`),
+      )
+    : undefined;
+}