@tailor-platform/erp-kit 0.5.1 → 0.6.0

package/src/modules/manufacturing/query/explodeBillOfMaterial.ts

@@ -0,0 +1,306 @@
+import type { DB } from "../generated/kysely-tailordb";
+import {
+  BomReferenceRequiredError,
+  EffectivityDateRequiredError,
+  BomNotFoundError,
+  BomNotEffectiveOnDateError,
+  ChildBomNotResolvedError,
+  BomCircularReferenceDetectedError,
+} from "../lib/errors.generated";
+import { ok, err, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
+
+export interface ExplodeBillOfMaterialInput {
+  bomId: string;
+  effectivityDate: Date;
+}
+
+interface ExplodedComponent {
+  itemId: string;
+  requiredQuantity: number;
+  unitOfMeasure: string | null;
+  depth: number;
+  bomPath: string[];
+  isSubassembly: boolean;
+}
+
+/**
+ * Function: explodeBillOfMaterial
+ *
+ * Expands one BOM revision into recursive component requirements using the
+ * requested effectivity date and site-applicable child BOM scope.
+ */
+export async function run(db: ReadonlyDB<DB>, input: ExplodeBillOfMaterialInput) {
+  if (!input.bomId) {
+    return err(new BomReferenceRequiredError("bomId"));
+  }
+
+  if (!input.effectivityDate) {
+    return err(new EffectivityDateRequiredError("effectivityDate"));
+  }
+
+  const rootBom = await db
+    .selectFrom("BillOfMaterial")
+    .selectAll()
+    .where("id", "=", input.bomId)
+    .executeTakeFirst();
+
+  if (!rootBom) {
+    return err(new BomNotFoundError(input.bomId));
+  }
+
+  if (!isEffectiveOnDate(rootBom, input.effectivityDate)) {
+    return err(new BomNotEffectiveOnDateError(input.bomId));
+  }
+
+  const components: ExplodedComponent[] = [];
+  const visitedItems = new Set<string>();
+
+  const result = await expandBom(
+    db,
+    rootBom.id,
+    rootBom.companyId,
+    rootBom.siteId,
+    rootBom.bomType as string,
+    input.effectivityDate,
+    1, // multiplier
+    0, // depth
+    [rootBom.id],
+    visitedItems,
+    components,
+  );
+
+  if (result) {
+    return result; // error result
+  }
+
+  return ok({ components });
+}
+
+function isEffectiveOnDate(
+  bom: { effectivityStartDate: unknown; effectivityEndDate: unknown },
+  date: Date,
+): boolean {
+  const dateMs = date.getTime();
+
+  if (bom.effectivityStartDate) {
+    const start = new Date(bom.effectivityStartDate as string);
+    if (dateMs < start.getTime()) {
+      return false;
+    }
+  }
+
+  if (bom.effectivityEndDate) {
+    const end = new Date(bom.effectivityEndDate as string);
+    if (dateMs > end.getTime()) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function resolveApplicableChildBom(
+  childBoms: {
+    id: string;
+    siteId?: string | null;
+    bomType: string;
+    effectivityStartDate: unknown;
+    effectivityEndDate: unknown;
+  }[],
+  effectivityDate: Date,
+  applicableSiteId: string | null,
+) {
+  const effectiveBoms = childBoms.filter((bom) => {
+    if (!isEffectiveOnDate(bom, effectivityDate)) {
+      return false;
+    }
+
+    if (applicableSiteId == null) {
+      return bom.siteId == null;
+    }
+
+    return bom.siteId == null || bom.siteId === applicableSiteId;
+  });
+
+  return (
+    effectiveBoms.find((bom) => bom.siteId === applicableSiteId) ??
+    effectiveBoms.find((bom) => bom.siteId == null)
+  );
+}
+
+async function expandBom(
+  db: ReadonlyDB<DB>,
+  bomId: string,
+  companyId: string,
+  applicableSiteId: string | null,
+  bomType: string,
+  effectivityDate: Date,
+  parentQuantityMultiplier: number,
+  depth: number,
+  bomPath: string[],
+  visitedItems: Set<string>,
+  components: ExplodedComponent[],
+): Promise<{ ok: false; error: Error } | undefined> {
+  const lines = await db
+    .selectFrom("BillOfMaterialLine")
+    .selectAll()
+    .where("billOfMaterialId", "=", bomId)
+    .execute();
+
+  for (const line of lines) {
+    const requiredQuantity = line.requiredQuantity * parentQuantityMultiplier;
+    const isSubassembly = line.isSubassembly === true;
+
+    // KIT: issue-only component demand — no recursive expansion
+    if (bomType === "KIT") {
+      components.push({
+        itemId: line.itemId,
+        requiredQuantity,
+        unitOfMeasure: line.unitOfMeasure,
+        depth: depth + 1,
+        bomPath: [...bomPath],
+        isSubassembly: false, // KIT components are always issue-only
+      });
+      continue;
+    }
+
+    // PHANTOM: flatten lines into parent path
+    if (bomType === "PHANTOM") {
+      if (isSubassembly) {
+        // Resolve child BOM and expand at SAME depth (no depth increment)
+        if (visitedItems.has(line.itemId)) {
+          return err(new BomCircularReferenceDetectedError(line.itemId));
+        }
+        visitedItems.add(line.itemId);
+
+        const childBoms = await db
+          .selectFrom("BillOfMaterial")
+          .selectAll()
+          .where("parentItemId", "=", line.itemId)
+          .where("companyId", "=", companyId)
+          .where("status", "=", "ACTIVE")
+          .execute();
+        const effectiveChildBom = resolveApplicableChildBom(
+          childBoms,
+          effectivityDate,
+          applicableSiteId,
+        );
+        if (!effectiveChildBom) {
+          return err(new ChildBomNotResolvedError(line.itemId));
+        }
+
+        const childResult = await expandBom(
+          db,
+          effectiveChildBom.id,
+          companyId,
+          applicableSiteId,
+          effectiveChildBom.bomType,
+          effectivityDate,
+          requiredQuantity,
+          depth, // same depth — flattening
+          [...bomPath, effectiveChildBom.id],
+          visitedItems,
+          components,
+        );
+        if (childResult) return childResult;
+        visitedItems.delete(line.itemId);
+      } else {
+        // Non-subassembly in phantom: push at current depth (flattened)
+        components.push({
+          itemId: line.itemId,
+          requiredQuantity,
+          unitOfMeasure: line.unitOfMeasure,
+          depth: depth + 1,
+          bomPath: [...bomPath],
+          isSubassembly: false,
+        });
+      }
+      continue;
+    }
+
+    // MANUFACTURE (default): add the component and recurse if subassembly
+    if (isSubassembly) {
+      if (visitedItems.has(line.itemId)) {
+        return err(new BomCircularReferenceDetectedError(line.itemId));
+      }
+      visitedItems.add(line.itemId);
+
+      // Find an active child BOM for this item effective on the date
+      const childBoms = await db
+        .selectFrom("BillOfMaterial")
+        .selectAll()
+        .where("parentItemId", "=", line.itemId)
+        .where("companyId", "=", companyId)
+        .where("status", "=", "ACTIVE")
+        .execute();
+
+      const effectiveChildBom = resolveApplicableChildBom(
+        childBoms,
+        effectivityDate,
+        applicableSiteId,
+      );
+
+      if (!effectiveChildBom) {
+        return err(new ChildBomNotResolvedError(line.itemId));
+      }
+
+      const childBomType = effectiveChildBom.bomType;
+
+      if (childBomType === "PHANTOM") {
+        // PHANTOM child: skip the phantom item, flatten its children to current depth
+        const childResult = await expandBom(
+          db,
+          effectiveChildBom.id,
+          companyId,
+          applicableSiteId,
+          childBomType,
+          effectivityDate,
+          requiredQuantity,
+          depth, // same depth — flattening
+          [...bomPath, effectiveChildBom.id],
+          visitedItems,
+          components,
+        );
+        if (childResult) return childResult;
+      } else {
+        // Non-phantom child: push the subassembly and recurse deeper
+        components.push({
+          itemId: line.itemId,
+          requiredQuantity,
+          unitOfMeasure: line.unitOfMeasure,
+          depth: depth + 1,
+          bomPath: [...bomPath],
+          isSubassembly: true,
+        });
+
+        const childResult = await expandBom(
+          db,
+          effectiveChildBom.id,
+          companyId,
+          applicableSiteId,
+          childBomType,
+          effectivityDate,
+          requiredQuantity,
+          depth + 1,
+          [...bomPath, effectiveChildBom.id],
+          visitedItems,
+          components,
+        );
+        if (childResult) return childResult;
+      }
+
+      visitedItems.delete(line.itemId);
+    } else {
+      components.push({
+        itemId: line.itemId,
+        requiredQuantity,
+        unitOfMeasure: line.unitOfMeasure,
+        depth: depth + 1,
+        bomPath: [...bomPath],
+        isSubassembly: false,
+      });
+    }
+  }
+
+  return undefined; // success, no error
+}

package/src/modules/manufacturing/query/getBillOfMaterial.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getBillOfMaterial";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getBillOfMaterial = defineQuery(run);

package/src/modules/manufacturing/query/getBillOfMaterial.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import {
+  baseDraftBom,
+  baseActiveBom,
+  baseInactiveBom,
+  baseBomLine,
+  baseBomLine2,
+} from "../testing/fixtures";
+import { expectOk, expectErr } from "../testing/commandTestUtils";
+import { BomNotFoundError } from "../lib/errors.generated";
+import { run } from "./getBillOfMaterial";
+
+describe("getBillOfMaterial", () => {
+  it("returns a BOM with component lines when found", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseActiveBom);
+    spies.select.mockReturnValueOnce([baseBomLine, baseBomLine2]);
+
+    const result = await run(db, { id: baseActiveBom.id });
+    const { billOfMaterial, lines } = expectOk<{
+      billOfMaterial: unknown;
+      lines: unknown[];
+    }>(result as never);
+
+    expect(billOfMaterial).toMatchObject({ id: baseActiveBom.id });
+    expect(lines).toHaveLength(2);
+  });
+
+  it("returns draft BOM versions when requested", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseDraftBom);
+    spies.select.mockReturnValueOnce([baseBomLine]);
+
+    const result = await run(db, { id: baseDraftBom.id });
+    const { billOfMaterial } = expectOk<{
+      billOfMaterial: { status: string };
+    }>(result as never);
+
+    expect(billOfMaterial.status).toBe("DRAFT");
+  });
+
+  it("returns inactive BOM versions when requested", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseInactiveBom);
+    spies.select.mockReturnValueOnce([]);
+
+    const result = await run(db, { id: baseInactiveBom.id });
+    const { billOfMaterial } = expectOk<{
+      billOfMaterial: { status: string };
+    }>(result as never);
+
+    expect(billOfMaterial.status).toBe("INACTIVE");
+  });
+
+  it("returns error when the BOM does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent-id" });
+    expectErr(result as never, BomNotFoundError);
+  });
+});

package/src/modules/manufacturing/query/getBillOfMaterial.ts

@@ -0,0 +1,27 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { BomNotFoundError } from "../lib/errors.generated";
+import { ok, err, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
+
+export interface GetBillOfMaterialInput {
+  id: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: GetBillOfMaterialInput) {
+  const billOfMaterial = await db
+    .selectFrom("BillOfMaterial")
+    .selectAll()
+    .where("id", "=", input.id)
+    .executeTakeFirst();
+
+  if (!billOfMaterial) {
+    return err(new BomNotFoundError(input.id));
+  }
+
+  const lines = await db
+    .selectFrom("BillOfMaterialLine")
+    .selectAll()
+    .where("billOfMaterialId", "=", billOfMaterial.id)
+    .execute();
+
+  return ok({ billOfMaterial, lines });
+}

package/src/modules/manufacturing/query/getManufacturingCostSummary.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getManufacturingCostSummary";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getManufacturingCostSummary = defineQuery(run);

package/src/modules/manufacturing/query/getManufacturingCostSummary.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { expectOk, expectErr } from "../testing/commandTestUtils";
+import {
+  baseCollectingCostSummary,
+  baseReviewedCostSummary,
+  baseSettledCostSummary,
+  baseCostLine,
+  baseVarianceLine,
+  baseSettlementRecord,
+} from "../testing/fixtures";
+import { CostSummaryNotFoundError } from "../lib/errors.generated";
+import { run } from "./getManufacturingCostSummary";
+
+describe("getManufacturingCostSummary", () => {
+  it("returns a collecting cost summary with planned and actual totals", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const costLine = { ...baseCostLine, costSummaryId: "cost-summary-1" };
+    // 1st select: costSummary
+    spies.select.mockReturnValueOnce(baseCollectingCostSummary);
+    // 2nd select: costLines
+    spies.select.mockReturnValueOnce([costLine]);
+    // 3rd select: varianceLines
+    spies.select.mockReturnValueOnce([]);
+    // 4th select: settlementRecords
+    spies.select.mockReturnValueOnce([]);
+
+    const result = await run(db, { id: "cost-summary-1" });
+    const { costSummary, costLines } = expectOk<{
+      costSummary: {
+        status: string;
+        plannedMaterialCost: number;
+        actualMaterialCost: number;
+      };
+      costLines: unknown[];
+      varianceLines: unknown[];
+      settlementRecords: unknown[];
+    }>(result as never);
+
+    expect(costSummary.status).toBe("COLLECTING");
+    expect(costSummary.plannedMaterialCost).toBe(2000);
+    expect(costSummary.actualMaterialCost).toBe(0);
+    expect(costLines).toHaveLength(1);
+  });
+
+  it("returns a reviewed cost summary with variance lines", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const varianceLine = {
+      ...baseVarianceLine,
+      costSummaryId: "cost-summary-3",
+    };
+    // 1st select: costSummary
+    spies.select.mockReturnValueOnce(baseReviewedCostSummary);
+    // 2nd select: costLines
+    spies.select.mockReturnValueOnce([]);
+    // 3rd select: varianceLines
+    spies.select.mockReturnValueOnce([varianceLine]);
+    // 4th select: settlementRecords
+    spies.select.mockReturnValueOnce([]);
+
+    const result = await run(db, { id: "cost-summary-3" });
+    const { costSummary, varianceLines } = expectOk<{
+      costSummary: { status: string; reviewedDate: Date | null };
+      costLines: unknown[];
+      varianceLines: { varianceType: string; amount: number }[];
+      settlementRecords: unknown[];
+    }>(result as never);
+
+    expect(costSummary.status).toBe("VARIANCE_REVIEWED");
+    expect(costSummary.reviewedDate).toEqual(new Date("2024-04-01T00:00:00.000Z"));
+    expect(varianceLines).toHaveLength(1);
+    expect(varianceLines[0].varianceType).toBe("MATERIAL_PRICE");
+    expect(varianceLines[0].amount).toBe(100);
+  });
+
+  it("returns a settled cost summary with acknowledgment traceability", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const settlement = {
+      ...baseSettlementRecord,
+      costSummaryId: "cost-summary-4",
+    };
+    // 1st select: costSummary
+    spies.select.mockReturnValueOnce(baseSettledCostSummary);
+    // 2nd select: costLines
+    spies.select.mockReturnValueOnce([]);
+    // 3rd select: varianceLines
+    spies.select.mockReturnValueOnce([]);
+    // 4th select: settlementRecords
+    spies.select.mockReturnValueOnce([settlement]);
+
+    const result = await run(db, { id: "cost-summary-4" });
+    const { costSummary, settlementRecords } = expectOk<{
+      costSummary: { status: string };
+      costLines: unknown[];
+      varianceLines: unknown[];
+      settlementRecords: {
+        settlementReference: string;
+        acknowledgedDate: Date;
+      }[];
+    }>(result as never);
+
+    expect(costSummary.status).toBe("SETTLED");
+    expect(settlementRecords).toHaveLength(1);
+    expect(settlementRecords[0].settlementReference).toBe("SETTLE-2024-001");
+    expect(settlementRecords[0].acknowledgedDate).toEqual(new Date("2024-04-15T00:00:00.000Z"));
+  });
+
+  it("returns variance lines with downstream account references", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const varianceLine = {
+      ...baseVarianceLine,
+      costSummaryId: "cost-summary-3",
+    };
+    // 1st select: costSummary
+    spies.select.mockReturnValueOnce(baseReviewedCostSummary);
+    // 2nd select: costLines
+    spies.select.mockReturnValueOnce([]);
+    // 3rd select: varianceLines
+    spies.select.mockReturnValueOnce([varianceLine]);
+    // 4th select: settlementRecords
+    spies.select.mockReturnValueOnce([]);
+
+    const result = await run(db, { id: "cost-summary-3" });
+    const { varianceLines } = expectOk<{
+      costSummary: unknown;
+      costLines: unknown[];
+      varianceLines: {
+        accountReference: string;
+        variancePercentage: number;
+      }[];
+      settlementRecords: unknown[];
+    }>(result as never);
+
+    expect(varianceLines[0].accountReference).toBe("acct-5001");
+    expect(varianceLines[0].variancePercentage).toBe(5.0);
+  });
+
+  it("returns error when the cost summary does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    // 1st select: costSummary returns undefined
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent-id" });
+    expectErr(result as never, CostSummaryNotFoundError);
+  });
+});

package/src/modules/manufacturing/query/getManufacturingCostSummary.ts

@@ -0,0 +1,46 @@
+import type { DB } from "../generated/kysely-tailordb";
+import { CostSummaryNotFoundError } from "../lib/errors.generated";
+import { ok, err, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
+
+export interface GetManufacturingCostSummaryInput {
+  id?: string;
+  productionOrderId?: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: GetManufacturingCostSummaryInput) {
+  let query = db.selectFrom("ManufacturingCostSummary").selectAll();
+
+  if (input.id) {
+    query = query.where("id", "=", input.id);
+  } else if (input.productionOrderId) {
+    query = query.where("productionOrderId", "=", input.productionOrderId);
+  } else {
+    return err(new CostSummaryNotFoundError("no id or productionOrderId provided"));
+  }
+
+  const costSummary = await query.executeTakeFirst();
+
+  if (!costSummary) {
+    return err(new CostSummaryNotFoundError(input.id ?? input.productionOrderId ?? "unknown"));
+  }
+
+  const costLines = await db
+    .selectFrom("ManufacturingCostLine")
+    .selectAll()
+    .where("costSummaryId", "=", costSummary.id)
+    .execute();
+
+  const varianceLines = await db
+    .selectFrom("CostVarianceLine")
+    .selectAll()
+    .where("costSummaryId", "=", costSummary.id)
+    .execute();
+
+  const settlementRecords = await db
+    .selectFrom("ManufacturingCostSettlementRecord")
+    .selectAll()
+    .where("costSummaryId", "=", costSummary.id)
+    .execute();
+
+  return ok({ costSummary, costLines, varianceLines, settlementRecords });
+}

package/src/modules/manufacturing/query/getProductionOrder.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { run } from "./getProductionOrder";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+
+export const getProductionOrder = defineQuery(run);