create-windy 0.1.0

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

@@ -0,0 +1,30 @@
+import { workOrderModule } from "@windy/example-work-order";
+import type { FeatureFlagDefinition } from "@windy/shared";
+import type { ScheduledTaskDefinition } from "../scheduler/types.js";
+import type { WorkOrderService } from "./service.js";
+import { platformDataActor } from "../data-access/platform-actor.js";
+
+export function createWorkOrderTaskDefinitions(
+  features: FeatureFlagDefinition[],
+  service: WorkOrderService,
+): ScheduledTaskDefinition[] {
+  const manifest = workOrderModule();
+  const feature = features.find(({ key }) => key === "work-order.ticket");
+  if (!feature) return [];
+  const actor = platformDataActor(
+    "task_work_order_snapshot",
+    "工单运营快照任务",
+  );
+
+  return manifest.tasks.map((task) => ({
+    key: task.key,
+    label: task.label,
+    description: task.description,
+    intervalSeconds: task.intervalSeconds,
+    maxAttempts: task.maxAttempts,
+    retryDelaySeconds: task.retryDelaySeconds,
+    permissionKey: task.permissionKey,
+    feature,
+    handler: () => service.operationalSnapshot(actor),
+  }));
+}

package/template/apps/server/src/workflow/assignee-directory.ts

@@ -0,0 +1,23 @@
+import type { SystemRepositories } from "../system/seed.js";
+import type { WorkflowAssigneeDirectory } from "./service.js";
+
+export class SystemWorkflowAssigneeDirectory implements WorkflowAssigneeDirectory {
+  constructor(
+    private readonly repositories: Pick<SystemRepositories, "users" | "roles">,
+  ) {}
+
+  async resolve(userId: string) {
+    const user = await this.repositories.users.get(userId);
+    if (!user || user.status !== "active") return undefined;
+    const roles = await Promise.all(
+      user.roleIds.map((roleId) => this.repositories.roles.get(roleId)),
+    );
+    return {
+      id: user.id,
+      name: user.displayName,
+      roleCodes: roles
+        .filter((role) => role?.status === "active")
+        .map((role) => role!.code),
+    };
+  }
+}

package/template/apps/server/src/workflow/drizzle-repository.integration.test.ts

@@ -0,0 +1,213 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+import type { WorkflowActor } from "@windy/shared";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { Pool } from "pg";
+import { DrizzleDurableExecutionRepository } from "../jobs/drizzle-execution-repository.js";
+import { DrizzleDurableJobRepository } from "../jobs/drizzle-repository.js";
+import { DurableHandlerRegistry } from "../jobs/handler-registry.js";
+import { DurableJobService } from "../jobs/service.js";
+import { DurableJobWorker } from "../jobs/worker.js";
+import { DrizzleWorkflowRepository } from "./drizzle-repository.js";
+import { WorkflowService } from "./service.js";
+import { WorkflowTimeoutRuntime } from "./timeout-runtime.js";
+
+const databaseUrl = process.env.WORKFLOW_TEST_DATABASE_URL;
+const describePostgres = databaseUrl ? describe : describe.skip;
+
+describePostgres("PostgreSQL 最小审批 Repository", () => {
+  let pool: Pool;
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: databaseUrl });
+    await migrate(drizzle(pool), {
+      migrationsFolder: resolve(
+        import.meta.dir,
+        "../../../../packages/database/drizzle",
+      ),
+      migrationsSchema: "public",
+      migrationsTable: "__workflow_test_migrations",
+    });
+    await pool.query(`truncate table
+      governed_export_requests,
+      bulk_data_artifacts, bulk_data_jobs, scheduled_task_runs,
+      durable_job_recoveries, durable_job_failures, durable_job_artifacts,
+      durable_job_progress, durable_job_leases, durable_job_attempts,
+      durable_job_stages, durable_jobs,
+      workflow_transitions, workflow_work_items`);
+  });
+
+  afterAll(async () => {
+    await pool?.end();
+  });
+
+  test("并发创建与命令幂等，状态更新只允许一个版本获胜", async () => {
+    const first = new DrizzleWorkflowRepository(drizzle(pool));
+    const second = new DrizzleWorkflowRepository(drizzle(pool));
+    const createdAt = "2026-07-16T00:00:00.000Z";
+    const base = {
+      title: "并发采购审批",
+      requesterId: requester.id,
+      candidateRoles: [{ code: "reviewer", name: "审核员" }],
+      dueAt: "2026-07-17T00:00:00.000Z",
+      target: { type: "purchase", id: "P-PG", route: "/purchases/P-PG" },
+      createdAt,
+    };
+    const created = await Promise.all([
+      first.create({ ...base, id: Bun.randomUUIDv7() }, "create-pg", requester),
+      second.create(
+        { ...base, id: Bun.randomUUIDv7() },
+        "create-pg",
+        requester,
+      ),
+    ]);
+    expect(new Set(created.map(({ id }) => id)).size).toBe(1);
+    const id = created[0]!.id;
+
+    const claims = await Promise.allSettled([
+      first.execute(
+        id,
+        { type: "claim", actor: reviewerA, at: "2026-07-16T01:00:00.000Z" },
+        1,
+        "claim-a",
+      ),
+      second.execute(
+        id,
+        { type: "claim", actor: reviewerB, at: "2026-07-16T01:00:00.000Z" },
+        1,
+        "claim-b",
+      ),
+    ]);
+    expect(claims.filter(({ status }) => status === "fulfilled")).toHaveLength(
+      1,
+    );
+
+    const restarted = new DrizzleWorkflowRepository(drizzle(pool));
+    const persisted = await restarted.get(id, manager);
+    expect(persisted).toMatchObject({ status: "claimed", version: 2 });
+    if (!persisted) throw new Error("审批任务未持久化");
+    const winner =
+      persisted.assignee!.id === reviewerA.id ? reviewerA : reviewerB;
+    const replay = await restarted.execute(
+      id,
+      { type: "claim", actor: winner, at: "2026-07-16T01:00:00.000Z" },
+      1,
+      winner.id === reviewerA.id ? "claim-a" : "claim-b",
+    );
+    expect(replay.workItem).toEqual(persisted);
+    expect(await restarted.history(id, manager)).toHaveLength(1);
+  });
+
+  test("可见范围由候选角色、发起人、领取人和管理权限约束", async () => {
+    const repository = new DrizzleWorkflowRepository(drizzle(pool));
+    const [item] = (await repository.list({ page: 1, pageSize: 10 }, manager))
+      .items;
+    if (!item) throw new Error("缺少审批测试记录");
+
+    expect(await repository.get(item.id, outsider)).toBeUndefined();
+    expect(await repository.get(item.id, reviewerA)).toBeDefined();
+    expect(await repository.get(item.id, requester)).toBeDefined();
+    expect(await repository.get(item.id, manager)).toBeDefined();
+  });
+
+  test("重建 PostgreSQL runtime 后仍会执行到期审批且重复派发幂等", async () => {
+    const createdAt = new Date("2026-07-16T03:00:00.000Z");
+    const dueAt = new Date("2026-07-16T03:10:00.000Z");
+    const db = drizzle(pool);
+    const repository = new DrizzleWorkflowRepository(db);
+    const item = await repository.create(
+      {
+        id: Bun.randomUUIDv7(),
+        title: "PostgreSQL 重启恢复审批",
+        requesterId: requester.id,
+        candidateRoles: [{ code: "reviewer", name: "审核员" }],
+        dueAt: dueAt.toISOString(),
+        target: {
+          type: "purchase",
+          id: "P-PG-RESTART",
+          route: "/purchases/P-PG-RESTART",
+        },
+        createdAt: createdAt.toISOString(),
+      },
+      "create-pg-restart",
+      requester,
+    );
+    const originalRegistry = new DurableHandlerRegistry();
+    const original = new WorkflowTimeoutRuntime(
+      new DurableJobService(
+        new DrizzleDurableJobRepository(db),
+        () => createdAt,
+      ),
+      new DurableJobWorker(
+        new DrizzleDurableExecutionRepository(db),
+        originalRegistry,
+        { now: () => createdAt },
+      ),
+      originalRegistry,
+      workflowService(repository, createdAt),
+      () => createdAt,
+    );
+    await original.schedule(item);
+    expect(await original.runNext()).toMatchObject({
+      claimed: false,
+      status: "idle",
+    });
+
+    const restartedDb = drizzle(pool);
+    const restartedRepository = new DrizzleWorkflowRepository(restartedDb);
+    const restartedRegistry = new DurableHandlerRegistry();
+    const restarted = new WorkflowTimeoutRuntime(
+      new DurableJobService(
+        new DrizzleDurableJobRepository(restartedDb),
+        () => dueAt,
+      ),
+      new DurableJobWorker(
+        new DrizzleDurableExecutionRepository(restartedDb),
+        restartedRegistry,
+        { now: () => dueAt },
+      ),
+      restartedRegistry,
+      workflowService(restartedRepository, dueAt),
+      () => dueAt,
+    );
+
+    expect(await restarted.runNext()).toMatchObject({
+      claimed: true,
+      status: "succeeded",
+    });
+    expect(await restartedRepository.get(item.id, manager)).toMatchObject({
+      status: "timed-out",
+      version: 2,
+    });
+    expect(await restartedRepository.history(item.id, manager)).toMatchObject([
+      { command: "timeout", target: item.target },
+    ]);
+    expect(await restarted.runNext()).toMatchObject({
+      claimed: false,
+      status: "idle",
+    });
+  });
+});
+
+function workflowService(repository: DrizzleWorkflowRepository, now: Date) {
+  return new WorkflowService(
+    repository,
+    {
+      async resolve() {
+        return undefined;
+      },
+    },
+    () => now,
+  );
+}
+
+const requester = actor("requester-pg", ["requester"]);
+const reviewerA = actor("reviewer-a-pg", ["reviewer"]);
+const reviewerB = actor("reviewer-b-pg", ["reviewer"]);
+const outsider = actor("outsider-pg", ["guest"]);
+const manager = { ...actor("manager-pg", ["manager"]), canManage: true };
+
+function actor(id: string, roleCodes: string[]): WorkflowActor {
+  return { id, name: id, type: "user", roleCodes };
+}

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

@@ -0,0 +1,299 @@
+import { workflowTransitions, workflowWorkItems } from "@windy/database";
+import type {
+  CreateWorkItemInput,
+  PageResult,
+  WorkItem,
+  WorkItemCommand,
+  WorkItemTransition,
+  WorkflowActor,
+} from "@windy/shared";
+import { createWorkItem, transitionWorkItem } from "@windy/shared";
+import { and, desc, eq, or, sql, type SQL } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import {
+  type WorkflowHistoryEntry,
+  type WorkflowListQuery,
+  type WorkflowRepository,
+  WorkflowRepositoryConflict,
+} from "./repository.js";
+
+export class DrizzleWorkflowRepository implements WorkflowRepository {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async list(query: WorkflowListQuery, actor: WorkflowActor) {
+    const where = visibilityWhere(actor, query.status);
+    const [rows, [{ count = 0 } = { count: 0 }]] = await Promise.all([
+      this.db
+        .select()
+        .from(workflowWorkItems)
+        .where(where)
+        .orderBy(desc(workflowWorkItems.updatedAt))
+        .limit(query.pageSize)
+        .offset((query.page - 1) * query.pageSize),
+      this.db
+        .select({ count: sql<number>`count(*)::int` })
+        .from(workflowWorkItems)
+        .where(where),
+    ]);
+    return {
+      items: rows.map(toWorkItem),
+      total: count,
+      page: query.page,
+      pageSize: query.pageSize,
+    } satisfies PageResult<WorkItem>;
+  }
+
+  async get(id: string, actor: WorkflowActor) {
+    const [row] = await this.db
+      .select()
+      .from(workflowWorkItems)
+      .where(and(eq(workflowWorkItems.id, id), visibilityWhere(actor)))
+      .limit(1);
+    return row ? toWorkItem(row) : undefined;
+  }
+
+  async history(id: string, actor: WorkflowActor) {
+    if (!(await this.get(id, actor))) return [];
+    const rows = await this.db
+      .select()
+      .from(workflowTransitions)
+      .where(eq(workflowTransitions.workItemId, id))
+      .orderBy(workflowTransitions.occurredAt);
+    return rows.map(toHistory);
+  }
+
+  async create(
+    input: CreateWorkItemInput,
+    idempotencyKey: string,
+    actor: WorkflowActor,
+  ) {
+    return this.db.transaction(async (tx) => {
+      await advisoryLock(tx, actor.id, idempotencyKey);
+      const [existing] = await tx
+        .select()
+        .from(workflowWorkItems)
+        .where(
+          and(
+            eq(workflowWorkItems.requesterId, actor.id),
+            eq(workflowWorkItems.createdIdempotencyKey, idempotencyKey),
+          ),
+        )
+        .limit(1);
+      if (existing) {
+        const item = toWorkItem(existing);
+        if (sameCreate(item, input)) return item;
+        throw new WorkflowRepositoryConflict("IDEMPOTENCY_CONFLICT");
+      }
+      const item = createWorkItem(input);
+      const [created] = await tx
+        .insert(workflowWorkItems)
+        .values(toWorkItemRow(item, idempotencyKey))
+        .onConflictDoNothing()
+        .returning();
+      if (!created) {
+        throw new WorkflowRepositoryConflict("IDEMPOTENCY_CONFLICT");
+      }
+      return toWorkItem(created);
+    });
+  }
+
+  async execute(
+    id: string,
+    command: WorkItemCommand,
+    expectedVersion: number,
+    idempotencyKey: string,
+  ) {
+    return this.db.transaction(async (tx) => {
+      await advisoryLock(tx, command.actor.id, idempotencyKey);
+      const [replay] = await tx
+        .select()
+        .from(workflowTransitions)
+        .where(
+          and(
+            eq(workflowTransitions.actorId, command.actor.id),
+            eq(workflowTransitions.idempotencyKey, idempotencyKey),
+          ),
+        )
+        .limit(1);
+      if (replay) {
+        if (replay.workItemId === id && replay.command === command.type) {
+          return toTransition(replay);
+        }
+        throw new WorkflowRepositoryConflict("IDEMPOTENCY_CONFLICT");
+      }
+      await tx.execute(
+        sql`select 1 from ${workflowWorkItems} where ${workflowWorkItems.id} = ${id} for update`,
+      );
+      const [row] = await tx
+        .select()
+        .from(workflowWorkItems)
+        .where(eq(workflowWorkItems.id, id))
+        .limit(1);
+      if (!row) throw new WorkflowRepositoryConflict("WORK_ITEM_NOT_FOUND");
+      const current = toWorkItem(row);
+      if (current.version !== expectedVersion) {
+        throw new WorkflowRepositoryConflict("VERSION_CONFLICT");
+      }
+      const result = transitionWorkItem(current, command);
+      const [updated] = await tx
+        .update(workflowWorkItems)
+        .set(toWorkItemUpdate(result.workItem))
+        .where(
+          and(
+            eq(workflowWorkItems.id, id),
+            eq(workflowWorkItems.version, expectedVersion),
+          ),
+        )
+        .returning({ id: workflowWorkItems.id });
+      if (!updated) throw new WorkflowRepositoryConflict("VERSION_CONFLICT");
+      const [fact] = await tx
+        .insert(workflowTransitions)
+        .values({
+          id: Bun.randomUUIDv7(),
+          workItemId: id,
+          command: result.fact.command,
+          beforeStatus: result.fact.beforeStatus,
+          afterStatus: result.fact.afterStatus,
+          actorId: result.fact.actorId,
+          idempotencyKey,
+          decision: result.fact.decision?.outcome,
+          reason: result.fact.reason?.text,
+          previousAssigneeId: result.fact.previousAssigneeId,
+          assigneeId: result.fact.assigneeId,
+          target: result.fact.target,
+          resultSnapshot: result.workItem,
+          occurredAt: new Date(result.fact.occurredAt),
+        })
+        .returning();
+      if (!fact) throw new Error("审批事实写入未返回记录");
+      return toTransition(fact);
+    });
+  }
+}
+
+function visibilityWhere(
+  actor: WorkflowActor,
+  status?: WorkItem["status"],
+): SQL {
+  const clauses: SQL[] = [];
+  if (!actor.canManage) {
+    const visible = [
+      eq(workflowWorkItems.requesterId, actor.id),
+      eq(workflowWorkItems.assigneeId, actor.id),
+      ...actor.roleCodes.map(
+        (role) =>
+          sql`${workflowWorkItems.candidateRoles} @> ${JSON.stringify([{ code: role }])}::jsonb`,
+      ),
+    ];
+    clauses.push(or(...visible) || sql`false`);
+  }
+  if (status) clauses.push(eq(workflowWorkItems.status, status));
+  return clauses.length ? and(...clauses)! : sql`true`;
+}
+
+function toWorkItem(row: typeof workflowWorkItems.$inferSelect): WorkItem {
+  return {
+    id: row.id,
+    title: row.title,
+    status: row.status as WorkItem["status"],
+    requesterId: row.requesterId,
+    candidateRoles: row.candidateRoles,
+    assignee: row.assigneeId
+      ? {
+          id: row.assigneeId,
+          name: row.assigneeName || row.assigneeId,
+          roleCodes: row.assigneeRoleCodes,
+        }
+      : undefined,
+    dueAt: row.dueAt.toISOString(),
+    target: row.target,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+    version: row.version,
+  };
+}
+
+function toWorkItemRow(item: WorkItem, idempotencyKey: string) {
+  return {
+    id: item.id,
+    title: item.title,
+    status: item.status,
+    requesterId: item.requesterId,
+    candidateRoles: item.candidateRoles,
+    assigneeId: item.assignee?.id,
+    assigneeName: item.assignee?.name,
+    assigneeRoleCodes: item.assignee?.roleCodes || [],
+    dueAt: new Date(item.dueAt),
+    target: item.target,
+    createdIdempotencyKey: idempotencyKey,
+    createdAt: new Date(item.createdAt),
+    updatedAt: new Date(item.updatedAt),
+    version: item.version,
+  };
+}
+
+function toWorkItemUpdate(item: WorkItem) {
+  return {
+    status: item.status,
+    assigneeId: item.assignee?.id,
+    assigneeName: item.assignee?.name,
+    assigneeRoleCodes: item.assignee?.roleCodes || [],
+    updatedAt: new Date(item.updatedAt),
+    version: item.version,
+  };
+}
+
+function toHistory(
+  row: typeof workflowTransitions.$inferSelect,
+): WorkflowHistoryEntry {
+  return { id: row.id, ...toTransition(row).fact };
+}
+
+function toTransition(
+  row: typeof workflowTransitions.$inferSelect,
+): WorkItemTransition {
+  const reason = row.reason ? { text: row.reason } : undefined;
+  return {
+    workItem: row.resultSnapshot,
+    fact: {
+      command: row.command as WorkItemTransition["fact"]["command"],
+      beforeStatus: row.beforeStatus as WorkItem["status"],
+      afterStatus: row.afterStatus as WorkItem["status"],
+      actorId: row.actorId,
+      occurredAt: row.occurredAt.toISOString(),
+      target: row.target,
+      decision: row.decision
+        ? {
+            outcome: row.decision as "approved" | "rejected",
+            reason: reason!,
+          }
+        : undefined,
+      reason,
+      previousAssigneeId: row.previousAssigneeId || undefined,
+      assigneeId: row.assigneeId || undefined,
+    },
+  };
+}
+
+function sameCreate(item: WorkItem, input: CreateWorkItemInput) {
+  return (
+    item.title === input.title.trim() &&
+    item.requesterId === input.requesterId &&
+    item.dueAt === input.dueAt &&
+    JSON.stringify(item.candidateRoles) ===
+      JSON.stringify(input.candidateRoles) &&
+    item.target.type === input.target.type &&
+    item.target.id === input.target.id &&
+    item.target.route === input.target.route
+  );
+}
+
+function advisoryLock(
+  tx: Parameters<Parameters<NodePgDatabase["transaction"]>[0]>[0],
+  actorId: string,
+  idempotencyKey: string,
+) {
+  return tx.execute(
+    sql`select pg_advisory_xact_lock(hashtextextended(${`${actorId}:${idempotencyKey}`}, 0))`,
+  );
+}

package/template/apps/server/src/workflow/effects.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { createWorkItem } from "@windy/shared";
+import type { RequestActor } from "../guards.js";
+import { InMemoryNotificationRepository } from "../notification/repository.js";
+import { NotificationWorkflowPort } from "./effects.js";
+
+describe("审批通知端口", () => {
+  test("候选角色收到带通用 TargetRef 的通知，其他角色不可见且重放幂等", async () => {
+    const notifications = new InMemoryNotificationRepository();
+    const port = new NotificationWorkflowPort(notifications);
+    const item = createWorkItem({
+      id: "workflow-notice-1",
+      title: "采购审批",
+      requesterId: "requester-1",
+      candidateRoles: [{ code: "reviewer", name: "审核员" }],
+      dueAt: "2026-07-17T00:00:00.000Z",
+      target: {
+        type: "purchase",
+        id: "P-100",
+        route: "/purchases/P-100",
+      },
+      createdAt: "2026-07-16T00:00:00.000Z",
+    });
+
+    await port.created(item);
+    await port.created(item);
+    const reviewerInbox = await notifications.listInbox(
+      actor("reviewer-user", ["reviewer"]),
+      1,
+      10,
+    );
+    const outsiderInbox = await notifications.listInbox(
+      actor("guest-user", ["guest"]),
+      1,
+      10,
+    );
+
+    expect(reviewerInbox.total).toBe(1);
+    expect(reviewerInbox.items[0]).toMatchObject({
+      target: {
+        type: "purchase",
+        id: "P-100",
+        route: "/purchases/P-100",
+      },
+      recipientRoleCodes: ["reviewer"],
+      sourceKey: "workflow:workflow-notice-1:created",
+    });
+    expect(outsiderInbox.total).toBe(0);
+    expect(
+      await notifications.markRead(
+        reviewerInbox.items[0]!.id,
+        outsiderInboxActor(),
+      ),
+    ).toBeUndefined();
+  });
+});
+
+function actor(id: string, roleCodes: string[]): RequestActor {
+  return { id, name: id, type: "user", roleCodes, permissionKeys: [] };
+}
+
+function outsiderInboxActor() {
+  return actor("guest-user", ["guest"]);
+}