@tailor-platform/erp-kit 0.5.1 → 0.6.0

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

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotCancellableError,
+  ExecutionAlreadyStartedError,
+  InventoryHandoffExistsError,
+} from "../lib/errors.generated";
+import {
+  baseDraftProductionOrder,
+  baseReleasedProductionOrder,
+  baseInProgressProductionOrder,
+  basePendingWorkOrder,
+  baseInProgressWorkOrder,
+  baseCollectingCostSummary,
+} from "../testing/fixtures";
+import { run } from "./cancelProductionOrder";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("cancelProductionOrder", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:cancelProductionOrder"],
+  };
+
+  it("cancels a draft production order", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const cancelled = { ...baseDraftProductionOrder, status: "CANCELLED" as const };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+    // update order status
+    spies.update.mockReturnValue(cancelled);
+
+    const result = await run(db, { id: baseDraftProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.productionOrder.status).toBe("CANCELLED");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("cancels a released order before execution starts", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const cancelled = { ...baseReleasedProductionOrder, status: "CANCELLED" as const };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // work orders - all pending
+    spies.select.mockReturnValueOnce([basePendingWorkOrder]);
+    // cost summary - no actuals
+    spies.select.mockReturnValueOnce(baseCollectingCostSummary);
+    // cascade cancel work orders
+    spies.update.mockReturnValueOnce(undefined);
+    // update order status
+    spies.update.mockReturnValue(cancelled);
+
+    const result = await run(db, { id: baseReleasedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.productionOrder.status).toBe("CANCELLED");
+    }
+  });
+
+  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 status does not allow cancellation", 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(ProductionOrderNotCancellableError);
+    }
+  });
+
+  it("returns error when execution evidence already exists", 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]);
+    // 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("cascades cancellation to pending work orders", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const cancelled = { ...baseReleasedProductionOrder, status: "CANCELLED" as const };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // work orders - all pending
+    spies.select.mockReturnValueOnce([basePendingWorkOrder]);
+    // cost summary - no actuals
+    spies.select.mockReturnValueOnce(baseCollectingCostSummary);
+    // cascade cancel work orders (first update call)
+    spies.update.mockReturnValueOnce(undefined);
+    // update order status (second update call)
+    spies.update.mockReturnValue(cancelled);
+
+    const result = await run(db, { id: baseReleasedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    // update should be called at least twice: once for work orders, once for order
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,114 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotCancellableError,
+  ExecutionAlreadyStartedError,
+  InventoryHandoffExistsError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+const CANCELLABLE_STATUSES = ["DRAFT", "RELEASED"] as const;
+
+export interface CancelProductionOrderInput {
+  id: string;
+  from?: string[];
+}
+
+/**
+ * Function: cancelProductionOrder
+ *
+ * Abandons a draft or not-yet-started released order. Preserves audit
+ * history while blocking further execution updates and cascading
+ * cancellation to pending work orders.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: CancelProductionOrderInput & CF,
+  _ctx: CommandContext,
+) {
+  const { id, from, ...customFields } = input;
+  void customFields;
+
+  const allowedStatuses = from ?? [...CANCELLABLE_STATUSES];
+
+  // 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 cancellable
+  if (!allowedStatuses.includes(order.status)) {
+    return err(new ProductionOrderNotCancellableError(id));
+  }
+
+  // 3. For released orders, check execution and inventory evidence
+  if (order.status === "RELEASED") {
+    // Check work orders for execution evidence
+    const workOrders = await db
+      .selectFrom("WorkOrder")
+      .selectAll()
+      .where("productionOrderId", "=", id)
+      .execute();
+
+    const hasExecution = workOrders.some(
+      (wo) =>
+        wo.status === "IN_PROGRESS" ||
+        wo.status === "PAUSED" ||
+        wo.status === "COMPLETE" ||
+        wo.completedQuantity > 0 ||
+        wo.actualStartDate != null,
+    );
+
+    if (hasExecution) {
+      return err(new ExecutionAlreadyStartedError(id));
+    }
+
+    // Check for inventory handoff evidence
+    const costSummary = await db
+      .selectFrom("ManufacturingCostSummary")
+      .selectAll()
+      .where("productionOrderId", "=", id)
+      .executeTakeFirst();
+
+    if (
+      costSummary &&
+      (costSummary.actualMaterialCost > 0 ||
+        costSummary.actualLaborCost > 0 ||
+        costSummary.actualMachineCost > 0 ||
+        costSummary.actualOverheadCost > 0)
+    ) {
+      return err(new InventoryHandoffExistsError(id));
+    }
+
+    // 4. Cascade cancellation to pending work orders
+    await db
+      .updateTable("WorkOrder")
+      .set({
+        status: "CANCELLED",
+        updatedAt: new Date(),
+      })
+      .where("productionOrderId", "=", id)
+      .where("status", "=", "PENDING")
+      .execute();
+  }
+
+  // 5. Set order status to CANCELLED
+  const cancelledOrder = await db
+    .updateTable("ProductionOrder")
+    .set({
+      status: "CANCELLED",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ productionOrder: cancelledOrder });
+}

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

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

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

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotClosableError,
+  OpenWorkRemainsError,
+  CostSummaryNotSettledError,
+} from "../lib/errors.generated";
+import {
+  baseTechCompleteProductionOrder,
+  baseCompletedProductionOrder,
+  baseClosedProductionOrder,
+  baseCompleteWorkOrder,
+  baseCancelledWorkOrder,
+  basePendingWorkOrder,
+  baseSettledCostSummary,
+  basePendingReviewCostSummary,
+} from "../testing/fixtures";
+import { run } from "./closeProductionOrder";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("closeProductionOrder", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:closeProductionOrder"],
+  };
+
+  it("closes a technically complete order with a settled cost summary", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const closed = { ...baseTechCompleteProductionOrder, status: "CLOSED" as const };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseTechCompleteProductionOrder);
+    // work orders - all complete or cancelled
+    spies.select.mockReturnValueOnce([baseCompleteWorkOrder, baseCancelledWorkOrder]);
+    // cost summary in SETTLED
+    spies.select.mockReturnValueOnce({
+      ...baseSettledCostSummary,
+      productionOrderId: baseTechCompleteProductionOrder.id,
+    });
+    // update order status
+    spies.update.mockReturnValue(closed);
+
+    const result = await run(db, { id: baseTechCompleteProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.productionOrder.status).toBe("CLOSED");
+    }
+    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 technically complete", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseCompletedProductionOrder);
+
+    const result = await run(db, { id: baseCompletedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductionOrderNotClosableError);
+    }
+  });
+
+  it("returns error when open work or execution exceptions remain", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseTechCompleteProductionOrder);
+    // work orders - one still pending
+    spies.select.mockReturnValueOnce([baseCompleteWorkOrder, basePendingWorkOrder]);
+
+    const result = await run(db, { id: baseTechCompleteProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(OpenWorkRemainsError);
+    }
+  });
+
+  it("returns error when the linked cost summary is not settled", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseTechCompleteProductionOrder);
+    // work orders - all complete
+    spies.select.mockReturnValueOnce([baseCompleteWorkOrder]);
+    // cost summary not settled
+    spies.select.mockReturnValueOnce({
+      ...basePendingReviewCostSummary,
+      productionOrderId: baseTechCompleteProductionOrder.id,
+    });
+
+    const result = await run(db, { id: baseTechCompleteProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CostSummaryNotSettledError);
+    }
+  });
+
+  it("blocks further execution commands after close", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseClosedProductionOrder);
+
+    const result = await run(db, { id: baseClosedProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductionOrderNotClosableError);
+    }
+  });
+});

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);
+    }
+  });
+});