@tailor-platform/erp-kit 0.5.0 → 0.6.0

package/src/modules/manufacturing/command/startWorkOrder.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  WorkOrderNotFoundError,
+  WorkOrderNotStartableError,
+  ParentOrderNotExecutableError,
+  OperationSequenceBlockedError,
+} from "../lib/errors.generated";
+import {
+  basePendingWorkOrder,
+  baseInProgressWorkOrder,
+  baseReleasedProductionOrder,
+  baseDraftProductionOrder,
+} from "../testing/fixtures";
+import { run } from "./startWorkOrder";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("startWorkOrder", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:startWorkOrder"],
+  };
+
+  it("starts a pending work order", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const startedWorkOrder = {
+      ...basePendingWorkOrder,
+      status: "IN_PROGRESS" as const,
+      actualStartDate: new Date(),
+    };
+
+    // work order lookup
+    spies.select.mockReturnValueOnce(basePendingWorkOrder);
+    // parent production order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // sibling work orders (no predecessors)
+    spies.select.mockReturnValueOnce([basePendingWorkOrder]);
+    // update work order
+    spies.update.mockReturnValueOnce(startedWorkOrder);
+    // insert execution event
+    spies.insert.mockReturnValueOnce(undefined);
+    // update parent production order to IN_PROGRESS
+    spies.update.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: basePendingWorkOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.workOrder.status).toBe("IN_PROGRESS");
+    }
+    expect(spies.update).toHaveBeenCalled();
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("returns error when the work order does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(WorkOrderNotFoundError);
+    }
+  });
+
+  it("returns error when the work order is not pending", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+
+    const result = await run(db, { id: baseInProgressWorkOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(WorkOrderNotStartableError);
+    }
+  });
+
+  it("returns error when the parent production order is not executable", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // work order lookup
+    spies.select.mockReturnValueOnce(basePendingWorkOrder);
+    // parent production order - DRAFT is not executable
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+
+    const result = await run(db, { id: basePendingWorkOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentOrderNotExecutableError);
+    }
+  });
+
+  it("returns error when required predecessor work is incomplete", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const secondWorkOrder = {
+      ...basePendingWorkOrder,
+      id: "work-order-second",
+      routingOperationSequenceNumber: 20,
+    };
+
+    // work order lookup (second operation)
+    spies.select.mockReturnValueOnce(secondWorkOrder);
+    // parent production order
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // sibling work orders - first is still PENDING
+    spies.select.mockReturnValueOnce([basePendingWorkOrder, secondWorkOrder]);
+
+    const result = await run(db, { id: secondWorkOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(OperationSequenceBlockedError);
+    }
+  });
+});

package/src/modules/manufacturing/command/startWorkOrder.ts

@@ -0,0 +1,126 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  WorkOrderNotFoundError,
+  WorkOrderNotStartableError,
+  ParentOrderNotExecutableError,
+  OperationSequenceBlockedError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+const EXECUTABLE_ORDER_STATUSES = ["RELEASED", "IN_PROGRESS"] as const;
+
+export interface StartWorkOrderInput {
+  id: string;
+}
+
+/**
+ * Function: startWorkOrder
+ *
+ * Begins execution on a pending work order. Records the actual start timestamp,
+ * moves the work order to IN_PROGRESS, and transitions the parent production
+ * order to IN_PROGRESS if it was RELEASED.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: StartWorkOrderInput & CF,
+  _ctx: CommandContext,
+) {
+  const { id, ...customFields } = input;
+  void customFields;
+
+  // 1. Fetch work order with lock
+  const workOrder = await db
+    .selectFrom("WorkOrder")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!workOrder) {
+    return err(new WorkOrderNotFoundError(id));
+  }
+
+  // 2. Validate status is PENDING
+  if (workOrder.status !== "PENDING") {
+    return err(new WorkOrderNotStartableError(id));
+  }
+
+  // 3. Check parent production order is in an execution-capable state
+  const parentOrder = await db
+    .selectFrom("ProductionOrder")
+    .selectAll()
+    .where("id", "=", workOrder.productionOrderId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (
+    !parentOrder ||
+    !EXECUTABLE_ORDER_STATUSES.includes(
+      parentOrder.status as (typeof EXECUTABLE_ORDER_STATUSES)[number],
+    )
+  ) {
+    return err(new ParentOrderNotExecutableError(id));
+  }
+
+  // 4. Check preceding operations are complete (sequence order guard)
+  const siblingWorkOrders = await db
+    .selectFrom("WorkOrder")
+    .selectAll()
+    .where("productionOrderId", "=", workOrder.productionOrderId)
+    .execute();
+
+  const hasPendingPredecessor = siblingWorkOrders.some(
+    (wo) =>
+      wo.routingOperationSequenceNumber < workOrder.routingOperationSequenceNumber &&
+      wo.status !== "COMPLETE" &&
+      wo.status !== "CANCELLED",
+  );
+
+  if (hasPendingPredecessor) {
+    return err(new OperationSequenceBlockedError(id));
+  }
+
+  // 5. Record actual start and set IN_PROGRESS
+  const now = new Date();
+
+  const updatedWorkOrder = await db
+    .updateTable("WorkOrder")
+    .set({
+      status: "IN_PROGRESS",
+      actualStartDate: now,
+      updatedAt: now,
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // 6. Create STARTED execution event
+  await db
+    .insertInto("WorkOrderExecutionEvent")
+    .values({
+      workOrderId: id,
+      eventType: "STARTED",
+      timestamp: now,
+      quantity: null,
+      timeValue: null,
+      scrapValue: null,
+      notes: null,
+      createdAt: now,
+      updatedAt: null,
+    })
+    .execute();
+
+  // 7. If parent production order is RELEASED, transition to IN_PROGRESS
+  if (parentOrder.status === "RELEASED") {
+    await db
+      .updateTable("ProductionOrder")
+      .set({
+        status: "IN_PROGRESS",
+        updatedAt: now,
+      })
+      .where("id", "=", parentOrder.id)
+      .execute();
+  }
+
+  return ok({ workOrder: updatedWorkOrder });
+}

package/src/modules/manufacturing/command/technicallyCompleteProductionOrder.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./technicallyCompleteProductionOrder";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const technicallyCompleteProductionOrder = defineCommand(permissions.technicallyCompleteProductionOrder, run);

package/src/modules/manufacturing/command/technicallyCompleteProductionOrder.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotTechnicallyCompletableError,
+  ExecutionExceptionRemainsError,
+  PendingMaterialIssueRequestsError,
+  CostSummaryNotReadyError,
+} from "../lib/errors.generated";
+import {
+  baseCompletedProductionOrder,
+  baseInProgressProductionOrder,
+  baseCompleteWorkOrder,
+  baseCancelledWorkOrder,
+  baseInProgressWorkOrder,
+  basePausedWorkOrder,
+  basePendingWorkOrder,
+  baseCollectingCostSummary,
+  basePendingReviewCostSummary,
+} from "../testing/fixtures";
+import { run } from "./technicallyCompleteProductionOrder";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("technicallyCompleteProductionOrder", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:technicallyCompleteProductionOrder"],
+  };
+
+  it("technically completes a completed order and opens variance review", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const techComplete = {
+      ...baseCompletedProductionOrder,
+      status: "TECHNICALLY_COMPLETE" as const,
+    };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseCompletedProductionOrder);
+    // work orders - all complete or cancelled
+    spies.select.mockReturnValueOnce([baseCompleteWorkOrder, baseCancelledWorkOrder]);
+    // cost summary in COLLECTING
+    spies.select.mockReturnValueOnce({
+      ...baseCollectingCostSummary,
+      productionOrderId: baseCompletedProductionOrder.id,
+    });
+    // update cost summary
+    spies.update.mockReturnValueOnce(undefined);
+    // update order status
+    spies.update.mockReturnValue(techComplete);
+
+    const result = await run(db, { id: baseCompletedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.productionOrder.status).toBe("TECHNICALLY_COMPLETE");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("returns error when the order does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductionOrderNotFoundError);
+    }
+  });
+
+  it("returns error when the order is not in COMPLETED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInProgressProductionOrder);
+
+    const result = await run(db, { id: baseInProgressProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductionOrderNotTechnicallyCompletableError);
+    }
+  });
+
+  it("returns error when unresolved execution exceptions remain", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseCompletedProductionOrder);
+    // work orders - one still in progress
+    spies.select.mockReturnValueOnce([baseInProgressWorkOrder]);
+
+    const result = await run(db, { id: baseCompletedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ExecutionExceptionRemainsError);
+    }
+  });
+
+  it("returns error when pending material issue requests or unresolved backflush intents remain", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseCompletedProductionOrder);
+    // work orders - one still pending
+    spies.select.mockReturnValueOnce([baseCompleteWorkOrder, basePendingWorkOrder]);
+
+    const result = await run(db, { id: baseCompletedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(PendingMaterialIssueRequestsError);
+    }
+  });
+
+  it("returns error when the linked cost summary is not ready for review", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseCompletedProductionOrder);
+    // work orders - all complete
+    spies.select.mockReturnValueOnce([baseCompleteWorkOrder]);
+    // cost summary already in PENDING_VARIANCE_REVIEW (not COLLECTING)
+    spies.select.mockReturnValueOnce({
+      ...basePendingReviewCostSummary,
+      productionOrderId: baseCompletedProductionOrder.id,
+    });
+
+    const result = await run(db, { id: baseCompletedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CostSummaryNotReadyError);
+    }
+  });
+
+  it("blocks further shop-floor reporting after technical completion", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // order lookup - already paused work order still open
+    spies.select.mockReturnValueOnce(baseCompletedProductionOrder);
+    // work orders - one paused (execution exception)
+    spies.select.mockReturnValueOnce([basePausedWorkOrder]);
+
+    const result = await run(db, { id: baseCompletedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ExecutionExceptionRemainsError);
+    }
+  });
+});

package/src/modules/manufacturing/command/technicallyCompleteProductionOrder.ts

@@ -0,0 +1,106 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotTechnicallyCompletableError,
+  ExecutionExceptionRemainsError,
+  PendingMaterialIssueRequestsError,
+  CostSummaryNotReadyError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface TechnicallyCompleteProductionOrderInput {
+  id: string;
+  from?: string[];
+}
+
+/**
+ * Function: technicallyCompleteProductionOrder
+ *
+ * Freezes the production order after physical completion and moves the linked
+ * manufacturing cost summary into variance review. Marks the point where no
+ * more normal execution or rescheduling is expected.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: TechnicallyCompleteProductionOrderInput & CF,
+  _ctx: CommandContext,
+) {
+  const { id, from, ...customFields } = input;
+  void customFields;
+
+  const allowedStatuses = from ?? ["COMPLETED"];
+
+  // 1. Fetch production order with lock
+  const order = await db
+    .selectFrom("ProductionOrder")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!order) {
+    return err(new ProductionOrderNotFoundError(id));
+  }
+
+  // 2. Validate status
+  if (!allowedStatuses.includes(order.status)) {
+    return err(new ProductionOrderNotTechnicallyCompletableError(id));
+  }
+
+  // 3. Check for open execution exceptions (work orders not COMPLETE or CANCELLED)
+  const workOrders = await db
+    .selectFrom("WorkOrder")
+    .selectAll()
+    .where("productionOrderId", "=", id)
+    .execute();
+
+  const hasExecutionExceptions = workOrders.some(
+    (wo) => wo.status === "IN_PROGRESS" || wo.status === "PAUSED",
+  );
+
+  if (hasExecutionExceptions) {
+    return err(new ExecutionExceptionRemainsError(id));
+  }
+
+  // 4. Check for pending material issue requests (work orders still PENDING)
+  const hasPendingWork = workOrders.some((wo) => wo.status === "PENDING");
+
+  if (hasPendingWork) {
+    return err(new PendingMaterialIssueRequestsError(id));
+  }
+
+  // 5. Find and validate cost summary
+  const costSummary = await db
+    .selectFrom("ManufacturingCostSummary")
+    .selectAll()
+    .where("productionOrderId", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (costSummary?.status !== "COLLECTING") {
+    return err(new CostSummaryNotReadyError(id));
+  }
+
+  // 6. Move cost summary to PENDING_VARIANCE_REVIEW
+  await db
+    .updateTable("ManufacturingCostSummary")
+    .set({
+      status: "PENDING_VARIANCE_REVIEW",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", costSummary.id)
+    .execute();
+
+  // 7. Set order status to TECHNICALLY_COMPLETE
+  const techCompleteOrder = await db
+    .updateTable("ProductionOrder")
+    .set({
+      status: "TECHNICALLY_COMPLETE",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ productionOrder: techCompleteOrder });
+}

package/src/modules/manufacturing/command/unreleaseProductionOrder.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./unreleaseProductionOrder";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const unreleaseProductionOrder = defineCommand(permissions.unreleaseProductionOrder, run);

package/src/modules/manufacturing/command/unreleaseProductionOrder.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotUnreleasableError,
+  ExecutionAlreadyStartedError,
+  InventoryHandoffExistsError,
+} from "../lib/errors.generated";
+import {
+  baseDraftProductionOrder,
+  baseReleasedProductionOrder,
+  basePendingWorkOrder,
+  baseInProgressWorkOrder,
+  baseMaterialRequirement,
+  baseCollectingCostSummary,
+} from "../testing/fixtures";
+import { run } from "./unreleaseProductionOrder";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("unreleaseProductionOrder", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:unreleaseProductionOrder"],
+  };
+
+  it("unreleases a released order with no execution evidence", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const draftOrder = { ...baseReleasedProductionOrder, status: "DRAFT" as const };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // work orders - all pending
+    spies.select.mockReturnValueOnce([basePendingWorkOrder]);
+    // material requirements
+    spies.select.mockReturnValueOnce([baseMaterialRequirement]);
+    // cost summary - no actuals
+    spies.select.mockReturnValueOnce(baseCollectingCostSummary);
+    // delete operations return
+    spies.delete.mockReturnValue(undefined);
+    // update order status
+    spies.update.mockReturnValue(draftOrder);
+
+    const result = await run(db, { id: baseReleasedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.productionOrder.status).toBe("DRAFT");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("returns error when the order does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductionOrderNotFoundError);
+    }
+  });
+
+  it("returns error when the order is not in RELEASED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+
+    const result = await run(db, { id: baseDraftProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductionOrderNotUnreleasableError);
+    }
+  });
+
+  it("returns error when a work order has already started", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // work orders - one in progress
+    spies.select.mockReturnValueOnce([baseInProgressWorkOrder]);
+
+    const result = await run(db, { id: baseReleasedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ExecutionAlreadyStartedError);
+    }
+  });
+
+  it("returns error when inventory handoff evidence already exists", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const costSummaryWithActuals = {
+      ...baseCollectingCostSummary,
+      actualMaterialCost: 500,
+    };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // work orders - all pending
+    spies.select.mockReturnValueOnce([basePendingWorkOrder]);
+    // material requirements
+    spies.select.mockReturnValueOnce([baseMaterialRequirement]);
+    // cost summary with actual costs
+    spies.select.mockReturnValueOnce(costSummaryWithActuals);
+
+    const result = await run(db, { id: baseReleasedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InventoryHandoffExistsError);
+    }
+  });
+
+  it("removes work orders and material requirements when unrelease succeeds", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const draftOrder = { ...baseReleasedProductionOrder, status: "DRAFT" as const };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // work orders - all pending
+    spies.select.mockReturnValueOnce([basePendingWorkOrder]);
+    // material requirements
+    spies.select.mockReturnValueOnce([]);
+    // cost summary
+    spies.select.mockReturnValueOnce(baseCollectingCostSummary);
+    // delete operations
+    spies.delete.mockReturnValue(undefined);
+    // update order
+    spies.update.mockReturnValue(draftOrder);
+
+    const result = await run(db, { id: baseReleasedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    expect(spies.delete).toHaveBeenCalled();
+    expect(spies.update).toHaveBeenCalled();
+  });
+});