create-windy 0.1.0

package/template/apps/server/src/scheduler/types.ts

@@ -0,0 +1,103 @@
+import type { FeatureFlagDefinition } from "@windy/shared";
+
+export interface SchedulerClock {
+  now(): Date;
+}
+
+export const systemClock: SchedulerClock = { now: () => new Date() };
+export const SCHEDULER_STALE_THRESHOLD_SECONDS = 15 * 60;
+
+export type ScheduledTaskHandler = () =>
+  | Promise<Record<string, unknown> | void>
+  | Record<string, unknown>
+  | void;
+
+export interface ScheduledTaskDefinition {
+  key: string;
+  label: string;
+  description?: string;
+  intervalSeconds: number;
+  maxAttempts: number;
+  retryDelaySeconds: number;
+  permissionKey: string;
+  feature: FeatureFlagDefinition;
+  handler: ScheduledTaskHandler;
+  isIdleResult?: (value: Record<string, unknown> | void) => boolean;
+}
+
+export interface StoredScheduledTask {
+  key: string;
+  label: string;
+  description?: string;
+  featureKey: string;
+  permissionKey: string;
+  intervalSeconds: number;
+  maxAttempts: number;
+  retryDelaySeconds: number;
+  enabled: boolean;
+  status: "active" | "archived";
+  nextRunAt: string;
+  lastRunAt?: string;
+}
+
+export type TaskRunTrigger = "scheduled" | "manual" | "retry";
+export type TaskRunStatus =
+  | "running"
+  | "succeeded"
+  | "retry-pending"
+  | "failed"
+  | "blocked";
+
+export interface ScheduledTaskRun {
+  id: string;
+  taskKey: string;
+  trigger: TaskRunTrigger;
+  status: TaskRunStatus;
+  attempt: number;
+  requestedBy: string;
+  retryOfRunId?: string;
+  scheduledFor: string;
+  startedAt: string;
+  finishedAt?: string;
+  nextAttemptAt?: string;
+  error?: string;
+  result?: Record<string, unknown>;
+  durableJobId?: string;
+}
+
+export interface TaskRunCompletion {
+  status: Exclude<TaskRunStatus, "running">;
+  finishedAt: Date;
+  nextAttemptAt?: Date;
+  error?: string;
+  result?: Record<string, unknown>;
+}
+
+export interface StaleRunRecovery {
+  recoveryId: string;
+  runId: string;
+  taskKey: string;
+  expectedStartedAt: string;
+  staleBefore: Date;
+  recoveredAt: Date;
+  recoveredBy: string;
+  reason: string;
+}
+
+export type StaleRunRecoveryConflict =
+  | "not-found"
+  | "task-mismatch"
+  | "not-running"
+  | "version-mismatch"
+  | "not-stale";
+
+export type StaleRunRecoveryResult =
+  | { ok: true; run: ScheduledTaskRun }
+  | { ok: false; reason: StaleRunRecoveryConflict };
+
+export interface SchedulerTickResult {
+  scheduled: number;
+  retried: number;
+  blocked: number;
+  failed: number;
+}

package/template/apps/server/src/scheduler/worker.ts

@@ -0,0 +1,38 @@
+import type { SchedulerService } from "./service.js";
+import type { SchedulerTickResult } from "./types.js";
+
+export class SchedulerWorker {
+  private timer?: ReturnType<typeof setInterval>;
+  private ticking = false;
+
+  constructor(
+    private readonly scheduler: SchedulerService,
+    private readonly pollIntervalMs = 1_000,
+    private readonly onError: (error: unknown) => void = () => undefined,
+    private readonly onTick: (result: SchedulerTickResult) => void = () =>
+      undefined,
+  ) {}
+
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => void this.poll(), this.pollIntervalMs);
+    this.timer.unref();
+  }
+
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
+
+  private async poll() {
+    if (this.ticking) return;
+    this.ticking = true;
+    try {
+      this.onTick(await this.scheduler.tick());
+    } catch (error) {
+      this.onError(error);
+    } finally {
+      this.ticking = false;
+    }
+  }
+}

package/template/apps/server/src/search/config.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { readSearchServiceOptions } from "./config.js";
+
+describe("搜索服务启动配置", () => {
+  test("未配置时使用 Core 默认值，显式空列表关闭全部 Provider", () => {
+    expect(readSearchServiceOptions({})).toEqual({
+      enabledProviderKeys: undefined,
+      providerTimeoutMs: undefined,
+      healthTimeoutMs: undefined,
+      maxRequestsPerMinute: undefined,
+    });
+    expect(
+      readSearchServiceOptions({ SEARCH_PROVIDER_KEYS: "  " })
+        .enabledProviderKeys,
+    ).toEqual([]);
+  });
+
+  test("解析 Provider 白名单、超时和按 Actor 限流", () => {
+    expect(
+      readSearchServiceOptions({
+        SEARCH_PROVIDER_KEYS: "work-order.ticket.search,asset.device-search",
+        SEARCH_PROVIDER_TIMEOUT_MS: "900",
+        SEARCH_HEALTH_TIMEOUT_MS: "400",
+        SEARCH_MAX_REQUESTS_PER_MINUTE: "45",
+      }),
+    ).toEqual({
+      enabledProviderKeys: ["work-order.ticket.search", "asset.device-search"],
+      providerTimeoutMs: 900,
+      healthTimeoutMs: 400,
+      maxRequestsPerMinute: 45,
+    });
+  });
+
+  test.each([
+    [{ SEARCH_PROVIDER_KEYS: "work-order.search,work-order.search" }, "重复"],
+    [{ SEARCH_PROVIDER_KEYS: "work_order.search" }, "非法"],
+    [{ SEARCH_PROVIDER_TIMEOUT_MS: "9" }, "10-5000"],
+    [{ SEARCH_HEALTH_TIMEOUT_MS: "10.5" }, "整数"],
+    [{ SEARCH_MAX_REQUESTS_PER_MINUTE: "301" }, "1-300"],
+  ])("非法配置在启动阶段失败：%j", (environment, message) => {
+    expect(() => readSearchServiceOptions(environment)).toThrow(message);
+  });
+});

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

@@ -0,0 +1,62 @@
+import type { SearchServiceOptions } from "./service.js";
+
+const providerKeyPattern = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+
+export function readSearchServiceOptions(
+  environment: Record<string, string | undefined>,
+): SearchServiceOptions {
+  return {
+    enabledProviderKeys: readProviderKeys(environment.SEARCH_PROVIDER_KEYS),
+    providerTimeoutMs: readBoundedInteger(
+      "SEARCH_PROVIDER_TIMEOUT_MS",
+      environment.SEARCH_PROVIDER_TIMEOUT_MS,
+      10,
+      5_000,
+    ),
+    healthTimeoutMs: readBoundedInteger(
+      "SEARCH_HEALTH_TIMEOUT_MS",
+      environment.SEARCH_HEALTH_TIMEOUT_MS,
+      10,
+      5_000,
+    ),
+    maxRequestsPerMinute: readBoundedInteger(
+      "SEARCH_MAX_REQUESTS_PER_MINUTE",
+      environment.SEARCH_MAX_REQUESTS_PER_MINUTE,
+      1,
+      300,
+    ),
+  };
+}
+
+function readProviderKeys(value: string | undefined): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!value.trim()) return [];
+  const keys = value.split(",").map((key) => key.trim());
+  if (
+    keys.length > 20 ||
+    keys.some((key) => key.length > 120 || !providerKeyPattern.test(key))
+  ) {
+    throw new Error("SEARCH_PROVIDER_KEYS 包含非法 Provider Key");
+  }
+  if (new Set(keys).size !== keys.length) {
+    throw new Error("SEARCH_PROVIDER_KEYS 不能包含重复 Provider Key");
+  }
+  return keys;
+}
+
+function readBoundedInteger(
+  name: string,
+  value: string | undefined,
+  minimum: number,
+  maximum: number,
+): number | undefined {
+  if (value === undefined) return undefined;
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`${name} 必须是整数`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+    throw new Error(`${name} 必须位于 ${minimum}-${maximum}`);
+  }
+  return parsed;
+}

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

@@ -0,0 +1,127 @@
+import {
+  SEARCH_PROVIDER_CONTRACT_VERSION,
+  type SearchProviderManifestDefinition,
+} from "@windy/shared";
+import type { ModuleManifest } from "@windy/modules";
+import type { ScopeContext } from "../data-access/context.js";
+import type { RequestActor } from "../guards.js";
+
+export { SEARCH_PROVIDER_CONTRACT_VERSION };
+
+export type SearchErrorCode =
+  | "INVALID_REQUEST"
+  | "INVALID_CURSOR"
+  | "RATE_LIMITED"
+  | "SCOPE_DENIED"
+  | "PROVIDER_UNAVAILABLE";
+
+export interface SearchRequest {
+  query: string;
+  limit?: number;
+  cursor?: string;
+  /** 只允许缩小已启用且已授权的 Provider 集合。 */
+  providerKeys?: string[];
+}
+
+export interface SearchProviderQuery {
+  text: string;
+  limit: number;
+  cursor?: string;
+  signal: AbortSignal;
+}
+
+export interface SearchExecutionContext {
+  actor: RequestActor & { scopeContext: ScopeContext };
+  userId: string;
+  roleCodes: readonly string[];
+  organizationId?: string;
+  requestId: string;
+}
+
+export interface SearchProviderHit {
+  id: string;
+  resourceType: string;
+  maskedTitle: string;
+  maskedExcerpt?: string;
+  score?: number;
+}
+
+export interface SearchProviderPage {
+  hits: SearchProviderHit[];
+  nextCursor?: string;
+}
+
+export interface SearchProviderHealth {
+  status: "healthy" | "degraded" | "unavailable";
+  checkedAt: string;
+  message?: string;
+}
+
+export interface SearchProvider {
+  readonly key: string;
+  readonly providerVersion: string;
+  search(
+    request: SearchProviderQuery,
+    context: SearchExecutionContext,
+  ): Promise<SearchProviderPage>;
+  health(signal: AbortSignal): Promise<SearchProviderHealth>;
+}
+
+export interface SearchHit extends SearchProviderHit {
+  providerKey: string;
+  deepLink: {
+    surface: "business";
+    routeTemplate: string;
+    params: Record<string, string>;
+  };
+  access: {
+    plaintext: "delegate-to-target-resource";
+    export: "delegate-to-governed-export";
+    permissionKey: string;
+  };
+}
+
+export interface SearchResultGroup {
+  providerKey: string;
+  label: string;
+  hits: SearchHit[];
+  nextCursor?: string;
+}
+
+export interface SearchProviderObservation {
+  providerKey: string;
+  status: "succeeded" | "failed" | "timeout";
+  durationMs: number;
+  hitCount: number;
+}
+
+export interface SearchProviderFailure {
+  providerKey: string;
+  code: "PROVIDER_FAILED" | "PROVIDER_TIMEOUT" | "INVALID_RESPONSE";
+  message: string;
+}
+
+export interface SearchResultPage {
+  groups: SearchResultGroup[];
+  nextCursor?: string;
+  partial: boolean;
+  failures: SearchProviderFailure[];
+  observations: SearchProviderObservation[];
+}
+
+export interface SearchProviderCatalogItem {
+  key: string;
+  label: string;
+  contractVersion: string;
+  providerVersion: string;
+  enabled: boolean;
+  health: SearchProviderHealth;
+}
+
+export type SearchProviderDefinition = SearchProviderManifestDefinition;
+
+export function isSearchProviderDefinition(
+  value: ModuleManifest["providers"][number],
+): value is SearchProviderDefinition {
+  return value.kind === "search";
+}

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

@@ -0,0 +1,39 @@
+import { SearchProtocolError } from "./errors.js";
+
+interface SearchCursorPayload {
+  version: 1;
+  providers: Record<string, string>;
+}
+
+export function encodeSearchCursor(
+  providerCursors: Record<string, string>,
+): string | undefined {
+  if (!Object.keys(providerCursors).length) return undefined;
+  const payload: SearchCursorPayload = {
+    version: 1,
+    providers: providerCursors,
+  };
+  return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+
+export function decodeSearchCursor(value: string | undefined) {
+  if (!value) return {};
+  try {
+    const parsed = JSON.parse(
+      Buffer.from(value, "base64url").toString("utf8"),
+    ) as SearchCursorPayload;
+    if (
+      parsed.version !== 1 ||
+      !parsed.providers ||
+      typeof parsed.providers !== "object" ||
+      Object.values(parsed.providers).some(
+        (cursor) => typeof cursor !== "string" || cursor.length > 500,
+      )
+    ) {
+      throw new Error("invalid");
+    }
+    return parsed.providers;
+  } catch {
+    throw new SearchProtocolError("INVALID_CURSOR", "搜索游标无效");
+  }
+}

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

@@ -0,0 +1,11 @@
+import type { SearchErrorCode } from "./contracts.js";
+
+export class SearchProtocolError extends Error {
+  constructor(
+    readonly code: SearchErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "SearchProtocolError";
+  }
+}

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

@@ -0,0 +1,36 @@
+import type { ModuleManifest } from "@windy/modules";
+import type { createServerRuntime } from "../runtime.js";
+import type { RouteApp } from "../system/route-types.js";
+import { readSearchServiceOptions } from "./config.js";
+import type { SearchProvider } from "./contracts.js";
+import { registerSearchRoutes } from "./routes.js";
+import { SearchService } from "./service.js";
+
+interface SearchProviderRuntime {
+  providers: readonly SearchProvider[];
+}
+
+export function createSearchHost(
+  modules: readonly ModuleManifest[],
+  providerRuntime: SearchProviderRuntime | undefined,
+  runtime: ReturnType<typeof createServerRuntime>,
+  environment: Record<string, string | undefined> = process.env,
+) {
+  const service = new SearchService(
+    modules,
+    providerRuntime?.providers || [],
+    runtime,
+    readSearchServiceOptions(environment),
+  );
+  return {
+    providerKeys: service.providerKeys(),
+    register(app: Pick<RouteApp, "get" | "post">) {
+      registerSearchRoutes(
+        app,
+        service,
+        runtime,
+        modules.flatMap(({ features }) => features),
+      );
+    },
+  };
+}

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

@@ -0,0 +1,6 @@
+export function maskSearchText(value: string, visible = 4): string {
+  const normalized = value.trim();
+  if (!normalized) return "[已脱敏]";
+  const prefix = normalized.slice(0, Math.max(1, visible));
+  return `${prefix}${"*".repeat(Math.min(8, Math.max(2, normalized.length - prefix.length)))}`;
+}

package/template/apps/server/src/search/provider-execution.ts

@@ -0,0 +1,195 @@
+import type {
+  SearchExecutionContext,
+  SearchHit,
+  SearchProvider,
+  SearchProviderFailure,
+  SearchProviderHealth,
+  SearchProviderObservation,
+  SearchResultGroup,
+} from "./contracts.js";
+import type { ProviderRegistration } from "./registry.js";
+
+export interface ProviderExecution {
+  group?: SearchResultGroup;
+  failure?: SearchProviderFailure;
+  observation: SearchProviderObservation;
+}
+
+export async function executeSearchProvider(
+  registration: ProviderRegistration,
+  text: string,
+  limit: number,
+  cursor: string | undefined,
+  context: SearchExecutionContext,
+  timeoutMs: number,
+  now: () => Date,
+): Promise<ProviderExecution> {
+  const startedAt = now().getTime();
+  try {
+    const page = await withTimeout(
+      (signal) =>
+        registration.provider.search({ text, limit, cursor, signal }, context),
+      timeoutMs,
+    );
+    validateProviderPage(page, limit);
+    const hits = page.hits.map(
+      (hit): SearchHit => ({
+        ...hit,
+        providerKey: registration.definition.key,
+        deepLink: {
+          surface: "business",
+          routeTemplate: registration.definition.deepLink.routeTemplate,
+          params: {
+            [registration.definition.deepLink.idParameter]: hit.id,
+          },
+        },
+        access: {
+          plaintext: "delegate-to-target-resource",
+          export: "delegate-to-governed-export",
+          permissionKey: registration.definition.permissionKey,
+        },
+      }),
+    );
+    return {
+      group: {
+        providerKey: registration.definition.key,
+        label: registration.definition.label,
+        hits,
+        nextCursor: page.nextCursor,
+      },
+      observation: observation(
+        registration.definition.key,
+        "succeeded",
+        startedAt,
+        now,
+        hits.length,
+      ),
+    };
+  } catch (error) {
+    const timeout = error instanceof ProviderTimeoutError;
+    return {
+      failure: {
+        providerKey: registration.definition.key,
+        code: timeout ? "PROVIDER_TIMEOUT" : failureCode(error),
+        message: timeout ? "搜索 Provider 超时" : "搜索 Provider 暂不可用",
+      },
+      observation: observation(
+        registration.definition.key,
+        timeout ? "timeout" : "failed",
+        startedAt,
+        now,
+        0,
+      ),
+    };
+  }
+}
+
+export async function readSearchProviderHealth(
+  provider: SearchProvider,
+  timeoutMs: number,
+  now: () => Date,
+): Promise<SearchProviderHealth> {
+  try {
+    return await withTimeout((signal) => provider.health(signal), timeoutMs);
+  } catch {
+    return {
+      status: "unavailable",
+      checkedAt: now().toISOString(),
+      message: "Provider 健康检查失败",
+    };
+  }
+}
+
+function validateProviderPage(
+  page: unknown,
+  limit: number,
+): asserts page is {
+  hits: Array<{
+    id: string;
+    resourceType: string;
+    maskedTitle: string;
+    maskedExcerpt?: string;
+    score?: number;
+  }>;
+  nextCursor?: string;
+} {
+  if (!page || typeof page !== "object" || !("hits" in page)) {
+    throw new InvalidProviderResponseError();
+  }
+  const value = page as { hits?: unknown; nextCursor?: unknown };
+  if (
+    !Array.isArray(value.hits) ||
+    value.hits.length > limit ||
+    (value.nextCursor !== undefined &&
+      (typeof value.nextCursor !== "string" || value.nextCursor.length > 500))
+  ) {
+    throw new InvalidProviderResponseError();
+  }
+  for (const hit of value.hits) {
+    if (
+      !hit ||
+      typeof hit !== "object" ||
+      typeof hit.id !== "string" ||
+      !hit.id ||
+      hit.id.length > 200 ||
+      typeof hit.resourceType !== "string" ||
+      !hit.resourceType ||
+      hit.resourceType.length > 120 ||
+      typeof hit.maskedTitle !== "string" ||
+      hit.maskedTitle.length > 300 ||
+      ("maskedExcerpt" in hit &&
+        (typeof hit.maskedExcerpt !== "string" ||
+          hit.maskedExcerpt.length > 1_000)) ||
+      ("score" in hit &&
+        (typeof hit.score !== "number" || !Number.isFinite(hit.score))) ||
+      "title" in hit ||
+      "description" in hit ||
+      "raw" in hit
+    ) {
+      throw new InvalidProviderResponseError();
+    }
+  }
+}
+
+async function withTimeout<T>(
+  execute: (signal: AbortSignal) => Promise<T>,
+  timeoutMs: number,
+): Promise<T> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new ProviderTimeoutError());
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([execute(controller.signal), timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function observation(
+  providerKey: string,
+  status: SearchProviderObservation["status"],
+  startedAt: number,
+  now: () => Date,
+  hitCount: number,
+): SearchProviderObservation {
+  return {
+    providerKey,
+    status,
+    durationMs: Math.max(0, now().getTime() - startedAt),
+    hitCount,
+  };
+}
+
+function failureCode(error: unknown): SearchProviderFailure["code"] {
+  return error instanceof InvalidProviderResponseError
+    ? "INVALID_RESPONSE"
+    : "PROVIDER_FAILED";
+}
+
+class ProviderTimeoutError extends Error {}
+class InvalidProviderResponseError extends Error {}

package/template/apps/server/src/search/rate-limiter.ts

@@ -0,0 +1,23 @@
+import { SearchProtocolError } from "./errors.js";
+
+export class SearchRateLimiter {
+  private readonly attempts = new Map<string, number[]>();
+
+  constructor(
+    private readonly maxRequests: number,
+    private readonly windowMs: number,
+    private readonly now: () => number,
+  ) {}
+
+  consume(actorId: string): void {
+    const current = this.now();
+    const active = (this.attempts.get(actorId) || []).filter(
+      (attemptedAt) => current - attemptedAt < this.windowMs,
+    );
+    if (active.length >= this.maxRequests) {
+      throw new SearchProtocolError("RATE_LIMITED", "搜索请求过于频繁");
+    }
+    active.push(current);
+    this.attempts.set(actorId, active);
+  }
+}