create-windy 0.1.0

package/template/apps/server/src/work-order/routes.ts

@@ -0,0 +1,159 @@
+import {
+  createWorkOrderSchema,
+  updateWorkOrderSchema,
+  workOrderModule,
+} from "@windy/example-work-order";
+import type { ApiPermissionBinding } from "@windy/shared";
+import { recordMutationAudit } from "../audit/policy.js";
+import { accessCall } from "../system/resource-access-response.js";
+import { evaluateRouteGuards } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  forbidden,
+  notFound,
+  resourceEvent,
+  routeContext,
+} from "../system/route-helpers.js";
+import type { RouteApp } from "../system/route-types.js";
+import { parsePagination } from "../pagination.js";
+import type { WorkOrderService } from "./service.js";
+import { searchAuditEvent } from "../audit/search-summary.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+const manifest = workOrderModule();
+const feature = manifest.features[0];
+
+export function registerWorkOrderRoutes(
+  app: RouteApp,
+  service: WorkOrderService,
+  runtime: ServerRuntime,
+) {
+  app.get("/work-orders", (raw) =>
+    guarded(raw, binding("GET", "/api/work-orders"), runtime, async () => {
+      const context = routeContext(raw);
+      const pagination = parsePagination(context.query);
+      if (pagination instanceof Response) return pagination;
+      const result = await accessCall(() =>
+        service.list(
+          { ...pagination, q: context.query.q },
+          context.guardContext.actor,
+        ),
+      );
+      if (!(result instanceof Response) && context.query.q?.trim()) {
+        runtime.auditSink.recordEvent(
+          searchAuditEvent(
+            context.guardContext,
+            "work-order",
+            context.query.q,
+            result.total,
+          ),
+        );
+      }
+      return result;
+    }),
+  );
+
+  app.get("/work-orders/:id", (raw) =>
+    guarded(raw, binding("GET", "/api/work-orders/:id"), runtime, async () => {
+      const context = routeContext(raw);
+      const id = context.params.id || "";
+      const item = await accessCall(() =>
+        service.get(id, context.guardContext.actor),
+      );
+      return item instanceof Response
+        ? item
+        : item || notFound("work-order", id);
+    }),
+  );
+
+  app.post("/work-orders", (raw) =>
+    guarded(raw, binding("POST", "/api/work-orders"), runtime, async () => {
+      const context = routeContext(raw);
+      const parsed = createWorkOrderSchema.safeParse(context.body);
+      if (!parsed.success) return invalid(parsed.error.issues[0]?.message);
+      const item = await accessCall(() =>
+        service.create(parsed.data, context.guardContext.actor),
+      );
+      if (item instanceof Response) return item;
+      await audit(runtime, context.guardContext, "crud.create", item.id);
+      return item;
+    }),
+  );
+
+  app.put("/work-orders/:id", (raw) =>
+    guarded(raw, binding("PUT", "/api/work-orders/:id"), runtime, async () => {
+      const context = routeContext(raw);
+      const id = context.params.id || "";
+      const parsed = updateWorkOrderSchema.safeParse(context.body);
+      if (!parsed.success) return invalid(parsed.error.issues[0]?.message);
+      const item = await accessCall(() =>
+        service.update(id, parsed.data, context.guardContext.actor),
+      );
+      if (item instanceof Response) return item;
+      if (!item) return notFound("work-order", id);
+      await audit(runtime, context.guardContext, "crud.update", id);
+      return item;
+    }),
+  );
+
+  app.delete("/work-orders/:id", (raw) =>
+    guarded(
+      raw,
+      binding("DELETE", "/api/work-orders/:id"),
+      runtime,
+      async () => {
+        const context = routeContext(raw);
+        const id = context.params.id || "";
+        const item = await accessCall(() =>
+          service.archive(id, context.guardContext.actor),
+        );
+        if (item instanceof Response) return item;
+        if (!item) return notFound("work-order", id);
+        await audit(runtime, context.guardContext, "crud.delete", id);
+        return item;
+      },
+    ),
+  );
+}
+
+async function guarded(
+  raw: unknown,
+  permission: ApiPermissionBinding,
+  runtime: ServerRuntime,
+  handler: () => unknown,
+) {
+  const decision = await evaluateRouteGuards(
+    runtime,
+    routeContext(raw).guardContext,
+    { permission, feature },
+  );
+  return decision.allowed ? handler() : forbidden(decision.reason);
+}
+
+function binding(method: string, path: string): ApiPermissionBinding {
+  const result = manifest.apiPermissions.find(
+    (item) => item.method === method && item.path === path,
+  );
+  if (!result) throw new Error(`示例工单缺少 API 绑定：${method} ${path}`);
+  return result;
+}
+
+function invalid(message = "工单内容无效") {
+  return Response.json(
+    { error: "INVALID_WORK_ORDER", message },
+    { status: 400 },
+  );
+}
+
+function audit(
+  runtime: ServerRuntime,
+  context: ReturnType<typeof routeContext>["guardContext"],
+  action: "crud.create" | "crud.update" | "crud.delete",
+  id: string,
+) {
+  return recordMutationAudit(
+    runtime,
+    "work-orders",
+    resourceEvent(context, action, "work-order", id),
+  );
+}

package/template/apps/server/src/work-order/search-api.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from "bun:test";
+import { workOrderModule, type WorkOrder } from "@windy/example-work-order";
+import { systemFoundationModule, type ModuleManifest } from "@windy/modules";
+import { licenseVersionKey } from "@windy/shared";
+import { buildScopeContext } from "../data-access/context.js";
+import { InMemoryScopedEntityRepository } from "../data-access/scoped-repository.js";
+import { createServerRuntime } from "../runtime.js";
+import { registerSearchRoutes } from "../search/routes.js";
+import { SearchService } from "../search/service.js";
+import { searchTestContext } from "../search/test-support.js";
+import type { ManagedDepartment } from "../system/entities.js";
+import { InMemoryEntityRepository } from "../system/repository.js";
+import type { RouteApp } from "../system/route-types.js";
+import { workOrderDataScopeBinding } from "./repository.js";
+import { WorkOrderSearchProvider } from "./search-provider.js";
+import { WorkOrderService } from "./service.js";
+
+describe("搜索 API 数据范围", () => {
+  test("客户端伪造身份与部门不能扩大 Server ScopeContext", async () => {
+    const repository = new InMemoryScopedEntityRepository<WorkOrder>(
+      [
+        ticket("ticket_self", "user_server", "数据库故障本人记录"),
+        ticket("ticket_other", "user_other", "数据库故障他人记录"),
+      ],
+      workOrderDataScopeBinding,
+    );
+    repository.list = () => {
+      throw new Error("搜索 API 不得绕过 scoped Repository");
+    };
+    const workOrders = new WorkOrderService(
+      repository,
+      new InMemoryEntityRepository<ManagedDepartment>(),
+    );
+    const modules: ModuleManifest[] = [
+      systemFoundationModule(),
+      workOrderModule(),
+    ];
+    const runtime = createServerRuntime(
+      { NODE_ENV: "development" },
+      {
+        featureResolver: {
+          resolve: (key) => ({ key, enabled: true, visible: "visible" }),
+        },
+      },
+    );
+    const service = new SearchService(
+      modules,
+      [new WorkOrderSearchProvider(workOrders)],
+      runtime,
+    );
+    const context = searchTestContext([
+      "system.search.read",
+      "work-order.ticket.read",
+    ]);
+    context.license = { versionKey: licenseVersionKey("standard") };
+    context.actor.scopeContext = buildScopeContext(
+      "user_server",
+      "dept_server",
+      [
+        {
+          id: "role_self",
+          code: "operator",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ],
+    );
+    let handler: ((context: unknown) => unknown) | undefined;
+    const app: Pick<RouteApp, "get" | "post"> = {
+      get: () => app,
+      post: (path, value) => {
+        if (path === "/search") handler = value;
+        return app;
+      },
+    };
+    registerSearchRoutes(
+      app,
+      service,
+      runtime,
+      modules.flatMap(({ features }) => features),
+    );
+
+    const result = await handler?.({
+      body: {
+        query: "数据库故障",
+        actorId: "user_other",
+        departmentId: "dept_other",
+      },
+      guardContext: context,
+      params: {},
+      query: { query: "不得读取 URL 查询" },
+    });
+
+    expect(result).not.toBeInstanceOf(Response);
+    expect(result).toMatchObject({
+      groups: [
+        {
+          hits: [{ id: "ticket_self", maskedTitle: "数据库故*****" }],
+        },
+      ],
+    });
+    expect(JSON.stringify(result)).not.toContain("他人记录");
+  });
+});
+
+function ticket(id: string, ownerId: string, title: string): WorkOrder {
+  return {
+    id,
+    title,
+    description: "仅授权范围可见的详情",
+    priority: "high",
+    workflowStatus: "open",
+    ownerId,
+    departmentId: ownerId === "user_server" ? "dept_server" : "dept_other",
+    status: "active",
+    createdAt: "2026-07-16T00:00:00.000Z",
+    createdBy: "system",
+    updatedAt: "2026-07-16T00:00:00.000Z",
+    updatedBy: "system",
+  };
+}

package/template/apps/server/src/work-order/search-provider.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, test } from "bun:test";
+import { workOrderModule, type WorkOrder } from "@windy/example-work-order";
+import type { ModuleManifest } from "@windy/modules";
+import { licenseVersionKey } from "@windy/shared";
+import { buildScopeContext } from "../data-access/context.js";
+import { InMemoryScopedEntityRepository } from "../data-access/scoped-repository.js";
+import type { DataScopeQuerySpecification } from "../data-access/query-specification.js";
+import type { RequestGuardContext } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import type { SearchProvider } from "../search/contracts.js";
+import { SearchService } from "../search/service.js";
+import type { ManagedDepartment } from "../system/entities.js";
+import { InMemoryEntityRepository } from "../system/repository.js";
+import { workOrderDataScopeBinding } from "./repository.js";
+import {
+  WorkOrderSearchProvider,
+  WORK_ORDER_SEARCH_PROVIDER_KEY,
+  WORK_ORDER_SEARCH_PROVIDER_VERSION,
+} from "./search-provider.js";
+import { WorkOrderService } from "./service.js";
+
+describe("示例工单 SearchProvider", () => {
+  test("搜索复用 scoped Repository 查询并只返回脱敏的本人结果", async () => {
+    const repository = new InMemoryScopedEntityRepository<WorkOrder>(
+      [
+        ticket("ticket_self", "user_self", "数据库故障需处理"),
+        ticket("ticket_other", "user_other", "数据库故障他人记录"),
+      ],
+      workOrderDataScopeBinding,
+    );
+    let capturedScope: DataScopeQuerySpecification | undefined;
+    let scopedCalls = 0;
+    const listScoped = repository.listScoped.bind(repository);
+    repository.listScoped = (...args) => {
+      scopedCalls += 1;
+      capturedScope = args[2];
+      return listScoped(...args);
+    };
+    repository.list = () => {
+      throw new Error("搜索不得调用裸 Repository.list");
+    };
+    const service = searchService([
+      new WorkOrderSearchProvider(
+        new WorkOrderService(
+          repository,
+          new InMemoryEntityRepository<ManagedDepartment>(),
+        ),
+      ),
+    ]);
+
+    const result = await service.search(
+      {
+        query: "数据库故障",
+        actorId: "user_other",
+        departmentId: "dept_other",
+      } as never,
+      selfContext(),
+    );
+
+    expect(scopedCalls).toBe(1);
+    expect(capturedScope?.branches).toEqual([
+      { kind: "owner", ownerId: "user_self" },
+    ]);
+    expect(result.groups[0]?.hits).toEqual([
+      {
+        id: "ticket_self",
+        resourceType: "work-order",
+        maskedTitle: "数据库故****",
+        maskedExcerpt: "仅本人可见的故障**",
+        providerKey: WORK_ORDER_SEARCH_PROVIDER_KEY,
+        deepLink: {
+          surface: "business",
+          routeTemplate: "/work-orders/:id",
+          params: { id: "ticket_self" },
+        },
+        access: {
+          plaintext: "delegate-to-target-resource",
+          export: "delegate-to-governed-export",
+          permissionKey: "work-order.ticket.read",
+        },
+      },
+    ]);
+    expect(JSON.stringify(result)).not.toContain("他人记录");
+  });
+
+  test("Provider 游标映射到 scoped Repository 分页", async () => {
+    const provider = new WorkOrderSearchProvider(
+      new WorkOrderService(
+        new InMemoryScopedEntityRepository<WorkOrder>(
+          [
+            ticket("ticket_1", "user_self", "故障一"),
+            ticket("ticket_2", "user_self", "故障二"),
+          ],
+          workOrderDataScopeBinding,
+        ),
+        new InMemoryEntityRepository<ManagedDepartment>(),
+      ),
+    );
+    const service = searchService([provider]);
+    const first = await service.search(
+      { query: "故障", limit: 1 },
+      selfContext(),
+    );
+    const second = await service.search(
+      { query: "故障", limit: 1, cursor: first.nextCursor },
+      selfContext(),
+    );
+
+    expect(first.groups[0]?.hits).toHaveLength(1);
+    expect(second.groups[0]?.hits).toHaveLength(1);
+    expect(second.groups[0]?.hits[0]?.id).not.toBe(
+      first.groups[0]?.hits[0]?.id,
+    );
+  });
+
+  test("同一 Manifest 可替换为第二个 Provider 而无需修改 Core", async () => {
+    const replacement: SearchProvider = {
+      key: WORK_ORDER_SEARCH_PROVIDER_KEY,
+      providerVersion: WORK_ORDER_SEARCH_PROVIDER_VERSION,
+      search: async () => ({
+        hits: [
+          {
+            id: "replacement_1",
+            resourceType: "replacement-ticket",
+            maskedTitle: "替换结果**",
+          },
+        ],
+      }),
+      health: async () => ({
+        status: "healthy",
+        checkedAt: "2026-07-16T00:00:00.000Z",
+      }),
+    };
+
+    const result = await searchService([replacement]).search(
+      { query: "任意查询" },
+      selfContext(),
+    );
+    expect(result.groups[0]?.hits[0]).toMatchObject({
+      id: "replacement_1",
+      resourceType: "replacement-ticket",
+      providerKey: WORK_ORDER_SEARCH_PROVIDER_KEY,
+    });
+  });
+});
+
+function searchService(providers: SearchProvider[]) {
+  const manifest: ModuleManifest = workOrderModule();
+  return new SearchService(
+    [manifest],
+    providers,
+    createServerRuntime(
+      { NODE_ENV: "development" },
+      {
+        featureResolver: {
+          resolve: (key) => ({ key, enabled: true, visible: "visible" }),
+        },
+      },
+    ),
+  );
+}
+
+function selfContext(): RequestGuardContext {
+  return {
+    requestId: "request_search_work_order",
+    startedAt: "2026-07-16T00:00:00.000Z",
+    license: { versionKey: licenseVersionKey("standard") },
+    actor: {
+      id: "user_self",
+      type: "user",
+      name: "本人用户",
+      roleCodes: ["user"],
+      permissionKeys: ["work-order.ticket.read"],
+      scopeContext: buildScopeContext("user_self", "dept_self", [
+        {
+          id: "role_user",
+          code: "user",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    },
+  };
+}
+
+function ticket(id: string, ownerId: string, title: string): WorkOrder {
+  return {
+    id,
+    title,
+    description: "仅本人可见的故障详情",
+    priority: "high",
+    workflowStatus: "open",
+    ownerId,
+    departmentId: ownerId === "user_self" ? "dept_self" : "dept_other",
+    status: "active",
+    createdAt: "2026-07-16T00:00:00.000Z",
+    createdBy: "system",
+    updatedAt: "2026-07-16T00:00:00.000Z",
+    updatedBy: "system",
+  };
+}

package/template/apps/server/src/work-order/search-provider.ts

@@ -0,0 +1,59 @@
+import type {
+  SearchExecutionContext,
+  SearchProvider,
+  SearchProviderPage,
+  SearchProviderQuery,
+} from "../search/contracts.js";
+import { SearchProtocolError } from "../search/errors.js";
+import { maskSearchText } from "../search/masking.js";
+import type { WorkOrderService } from "./service.js";
+
+export const WORK_ORDER_SEARCH_PROVIDER_KEY = "work-order.ticket.search";
+export const WORK_ORDER_SEARCH_PROVIDER_VERSION = "0.1.0";
+
+export class WorkOrderSearchProvider implements SearchProvider {
+  readonly key = WORK_ORDER_SEARCH_PROVIDER_KEY;
+  readonly providerVersion = WORK_ORDER_SEARCH_PROVIDER_VERSION;
+
+  constructor(private readonly service: WorkOrderService) {}
+
+  async search(
+    request: SearchProviderQuery,
+    context: SearchExecutionContext,
+  ): Promise<SearchProviderPage> {
+    if (request.signal.aborted) throw new Error("search aborted");
+    const page = parseProviderCursor(request.cursor);
+    const result = await this.service.list(
+      { q: request.text, page, pageSize: request.limit },
+      context.actor,
+    );
+    if (request.signal.aborted) throw new Error("search aborted");
+    return {
+      hits: result.items.map((workOrder) => ({
+        id: workOrder.id,
+        resourceType: "work-order",
+        maskedTitle: maskSearchText(workOrder.title),
+        maskedExcerpt: maskSearchText(workOrder.description, 8),
+      })),
+      nextCursor:
+        result.page * result.pageSize < result.total
+          ? String(result.page + 1)
+          : undefined,
+    };
+  }
+
+  async health(signal: AbortSignal) {
+    return {
+      status: signal.aborted ? ("unavailable" as const) : ("healthy" as const),
+      checkedAt: new Date().toISOString(),
+    };
+  }
+}
+
+function parseProviderCursor(value: string | undefined): number {
+  if (!value) return 1;
+  if (!/^[1-9][0-9]{0,5}$/.test(value)) {
+    throw new SearchProtocolError("INVALID_CURSOR", "工单搜索游标无效");
+  }
+  return Number(value);
+}

package/template/apps/server/src/work-order/service.ts

@@ -0,0 +1,82 @@
+import type {
+  CreateWorkOrderInput,
+  UpdateWorkOrderInput,
+  WorkOrder,
+  WorkOrderListQuery,
+} from "@windy/example-work-order";
+import { DataScopedResourceService } from "../data-access/scoped-resource.js";
+import { departmentDescendantResolver } from "../data-access/department-tree.js";
+import type { RequestActor } from "../guards.js";
+import type { ManagedDepartment } from "../system/entities.js";
+import type { EntityRepository } from "../system/repository.js";
+import type { ScopedEntityRepository } from "../data-access/scoped-repository.js";
+
+export class WorkOrderService {
+  private readonly access: DataScopedResourceService<WorkOrder>;
+
+  constructor(
+    private readonly repository: ScopedEntityRepository<WorkOrder>,
+    departments: EntityRepository<ManagedDepartment>,
+  ) {
+    this.access = new DataScopedResourceService(
+      repository,
+      departmentDescendantResolver(departments),
+    );
+  }
+
+  list(query: WorkOrderListQuery, actor: RequestActor) {
+    return this.access.list(
+      {
+        page: query.page,
+        pageSize: query.pageSize,
+        q: query.q,
+        sort: [{ field: "updatedAt", order: "desc" }],
+      },
+      ["title", "description"],
+      actor,
+    );
+  }
+
+  get(id: string, actor: RequestActor) {
+    return this.access.get(id, actor);
+  }
+
+  create(input: CreateWorkOrderInput, actor: RequestActor) {
+    return this.access.create(
+      {
+        ...input,
+        workflowStatus: "open",
+        ownerId: actor.id,
+        departmentId: actor.scopeContext?.departmentId,
+        status: "active",
+      },
+      actor,
+    );
+  }
+
+  update(id: string, input: UpdateWorkOrderInput, actor: RequestActor) {
+    return this.access.update(id, input, actor);
+  }
+
+  archive(id: string, actor: RequestActor) {
+    return this.access.softDelete(id, actor);
+  }
+
+  async operationalSnapshot(
+    actor: RequestActor,
+  ): Promise<Record<string, number>> {
+    const items = await this.access.all({ status: "active" }, [], actor);
+    return {
+      total: items.length,
+      open: items.filter(({ workflowStatus }) => workflowStatus === "open")
+        .length,
+      inProgress: items.filter(
+        ({ workflowStatus }) => workflowStatus === "in-progress",
+      ).length,
+      highPriorityPending: items.filter(
+        ({ priority, workflowStatus }) =>
+          priority === "high" && workflowStatus !== "resolved",
+      ).length,
+    };
+  }
+}

package/template/apps/server/src/work-order/task.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import type { WorkOrder } from "@windy/example-work-order";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import { InMemorySchedulerRepository } from "../scheduler/repository.js";
+import { SchedulerService } from "../scheduler/service.js";
+import type { ManagedDepartment } from "../system/entities.js";
+import { InMemoryEntityRepository } from "../system/repository.js";
+import { InMemoryScopedEntityRepository } from "../data-access/scoped-repository.js";
+import { WorkOrderService } from "./service.js";
+import { workOrderDataScopeBinding } from "./repository.js";
+import { createWorkOrderTaskDefinitions } from "./task.js";
+
+describe("示例工单后台任务", () => {
+  test("通过统一调度 Guard 执行并把业务快照写入历史", async () => {
+    const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token" });
+    const service = new WorkOrderService(
+      new InMemoryScopedEntityRepository<WorkOrder>(
+        [
+          item("ticket_high", "high", "open"),
+          item("ticket_progress", "medium", "in-progress"),
+          item("ticket_resolved", "high", "resolved"),
+        ],
+        workOrderDataScopeBinding,
+      ),
+      new InMemoryEntityRepository<ManagedDepartment>(),
+    );
+    const scheduler = new SchedulerService(
+      new InMemorySchedulerRepository(),
+      createWorkOrderTaskDefinitions(
+        createFoundationSnapshot().features,
+        service,
+      ),
+      runtime,
+    );
+    await scheduler.initialize();
+    const context = await runtime.createGuardContext(
+      new Request(
+        "http://localhost/api/system/scheduled-tasks/work-order.ticket.snapshot/trigger",
+        { headers: { authorization: "Bearer token" } },
+      ),
+    );
+
+    expect(
+      await scheduler.triggerManual("work-order.ticket.snapshot", context),
+    ).toMatchObject({
+      ok: true,
+      run: {
+        status: "succeeded",
+        result: { total: 3, open: 1, inProgress: 1, highPriorityPending: 1 },
+      },
+    });
+    expect(runtime.auditSink.list().map(({ action }) => action)).toEqual([
+      "task.trigger",
+      "task.execute",
+    ]);
+  });
+});
+
+function item(
+  id: string,
+  priority: WorkOrder["priority"],
+  workflowStatus: WorkOrder["workflowStatus"],
+): WorkOrder {
+  return {
+    id,
+    title: id,
+    description: id,
+    priority,
+    workflowStatus,
+    ownerId: "user_dev_admin",
+    departmentId: "dept_platform",
+    status: "active",
+    createdAt: "2026-07-15T00:00:00.000Z",
+    createdBy: "system",
+    updatedAt: "2026-07-15T00:00:00.000Z",
+    updatedBy: "system",
+  };
+}