@tailor-platform/erp-kit 0.5.0 → 0.6.0

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

@@ -0,0 +1,131 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotUnreleasableError,
+  ExecutionAlreadyStartedError,
+  InventoryHandoffExistsError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface UnreleaseProductionOrderInput {
+  id: string;
+  from?: string[];
+}
+
+/**
+ * Function: unreleaseProductionOrder
+ *
+ * Returns a released order to DRAFT when execution has not meaningfully
+ * started. Removes release artifacts so the planner can safely revise
+ * the order.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UnreleaseProductionOrderInput & CF,
+  _ctx: CommandContext,
+) {
+  const { id, from, ...customFields } = input;
+  void customFields;
+
+  const allowedStatuses = from ?? ["RELEASED"];
+
+  // 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 unreleasable
+  if (!allowedStatuses.includes(order.status)) {
+    return err(new ProductionOrderNotUnreleasableError(id));
+  }
+
+  // 3. Check no work order has 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));
+  }
+
+  // 4. Check no irreversible inventory handoff
+  const _materialRequirements = await db
+    .selectFrom("ProductionOrderMaterialRequirement")
+    .selectAll()
+    .where("productionOrderId", "=", id)
+    .execute();
+
+  // Check if any cost summary has actual costs recorded (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));
+  }
+
+  // 5. Remove release artifacts - delete work orders
+  await db.deleteFrom("WorkOrder").where("productionOrderId", "=", id).execute();
+
+  // 6. Remove material requirements
+  await db
+    .deleteFrom("ProductionOrderMaterialRequirement")
+    .where("productionOrderId", "=", id)
+    .execute();
+
+  // 7. Remove BOM snapshot
+  await db.deleteFrom("ProductionOrderBomSnapshot").where("productionOrderId", "=", id).execute();
+
+  // 8. Remove routing snapshot
+  await db
+    .deleteFrom("ProductionOrderRoutingSnapshot")
+    .where("productionOrderId", "=", id)
+    .execute();
+
+  // 9. Remove cost baseline
+  await db.deleteFrom("ProductionOrderCostBaseline").where("productionOrderId", "=", id).execute();
+
+  // 10. Remove cost summary
+  await db.deleteFrom("ManufacturingCostSummary").where("productionOrderId", "=", id).execute();
+
+  // 11. Set status to DRAFT
+  const draftOrder = await db
+    .updateTable("ProductionOrder")
+    .set({
+      selectedBomVersionId: null,
+      selectedRoutingRevisionId: null,
+      status: "DRAFT",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ productionOrder: draftOrder });
+}

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

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

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

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  BomNotFoundError,
+  BomNotMutableError,
+  InvalidComponentQuantityError,
+  ComponentItemInactiveError,
+  AmbiguousEffectivityRuleError,
+} from "../lib/errors.generated";
+import { baseDraftBom, baseActiveBom, baseBomLine } from "../testing/fixtures";
+import { run } from "./updateBillOfMaterial";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("updateBillOfMaterial", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:updateBillOfMaterial"],
+  };
+
+  const validInput = {
+    id: "bom-1",
+    bomType: "PHANTOM" as const,
+    lines: [
+      {
+        itemId: "item-2",
+        requiredQuantity: 3.0,
+        unitOfMeasure: "EA",
+      },
+    ],
+  };
+
+  it("updates draft BOM metadata and component lines", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedBom = {
+      ...baseDraftBom,
+      bomType: "PHANTOM" as const,
+    };
+
+    // BOM exists and is DRAFT
+    spies.select.mockReturnValueOnce(baseDraftBom);
+    // component item exists
+    spies.select.mockReturnValueOnce({ id: "item-2" });
+    // update BOM header
+    spies.update.mockReturnValueOnce(updatedBom);
+    // delete old lines
+    spies.delete.mockReturnValueOnce(undefined);
+    // insert new line
+    spies.insert.mockReturnValueOnce({ ...baseBomLine, requiredQuantity: 3.0 });
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.billOfMaterial.bomType).toBe("PHANTOM");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("returns error when the BOM does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(BomNotFoundError);
+    }
+  });
+
+  it("returns error when the BOM is not in DRAFT", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseActiveBom);
+
+    const result = await run(db, { ...validInput, id: "bom-2" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(BomNotMutableError);
+    }
+  });
+
+  it("returns error when a revised component quantity is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseDraftBom);
+
+    const result = await run(
+      db,
+      {
+        ...validInput,
+        lines: [{ itemId: "item-2", requiredQuantity: -1, unitOfMeasure: "EA" }],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidComponentQuantityError);
+    }
+  });
+
+  it("returns error when a newly referenced component is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // BOM exists and is DRAFT
+    spies.select.mockReturnValueOnce(baseDraftBom);
+    // component item not found (inactive)
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ComponentItemInactiveError);
+    }
+  });
+
+  it("returns error when effectivity changes would create ambiguous selection", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // BOM exists and is DRAFT
+    spies.select.mockReturnValueOnce(baseDraftBom);
+    // conflicting active BOM with same default selection
+    spies.select.mockReturnValueOnce({
+      ...baseActiveBom,
+      defaultSelection: true,
+      effectivityStartDate: null,
+      effectivityEndDate: null,
+    });
+
+    const result = await run(
+      db,
+      {
+        id: "bom-1",
+        defaultSelection: true,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AmbiguousEffectivityRuleError);
+    }
+  });
+});

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

@@ -0,0 +1,174 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  BomNotFoundError,
+  BomNotMutableError,
+  InvalidComponentQuantityError,
+  ComponentItemInactiveError,
+  AmbiguousEffectivityRuleError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface UpdateBillOfMaterialLineInput {
+  itemId: string;
+  requiredQuantity: number;
+  unitOfMeasure?: string | null;
+  scrapAssumption?: number | null;
+  isSubassembly?: boolean | null;
+}
+
+export interface UpdateBillOfMaterialInput {
+  id: string;
+  bomType?: string | null;
+  effectivityStartDate?: Date | null;
+  effectivityEndDate?: Date | null;
+  defaultSelection?: boolean | null;
+  revisionNumber?: string | null;
+  lines?: UpdateBillOfMaterialLineInput[];
+}
+
+/**
+ * Function: updateBillOfMaterial
+ *
+ * Revises mutable draft BOM content before activation. Supports changes to
+ * effectivity, default flags, bomType, and component lines while preserving
+ * released production-order snapshots.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UpdateBillOfMaterialInput & CF,
+  _ctx: CommandContext,
+) {
+  const {
+    id,
+    bomType,
+    effectivityStartDate,
+    effectivityEndDate,
+    defaultSelection,
+    revisionNumber,
+    lines,
+    ...customFields
+  } = input;
+
+  // 1. Fetch BOM with lock
+  const bom = await db
+    .selectFrom("BillOfMaterial")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!bom) {
+    return err(new BomNotFoundError(id));
+  }
+
+  // 2. Only DRAFT BOMs are mutable
+  if (bom.status !== "DRAFT") {
+    return err(new BomNotMutableError(id));
+  }
+
+  // 3. Validate revised component lines if provided
+  if (lines) {
+    for (const line of lines) {
+      if (line.requiredQuantity <= 0) {
+        return err(new InvalidComponentQuantityError(line.itemId));
+      }
+
+      // Check component item is not inactive
+      const componentItem = await db
+        .selectFrom("Item")
+        .selectAll()
+        .where("id", "=", line.itemId)
+        .executeTakeFirst();
+
+      if (!componentItem) {
+        return err(new ComponentItemInactiveError(line.itemId));
+      }
+    }
+  }
+
+  // 4. Check effectivity ambiguity — if effectivity or default selection changed,
+  //    verify no ambiguous active-selection plan would result once activated
+  const effectiveDefaultSelection =
+    defaultSelection !== undefined ? defaultSelection : bom.defaultSelection;
+  const effectiveStartDate =
+    effectivityStartDate !== undefined ? effectivityStartDate : bom.effectivityStartDate;
+  const effectiveEndDate =
+    effectivityEndDate !== undefined ? effectivityEndDate : bom.effectivityEndDate;
+
+  if (
+    defaultSelection !== undefined ||
+    effectivityStartDate !== undefined ||
+    effectivityEndDate !== undefined
+  ) {
+    // Find other active BOMs for same parent item and scope that could conflict
+    const conflictingBom = await db
+      .selectFrom("BillOfMaterial")
+      .selectAll()
+      .where("parentItemId", "=", bom.parentItemId)
+      .where("companyId", "=", bom.companyId)
+      .where("id", "!=", id)
+      .where("status", "=", "ACTIVE")
+      .where("defaultSelection", "=", effectiveDefaultSelection ?? false)
+      .executeTakeFirst();
+
+    if (conflictingBom && effectiveDefaultSelection) {
+      // Check date overlap
+      const hasOverlap =
+        !effectiveStartDate ||
+        !conflictingBom.effectivityEndDate ||
+        effectiveStartDate <= conflictingBom.effectivityEndDate;
+      const hasOverlap2 =
+        !effectiveEndDate ||
+        !conflictingBom.effectivityStartDate ||
+        effectiveEndDate >= conflictingBom.effectivityStartDate;
+
+      if (hasOverlap && hasOverlap2) {
+        return err(new AmbiguousEffectivityRuleError(id));
+      }
+    }
+  }
+
+  // 5. Build update set for BOM header
+  const updateSet: Record<string, unknown> = {
+    ...customFields,
+    updatedAt: new Date(),
+  };
+
+  if (bomType !== undefined) updateSet.bomType = bomType;
+  if (effectivityStartDate !== undefined) updateSet.effectivityStartDate = effectivityStartDate;
+  if (effectivityEndDate !== undefined) updateSet.effectivityEndDate = effectivityEndDate;
+  if (defaultSelection !== undefined) updateSet.defaultSelection = defaultSelection;
+  if (revisionNumber !== undefined) updateSet.revisionNumber = revisionNumber;
+
+  // 6. Persist BOM header changes
+  const updatedBom = await db
+    .updateTable("BillOfMaterial")
+    .set(updateSet)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // 7. Replace lines if provided (delete old, insert new)
+  if (lines) {
+    await db.deleteFrom("BillOfMaterialLine").where("billOfMaterialId", "=", id).execute();
+
+    for (const line of lines) {
+      await db
+        .insertInto("BillOfMaterialLine")
+        .values({
+          billOfMaterialId: id,
+          itemId: line.itemId,
+          requiredQuantity: line.requiredQuantity,
+          unitOfMeasure: line.unitOfMeasure ?? null,
+          scrapAssumption: line.scrapAssumption ?? null,
+          isSubassembly: line.isSubassembly ?? null,
+          createdAt: new Date(),
+          updatedAt: null,
+        })
+        .returningAll()
+        .executeTakeFirst();
+    }
+  }
+
+  return ok({ billOfMaterial: updatedBom });
+}

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

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

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

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotMutableError,
+  InvalidPlannedQuantityError,
+  ImmutableScopeFieldError,
+  CrossScopeMasterReferenceError,
+} from "../lib/errors.generated";
+import {
+  baseDraftProductionOrder,
+  baseReleasedProductionOrder,
+  baseActiveBom,
+} from "../testing/fixtures";
+import { run } from "./updateProductionOrder";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("updateProductionOrder", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:updateProductionOrder"],
+  };
+
+  it("updates draft planning fields on a production order", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updated = { ...baseDraftProductionOrder, plannedQuantity: 200 };
+
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+    spies.update.mockReturnValue(updated);
+
+    const result = await run(db, { id: baseDraftProductionOrder.id, plannedQuantity: 200 }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.productionOrder.plannedQuantity).toBe(200);
+    }
+    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 DRAFT", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+
+    const result = await run(db, { id: baseReleasedProductionOrder.id, plannedQuantity: 200 }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductionOrderNotMutableError);
+    }
+  });
+
+  it("returns error when planned quantity is not positive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+
+    const result = await run(db, { id: baseDraftProductionOrder.id, plannedQuantity: 0 }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidPlannedQuantityError);
+    }
+  });
+
+  it("returns error when immutable scope identity is changed", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+
+    const result = await run(
+      db,
+      { id: baseDraftProductionOrder.id, orderedItemId: "different-item" },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ImmutableScopeFieldError);
+    }
+  });
+
+  it("returns error when BOM or routing references are out of scope", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const crossScopeBom = { ...baseActiveBom, companyId: "other-company" };
+
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+    // bom lookup
+    spies.select.mockReturnValueOnce(crossScopeBom);
+
+    const result = await run(
+      db,
+      { id: baseDraftProductionOrder.id, selectedBomVersionId: crossScopeBom.id },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CrossScopeMasterReferenceError);
+    }
+  });
+});