create-windy 0.1.0

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

@@ -0,0 +1,257 @@
+import { randomUUIDv7 } from "bun";
+import type { ModuleManifest } from "@windy/modules";
+import type { AuditEvent } from "@windy/shared";
+import { evaluateAccessGuards } from "../access-guards.js";
+import { isServerScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { decodeSearchCursor, encodeSearchCursor } from "./cursor.js";
+import { SearchProtocolError } from "./errors.js";
+import { SearchRateLimiter } from "./rate-limiter.js";
+import {
+  type SearchExecutionContext,
+  type SearchProvider,
+  type SearchProviderCatalogItem,
+  type SearchRequest,
+  type SearchResultPage,
+} from "./contracts.js";
+import {
+  executeSearchProvider,
+  readSearchProviderHealth,
+} from "./provider-execution.js";
+import {
+  buildSearchRegistrations,
+  selectSearchProviders,
+  type ProviderRegistration,
+} from "./registry.js";
+
+type SearchRuntime = Pick<
+  ReturnType<typeof createServerRuntime>,
+  "auditSink" | "recordDecisions" | "resolveFeature"
+>;
+
+export interface SearchServiceOptions {
+  enabledProviderKeys?: readonly string[];
+  providerTimeoutMs?: number;
+  healthTimeoutMs?: number;
+  maxRequestsPerMinute?: number;
+  now?: () => Date;
+}
+
+export class SearchService {
+  private readonly registrations: ProviderRegistration[];
+  private readonly providerTimeoutMs: number;
+  private readonly healthTimeoutMs: number;
+  private readonly now: () => Date;
+  private readonly limiter: SearchRateLimiter;
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    providers: readonly SearchProvider[],
+    private readonly runtime: SearchRuntime,
+    options: SearchServiceOptions = {},
+  ) {
+    this.now = options.now || (() => new Date());
+    this.providerTimeoutMs = boundedTimeout(options.providerTimeoutMs, 800);
+    this.healthTimeoutMs = boundedTimeout(options.healthTimeoutMs, 500);
+    this.limiter = new SearchRateLimiter(
+      clamp(options.maxRequestsPerMinute || 30, 1, 300),
+      60_000,
+      () => this.now().getTime(),
+    );
+    this.registrations = buildSearchRegistrations(
+      modules,
+      providers,
+      options.enabledProviderKeys,
+    );
+  }
+
+  providerKeys(): string[] {
+    return this.registrations.map(({ definition }) => definition.key);
+  }
+
+  async discover(
+    context: RequestGuardContext,
+  ): Promise<SearchProviderCatalogItem[]> {
+    const allowed = await this.authorized(context, this.registrations);
+    return Promise.all(
+      allowed.map(async ({ definition, provider, enabled }) => ({
+        key: definition.key,
+        label: definition.label,
+        contractVersion: definition.contractVersion,
+        providerVersion: provider.providerVersion,
+        enabled,
+        health: await readSearchProviderHealth(
+          provider,
+          this.healthTimeoutMs,
+          this.now,
+        ),
+      })),
+    );
+  }
+
+  async search(
+    input: SearchRequest,
+    context: RequestGuardContext,
+  ): Promise<SearchResultPage> {
+    const request = validateRequest(input);
+    if (!isServerScopeContext(context.actor.scopeContext)) {
+      throw new SearchProtocolError("SCOPE_DENIED", "缺少服务端搜索范围");
+    }
+    this.limiter.consume(context.actor.id);
+    const providerCursors = decodeSearchCursor(request.cursor);
+    const authorized = await this.authorized(context, this.registrations);
+    const selected = selectSearchProviders(authorized, request.providerKeys);
+    this.runtime.auditSink.recordEvent(
+      searchEvent(context, "search.query", this.now(), {
+        queryDigest: digest(request.query),
+        queryLength: request.query.length,
+        providerKeys: selected.map(({ definition }) => definition.key),
+      }),
+    );
+    const executionContext: SearchExecutionContext = {
+      actor: { ...context.actor, scopeContext: context.actor.scopeContext },
+      userId: context.actor.id,
+      roleCodes: context.actor.roleCodes,
+      organizationId: context.actor.scopeContext.departmentId,
+      requestId: context.requestId,
+    };
+    const executions = await Promise.all(
+      selected.map((registration) =>
+        executeSearchProvider(
+          registration,
+          request.query,
+          request.limit,
+          providerCursors[registration.definition.key],
+          executionContext,
+          this.providerTimeoutMs,
+          this.now,
+        ),
+      ),
+    );
+    const groups = executions.flatMap(({ group }) => (group ? [group] : []));
+    const failures = executions.flatMap(({ failure }) =>
+      failure ? [failure] : [],
+    );
+    const nextCursor = encodeSearchCursor(
+      Object.fromEntries(
+        groups.flatMap((group) =>
+          group.nextCursor ? [[group.providerKey, group.nextCursor]] : [],
+        ),
+      ),
+    );
+    const result = {
+      groups,
+      nextCursor,
+      partial: failures.length > 0,
+      failures,
+      observations: executions.map(({ observation }) => observation),
+    };
+    this.runtime.auditSink.recordEvent(
+      searchEvent(context, "search.result.access", this.now(), {
+        providerKeys: selected.map(({ definition }) => definition.key),
+        groupCount: groups.length,
+        hitCount: groups.reduce((total, group) => total + group.hits.length, 0),
+        partial: result.partial,
+      }),
+    );
+    return result;
+  }
+
+  private async authorized(
+    context: RequestGuardContext,
+    registrations: ProviderRegistration[],
+  ) {
+    const checks = await Promise.all(
+      registrations.map(async (registration) => ({
+        registration,
+        allowed: (
+          await evaluateAccessGuards(
+            this.runtime,
+            context,
+            {
+              permission: {
+                permissionKey: registration.definition.permissionKey,
+              },
+              feature: registration.feature,
+            },
+            { record: false },
+          )
+        ).decision.allowed,
+      })),
+    );
+    return checks
+      .filter(({ allowed }) => allowed)
+      .map(({ registration }) => registration);
+  }
+}
+
+function validateRequest(input: SearchRequest) {
+  if (!input || typeof input !== "object") {
+    throw new SearchProtocolError("INVALID_REQUEST", "搜索请求无效");
+  }
+  const query = typeof input.query === "string" ? input.query.trim() : "";
+  if (!query || query.length > 200) {
+    throw new SearchProtocolError("INVALID_REQUEST", "查询词长度必须为 1-200");
+  }
+  if (
+    input.limit !== undefined &&
+    (typeof input.limit !== "number" || !Number.isFinite(input.limit))
+  ) {
+    throw new SearchProtocolError("INVALID_REQUEST", "分页大小无效");
+  }
+  if (input.cursor !== undefined && typeof input.cursor !== "string") {
+    throw new SearchProtocolError("INVALID_REQUEST", "搜索游标无效");
+  }
+  if (
+    input.providerKeys &&
+    (!Array.isArray(input.providerKeys) ||
+      input.providerKeys.length > 20 ||
+      input.providerKeys.some(
+        (key) =>
+          typeof key !== "string" || !key.trim() || key.trim().length > 120,
+      ))
+  ) {
+    throw new SearchProtocolError("INVALID_REQUEST", "Provider 选择无效");
+  }
+  return {
+    query,
+    limit: clamp(input.limit || 10, 1, 50),
+    cursor: input.cursor,
+    providerKeys: input.providerKeys,
+  };
+}
+
+function searchEvent(
+  context: RequestGuardContext,
+  action: "search.query" | "search.result.access",
+  now: Date,
+  metadata: Record<string, unknown>,
+): AuditEvent {
+  return {
+    id: randomUUIDv7(),
+    action,
+    outcome: "success",
+    actor: {
+      id: context.actor.id,
+      type: context.actor.type === "anonymous" ? "user" : context.actor.type,
+      name: context.actor.name,
+    },
+    target: { type: "search-provider" },
+    requestId: context.requestId,
+    metadata,
+    occurredAt: now.toISOString(),
+  };
+}
+
+function digest(value: string) {
+  return new Bun.CryptoHasher("sha256").update(value).digest("hex");
+}
+
+function boundedTimeout(value: number | undefined, fallback: number) {
+  return clamp(value || fallback, 10, 5_000);
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}

package/template/apps/server/src/search/test-support.ts

@@ -0,0 +1,122 @@
+import type { ModuleManifest } from "@windy/modules";
+import { defineSearchProvider, featureKey } from "@windy/shared";
+import { buildScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import type { SearchProvider, SearchProviderPage } from "./contracts.js";
+import { SearchService } from "./service.js";
+
+export function createSearchTestService(
+  modules: ModuleManifest[],
+  providers: SearchProvider[],
+  options: ConstructorParameters<typeof SearchService>[3] = {},
+) {
+  return new SearchService(
+    modules,
+    providers,
+    createServerRuntime({ NODE_ENV: "development" }),
+    options,
+  );
+}
+
+export function searchTestProvider(
+  key: string,
+  providerVersion = "0.1.0",
+  search: SearchProvider["search"] = async (): Promise<SearchProviderPage> => ({
+    hits: [],
+  }),
+): SearchProvider {
+  return {
+    key,
+    providerVersion,
+    search,
+    health: async () => ({
+      status: "healthy",
+      checkedAt: "2026-07-16T00:00:00.000Z",
+    }),
+  };
+}
+
+export function searchTestContext(
+  permissionKeys: string[],
+): RequestGuardContext {
+  return {
+    requestId: "request_server",
+    startedAt: "2026-07-16T00:00:00.000Z",
+    actor: {
+      id: "user_server",
+      type: "user",
+      name: "服务端用户",
+      roleCodes: ["operator"],
+      permissionKeys,
+      scopeContext: buildScopeContext("user_server", "dept_server", [
+        {
+          id: "role_operator",
+          code: "operator",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    },
+  };
+}
+
+export function searchTestModule(
+  providerKey = "example.search",
+  permissionKey = "example.ticket.read",
+  name = "example",
+): ModuleManifest {
+  const capabilityKey = featureKey(`${name}.ticket`);
+  return {
+    name,
+    version: "0.1.0",
+    label: name,
+    description: `${name} module`,
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: permissionKey,
+        label: "查看",
+        module: name,
+        moduleLabel: name,
+        resource: "ticket",
+        resourceLabel: "工单",
+        action: "read",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: capabilityKey,
+        label: "工单",
+        module: name,
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [
+      defineSearchProvider({
+        key: providerKey,
+        kind: "search",
+        contractVersion: "1",
+        providerVersion: "0.1.0",
+        label: "示例搜索",
+        enabledByDefault: true,
+        permissionKey,
+        featureKey: capabilityKey,
+        deepLink: {
+          surface: "business",
+          routeTemplate: "/tickets/:id",
+          idParameter: "id",
+        },
+      }),
+    ],
+    auditActions: [],
+  };
+}

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

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test";
+import type { RequestActor } from "../guards.js";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import { FakeRouteApp } from "../system/route-test-app.js";
+import { registerSessionContextRoute } from "./routes.js";
+
+describe("会话上下文", () => {
+  test("普通账号只获得最小用户信息且不暴露权限列表", async () => {
+    const response = await invoke(businessActor(), true);
+    const body = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    expect(body).toEqual({
+      user: {
+        id: "user_business",
+        username: "business",
+        displayName: "业务用户",
+      },
+      capabilities: { adminAccess: false },
+    });
+    expect(JSON.stringify(body)).not.toContain("permissionKeys");
+    expect(JSON.stringify(body)).not.toContain("roleCodes");
+  });
+
+  test("管理员在功能启用时获得管理面入口能力", async () => {
+    const response = await invoke(adminActor(), true);
+
+    await expect(response.json()).resolves.toMatchObject({
+      capabilities: { adminAccess: true },
+    });
+  });
+
+  test("管理面功能关闭时不展示入口", async () => {
+    const response = await invoke(adminActor(), false);
+
+    await expect(response.json()).resolves.toMatchObject({
+      capabilities: { adminAccess: false },
+    });
+  });
+
+  test("匿名请求被拒绝", async () => {
+    const response = await invoke(anonymousActor(), true);
+
+    expect(response.status).toBe(401);
+    await expect(response.json()).resolves.toEqual({ error: "UNAUTHENTICATED" });
+  });
+});
+
+async function invoke(
+  actor: RequestActor,
+  adminEnabled: boolean,
+): Promise<Response> {
+  const snapshot = createFoundationSnapshot();
+  const runtime = createServerRuntime(
+    {},
+    {
+      actorResolver: { resolve: () => actor },
+      featureResolver: {
+        resolve: (key) => ({
+          key,
+          enabled: key === "system.admin" ? adminEnabled : true,
+          visible: "visible",
+        }),
+      },
+    },
+  );
+  const app = new FakeRouteApp();
+  registerSessionContextRoute(app, runtime, snapshot.features);
+  const guardContext = await runtime.createGuardContext(
+    new Request("http://localhost/api/session/context"),
+  );
+  return (await app.invoke("GET", "/session/context", {
+    guardContext,
+    params: {},
+    query: {},
+  })) as Response;
+}
+
+function businessActor(): RequestActor {
+  return {
+    id: "user_business",
+    type: "user",
+    name: "业务用户",
+    username: "business",
+    roleCodes: ["user"],
+    permissionKeys: ["work-order.ticket.read"],
+  };
+}
+
+function adminActor(): RequestActor {
+  return {
+    id: "user_admin",
+    type: "user",
+    name: "平台管理员",
+    displayName: "平台管理员",
+    roleCodes: ["super-admin"],
+    permissionKeys: ["system.admin.access"],
+  };
+}
+
+function anonymousActor(): RequestActor {
+  return {
+    id: "anonymous",
+    type: "anonymous",
+    name: "匿名访问",
+    roleCodes: [],
+    permissionKeys: [],
+  };
+}

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

@@ -0,0 +1,56 @@
+import type { FeatureFlagDefinition } from "@windy/shared";
+import { evaluateAdminAccess } from "../admin/routes.js";
+import type { createServerRuntime } from "../runtime.js";
+import { routeContext } from "../system/route-helpers.js";
+import type { RouteApp } from "../system/route-types.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export interface SessionContextResponse {
+  user: {
+    id: string;
+    username?: string;
+    displayName: string;
+  };
+  capabilities: {
+    adminAccess: boolean;
+  };
+}
+
+export function registerSessionContextRoute(
+  app: Pick<RouteApp, "get">,
+  runtime: ServerRuntime,
+  features: FeatureFlagDefinition[],
+): void {
+  app.get("/session/context", async (rawContext) => {
+    const { guardContext } = routeContext(rawContext);
+    if (guardContext.actor.type === "anonymous") {
+      return Response.json(
+        { error: "UNAUTHENTICATED" },
+        { status: 401, headers: { "cache-control": "no-store" } },
+      );
+    }
+
+    const adminDecision = await evaluateAdminAccess(
+      runtime,
+      guardContext,
+      features,
+      { record: false },
+    );
+    const actor = guardContext.actor;
+    const response: SessionContextResponse = {
+      user: {
+        id: actor.id,
+        username: actor.username,
+        displayName: actor.displayName || actor.name,
+      },
+      capabilities: {
+        adminAccess: adminDecision.allowed,
+      },
+    };
+
+    return Response.json(response, {
+      headers: { "cache-control": "no-store" },
+    });
+  });
+}

package/template/apps/server/src/settings/drizzle-repository.ts

@@ -0,0 +1,66 @@
+import { platformBrandingSettings } from "@windy/database";
+import type { PlatformBrandingSettings } from "@windy/shared";
+import { eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { BrandingSettingsRepository } from "./repository.js";
+
+const PLATFORM_BRANDING_ID = "platform";
+
+export class DrizzleBrandingSettingsRepository implements BrandingSettingsRepository {
+  constructor(
+    private readonly db: NodePgDatabase,
+    private readonly defaults: PlatformBrandingSettings,
+  ) {}
+
+  async get(): Promise<PlatformBrandingSettings> {
+    const [row] = await this.db
+      .select()
+      .from(platformBrandingSettings)
+      .where(eq(platformBrandingSettings.id, PLATFORM_BRANDING_ID))
+      .limit(1);
+    return row
+      ? brandingSettings(row.softwareName, row.logoUrl, row.description)
+      : { ...this.defaults };
+  }
+
+  async update(
+    settings: PlatformBrandingSettings,
+    actorId: string,
+  ): Promise<PlatformBrandingSettings> {
+    const [row] = await this.db
+      .insert(platformBrandingSettings)
+      .values({
+        id: PLATFORM_BRANDING_ID,
+        softwareName: settings.softwareName,
+        logoUrl: settings.logoUrl,
+        description: settings.description,
+        createdBy: actorId,
+        updatedBy: actorId,
+      })
+      .onConflictDoUpdate({
+        target: platformBrandingSettings.id,
+        set: {
+          softwareName: settings.softwareName,
+          logoUrl: settings.logoUrl,
+          description: settings.description,
+          updatedAt: new Date(),
+          updatedBy: actorId,
+        },
+      })
+      .returning();
+    if (!row) throw new Error("品牌设置保存失败");
+    return brandingSettings(row.softwareName, row.logoUrl, row.description);
+  }
+}
+
+function brandingSettings(
+  softwareName: string,
+  logoUrl: string | null,
+  description: string | null,
+): PlatformBrandingSettings {
+  return {
+    softwareName,
+    logoUrl: logoUrl || undefined,
+    description: description || undefined,
+  };
+}

package/template/apps/server/src/settings/repository.ts

@@ -0,0 +1,29 @@
+import type { PlatformBrandingSettings } from "@windy/shared";
+
+export interface BrandingSettingsRepository {
+  get(): Promise<PlatformBrandingSettings>;
+  update(
+    settings: PlatformBrandingSettings,
+    actorId: string,
+  ): Promise<PlatformBrandingSettings>;
+}
+
+export class InMemoryBrandingSettingsRepository implements BrandingSettingsRepository {
+  private settings: PlatformBrandingSettings;
+
+  constructor(defaults: PlatformBrandingSettings) {
+    this.settings = { ...defaults };
+  }
+
+  async get(): Promise<PlatformBrandingSettings> {
+    return { ...this.settings };
+  }
+
+  async update(
+    settings: PlatformBrandingSettings,
+    _actorId: string,
+  ): Promise<PlatformBrandingSettings> {
+    this.settings = { ...settings };
+    return this.get();
+  }
+}