@tailor-platform/erp-kit 0.5.0 → 0.6.0

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

@@ -0,0 +1,212 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  WorkOrderNotFoundError,
+  WorkOrderNotCompletableError,
+  WorkOrderNotStartedError,
+  InvalidCompletionQuantityError,
+  DuplicateBackflushRiskError,
+  ReceiptHandoffRequiredError,
+  LotReferenceRequiredError,
+  SerialReferenceRequiredError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ReceiptData {
+  itemReference?: string | null;
+  unitOfMeasure?: string | null;
+  siteReference?: string | null;
+  postingDate?: Date | null;
+  storageLocationReference?: string | null;
+  lotTracked: boolean;
+  serialTracked: boolean;
+  finishedGoodLotReference?: string | null;
+  serialReferences?: string[] | null;
+}
+
+export interface ZeroQuantityBypassPolicy {
+  allowZeroCompletion: boolean;
+  reasonCode?: string | null;
+}
+
+export interface CompleteWorkOrderInput {
+  id: string;
+  completedQuantity: number;
+  zeroQuantityBypassPolicy?: ZeroQuantityBypassPolicy | null;
+  backflushRequired: boolean;
+  manuallyIssuedQuantity?: number;
+  receiptRequired: boolean;
+  receiptData?: ReceiptData | null;
+  notes?: string | null;
+}
+
+/**
+ * Function: completeWorkOrder
+ *
+ * Finishes execution on an in-progress work order. Records the final completed
+ * quantity, validates backflush and receipt-handoff obligations, creates a
+ * COMPLETED execution event, and rolls up completion to the parent production
+ * order when all sibling work orders are finished.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: CompleteWorkOrderInput & CF,
+  _ctx: CommandContext,
+) {
+  const {
+    id,
+    completedQuantity,
+    zeroQuantityBypassPolicy,
+    backflushRequired,
+    manuallyIssuedQuantity,
+    receiptRequired,
+    receiptData,
+    notes,
+    ...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 IN_PROGRESS
+  if (workOrder.status !== "IN_PROGRESS") {
+    return err(new WorkOrderNotCompletableError(id));
+  }
+
+  // 3. Validate actual start evidence exists
+  if (!workOrder.actualStartDate) {
+    return err(new WorkOrderNotStartedError(id));
+  }
+
+  // 4. Validate completed quantity, allowing explicit zero-quantity bypass.
+  const zeroQuantityBypassAllowed =
+    completedQuantity === 0 && zeroQuantityBypassPolicy?.allowZeroCompletion === true;
+  if (completedQuantity < 0 || (completedQuantity === 0 && !zeroQuantityBypassAllowed)) {
+    return err(new InvalidCompletionQuantityError(id));
+  }
+
+  // 5. Validate backflush does not duplicate manual issue
+  if (backflushRequired && manuallyIssuedQuantity != null && manuallyIssuedQuantity > 0) {
+    return err(new DuplicateBackflushRiskError(id));
+  }
+
+  // 6. Validate receipt handoff data when receipt is required
+  if (receiptRequired) {
+    if (!receiptData) {
+      return err(new ReceiptHandoffRequiredError(id));
+    }
+
+    if (
+      !receiptData.itemReference ||
+      !receiptData.unitOfMeasure ||
+      !receiptData.siteReference ||
+      !receiptData.postingDate
+    ) {
+      return err(new ReceiptHandoffRequiredError(id));
+    }
+
+    if (receiptData.lotTracked && !receiptData.finishedGoodLotReference) {
+      return err(new LotReferenceRequiredError(id));
+    }
+
+    if (
+      receiptData.serialTracked &&
+      (!receiptData.serialReferences || receiptData.serialReferences.length === 0)
+    ) {
+      return err(new SerialReferenceRequiredError(id));
+    }
+  }
+
+  // 7. Update work order to COMPLETE
+  const now = new Date();
+  const updatedWorkOrder = await db
+    .updateTable("WorkOrder")
+    .set({
+      status: "COMPLETE",
+      completedQuantity: workOrder.completedQuantity + completedQuantity,
+      executionNotes: notes ?? workOrder.executionNotes,
+      updatedAt: now,
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // 8. Create COMPLETED execution event
+  await db
+    .insertInto("WorkOrderExecutionEvent")
+    .values({
+      workOrderId: id,
+      eventType: "COMPLETED",
+      timestamp: now,
+      quantity: completedQuantity,
+      timeValue: null,
+      scrapValue: null,
+      notes: notes ?? null,
+      createdAt: now,
+      updatedAt: null,
+    })
+    .execute();
+
+  const backflushHandoff = backflushRequired
+    ? {
+        productionOrderReference: workOrder.productionOrderId,
+        workOrderReference: id,
+        completedQuantity,
+        manuallyIssuedQuantity: manuallyIssuedQuantity ?? 0,
+        postingDate: receiptData?.postingDate ?? now,
+        bypassReason: zeroQuantityBypassAllowed
+          ? (zeroQuantityBypassPolicy?.reasonCode ?? null)
+          : null,
+      }
+    : null;
+
+  const receiptHandoff =
+    receiptRequired && receiptData
+      ? {
+          productionOrderReference: workOrder.productionOrderId,
+          workOrderReference: id,
+          itemReference: receiptData.itemReference,
+          quantity: completedQuantity,
+          unitOfMeasure: receiptData.unitOfMeasure,
+          siteReference: receiptData.siteReference,
+          postingDate: receiptData.postingDate,
+          storageLocationReference: receiptData.storageLocationReference ?? null,
+          finishedGoodLotReference: receiptData.finishedGoodLotReference ?? null,
+          serialReferences: receiptData.serialReferences ?? null,
+        }
+      : null;
+
+  // 9. Roll up to parent production order
+  const siblingWorkOrders = await db
+    .selectFrom("WorkOrder")
+    .selectAll()
+    .where("productionOrderId", "=", workOrder.productionOrderId)
+    .execute();
+
+  const allComplete = (siblingWorkOrders as { id: string; status: string }[]).every((wo) => {
+    if (wo.id === id) return true; // this one was just completed
+    return wo.status === "COMPLETE" || wo.status === "CANCELLED";
+  });
+
+  if (allComplete) {
+    await db
+      .updateTable("ProductionOrder")
+      .set({
+        status: "COMPLETED",
+        updatedAt: now,
+      })
+      .where("id", "=", workOrder.productionOrderId)
+      .execute();
+  }
+
+  return ok({ workOrder: updatedWorkOrder, backflushHandoff, receiptHandoff });
+}

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

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

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

@@ -0,0 +1,210 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ParentItemNotFoundError,
+  ParentItemNotManufacturedError,
+  InvalidBomTypeError,
+  ComponentLineRequiredError,
+  InvalidComponentQuantityError,
+  ComponentItemInactiveError,
+  BomVersionConflictError,
+} from "../lib/errors.generated";
+import { baseDraftBom, baseBomLine } from "../testing/fixtures";
+import { run } from "./createBillOfMaterial";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("createBillOfMaterial", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:createBillOfMaterial"],
+  };
+
+  const validInput = {
+    parentItemId: "item-1",
+    companyId: "company-1",
+    siteId: null,
+    bomType: "MANUFACTURE",
+    effectivityStartDate: null,
+    effectivityEndDate: null,
+    defaultSelection: true,
+    revisionNumber: "V1",
+    lines: [
+      {
+        itemId: "item-2",
+        requiredQuantity: 2.0,
+        unitOfMeasure: "EA",
+        scrapAssumption: 5.0,
+        isSubassembly: false,
+      },
+    ],
+  };
+
+  it("creates a draft BOM for an active manufactured item", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdBom = {
+      ...baseDraftBom,
+      id: "new-bom-id",
+    };
+
+    // parent item exists
+    spies.select.mockReturnValueOnce({ id: "item-1", status: "ACTIVE", isManufacturable: true });
+    // component item exists
+    spies.select.mockReturnValueOnce({ id: "item-2", status: "ACTIVE" });
+    // no existing BOM with same version identity
+    spies.select.mockReturnValueOnce(undefined);
+    // insert BOM
+    spies.insert.mockReturnValueOnce(createdBom);
+    // insert BOM line
+    spies.insert.mockReturnValueOnce({ ...baseBomLine, billOfMaterialId: "new-bom-id" });
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.billOfMaterial.status).toBe("DRAFT");
+      expect(result.value.billOfMaterial.id).toBe("new-bom-id");
+    }
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("returns error when the parent item does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // parent item not found
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentItemNotFoundError);
+    }
+  });
+
+  it("returns error when the parent item is not manufacturable", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // parent item exists but not manufacturable
+    spies.select.mockReturnValueOnce({ id: "item-1", status: "ACTIVE", isManufacturable: false });
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentItemNotManufacturedError);
+    }
+  });
+
+  it("returns error when bomType is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // parent item exists
+    spies.select.mockReturnValueOnce({ id: "item-1", status: "ACTIVE", isManufacturable: true });
+
+    const result = await run(db, { ...validInput, bomType: "UNSUPPORTED" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidBomTypeError);
+    }
+  });
+
+  it("returns error when no component lines are provided", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // parent item exists
+    spies.select.mockReturnValueOnce({ id: "item-1", status: "ACTIVE", isManufacturable: true });
+
+    const result = await run(db, { ...validInput, lines: [] }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ComponentLineRequiredError);
+    }
+  });
+
+  it("returns error when a component quantity is not positive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // parent item exists
+    spies.select.mockReturnValueOnce({ id: "item-1", status: "ACTIVE", isManufacturable: true });
+
+    const result = await run(
+      db,
+      {
+        ...validInput,
+        lines: [{ itemId: "item-2", requiredQuantity: 0, unitOfMeasure: "EA" }],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidComponentQuantityError);
+    }
+  });
+
+  it("returns error when a component item is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // parent item exists
+    spies.select.mockReturnValueOnce({ id: "item-1", status: "ACTIVE", isManufacturable: true });
+    // component item not found (treated as 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 a component item exists but is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // parent item exists
+    spies.select.mockReturnValueOnce({ id: "item-1", status: "ACTIVE", isManufacturable: true });
+    // component item exists but is inactive
+    spies.select.mockReturnValueOnce({ id: "item-2", isActive: false });
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ComponentItemInactiveError);
+    }
+  });
+
+  it("returns error when the version identity already exists in scope", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // parent item exists
+    spies.select.mockReturnValueOnce({ id: "item-1", status: "ACTIVE", isManufacturable: true });
+    // component item exists
+    spies.select.mockReturnValueOnce({ id: "item-2", status: "ACTIVE" });
+    // existing BOM with same version identity
+    spies.select.mockReturnValueOnce(baseDraftBom);
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(BomVersionConflictError);
+    }
+  });
+
+  it("returns error when the parent item is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce({ id: "item-1", status: "INACTIVE", isManufacturable: true });
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentItemNotManufacturedError);
+    }
+  });
+});

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

@@ -0,0 +1,176 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ParentItemNotFoundError,
+  ParentItemNotManufacturedError,
+  InvalidBomTypeError,
+  ComponentLineRequiredError,
+  InvalidComponentQuantityError,
+  ComponentItemInactiveError,
+  BomVersionConflictError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+const VALID_BOM_TYPES = ["MANUFACTURE", "PHANTOM", "KIT"] as const;
+
+export interface CreateBillOfMaterialLineInput {
+  itemId: string;
+  requiredQuantity: number;
+  unitOfMeasure?: string | null;
+  scrapAssumption?: number | null;
+  isSubassembly?: boolean | null;
+}
+
+export interface CreateBillOfMaterialInput {
+  parentItemId: string;
+  companyId: string;
+  siteId?: string | null;
+  bomType: string;
+  effectivityStartDate?: Date | null;
+  effectivityEndDate?: Date | null;
+  defaultSelection?: boolean | null;
+  revisionNumber?: string | null;
+  lines: CreateBillOfMaterialLineInput[];
+}
+
+/**
+ * Function: createBillOfMaterial
+ *
+ * Creates a draft BOM version for one manufactured parent item at company or
+ * site scope. Establishes the initial bomType, effectivity window,
+ * default-selection intent, and component-line payload.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: CreateBillOfMaterialInput & CF,
+  _ctx: CommandContext,
+) {
+  const {
+    parentItemId,
+    companyId,
+    siteId,
+    bomType,
+    effectivityStartDate,
+    effectivityEndDate,
+    defaultSelection,
+    revisionNumber,
+    lines,
+    ...customFields
+  } = input;
+
+  // 1. Validate parent item exists
+  const parentItem = await db
+    .selectFrom("Item")
+    .selectAll()
+    .where("id", "=", parentItemId)
+    .executeTakeFirst();
+
+  if (!parentItem) {
+    return err(new ParentItemNotFoundError(parentItemId));
+  }
+
+  // 2. Validate parent item is active and manufacturable.
+  const parentItemRecord = parentItem as Record<string, unknown>;
+  const isInactive =
+    ("status" in parentItemRecord && parentItemRecord.status !== "ACTIVE") ||
+    ("isActive" in parentItemRecord && parentItemRecord.isActive === false);
+  const isNotManufacturable =
+    "isManufacturable" in parentItemRecord && parentItemRecord.isManufacturable === false;
+
+  if (isInactive || isNotManufacturable) {
+    return err(new ParentItemNotManufacturedError(parentItemId));
+  }
+
+  // 3. Validate bomType
+  if (!VALID_BOM_TYPES.includes(bomType as (typeof VALID_BOM_TYPES)[number])) {
+    return err(new InvalidBomTypeError(parentItemId));
+  }
+
+  // 4. Validate at least one component line
+  if (!lines || lines.length === 0) {
+    return err(new ComponentLineRequiredError(parentItemId));
+  }
+
+  // 5. Validate each component line
+  for (const line of lines) {
+    if (line.requiredQuantity <= 0) {
+      return err(new InvalidComponentQuantityError(line.itemId));
+    }
+
+    // Check component item is not inactive (exists in Item table)
+    const componentItem = await db
+      .selectFrom("Item")
+      .selectAll()
+      .where("id", "=", line.itemId)
+      .executeTakeFirst();
+
+    if (!componentItem) {
+      return err(new ComponentItemInactiveError(line.itemId));
+    }
+
+    // Check component item is active
+    if ("isActive" in componentItem && componentItem.isActive === false) {
+      return err(new ComponentItemInactiveError(line.itemId));
+    }
+    if ("status" in componentItem && componentItem.status === "INACTIVE") {
+      return err(new ComponentItemInactiveError(line.itemId));
+    }
+  }
+
+  // 6. Check version identity uniqueness within same parent item and scope
+  const existingBomQuery = db
+    .selectFrom("BillOfMaterial")
+    .selectAll()
+    .where("parentItemId", "=", parentItemId)
+    .where("companyId", "=", companyId);
+
+  const existingBom = await (
+    siteId ? existingBomQuery.where("siteId", "=", siteId) : existingBomQuery
+  )
+    .where("revisionNumber", "=", revisionNumber ?? null)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (existingBom) {
+    return err(new BomVersionConflictError(parentItemId));
+  }
+
+  // 7. Create draft BOM
+  const billOfMaterial = await db
+    .insertInto("BillOfMaterial")
+    .values({
+      ...(customFields as Record<string, unknown>),
+      parentItemId,
+      companyId,
+      siteId: siteId ?? null,
+      bomType: bomType as "MANUFACTURE" | "PHANTOM" | "KIT",
+      effectivityStartDate: effectivityStartDate ?? null,
+      effectivityEndDate: effectivityEndDate ?? null,
+      defaultSelection: defaultSelection ?? null,
+      revisionNumber: revisionNumber ?? null,
+      status: "DRAFT",
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  // 8. Create component lines
+  for (const line of lines) {
+    await db
+      .insertInto("BillOfMaterialLine")
+      .values({
+        billOfMaterialId: billOfMaterial!.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: billOfMaterial! });
+}

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

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