create-windy 0.2.33 → 0.3.0

package/template/apps/server/src/notification/route-support.ts

@@ -0,0 +1,225 @@
+import { randomUUIDv7 } from "bun";
+import type {
+  AuditActionType,
+  NotificationInboxFilters,
+  UpdateNotificationPreferenceInput,
+  PublishNotificationInput,
+  UpdateNotificationInput,
+} from "@southwind-ai/shared";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+
+export type NotificationRouteContext = {
+  body?: unknown;
+  guardContext: RequestGuardContext;
+  params: Record<string, string | undefined>;
+  query: Record<string, string | undefined>;
+};
+
+export function parsePublishInput(
+  body: unknown,
+): PublishNotificationInput | Response {
+  const content = parseContentInput(body);
+  if (content instanceof Response) return content;
+  const value = body as Record<string, unknown>;
+  const scheduledFor = optionalText(value.scheduledFor);
+  if (scheduledFor && !validFutureDate(scheduledFor)) {
+    return invalidNotification("scheduledFor 必须是未来的 ISO 时间");
+  }
+  const recipientUserIds = stringArray(value.recipientUserIds);
+  const recipientRoleCodes = stringArray(value.recipientRoleCodes);
+  const recipientDepartmentIds = stringArray(value.recipientDepartmentIds);
+  const deliveryChannels = stringArray(value.deliveryChannels);
+  if (
+    recipientUserIds instanceof Response ||
+    recipientRoleCodes instanceof Response ||
+    recipientDepartmentIds instanceof Response ||
+    deliveryChannels instanceof Response
+  ) {
+    return invalidNotification("通知受众与渠道必须是字符串数组");
+  }
+  if (
+    deliveryChannels.some((channel) => channel !== "email" && channel !== "sms")
+  ) {
+    return invalidNotification("deliveryChannels 仅支持 email 或 sms");
+  }
+  if (
+    [recipientUserIds, recipientRoleCodes, recipientDepartmentIds].some(
+      (values) => values.length > 100,
+    )
+  ) {
+    return invalidNotification("单次发布的每类受众最多 100 项");
+  }
+  return {
+    ...content,
+    scheduledFor,
+    recipientUserIds,
+    recipientRoleCodes,
+    recipientDepartmentIds,
+    includeChildDepartments: value.includeChildDepartments === true,
+    deliveryChannels: deliveryChannels.filter(
+      (channel): channel is "email" | "sms" =>
+        channel === "email" || channel === "sms",
+    ),
+  };
+}
+
+export function parseUpdateInput(
+  body: unknown,
+): UpdateNotificationInput | Response {
+  return parseContentInput(body);
+}
+
+export function parsePreferenceInput(
+  body: unknown,
+): UpdateNotificationPreferenceInput | Response {
+  const value =
+    body && typeof body === "object" ? (body as Record<string, unknown>) : {};
+  const enabledChannels = stringArray(value.enabledChannels);
+  const disabledCategories = stringArray(value.disabledCategories);
+  if (
+    enabledChannels instanceof Response ||
+    disabledCategories instanceof Response
+  ) {
+    return invalidNotification("通知偏好必须是字符串数组");
+  }
+  if (
+    enabledChannels.some(
+      (channel) => channel !== "email" && channel !== "sms",
+    ) ||
+    disabledCategories.length > 100 ||
+    disabledCategories.some((category) => category.length > 40)
+  ) {
+    return invalidNotification("通知偏好包含不支持的渠道或分类");
+  }
+  return {
+    enabledChannels: enabledChannels.filter(
+      (channel): channel is "email" | "sms" =>
+        channel === "email" || channel === "sms",
+    ),
+    disabledCategories,
+  };
+}
+
+export function parseInboxFilters(
+  query: Record<string, string | undefined>,
+): NotificationInboxFilters | Response {
+  const q = query.q?.trim();
+  const category = query.category?.trim();
+  if (q && q.length > 200) return invalidFilter("q 最多 200 个字符");
+  if (category && category.length > 40)
+    return invalidFilter("category 最多 40 个字符");
+  if (query.read && query.read !== "read" && query.read !== "unread") {
+    return invalidFilter("read 仅支持 read 或 unread");
+  }
+  if (
+    query.favorite !== undefined &&
+    query.favorite !== "" &&
+    query.favorite !== "true" &&
+    query.favorite !== "false"
+  ) {
+    return invalidFilter("favorite 仅支持 true 或 false");
+  }
+  return {
+    q: q || undefined,
+    category: category || undefined,
+    read:
+      query.read === "read" || query.read === "unread" ? query.read : undefined,
+    favorite:
+      query.favorite === "true"
+        ? true
+        : query.favorite === "false"
+          ? false
+          : undefined,
+  };
+}
+
+export function notificationEvent(
+  context: NotificationRouteContext,
+  action: AuditActionType,
+  id: string,
+) {
+  return {
+    id: randomUUIDv7(),
+    action,
+    outcome: "success" as const,
+    actor: auditActor(context.guardContext),
+    target: { type: "notification", id },
+    requestId: context.guardContext.requestId,
+    occurredAt: new Date().toISOString(),
+  };
+}
+
+export function notificationNotFound(id: string) {
+  return Response.json(
+    { error: "NOT_FOUND", resource: "notification", id },
+    { status: 404 },
+  );
+}
+
+function parseContentInput(body: unknown): UpdateNotificationInput | 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 invalidFilter(message: string) {
+  return Response.json(
+    { error: "INVALID_NOTIFICATION_FILTER", message },
+    { status: 400 },
+  );
+}
+
+function invalidNotification(message: string) {
+  return Response.json(
+    { error: "INVALID_NOTIFICATION", message },
+    { status: 400 },
+  );
+}
+
+function text(value: unknown) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function optionalText(value: unknown) {
+  const result = text(value);
+  return result || undefined;
+}
+
+function stringArray(value: unknown): string[] | Response {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    return invalidNotification("字段必须是字符串数组");
+  }
+  return [...new Set(value.map((item) => item.trim()).filter(Boolean))];
+}
+
+function validFutureDate(value: string) {
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) && timestamp > Date.now();
+}

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