create-windy 0.1.0

package/template/packages/shared/src/workflow.test.ts

@@ -0,0 +1,225 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createWorkItem,
+  transitionWorkItem,
+  WorkflowInvariantError,
+  type WorkItem,
+  type WorkflowActor,
+} from "./workflow.js";
+
+const reviewer: WorkflowActor = {
+  id: "user-reviewer",
+  name: "审核员甲",
+  type: "user",
+  roleCodes: ["reviewer"],
+};
+const manager: WorkflowActor = {
+  id: "user-manager",
+  name: "审批管理员",
+  type: "user",
+  roleCodes: ["manager"],
+  canManage: true,
+};
+const service: WorkflowActor = {
+  id: "workflow-timeout",
+  name: "审批超时服务",
+  type: "service",
+  roleCodes: [],
+};
+
+describe("审批任务状态机", () => {
+  test("候选角色可领取，当前领取人可批准并形成完整决定事实", () => {
+    const claimed = transitionWorkItem(pending(), {
+      type: "claim",
+      actor: reviewer,
+      at: "2026-07-16T01:00:00.000Z",
+    }).workItem;
+    const result = transitionWorkItem(claimed, {
+      type: "approve",
+      actor: reviewer,
+      reason: { text: "资料核验通过" },
+      at: "2026-07-16T02:00:00.000Z",
+    });
+
+    expect(result.workItem.status).toBe("approved");
+    expect(result.workItem.version).toBe(3);
+    expect(result.fact).toMatchObject({
+      command: "approve",
+      beforeStatus: "claimed",
+      afterStatus: "approved",
+      actorId: reviewer.id,
+      decision: { outcome: "approved", reason: { text: "资料核验通过" } },
+      target: {
+        type: "work-order",
+        id: "WO-100",
+        route: "/work-orders/WO-100",
+      },
+    });
+  });
+
+  test("非候选角色不能领取，非领取人不能做决定", () => {
+    expectCode(
+      () =>
+        transitionWorkItem(pending(), {
+          type: "claim",
+          actor: manager,
+          at: "2026-07-16T01:00:00.000Z",
+        }),
+      "ROLE_NOT_CANDIDATE",
+    );
+    const claimed = claim(pending());
+    expectCode(
+      () =>
+        transitionWorkItem(claimed, {
+          type: "reject",
+          actor: manager,
+          reason: { text: "尝试越权驳回" },
+          at: "2026-07-16T02:00:00.000Z",
+        }),
+      "ASSIGNEE_MISMATCH",
+    );
+  });
+
+  test("领取人或管理员可转交，但新领取人仍必须属于候选角色", () => {
+    const claimed = claim(pending());
+    expectCode(
+      () =>
+        transitionWorkItem(claimed, {
+          type: "transfer",
+          actor: reviewer,
+          assignee: { id: "outsider", name: "外部用户", roleCodes: ["guest"] },
+          reason: { text: "错误转交" },
+          at: "2026-07-16T02:00:00.000Z",
+        }),
+      "ROLE_NOT_CANDIDATE",
+    );
+    const transferred = transitionWorkItem(claimed, {
+      type: "transfer",
+      actor: manager,
+      assignee: { id: "reviewer-2", name: "审核员乙", roleCodes: ["reviewer"] },
+      reason: { text: "工作量调配" },
+      at: "2026-07-16T02:00:00.000Z",
+    });
+    expect(transferred.workItem.assignee?.id).toBe("reviewer-2");
+    expect(transferred.workItem.status).toBe("claimed");
+  });
+
+  test("发起人或管理员可取消，其他人不能取消", () => {
+    const item = pending();
+    expectCode(
+      () =>
+        transitionWorkItem(item, {
+          type: "cancel",
+          actor: reviewer,
+          reason: { text: "越权取消" },
+          at: "2026-07-16T01:00:00.000Z",
+        }),
+      "MANAGE_REQUIRED",
+    );
+    const result = transitionWorkItem(item, {
+      type: "cancel",
+      actor: { ...reviewer, id: item.requesterId },
+      reason: { text: "业务申请撤回" },
+      at: "2026-07-16T01:00:00.000Z",
+    });
+    expect(result.workItem.status).toBe("cancelled");
+  });
+
+  test("到期后拒绝业务决定，且仅服务可在截止时间后执行超时", () => {
+    const item = claim(pending());
+    expectCode(
+      () =>
+        transitionWorkItem(item, {
+          type: "approve",
+          actor: reviewer,
+          reason: { text: "已超过截止时间" },
+          at: item.dueAt,
+        }),
+      "WORK_ITEM_OVERDUE",
+    );
+    expectCode(
+      () =>
+        transitionWorkItem(item, {
+          type: "timeout",
+          actor: manager,
+          at: item.dueAt,
+        }),
+      "SERVICE_REQUIRED",
+    );
+    expect(
+      transitionWorkItem(item, {
+        type: "timeout",
+        actor: service,
+        at: item.dueAt,
+      }).workItem.status,
+    ).toBe("timed-out");
+  });
+
+  test("终态不可再次变更", () => {
+    const approved = transitionWorkItem(claim(pending()), {
+      type: "approve",
+      actor: reviewer,
+      reason: { text: "通过" },
+      at: "2026-07-16T02:00:00.000Z",
+    }).workItem;
+    expectCode(
+      () =>
+        transitionWorkItem(approved, {
+          type: "cancel",
+          actor: manager,
+          reason: { text: "尝试改变终态" },
+          at: "2026-07-16T03:00:00.000Z",
+        }),
+      "TERMINAL_WORK_ITEM",
+    );
+  });
+
+  test("创建时拒绝无候选角色、外部跳转和非法截止时间", () => {
+    expectCode(() => pending({ candidateRoles: [] }), "INVALID_WORK_ITEM");
+    expectCode(
+      () =>
+        pending({ target: { type: "x", id: "1", route: "https://x.test" } }),
+      "INVALID_TARGET",
+    );
+    expectCode(
+      () => pending({ dueAt: "2026-07-16T00:00:00.000Z" }),
+      "INVALID_DUE_AT",
+    );
+  });
+});
+
+function pending(
+  overrides: Partial<Parameters<typeof createWorkItem>[0]> = {},
+) {
+  return createWorkItem({
+    id: "approval-100",
+    title: "工单审批",
+    requesterId: "requester-1",
+    candidateRoles: [{ code: "reviewer", name: "审核员" }],
+    dueAt: "2026-07-17T00:00:00.000Z",
+    target: { type: "work-order", id: "WO-100", route: "/work-orders/WO-100" },
+    createdAt: "2026-07-16T00:00:00.000Z",
+    ...overrides,
+  });
+}
+
+function claim(item: WorkItem) {
+  return transitionWorkItem(item, {
+    type: "claim",
+    actor: reviewer,
+    at: "2026-07-16T01:00:00.000Z",
+  }).workItem;
+}
+
+function expectCode(
+  action: () => unknown,
+  code: WorkflowInvariantError["code"],
+) {
+  try {
+    action();
+    throw new Error(`预期抛出 ${code}`);
+  } catch (error) {
+    expect(error).toBeInstanceOf(WorkflowInvariantError);
+    expect((error as WorkflowInvariantError).code).toBe(code);
+  }
+}

package/template/packages/shared/src/workflow.ts

@@ -0,0 +1,307 @@
+import type { ISODateTime } from "./primitives.js";
+
+export type WorkItemStatus =
+  | "pending"
+  | "claimed"
+  | "approved"
+  | "rejected"
+  | "cancelled"
+  | "timed-out";
+
+export interface CandidateRole {
+  code: string;
+  name?: string;
+}
+
+export interface Assignee {
+  id: string;
+  name: string;
+  roleCodes: string[];
+}
+
+export type DueAt = ISODateTime;
+
+export interface Reason {
+  text: string;
+}
+
+export interface Decision {
+  outcome: "approved" | "rejected";
+  reason: Reason;
+}
+
+export interface TargetRef {
+  type: string;
+  id: string;
+  /** 仅允许站内绝对路径，供通知等通用入口跳转。 */
+  route: string;
+}
+
+export interface WorkItem {
+  id: string;
+  title: string;
+  status: WorkItemStatus;
+  requesterId: string;
+  candidateRoles: CandidateRole[];
+  assignee?: Assignee;
+  dueAt: DueAt;
+  target: TargetRef;
+  createdAt: ISODateTime;
+  updatedAt: ISODateTime;
+  version: number;
+}
+
+export interface WorkflowActor {
+  id: string;
+  name: string;
+  type: "user" | "service";
+  roleCodes: string[];
+  canManage?: boolean;
+}
+
+export type WorkItemCommand =
+  | { type: "claim"; actor: WorkflowActor; at: ISODateTime }
+  | {
+      type: "transfer";
+      actor: WorkflowActor;
+      assignee: Assignee;
+      reason: Reason;
+      at: ISODateTime;
+    }
+  | { type: "approve"; actor: WorkflowActor; reason: Reason; at: ISODateTime }
+  | { type: "reject"; actor: WorkflowActor; reason: Reason; at: ISODateTime }
+  | { type: "cancel"; actor: WorkflowActor; reason: Reason; at: ISODateTime }
+  | { type: "timeout"; actor: WorkflowActor; at: ISODateTime };
+
+export interface WorkItemTransition {
+  workItem: WorkItem;
+  fact: {
+    command: WorkItemCommand["type"];
+    beforeStatus: WorkItemStatus;
+    afterStatus: WorkItemStatus;
+    actorId: string;
+    occurredAt: ISODateTime;
+    target: TargetRef;
+    decision?: Decision;
+    reason?: Reason;
+    previousAssigneeId?: string;
+    assigneeId?: string;
+  };
+}
+
+export type WorkflowInvariantCode =
+  | "INVALID_WORK_ITEM"
+  | "INVALID_REASON"
+  | "INVALID_TARGET"
+  | "INVALID_DUE_AT"
+  | "TERMINAL_WORK_ITEM"
+  | "WORK_ITEM_OVERDUE"
+  | "ROLE_NOT_CANDIDATE"
+  | "ASSIGNEE_REQUIRED"
+  | "ASSIGNEE_MISMATCH"
+  | "MANAGE_REQUIRED"
+  | "SERVICE_REQUIRED"
+  | "DUE_AT_NOT_REACHED";
+
+export class WorkflowInvariantError extends Error {
+  constructor(
+    readonly code: WorkflowInvariantCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "WorkflowInvariantError";
+  }
+}
+
+export interface CreateWorkItemInput {
+  id: string;
+  title: string;
+  requesterId: string;
+  candidateRoles: CandidateRole[];
+  dueAt: DueAt;
+  target: TargetRef;
+  createdAt: ISODateTime;
+}
+
+export function createWorkItem(input: CreateWorkItemInput): WorkItem {
+  if (!input.id.trim() || !input.title.trim() || !input.requesterId.trim()) {
+    fail("INVALID_WORK_ITEM", "审批任务标识、标题和发起人不能为空");
+  }
+  const roles = uniqueRoles(input.candidateRoles);
+  if (!roles.length) fail("INVALID_WORK_ITEM", "审批任务至少需要一个候选角色");
+  assertTarget(input.target);
+  if (dateValue(input.dueAt) <= dateValue(input.createdAt)) {
+    fail("INVALID_DUE_AT", "审批截止时间必须晚于创建时间");
+  }
+  return {
+    ...input,
+    title: input.title.trim(),
+    candidateRoles: roles,
+    status: "pending",
+    version: 1,
+    updatedAt: input.createdAt,
+  };
+}
+
+export function transitionWorkItem(
+  item: WorkItem,
+  command: WorkItemCommand,
+): WorkItemTransition {
+  assertMutable(item);
+  assertChronology(item, command.at);
+  const beforeStatus = item.status;
+  const previousAssigneeId = item.assignee?.id;
+  let status = item.status;
+  let assignee = item.assignee;
+  let decision: Decision | undefined;
+  let reason: Reason | undefined;
+
+  switch (command.type) {
+    case "claim":
+      assertPending(item);
+      assertCandidate(item, command.actor.roleCodes);
+      assignee = actorAssignee(command.actor);
+      status = "claimed";
+      break;
+    case "transfer":
+      assertClaimed(item);
+      if (item.assignee?.id !== command.actor.id && !command.actor.canManage) {
+        fail("MANAGE_REQUIRED", "仅当前领取人或管理员可以转交审批任务");
+      }
+      assertCandidate(item, command.assignee.roleCodes);
+      reason = validReason(command.reason);
+      assignee = command.assignee;
+      break;
+    case "approve":
+    case "reject":
+      assertClaimedBy(item, command.actor.id);
+      assertBeforeDue(item, command.at);
+      reason = validReason(command.reason);
+      status = command.type === "approve" ? "approved" : "rejected";
+      decision = { outcome: status, reason };
+      break;
+    case "cancel":
+      if (command.actor.id !== item.requesterId && !command.actor.canManage) {
+        fail("MANAGE_REQUIRED", "仅发起人或管理员可以取消审批任务");
+      }
+      reason = validReason(command.reason);
+      status = "cancelled";
+      break;
+    case "timeout":
+      if (command.actor.type !== "service") {
+        fail("SERVICE_REQUIRED", "仅后台服务可以执行审批超时");
+      }
+      if (dateValue(command.at) < dateValue(item.dueAt)) {
+        fail("DUE_AT_NOT_REACHED", "尚未到达审批截止时间");
+      }
+      status = "timed-out";
+      break;
+  }
+
+  const workItem = {
+    ...item,
+    status,
+    assignee,
+    updatedAt: command.at,
+    version: item.version + 1,
+  };
+  return {
+    workItem,
+    fact: {
+      command: command.type,
+      beforeStatus,
+      afterStatus: status,
+      actorId: command.actor.id,
+      occurredAt: command.at,
+      target: item.target,
+      decision,
+      reason,
+      previousAssigneeId,
+      assigneeId: assignee?.id,
+    },
+  };
+}
+
+function assertMutable(item: WorkItem) {
+  if (!["pending", "claimed"].includes(item.status)) {
+    fail("TERMINAL_WORK_ITEM", "终态审批任务不能再次变更");
+  }
+}
+
+function assertChronology(item: WorkItem, at: ISODateTime) {
+  if (dateValue(at) < dateValue(item.updatedAt)) {
+    fail("INVALID_WORK_ITEM", "命令时间不能早于审批任务最后更新时间");
+  }
+}
+
+function assertPending(item: WorkItem) {
+  if (item.status !== "pending")
+    fail("INVALID_WORK_ITEM", "仅待领取任务可以领取");
+}
+
+function assertClaimed(item: WorkItem) {
+  if (item.status !== "claimed" || !item.assignee) {
+    fail("ASSIGNEE_REQUIRED", "审批任务尚未领取");
+  }
+}
+
+function assertClaimedBy(item: WorkItem, actorId: string) {
+  assertClaimed(item);
+  if (item.assignee?.id !== actorId) {
+    fail("ASSIGNEE_MISMATCH", "仅当前领取人可以提交审批决定");
+  }
+}
+
+function assertCandidate(item: WorkItem, roleCodes: string[]) {
+  if (!item.candidateRoles.some(({ code }) => roleCodes.includes(code))) {
+    fail("ROLE_NOT_CANDIDATE", "领取人不属于候选角色");
+  }
+}
+
+function assertBeforeDue(item: WorkItem, at: ISODateTime) {
+  if (dateValue(at) >= dateValue(item.dueAt)) {
+    fail("WORK_ITEM_OVERDUE", "审批任务已到期，不能再提交决定");
+  }
+}
+
+function actorAssignee(actor: WorkflowActor): Assignee {
+  return { id: actor.id, name: actor.name, roleCodes: [...actor.roleCodes] };
+}
+
+function validReason(reason: Reason) {
+  const text = reason.text.trim();
+  if (!text || text.length > 500) {
+    fail("INVALID_REASON", "审批理由必须为 1 至 500 个字符");
+  }
+  return { text };
+}
+
+function uniqueRoles(roles: CandidateRole[]) {
+  const byCode = new Map<string, CandidateRole>();
+  for (const role of roles) {
+    const code = role.code.trim();
+    if (code) byCode.set(code, { ...role, code });
+  }
+  return [...byCode.values()];
+}
+
+function assertTarget(target: TargetRef) {
+  if (
+    !target.type.trim() ||
+    !target.id.trim() ||
+    !target.route.startsWith("/") ||
+    target.route.startsWith("//")
+  ) {
+    fail("INVALID_TARGET", "审批目标必须包含合法的站内引用");
+  }
+}
+
+function dateValue(value: ISODateTime) {
+  const result = Date.parse(value);
+  if (!Number.isFinite(result)) fail("INVALID_WORK_ITEM", "时间格式无效");
+  return result;
+}
+
+function fail(code: WorkflowInvariantCode, message: string): never {
+  throw new WorkflowInvariantError(code, message);
+}

package/template/packages/storage/index.ts

@@ -0,0 +1,11 @@
+export * from "./src/blob-store.js";
+export * from "./src/content-hash.js";
+export * from "./src/file-service.js";
+export * from "./src/local-file-blob-store.js";
+export * from "./src/local-file-maintenance.js";
+export * from "./src/memory-blob-store.js";
+export * from "./src/in-memory-upload-repository.js";
+export * from "./src/upload-repository.js";
+export * from "./src/upload-service.js";
+export * from "./src/upload-streams.js";
+export * from "./src/upload-types.js";

package/template/packages/storage/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@windy/storage",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "exports": {
+    ".": "./index.ts"
+  }
+}

package/template/packages/storage/src/blob-store.ts

@@ -0,0 +1,64 @@
+export type ArtifactRef = string & { readonly __artifactRef: unique symbol };
+
+export interface ContentHash {
+  algorithm: "sha256";
+  value: string;
+}
+
+export interface StoredBlob {
+  ref: ArtifactRef;
+  byteSize: number;
+  contentHash: ContentHash;
+  createdAt: string;
+}
+
+export interface ReadableBlob extends StoredBlob {
+  body: ReadableStream<Uint8Array>;
+}
+
+export interface PutBlobInput {
+  body: ReadableStream<Uint8Array>;
+  expectedByteSize?: number;
+  expectedContentHash?: ContentHash;
+}
+
+export interface BlobStore {
+  put(input: PutBlobInput): Promise<StoredBlob>;
+  inspect(ref: ArtifactRef): Promise<StoredBlob | undefined>;
+  open(ref: ArtifactRef): Promise<ReadableBlob | undefined>;
+  delete(ref: ArtifactRef): Promise<boolean>;
+}
+
+export interface BlobStoreMaintenance {
+  cleanupOrphans(input: {
+    referencedRefs: ReadonlySet<ArtifactRef>;
+    olderThan: Date;
+    limit: number;
+  }): Promise<number>;
+}
+
+export type BlobStoreErrorCode =
+  | "INVALID_ARTIFACT_REF"
+  | "INVALID_CONTENT_HASH"
+  | "SIZE_MISMATCH"
+  | "HASH_MISMATCH"
+  | "CORRUPT_BLOB_METADATA";
+
+export class BlobStoreError extends Error {
+  constructor(
+    readonly code: BlobStoreErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "BlobStoreError";
+  }
+}
+
+const artifactRefPattern = /^blob_[a-f0-9]{32}$/;
+
+export function artifactRef(value: string): ArtifactRef {
+  if (!artifactRefPattern.test(value)) {
+    throw new BlobStoreError("INVALID_ARTIFACT_REF", "Artifact 引用格式无效");
+  }
+  return value as ArtifactRef;
+}

package/template/packages/storage/src/content-hash.ts

@@ -0,0 +1,24 @@
+import { createHash } from "node:crypto";
+import { BlobStoreError, type ContentHash } from "./blob-store.js";
+
+const sha256Pattern = /^[a-f0-9]{64}$/;
+
+export function sha256ContentHash(value: string): ContentHash {
+  const normalized = value.toLowerCase();
+  if (!sha256Pattern.test(normalized)) {
+    throw new BlobStoreError("INVALID_CONTENT_HASH", "SHA-256 摘要格式无效");
+  }
+  return { algorithm: "sha256", value: normalized };
+}
+
+export function createSha256Accumulator() {
+  const hash = createHash("sha256");
+  return {
+    update(chunk: Uint8Array): void {
+      hash.update(chunk);
+    },
+    digest(): ContentHash {
+      return sha256ContentHash(hash.digest("hex"));
+    },
+  };
+}