create-windy 0.2.33 → 0.3.0

package/template/apps/server/src/module-host/user-directory-port.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, test } from "bun:test";
+import { ModuleUserDirectoryError } from "@southwind-ai/server-sdk";
+import { buildScopeContext } from "../data-access/context.js";
+import { createFoundationSnapshot } from "../foundation.js";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import type { ManagedDepartment, ManagedUser } from "../system/entities.js";
+import { createSystemRepositories } from "../system/seed.js";
+import { createModuleUserDirectoryPort } from "./user-directory-port.js";
+
+describe("模块用户目录 Port", () => {
+  test("只返回启用用户最小投影，并在 Repository 查询中执行部门范围", async () => {
+    const fixture = await createFixture();
+    const page = await fixture.port.list({
+      page: 1,
+      pageSize: 10,
+      q: "案",
+      ...({ actorId: "forged", departmentId: "dept_other" } as object),
+    });
+
+    expect(page).toEqual({
+      items: [
+        {
+          id: "user_child",
+          displayName: "子部门办案员",
+        },
+      ],
+      total: 1,
+      page: 1,
+      pageSize: 10,
+    });
+    expect(Object.keys(page.items[0] ?? {}).sort()).toEqual([
+      "displayName",
+      "id",
+    ]);
+    expect(fixture.runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "system.user-directory.query",
+        actor: expect.objectContaining({ id: "actor_manager" }),
+        metadata: expect.objectContaining({ resultCount: 1, total: 1 }),
+      }),
+    );
+  });
+
+  test("缺少权限或 Feature 停用时 fail closed 并记录拒绝", async () => {
+    const missingPermission = await createFixture({ permission: false });
+    await expect(missingPermission.port.list()).rejects.toMatchObject({
+      code: "USER_DIRECTORY_FORBIDDEN",
+    });
+    expect(missingPermission.runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({
+        action: "security.denied",
+        outcome: "denied",
+      }),
+    );
+
+    const disabledFeature = await createFixture({ featureEnabled: false });
+    await expect(disabledFeature.port.list()).rejects.toMatchObject({
+      code: "USER_DIRECTORY_FORBIDDEN",
+    });
+  });
+
+  test("拒绝越界分页与搜索 Schema", async () => {
+    const fixture = await createFixture();
+    for (const query of [
+      { page: 0 },
+      { pageSize: 101 },
+      { q: "x".repeat(101) },
+      { q: 23 } as never,
+    ]) {
+      await expect(fixture.port.list(query)).rejects.toBeInstanceOf(
+        ModuleUserDirectoryError,
+      );
+      await expect(fixture.port.list(query)).rejects.toMatchObject({
+        code: "USER_DIRECTORY_INVALID_QUERY",
+      });
+    }
+  });
+
+  test("V1 tenant、custom 与 self 均只读取宿主 nominal ScopeContext", async () => {
+    const tenant = await createFixture({ dataScope: "tenant" });
+    expect((await tenant.port.list({ q: "办案员" })).items).toHaveLength(2);
+
+    const custom = await createFixture({ dataScope: "custom" });
+    expect((await custom.port.list({ q: "办案员" })).items).toEqual([
+      { id: "user_child", displayName: "子部门办案员" },
+    ]);
+
+    const self = await createFixture({ dataScope: "self" });
+    expect((await self.port.list({ q: "办案员" })).items).toEqual([
+      { id: "user_child", displayName: "子部门办案员" },
+    ]);
+  });
+
+  test("缺少宿主 nominal ScopeContext 时拒绝，不回退全量目录", async () => {
+    const fixture = await createFixture({ dataScope: "missing" });
+    await expect(fixture.port.list()).rejects.toThrow("data-scope-denied");
+  });
+
+  test("生产关键审计不可持久化时不返回目录结果", async () => {
+    const fixture = await createFixture({ productionAudit: true });
+    await expect(fixture.port.list()).rejects.toThrow(
+      "关键审计事件无法持久化或进入恢复队列",
+    );
+  });
+});
+
+interface FixtureOptions {
+  permission?: boolean;
+  featureEnabled?: boolean;
+  dataScope?: DirectoryScope;
+  productionAudit?: boolean;
+}
+
+type DirectoryScope =
+  | "all"
+  | "tenant"
+  | "department-and-children"
+  | "custom"
+  | "self"
+  | "missing";
+
+async function createFixture(options: FixtureOptions = {}) {
+  const snapshot = createFoundationSnapshot();
+  const repositories = createSystemRepositories(snapshot);
+  await seedDirectory(repositories);
+  const actor = directoryActor(
+    options.permission ?? true,
+    options.dataScope ?? "department-and-children",
+  );
+  const runtime = createServerRuntime(
+    options.productionAudit ? { NODE_ENV: "production" } : {},
+    {
+      featureCatalog: snapshot.features,
+      featureResolver: {
+        resolve: (key) => ({
+          key,
+          enabled: options.featureEnabled ?? true,
+          visible: "visible",
+        }),
+      },
+    },
+  );
+  const context: RequestGuardContext = {
+    requestId: "request-directory",
+    actor,
+    startedAt: "2026-07-25T00:00:00.000Z",
+  };
+  return {
+    runtime,
+    port: createModuleUserDirectoryPort(
+      { repositories, runtime, features: snapshot.features },
+      context,
+    ),
+  };
+}
+
+async function seedDirectory(
+  repositories: ReturnType<typeof createSystemRepositories>,
+) {
+  const system = directoryActor(true, "all");
+  for (const departmentInput of [
+    department("dept_root", "业务部门"),
+    department("dept_child", "子部门", "dept_root"),
+    department("dept_other", "其它部门"),
+  ]) {
+    await repositories.departments.create(departmentInput, system);
+  }
+  for (const userInput of [
+    user("user_root", "根部门用户", "dept_root"),
+    user("user_child", "子部门办案员", "dept_child"),
+    user("user_other", "其它办案员", "dept_other"),
+    user("user_disabled", "停用办案员", "dept_child", "disabled"),
+  ]) {
+    await repositories.users.create(userInput, system);
+  }
+}
+
+function directoryActor(
+  permission: boolean,
+  scope: DirectoryScope = "department-and-children",
+): RequestActor {
+  const actorId = scope === "self" ? "user_child" : "actor_manager";
+  const role =
+    scope === "custom"
+      ? {
+          id: "role",
+          code: "role",
+          dataScope: "custom" as const,
+          departmentIds: ["dept_child"],
+        }
+      : {
+          id: "role",
+          code: "role",
+          dataScope: scope === "missing" ? ("self" as const) : scope,
+          departmentIds: [],
+        };
+  return {
+    id: scope === "all" ? "system_seed" : actorId,
+    type: "user",
+    name: "部门负责人",
+    roleCodes: ["department-manager"],
+    permissionKeys: permission ? ["system.user-directory.read"] : [],
+    ...(scope === "missing"
+      ? {}
+      : {
+          scopeContext: buildScopeContext(
+            scope === "all" ? "system_seed" : actorId,
+            scope === "all" || scope === "tenant" ? undefined : "dept_root",
+            [role],
+          ),
+        }),
+  };
+}
+
+function department(
+  id: string,
+  name: string,
+  parentId?: string,
+): Partial<ManagedDepartment> {
+  return { id, name, code: id, order: 10, status: "active", parentId };
+}
+
+function user(
+  id: string,
+  displayName: string,
+  departmentId: string,
+  status: ManagedUser["status"] = "active",
+): Partial<ManagedUser> {
+  return {
+    id,
+    username: id,
+    displayName,
+    departmentId,
+    roleIds: [],
+    status,
+  };
+}

package/template/apps/server/src/module-host/user-directory-port.ts

@@ -0,0 +1,139 @@
+import { randomUUIDv7 } from "bun";
+import {
+  ModuleUserDirectoryError,
+  type ModuleUserDirectoryPage,
+  type ModuleUserDirectoryPort,
+  type ModuleUserDirectoryQuery,
+} from "@southwind-ai/server-sdk";
+import type { AuditEvent, FeatureFlagDefinition } from "@southwind-ai/shared";
+import { DataScopedResourceService } from "../data-access/scoped-resource.js";
+import { departmentDescendantResolver } from "../data-access/department-tree.js";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+import { evaluateRouteGuards, findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { SystemRepositories } from "../system/seed.js";
+
+const featureKey = "system.user-directory";
+const permissionKey = "system.user-directory.read";
+const auditAction = "system.user-directory.query";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export interface ModuleUserDirectoryServices {
+  readonly repositories: Pick<SystemRepositories, "users" | "departments">;
+  readonly runtime: ServerRuntime;
+  readonly features: readonly FeatureFlagDefinition[];
+}
+
+export function createModuleUserDirectoryPort(
+  services: ModuleUserDirectoryServices,
+  context: RequestGuardContext,
+): ModuleUserDirectoryPort {
+  const feature = findFeature([...services.features], featureKey);
+  const access = new DataScopedResourceService(
+    services.repositories.users,
+    departmentDescendantResolver(services.repositories.departments),
+  );
+  return {
+    async list(rawQuery = {}) {
+      if (!feature) {
+        throw new ModuleUserDirectoryError(
+          "USER_DIRECTORY_UNAVAILABLE",
+          `宿主未注册 Feature：${featureKey}`,
+        );
+      }
+      const decision = await evaluateRouteGuards(services.runtime, context, {
+        permission: {
+          method: "GET",
+          path: "/internal/module-user-directory",
+          permissionKey,
+        },
+        feature,
+      });
+      if (!decision.allowed) {
+        throw new ModuleUserDirectoryError(
+          "USER_DIRECTORY_FORBIDDEN",
+          `用户目录访问被拒绝：${decision.reason}`,
+        );
+      }
+      const query = normalizeQuery(rawQuery);
+      const page = await access.list(
+        {
+          page: query.page,
+          pageSize: query.pageSize,
+          q: query.q,
+          status: "active",
+          sort: [{ field: "displayName", order: "asc" }],
+        },
+        ["displayName", "username"],
+        context.actor,
+      );
+      const result: ModuleUserDirectoryPage = {
+        items: page.items.map((user) => ({
+          id: user.id,
+          displayName:
+            user.displayName?.trim() || user.username || "未命名用户",
+        })),
+        total: page.total,
+        page: page.page,
+        pageSize: page.pageSize,
+      };
+      await services.runtime.auditSink.recordCriticalEvent(
+        queryAuditEvent(context, result),
+      );
+      return result;
+    },
+  };
+}
+
+function normalizeQuery(
+  query: ModuleUserDirectoryQuery,
+): Required<Pick<ModuleUserDirectoryQuery, "page" | "pageSize">> &
+  Pick<ModuleUserDirectoryQuery, "q"> {
+  const page = positiveInteger(query.page ?? 1, "page", 10_000);
+  const pageSize = positiveInteger(query.pageSize ?? 20, "pageSize", 100);
+  if (query.q !== undefined && typeof query.q !== "string") {
+    invalidQuery("q 必须是字符串");
+  }
+  const q = query.q?.trim();
+  if (q && q.length > 100) {
+    invalidQuery("q 最多 100 个字符");
+  }
+  return { page, pageSize, ...(q ? { q } : {}) };
+}
+
+function positiveInteger(
+  value: number,
+  field: string,
+  maximum: number,
+): number {
+  if (!Number.isInteger(value) || value < 1 || value > maximum) {
+    invalidQuery(`${field} 必须是 1-${maximum} 的整数`);
+  }
+  return value;
+}
+
+function invalidQuery(message: string): never {
+  throw new ModuleUserDirectoryError("USER_DIRECTORY_INVALID_QUERY", message);
+}
+
+function queryAuditEvent(
+  context: RequestGuardContext,
+  result: ModuleUserDirectoryPage,
+): AuditEvent {
+  return {
+    id: randomUUIDv7(),
+    action: auditAction,
+    outcome: "success",
+    actor: auditActor(context),
+    target: { type: "system.user-directory", id: "enabled-users" },
+    requestId: context.requestId,
+    metadata: {
+      page: result.page,
+      pageSize: result.pageSize,
+      resultCount: result.items.length,
+      total: result.total,
+    },
+    occurredAt: new Date().toISOString(),
+  };
+}

package/template/apps/server/src/module-host.ts

@@ -33,6 +33,10 @@ export {
   type ModuleStorageScope,
   type ModuleStorageServices,
 } from "./module-host/storage-port.js";
+export {
+  createModuleUserDirectoryPort,
+  type ModuleUserDirectoryServices,
+} from "./module-host/user-directory-port.js";
 // @windy-module system.scheduler begin
 export { createModuleTaskDefinitions } from "./module-host/task-definitions.js";
 // @windy-module system.scheduler end

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