create-windy 0.2.33 → 0.3.0

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

@@ -1,27 +1,25 @@
-import { randomUUIDv7 } from "bun";
-import type {
-  AuditActionType,
-  FeatureFlagDefinition,
-  HttpMethod,
-  PublishNotificationInput,
-} from "@southwind-ai/shared";
-import type { RequestGuardContext } from "../guards.js";
+import type { FeatureFlagDefinition, HttpMethod } from "@southwind-ai/shared";
 import { evaluateRouteGuards, findSystemFeature } from "../route-guards.js";
 import type { createServerRuntime } from "../runtime.js";
 import type { NotificationRepository } from "./repository.js";
+import type { NotificationService } from "./service.js";
+import { registerNotificationExtensionRoutes } from "./extension-routes.js";
 import { parsePagination } from "../pagination.js";
+import {
+  notificationEvent,
+  notificationNotFound,
+  parseInboxFilters,
+  parsePublishInput,
+  parseUpdateInput,
+  type NotificationRouteContext,
+} from "./route-support.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
-type RouteContext = {
-  body?: unknown;
-  guardContext: RequestGuardContext;
-  params: Record<string, string | undefined>;
-  query: Record<string, string | undefined>;
-};
 
-interface NotificationRouteApp {
+export interface NotificationRouteApp {
   get(path: string, handler: (context: unknown) => unknown): unknown;
   post(path: string, handler: (context: unknown) => unknown): unknown;
+  put(path: string, handler: (context: unknown) => unknown): unknown;
   delete(path: string, handler: (context: unknown) => unknown): unknown;
 }
 
@@ -30,86 +28,243 @@ export function registerNotificationRoutes(
   repository: NotificationRepository,
   runtime: ServerRuntime,
   features: FeatureFlagDefinition[] = [],
+  service?: NotificationService,
 ) {
   const feature = findSystemFeature(features, "notification");
 
   app.get("/notifications", (raw) =>
-    guarded(raw, "GET", "read", feature, runtime, async (context) => {
-      const pagination = parsePagination(context.query);
-      if (pagination instanceof Response) return pagination;
-      return repository.listInbox(
-        context.guardContext.actor,
-        pagination.page,
-        pagination.pageSize,
-      );
-    }),
+    guarded(
+      raw,
+      "GET",
+      "/api/notifications",
+      "read",
+      feature,
+      runtime,
+      async (context) => {
+        const pagination = parsePagination(context.query);
+        if (pagination instanceof Response) return pagination;
+        const filters = parseInboxFilters(context.query);
+        if (filters instanceof Response) return filters;
+        return repository.listInbox(
+          context.guardContext.actor,
+          pagination.page,
+          pagination.pageSize,
+          filters,
+        );
+      },
+    ),
   );
   app.post("/notifications/:id/read", (raw) =>
-    guarded(raw, "POST", "read", feature, runtime, async (context) => {
-      const id = context.params.id || "";
-      const result = await repository.markRead(id, context.guardContext.actor);
-      if (!result) return notFound(id);
-      if (!result.alreadyRead) {
-        runtime.auditSink.recordEvent(event(context, "notification.read", id));
-      }
-      return result;
-    }),
+    guarded(
+      raw,
+      "POST",
+      "/api/notifications/:id/read",
+      "read",
+      feature,
+      runtime,
+      async (context) => {
+        const id = context.params.id || "";
+        const result = await repository.markRead(
+          id,
+          context.guardContext.actor,
+        );
+        if (!result) return notificationNotFound(id);
+        if (!result.alreadyRead) {
+          runtime.auditSink.recordEvent(
+            notificationEvent(context, "notification.read", id),
+          );
+        }
+        return result;
+      },
+    ),
+  );
+  app.put("/notifications/:id/favorite", (raw) =>
+    guarded(
+      raw,
+      "PUT",
+      "/api/notifications/:id/favorite",
+      "read",
+      feature,
+      runtime,
+      async (context) => {
+        const id = context.params.id || "";
+        const result = await repository.setFavorite(
+          id,
+          true,
+          context.guardContext.actor,
+        );
+        if (!result) return notificationNotFound(id);
+        if (result.changed) {
+          runtime.auditSink.recordEvent(
+            notificationEvent(context, "notification.favorite", id),
+          );
+        }
+        return result;
+      },
+    ),
+  );
+  app.delete("/notifications/:id/favorite", (raw) =>
+    guarded(
+      raw,
+      "DELETE",
+      "/api/notifications/:id/favorite",
+      "read",
+      feature,
+      runtime,
+      async (context) => {
+        const id = context.params.id || "";
+        const result = await repository.setFavorite(
+          id,
+          false,
+          context.guardContext.actor,
+        );
+        if (!result) return notificationNotFound(id);
+        if (result.changed) {
+          runtime.auditSink.recordEvent(
+            notificationEvent(context, "notification.unfavorite", id),
+          );
+        }
+        return result;
+      },
+    ),
   );
   app.get("/system/notifications", (raw) =>
-    guarded(raw, "GET", "manage", feature, runtime, async (context) => {
-      const pagination = parsePagination(context.query);
-      if (pagination instanceof Response) return pagination;
-      return repository.listManaged(
-        pagination.page,
-        pagination.pageSize,
-        context.query.q,
-      );
-    }),
+    guarded(
+      raw,
+      "GET",
+      "/api/system/notifications",
+      "manage",
+      feature,
+      runtime,
+      async (context) => {
+        const pagination = parsePagination(context.query);
+        if (pagination instanceof Response) return pagination;
+        return repository.listManaged(
+          pagination.page,
+          pagination.pageSize,
+          context.query.q,
+        );
+      },
+    ),
+  );
+  app.get("/system/notifications/:id/revisions", (raw) =>
+    guarded(
+      raw,
+      "GET",
+      "/api/system/notifications/:id/revisions",
+      "manage",
+      feature,
+      runtime,
+      async (context) => {
+        const pagination = parsePagination(context.query);
+        if (pagination instanceof Response) return pagination;
+        const id = context.params.id || "";
+        const revisions = await repository.listRevisions(
+          id,
+          pagination.page,
+          pagination.pageSize,
+        );
+        return revisions || notificationNotFound(id);
+      },
+    ),
   );
   app.post("/system/notifications", (raw) =>
-    guarded(raw, "POST", "manage", feature, runtime, async (context) => {
-      const input = parsePublishInput(context.body);
-      if (input instanceof Response) return input;
-      const notification = await repository.publish(
-        input,
-        context.guardContext.actor,
-      );
-      await runtime.auditSink.recordCriticalEvent(
-        event(context, "notification.publish", notification.id),
-      );
-      return notification;
-    }),
+    guarded(
+      raw,
+      "POST",
+      "/api/system/notifications",
+      "manage",
+      feature,
+      runtime,
+      async (context) => {
+        const input = parsePublishInput(context.body);
+        if (input instanceof Response) return input;
+        const notification = await (service || repository).publish(
+          input,
+          context.guardContext.actor,
+        );
+        await runtime.auditSink.recordCriticalEvent(
+          notificationEvent(
+            context,
+            notification.status === "scheduled"
+              ? "notification.schedule"
+              : "notification.publish",
+            notification.id,
+          ),
+        );
+        return notification;
+      },
+    ),
+  );
+  app.put("/system/notifications/:id", (raw) =>
+    guarded(
+      raw,
+      "PUT",
+      "/api/system/notifications/:id",
+      "update",
+      feature,
+      runtime,
+      async (context) => {
+        const input = parseUpdateInput(context.body);
+        if (input instanceof Response) return input;
+        const id = context.params.id || "";
+        const result = await repository.update(
+          id,
+          input,
+          context.guardContext.actor,
+        );
+        if (!result) return notificationNotFound(id);
+        if (result.changed) {
+          await runtime.auditSink.recordCriticalEvent(
+            notificationEvent(context, "notification.update", id),
+          );
+        }
+        return result;
+      },
+    ),
   );
   app.delete("/system/notifications/:id", (raw) =>
-    guarded(raw, "DELETE", "manage", feature, runtime, async (context) => {
-      const id = context.params.id || "";
-      const notification = await repository.archive(
-        id,
-        context.guardContext.actor,
-      );
-      if (!notification) return notFound(id);
-      await runtime.auditSink.recordCriticalEvent(
-        event(context, "notification.archive", id),
-      );
-      return notification;
-    }),
+    guarded(
+      raw,
+      "DELETE",
+      "/api/system/notifications/:id",
+      "manage",
+      feature,
+      runtime,
+      async (context) => {
+        const id = context.params.id || "";
+        const notification = await repository.archive(
+          id,
+          context.guardContext.actor,
+        );
+        if (!notification) return notificationNotFound(id);
+        await runtime.auditSink.recordCriticalEvent(
+          notificationEvent(context, "notification.archive", id),
+        );
+        return notification;
+      },
+    ),
   );
+  if (service) {
+    registerNotificationExtensionRoutes(app, service, runtime, feature);
+  }
   return app;
 }
 
 async function guarded(
   raw: unknown,
   method: HttpMethod,
-  action: "read" | "manage",
+  path: string,
+  action: "read" | "update" | "manage",
   feature: FeatureFlagDefinition | undefined,
   runtime: ServerRuntime,
-  handler: (context: RouteContext) => unknown,
+  handler: (context: NotificationRouteContext) => unknown,
 ) {
-  const context = raw as RouteContext;
+  const context = raw as NotificationRouteContext;
   const decision = await evaluateRouteGuards(runtime, context.guardContext, {
     permission: {
       method,
-      path: "/api/notifications",
+      path,
       permissionKey: `system.notification.${action}`,
     },
     feature,
@@ -121,65 +276,3 @@ async function guarded(
         { status: 403 },
       );
 }
-
-function parsePublishInput(body: unknown): PublishNotificationInput | Response {
-  const value =
-    body && typeof body === "object" ? (body as Record<string, unknown>) : {};
-  const input = {
-    title: text(value.title),
-    summary: text(value.summary),
-    content: text(value.content),
-    category: text(value.category),
-  };
-  if (!input.title || !input.summary || !input.content || !input.category) {
-    return Response.json(
-      {
-        error: "INVALID_NOTIFICATION",
-        message: "标题、摘要、正文和分类均不能为空",
-      },
-      { status: 400 },
-    );
-  }
-  if (
-    input.title.length > 120 ||
-    input.summary.length > 240 ||
-    input.content.length > 10_000 ||
-    input.category.length > 40
-  ) {
-    return Response.json(
-      { error: "INVALID_NOTIFICATION", message: "通知内容超过长度限制" },
-      { status: 400 },
-    );
-  }
-  return input;
-}
-
-function event(context: RouteContext, action: AuditActionType, id: string) {
-  return {
-    id: randomUUIDv7(),
-    action,
-    outcome: "success" as const,
-    actor: {
-      id: context.guardContext.actor.id,
-      type:
-        context.guardContext.actor.type === "anonymous"
-          ? ("user" as const)
-          : context.guardContext.actor.type,
-      name: context.guardContext.actor.name,
-    },
-    target: { type: "notification", id },
-    requestId: context.guardContext.requestId,
-    occurredAt: new Date().toISOString(),
-  };
-}
-
-function notFound(id: string) {
-  return Response.json(
-    { error: "NOT_FOUND", resource: "notification", id },
-    { status: 404 },
-  );
-}
-
-function text(value: unknown) {
-  return typeof value === "string" ? value.trim() : "";
-}

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

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+import type { NotificationRecipientDirectory } from "./recipient-directory.js";
+import { InMemoryNotificationDeliveryRepository } from "./memory-delivery-repository.js";
+import { InMemoryNotificationPreferenceRepository } from "./preference-repository.js";
+import { InMemoryNotificationRepository } from "./repository.js";
+import { NotificationService } from "./service.js";
+
+const recipients: NotificationRecipientDirectory = {
+  async options() {
+    return {
+      users: [{ id: "u1", label: "用户一" }],
+      roles: [],
+      departments: [],
+    };
+  },
+  async resolve() {
+    return [{ id: "u1", email: "u1@example.com" }];
+  },
+  async address() {
+    return "u1@example.com";
+  },
+};
+
+describe("NotificationService", () => {
+  test("普通通知只为用户启用且发布者请求的渠道创建 outbox", async () => {
+    const fixture = createFixture();
+    await fixture.preferences.save(
+      "u1",
+      { enabledChannels: ["email"], disabledCategories: [] },
+      "u1",
+    );
+    const notification = await fixture.service.publish(
+      {
+        title: "运营通知",
+        summary: "摘要",
+        content: "正文",
+        category: "运营",
+        deliveryChannels: ["email", "sms"],
+      },
+      actor,
+    );
+    expect(notification.status).toBe("published");
+    expect(await fixture.deliveries.list(notification.id)).toMatchObject([
+      { userId: "u1", channel: "email", status: "pending" },
+    ]);
+  });
+
+  test("定时通知到期前不入 outbox，到期后幂等激活并入队", async () => {
+    const fixture = createFixture();
+    await fixture.preferences.save(
+      "u1",
+      { enabledChannels: ["email"], disabledCategories: [] },
+      "u1",
+    );
+    const scheduledFor = "2030-01-01T00:00:00.000Z";
+    const notification = await fixture.service.publish(
+      {
+        title: "定时通知",
+        summary: "摘要",
+        content: "正文",
+        category: "运营",
+        deliveryChannels: ["email"],
+        scheduledFor,
+      },
+      actor,
+    );
+    expect(notification.status).toBe("scheduled");
+    expect(await fixture.deliveries.list(notification.id)).toEqual([]);
+    expect(
+      await fixture.service.dispatchScheduled(
+        new Date("2030-01-01T00:00:01.000Z"),
+      ),
+    ).toEqual({ claimed: 1, published: 1, deliveries: 1 });
+    expect(
+      await fixture.service.dispatchScheduled(
+        new Date("2030-01-01T00:00:02.000Z"),
+      ),
+    ).toEqual({ claimed: 0, published: 0, deliveries: 0 });
+  });
+});
+
+function createFixture() {
+  const preferences = new InMemoryNotificationPreferenceRepository();
+  const deliveries = new InMemoryNotificationDeliveryRepository();
+  return {
+    preferences,
+    deliveries,
+    service: new NotificationService(
+      new InMemoryNotificationRepository(),
+      preferences,
+      deliveries,
+      recipients,
+      { mandatoryCategories: ["安全"] },
+    ),
+  };
+}
+
+const actor = {
+  id: "admin",
+  type: "user" as const,
+  name: "管理员",
+  roleCodes: ["admin"],
+  permissionKeys: ["system.notification.manage"],
+};

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

@@ -0,0 +1,140 @@
+import type {
+  ExternalNotificationChannel,
+  PlatformNotification,
+  PublishNotificationInput,
+  UpdateNotificationPreferenceInput,
+} from "@southwind-ai/shared";
+import type { RequestActor } from "../guards.js";
+import type { NotificationDeliveryRepository } from "./delivery-repository.js";
+import { mergeExternalDeliveryPolicy } from "./delivery-policy.js";
+import type { NotificationPreferenceRepository } from "./preference-repository.js";
+import type { NotificationRecipientDirectory } from "./recipient-directory.js";
+import type { NotificationRepository } from "./repository.js";
+
+export interface NotificationServiceOptions {
+  mandatoryCategories?: string[];
+}
+
+export class NotificationService {
+  private readonly mandatoryCategories: ReadonlySet<string>;
+
+  constructor(
+    readonly repository: NotificationRepository,
+    private readonly preferences: NotificationPreferenceRepository,
+    private readonly deliveries: NotificationDeliveryRepository,
+    private readonly recipients: NotificationRecipientDirectory,
+    options: NotificationServiceOptions = {},
+  ) {
+    this.mandatoryCategories = new Set(options.mandatoryCategories || []);
+  }
+
+  async publish(input: PublishNotificationInput, actor: RequestActor) {
+    const normalized = normalizePublishInput(input);
+    const notification = await this.repository.publish(normalized, actor);
+    if (notification.status === "published") {
+      await this.enqueue(notification);
+    }
+    return notification;
+  }
+
+  async dispatchScheduled(now = new Date()) {
+    const due = await this.repository.listDueScheduled(now, 20);
+    let published = 0;
+    let deliveries = 0;
+    for (const notification of due) {
+      const activated = await this.repository.activateScheduled(
+        notification.id,
+        now,
+      );
+      if (!activated) continue;
+      published += 1;
+      deliveries += await this.enqueue(activated);
+    }
+    return { claimed: due.length, published, deliveries };
+  }
+
+  getPreference(userId: string) {
+    return this.preferences.get(userId);
+  }
+
+  savePreference(
+    userId: string,
+    input: UpdateNotificationPreferenceInput,
+    actorId: string,
+  ) {
+    return this.preferences.save(userId, normalizePreference(input), actorId);
+  }
+
+  audienceOptions() {
+    return this.recipients.options();
+  }
+
+  listDeliveries(notificationId: string) {
+    return this.deliveries.list(notificationId);
+  }
+
+  private async enqueue(notification: PlatformNotification) {
+    const recipients = await this.recipients.resolve(notification);
+    const drafts = [];
+    for (const recipient of recipients) {
+      const preference = await this.preferences.get(recipient.id);
+      const channels = mergeExternalDeliveryPolicy({
+        category: notification.category,
+        requestedChannels: notification.deliveryChannels || [],
+        preference,
+        mandatoryCategories: this.mandatoryCategories,
+      });
+      for (const channel of channels) {
+        if (!hasAddress(recipient, channel)) continue;
+        drafts.push({
+          notificationId: notification.id,
+          userId: recipient.id,
+          channel,
+          subject: notification.title,
+          content: notification.content,
+        });
+      }
+    }
+    return this.deliveries.enqueue(drafts);
+  }
+}
+
+function normalizePublishInput(
+  input: PublishNotificationInput,
+): PublishNotificationInput {
+  return {
+    ...input,
+    recipientUserIds: unique([
+      ...(input.recipientUserIds || []),
+      ...(input.recipientUserId ? [input.recipientUserId] : []),
+    ]),
+    recipientRoleCodes: unique(input.recipientRoleCodes || []),
+    recipientDepartmentIds: unique(input.recipientDepartmentIds || []),
+    deliveryChannels: unique(input.deliveryChannels || []),
+    includeChildDepartments: Boolean(input.includeChildDepartments),
+  };
+}
+
+function normalizePreference(input: UpdateNotificationPreferenceInput) {
+  return {
+    enabledChannels: unique(input.enabledChannels).filter(isChannel),
+    disabledCategories: unique(
+      input.disabledCategories.map((item) => item.trim()).filter(Boolean),
+    ),
+  };
+}
+
+function hasAddress(
+  recipient: { email?: string; phone?: string },
+  channel: ExternalNotificationChannel,
+) {
+  return Boolean(channel === "email" ? recipient.email : recipient.phone);
+}
+
+function isChannel(value: string): value is ExternalNotificationChannel {
+  return value === "email" || value === "sms";
+}
+
+function unique<T>(values: T[]) {
+  return [...new Set(values)];
+}