create-windy 0.2.34 → 0.3.0

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

@@ -15,6 +15,10 @@ class FakeRouteApp {
     this.handlers.set(`POST ${path}`, handler);
   }
 
+  put(path: string, handler: (context: unknown) => unknown) {
+    this.handlers.set(`PUT ${path}`, handler);
+  }
+
   delete(path: string, handler: (context: unknown) => unknown) {
     this.handlers.set(`DELETE ${path}`, handler);
   }
@@ -148,4 +152,182 @@ describe("站内通知闭环", () => {
 
     expect(response.status).toBe(403);
   });
+
+  test("收藏和取消收藏路由幂等且只审计真实状态变化", async () => {
+    const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token_1" });
+    const app = new FakeRouteApp();
+    registerNotificationRoutes(
+      app,
+      new InMemoryNotificationRepository(),
+      runtime,
+      createFoundationSnapshot().features,
+    );
+    const guardContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/notifications", {
+        headers: { authorization: "Bearer token_1" },
+      }),
+    );
+    const published = (await app.invoke("POST", "/system/notifications", {
+      guardContext,
+      params: {},
+      query: {},
+      body: {
+        title: "收藏测试",
+        summary: "收藏测试摘要",
+        content: "收藏测试正文",
+        category: "系统",
+      },
+    })) as { id: string };
+
+    const first = await app.invoke("PUT", "/notifications/:id/favorite", {
+      guardContext,
+      params: { id: published.id },
+      query: {},
+    });
+    const repeated = await app.invoke("PUT", "/notifications/:id/favorite", {
+      guardContext,
+      params: { id: published.id },
+      query: {},
+    });
+    const removed = await app.invoke("DELETE", "/notifications/:id/favorite", {
+      guardContext,
+      params: { id: published.id },
+      query: {},
+    });
+    const repeatedRemove = await app.invoke(
+      "DELETE",
+      "/notifications/:id/favorite",
+      {
+        guardContext,
+        params: { id: published.id },
+        query: {},
+      },
+    );
+
+    expect(first).toMatchObject({ favorite: true, changed: true });
+    expect(repeated).toMatchObject({ favorite: true, changed: false });
+    expect(removed).toEqual({
+      success: true,
+      favorite: false,
+      changed: true,
+    });
+    expect(repeatedRemove).toEqual({
+      success: true,
+      favorite: false,
+      changed: false,
+    });
+    expect(runtime.auditSink.list().map(({ action }) => action)).toEqual([
+      "notification.publish",
+      "notification.favorite",
+      "notification.unfavorite",
+    ]);
+  });
+
+  test("非法收件箱筛选被拒绝", async () => {
+    const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token_1" });
+    const app = new FakeRouteApp();
+    registerNotificationRoutes(
+      app,
+      new InMemoryNotificationRepository(),
+      runtime,
+      createFoundationSnapshot().features,
+    );
+    const guardContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/notifications", {
+        headers: { authorization: "Bearer token_1" },
+      }),
+    );
+
+    const response = (await app.invoke("GET", "/notifications", {
+      guardContext,
+      params: {},
+      query: { read: "all", favorite: "yes" },
+    })) as Response;
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toMatchObject({
+      error: "INVALID_NOTIFICATION_FILTER",
+    });
+  });
+
+  test("system.notification Feature 关闭时收件箱 Guard 拒绝", async () => {
+    const runtime = createServerRuntime(
+      { WINDY_DEV_ADMIN_TOKEN: "token_1" },
+      {
+        featureResolver: {
+          resolve(key) {
+            return { key, enabled: false, visible: "hidden" };
+          },
+        },
+      },
+    );
+    const app = new FakeRouteApp();
+    registerNotificationRoutes(
+      app,
+      new InMemoryNotificationRepository(),
+      runtime,
+      createFoundationSnapshot().features,
+    );
+    const guardContext = await runtime.createGuardContext(
+      new Request("http://localhost/api/notifications", {
+        headers: { authorization: "Bearer token_1" },
+      }),
+    );
+
+    const response = (await app.invoke("GET", "/notifications", {
+      guardContext,
+      params: {},
+      query: {},
+    })) as Response;
+
+    expect(response.status).toBe(403);
+    expect(await response.json()).toMatchObject({ reason: "feature-disabled" });
+  });
+
+  test("猜测不可见通知 ID 不能通过收藏 API 探测受众", async () => {
+    const runtime = createServerRuntime();
+    const repository = new InMemoryNotificationRepository();
+    const app = new FakeRouteApp();
+    registerNotificationRoutes(
+      app,
+      repository,
+      runtime,
+      createFoundationSnapshot().features,
+    );
+    const actor = {
+      id: "outsider",
+      type: "user" as const,
+      name: "外部用户",
+      roleCodes: ["guest"],
+      permissionKeys: ["system.notification.read"],
+    };
+    const guardContext = await runtime.createGuardContextForActor(
+      new Request("http://localhost/api/notifications/targeted/favorite"),
+      actor,
+    );
+    const targeted = await repository.publish(
+      {
+        title: "定向通知",
+        summary: "仅指定用户可见",
+        content: "不可通过 ID 猜测访问",
+        category: "审批",
+        recipientUserId: "recipient",
+      },
+      { ...actor, id: "publisher" },
+    );
+
+    for (const method of ["PUT", "DELETE"]) {
+      const response = (await app.invoke(
+        method,
+        "/notifications/:id/favorite",
+        {
+          guardContext,
+          params: { id: targeted.id },
+          query: {},
+        },
+      )) as Response;
+      expect(response.status).toBe(404);
+      expect(await response.json()).toMatchObject({ error: "NOT_FOUND" });
+    }
+  });
 });

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"],
+};