@tailor-platform/erp-kit 0.5.0 → 0.6.0

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

@@ -0,0 +1,87 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotClosableError,
+  OpenWorkRemainsError,
+  CostSummaryNotSettledError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CloseProductionOrderInput {
+  id: string;
+  from?: string[];
+}
+
+/**
+ * Function: closeProductionOrder
+ *
+ * Performs the final administrative close after technical completion and
+ * downstream cost settlement are done. The command is the last lifecycle
+ * step for the production order.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: CloseProductionOrderInput & CF,
+  _ctx: CommandContext,
+) {
+  const { id, from, ...customFields } = input;
+  void customFields;
+
+  const allowedStatuses = from ?? ["TECHNICALLY_COMPLETE"];
+
+  // 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 is closable
+  if (!allowedStatuses.includes(order.status)) {
+    return err(new ProductionOrderNotClosableError(id));
+  }
+
+  // 3. Check all work orders are resolved (COMPLETE or CANCELLED)
+  const workOrders = await db
+    .selectFrom("WorkOrder")
+    .selectAll()
+    .where("productionOrderId", "=", id)
+    .execute();
+
+  const hasOpenWork = workOrders.some(
+    (wo) => wo.status !== "COMPLETE" && wo.status !== "CANCELLED",
+  );
+
+  if (hasOpenWork) {
+    return err(new OpenWorkRemainsError(id));
+  }
+
+  // 4. Check cost summary is SETTLED
+  const costSummary = await db
+    .selectFrom("ManufacturingCostSummary")
+    .selectAll()
+    .where("productionOrderId", "=", id)
+    .executeTakeFirst();
+
+  if (costSummary?.status !== "SETTLED") {
+    return err(new CostSummaryNotSettledError(id));
+  }
+
+  // 5. Set order status to CLOSED
+  const closedOrder = await db
+    .updateTable("ProductionOrder")
+    .set({
+      status: "CLOSED",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ productionOrder: closedOrder });
+}

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

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

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

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotCompletableError,
+  OpenWorkOrderRemainsError,
+  FinalOutputRequiredError,
+  FinalReceiptRequiredError,
+} from "../lib/errors.generated";
+import {
+  baseInProgressProductionOrder,
+  baseDraftProductionOrder,
+  baseCompleteWorkOrder,
+  baseCancelledWorkOrder,
+  baseInProgressWorkOrder,
+  baseCollectingCostSummary,
+} from "../testing/fixtures";
+import { run } from "./completeProductionOrder";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("completeProductionOrder", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:completeProductionOrder"],
+  };
+
+  it("completes an in-progress order after all required work orders finish", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const completed = { ...baseInProgressProductionOrder, status: "COMPLETED" as const };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseInProgressProductionOrder);
+    // work orders - all complete or cancelled
+    spies.select.mockReturnValueOnce([baseCompleteWorkOrder, baseCancelledWorkOrder]);
+    // cost summary with actual costs
+    spies.select.mockReturnValueOnce({
+      ...baseCollectingCostSummary,
+      productionOrderId: baseInProgressProductionOrder.id,
+      actualMaterialCost: 500,
+    });
+    // update order status
+    spies.update.mockReturnValue(completed);
+
+    const result = await run(db, { id: baseInProgressProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.productionOrder.status).toBe("COMPLETED");
+    }
+    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 IN_PROGRESS", 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(ProductionOrderNotCompletableError);
+    }
+  });
+
+  it("returns error when required work orders remain open", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseInProgressProductionOrder);
+    // work orders - one still in progress
+    spies.select.mockReturnValueOnce([baseInProgressWorkOrder, baseCompleteWorkOrder]);
+
+    const result = await run(db, { id: baseInProgressProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(OpenWorkOrderRemainsError);
+    }
+  });
+
+  it("returns error when final output reporting is incomplete", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const completedWithZero = { ...baseCompleteWorkOrder, completedQuantity: 0 };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseInProgressProductionOrder);
+    // work orders - all cancelled (no completed output)
+    spies.select.mockReturnValueOnce([baseCancelledWorkOrder, completedWithZero]);
+
+    const result = await run(db, { id: baseInProgressProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(FinalOutputRequiredError);
+    }
+  });
+
+  it("returns error when required receipt handoff evidence is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseInProgressProductionOrder);
+    // work orders - all complete with output
+    spies.select.mockReturnValueOnce([baseCompleteWorkOrder]);
+    // cost summary with no actual costs
+    spies.select.mockReturnValueOnce({
+      ...baseCollectingCostSummary,
+      productionOrderId: baseInProgressProductionOrder.id,
+      actualMaterialCost: 0,
+    });
+
+    const result = await run(db, { id: baseInProgressProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(FinalReceiptRequiredError);
+    }
+  });
+});

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

@@ -0,0 +1,97 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotCompletableError,
+  OpenWorkOrderRemainsError,
+  FinalOutputRequiredError,
+  FinalReceiptRequiredError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface CompleteProductionOrderInput {
+  id: string;
+  from?: string[];
+}
+
+/**
+ * Function: completeProductionOrder
+ *
+ * Marks physical production complete once required work orders are finished
+ * and final receipt obligations are satisfied. The command freezes production
+ * execution while still allowing later technical completion and review.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: CompleteProductionOrderInput & CF,
+  _ctx: CommandContext,
+) {
+  const { id, from, ...customFields } = input;
+  void customFields;
+
+  const allowedStatuses = from ?? ["IN_PROGRESS"];
+
+  // 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 is completable
+  if (!allowedStatuses.includes(order.status)) {
+    return err(new ProductionOrderNotCompletableError(id));
+  }
+
+  // 3. Check all required work orders are COMPLETE or CANCELLED
+  const workOrders = await db
+    .selectFrom("WorkOrder")
+    .selectAll()
+    .where("productionOrderId", "=", id)
+    .execute();
+
+  const hasOpenWorkOrders = workOrders.some(
+    (wo) => wo.status !== "COMPLETE" && wo.status !== "CANCELLED",
+  );
+
+  if (hasOpenWorkOrders) {
+    return err(new OpenWorkOrderRemainsError(id));
+  }
+
+  // 4. Check final output has been reported
+  const hasCompletedOutput = workOrders.some(
+    (wo) => wo.status === "COMPLETE" && wo.completedQuantity > 0,
+  );
+
+  if (!hasCompletedOutput) {
+    return err(new FinalOutputRequiredError(id));
+  }
+
+  // 5. Check receipt handoff evidence exists
+  const costSummary = await db
+    .selectFrom("ManufacturingCostSummary")
+    .selectAll()
+    .where("productionOrderId", "=", id)
+    .executeTakeFirst();
+
+  if (!costSummary || costSummary.actualMaterialCost <= 0) {
+    return err(new FinalReceiptRequiredError(id));
+  }
+
+  // 6. Set status to COMPLETED
+  const completedOrder = await db
+    .updateTable("ProductionOrder")
+    .set({
+      status: "COMPLETED",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ productionOrder: completedOrder });
+}

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

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

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

@@ -0,0 +1,369 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  WorkOrderNotFoundError,
+  WorkOrderNotCompletableError,
+  WorkOrderNotStartedError,
+  InvalidCompletionQuantityError,
+  DuplicateBackflushRiskError,
+  ReceiptHandoffRequiredError,
+  LotReferenceRequiredError,
+  SerialReferenceRequiredError,
+} from "../lib/errors.generated";
+import {
+  baseInProgressWorkOrder,
+  basePendingWorkOrder,
+  baseCompleteWorkOrder,
+} from "../testing/fixtures";
+import { run } from "./completeWorkOrder";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("completeWorkOrder", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:completeWorkOrder"],
+  };
+
+  const baseInput = {
+    id: baseInProgressWorkOrder.id,
+    completedQuantity: 50,
+    backflushRequired: false,
+    receiptRequired: false,
+    notes: "Final completion",
+  };
+
+  it("completes an in-progress work order with final quantity reporting", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const completedWorkOrder = {
+      ...baseInProgressWorkOrder,
+      status: "COMPLETE" as const,
+      completedQuantity: 100,
+    };
+
+    // work order lookup
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+    // update work order
+    spies.update.mockReturnValueOnce(completedWorkOrder);
+    // insert execution event
+    spies.insert.mockReturnValueOnce(undefined);
+    // sibling work orders (all complete after this one)
+    spies.select.mockReturnValueOnce([
+      { ...baseInProgressWorkOrder, id: baseInProgressWorkOrder.id, status: "IN_PROGRESS" },
+    ]);
+    // update parent production order
+    spies.update.mockReturnValueOnce(undefined);
+
+    const result = await run(db, baseInput, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.workOrder.status).toBe("COMPLETE");
+      expect(result.value.workOrder.completedQuantity).toBe(100);
+    }
+    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, { ...baseInput, 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 in progress", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(basePendingWorkOrder);
+
+    const result = await run(db, { ...baseInput, id: basePendingWorkOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(WorkOrderNotCompletableError);
+    }
+  });
+
+  it("returns error when the work order was never started", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const unstartedWorkOrder = {
+      ...baseInProgressWorkOrder,
+      actualStartDate: null,
+    };
+    spies.select.mockReturnValueOnce(unstartedWorkOrder);
+
+    const result = await run(db, baseInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(WorkOrderNotStartedError);
+    }
+  });
+
+  it("returns error when completion quantity is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+
+    const result = await run(db, { ...baseInput, completedQuantity: 0 }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidCompletionQuantityError);
+    }
+  });
+
+  it("returns error when backflush would duplicate manual issue", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+
+    const result = await run(
+      db,
+      {
+        ...baseInput,
+        backflushRequired: true,
+        manuallyIssuedQuantity: 10,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateBackflushRiskError);
+    }
+  });
+
+  it("emits receipt handoff when output receipt is required", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const completedWorkOrder = {
+      ...baseInProgressWorkOrder,
+      status: "COMPLETE" as const,
+      completedQuantity: 100,
+    };
+
+    // work order lookup
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+    // update work order
+    spies.update.mockReturnValueOnce(completedWorkOrder);
+    // insert execution event
+    spies.insert.mockReturnValueOnce(undefined);
+    // sibling work orders
+    spies.select.mockReturnValueOnce([
+      { ...baseInProgressWorkOrder, id: baseInProgressWorkOrder.id, status: "IN_PROGRESS" },
+    ]);
+    // update parent production order
+    spies.update.mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        ...baseInput,
+        receiptRequired: true,
+        receiptData: {
+          itemReference: "item-fg-1",
+          unitOfMeasure: "EA",
+          siteReference: "site-1",
+          postingDate: new Date("2024-03-01T12:00:00.000Z"),
+          lotTracked: false,
+          serialTracked: false,
+        },
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.workOrder.status).toBe("COMPLETE");
+      expect(result.value.receiptHandoff?.itemReference).toBe("item-fg-1");
+    }
+  });
+
+  it("returns error when receipt is required but receipt data is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+
+    const result = await run(
+      db,
+      {
+        ...baseInput,
+        receiptRequired: true,
+        receiptData: null,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ReceiptHandoffRequiredError);
+    }
+  });
+
+  it("returns error when a lot-tracked receipt omits finishedGoodLotReference", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+
+    const result = await run(
+      db,
+      {
+        ...baseInput,
+        receiptRequired: true,
+        receiptData: {
+          itemReference: "item-fg-1",
+          unitOfMeasure: "EA",
+          siteReference: "site-1",
+          postingDate: new Date("2024-03-01T12:00:00.000Z"),
+          lotTracked: true,
+          serialTracked: false,
+          finishedGoodLotReference: null,
+        },
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(LotReferenceRequiredError);
+    }
+  });
+
+  it("returns error when a serial-tracked receipt omits serialReferences", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+
+    const result = await run(
+      db,
+      {
+        ...baseInput,
+        receiptRequired: true,
+        receiptData: {
+          itemReference: "item-fg-1",
+          unitOfMeasure: "EA",
+          siteReference: "site-1",
+          postingDate: new Date("2024-03-01T12:00:00.000Z"),
+          lotTracked: false,
+          serialTracked: true,
+          serialReferences: null,
+        },
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(SerialReferenceRequiredError);
+    }
+  });
+
+  it("rolls up completion to the parent order", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const completedWorkOrder = {
+      ...baseInProgressWorkOrder,
+      status: "COMPLETE" as const,
+      completedQuantity: 100,
+    };
+
+    // work order lookup
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+    // update work order
+    spies.update.mockReturnValueOnce(completedWorkOrder);
+    // insert execution event
+    spies.insert.mockReturnValueOnce(undefined);
+    // sibling work orders - all siblings already complete/cancelled
+    spies.select.mockReturnValueOnce([
+      { ...baseInProgressWorkOrder, id: baseInProgressWorkOrder.id, status: "IN_PROGRESS" },
+      { ...baseCompleteWorkOrder, id: "work-order-sibling", status: "COMPLETE" },
+    ]);
+    // update parent production order to COMPLETED
+    spies.update.mockReturnValueOnce(undefined);
+
+    const result = await run(db, baseInput, ctx);
+
+    expect(result.ok).toBe(true);
+    // The update spy should have been called twice: once for the work order, once for the parent order
+    expect(spies.update).toHaveBeenCalledTimes(2);
+  });
+
+  it("allows zero-quantity completion only under an explicit bypass policy", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const completedWorkOrder = {
+      ...baseInProgressWorkOrder,
+      status: "COMPLETE" as const,
+      completedQuantity: baseInProgressWorkOrder.completedQuantity,
+    };
+
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+    spies.update.mockReturnValueOnce(completedWorkOrder);
+    spies.insert.mockReturnValueOnce(undefined);
+    spies.select.mockReturnValueOnce([
+      { ...baseInProgressWorkOrder, id: baseInProgressWorkOrder.id, status: "IN_PROGRESS" },
+    ]);
+    spies.update.mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        ...baseInput,
+        completedQuantity: 0,
+        zeroQuantityBypassPolicy: {
+          allowZeroCompletion: true,
+          reasonCode: "QUALITY_HOLD",
+        },
+        receiptRequired: true,
+        receiptData: {
+          itemReference: "item-fg-1",
+          unitOfMeasure: "EA",
+          siteReference: "site-1",
+          postingDate: new Date("2024-03-01T12:00:00.000Z"),
+          lotTracked: false,
+          serialTracked: false,
+        },
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.backflushHandoff).toBeNull();
+      expect(result.value.receiptHandoff?.quantity).toBe(0);
+    }
+  });
+
+  it("emits a backflush handoff when completion requires backflush consumption", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const completedWorkOrder = {
+      ...baseInProgressWorkOrder,
+      status: "COMPLETE" as const,
+      completedQuantity: 100,
+    };
+
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+    spies.update.mockReturnValueOnce(completedWorkOrder);
+    spies.insert.mockReturnValueOnce(undefined);
+    spies.select.mockReturnValueOnce([
+      { ...baseInProgressWorkOrder, id: baseInProgressWorkOrder.id, status: "IN_PROGRESS" },
+    ]);
+    spies.update.mockReturnValueOnce(undefined);
+
+    const result = await run(
+      db,
+      {
+        ...baseInput,
+        backflushRequired: true,
+        manuallyIssuedQuantity: 0,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.backflushHandoff?.productionOrderReference).toBe(
+        baseInProgressWorkOrder.productionOrderId,
+      );
+      expect(result.value.backflushHandoff?.completedQuantity).toBe(50);
+    }
+  });
+});