@tailor-platform/erp-kit 0.5.0 → 0.6.0

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

@@ -0,0 +1,139 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  CostSummaryNotFoundError,
+  CostSummaryNotCollectingError,
+  MissingInventoryIssueReferenceError,
+  MissingActualUnitCostError,
+  MissingActualExtendedCostError,
+  MissingPostingDateError,
+  IssueOutcomeNotFinalError,
+  DuplicateIssueOutcomeError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface RecordInventoryIssueOutcomeInput {
+  productionOrderId: string;
+  inventoryIssueReference: string;
+  itemReference: string;
+  issuedQuantity: number;
+  unitOfMeasure: string;
+  actualUnitCost: number;
+  actualExtendedCost: number;
+  currency: string;
+  valuationMethod: string;
+  postingDate: string;
+  siteReference: string;
+  isFinalValuation: boolean;
+}
+
+/**
+ * Function: recordInventoryIssueOutcome
+ *
+ * Applies one inventory-owned valuation outcome to the manufacturing cost
+ * summary for a production order. It is the only valid path for actual
+ * material cost to enter manufacturing.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: RecordInventoryIssueOutcomeInput & CF,
+  _ctx: CommandContext,
+) {
+  const {
+    productionOrderId,
+    inventoryIssueReference,
+    actualUnitCost,
+    actualExtendedCost,
+    postingDate,
+    isFinalValuation,
+    ...customFields
+  } = input;
+  void customFields;
+
+  // 1. Validate required payload fields
+  if (!inventoryIssueReference) {
+    return err(new MissingInventoryIssueReferenceError(productionOrderId));
+  }
+  if (actualUnitCost == null) {
+    return err(new MissingActualUnitCostError(productionOrderId));
+  }
+  if (actualExtendedCost == null) {
+    return err(new MissingActualExtendedCostError(productionOrderId));
+  }
+  if (!postingDate) {
+    return err(new MissingPostingDateError(productionOrderId));
+  }
+
+  // 2. Resolve production order
+  const productionOrder = await db
+    .selectFrom("ProductionOrder")
+    .selectAll()
+    .where("id", "=", productionOrderId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!productionOrder) {
+    return err(new ProductionOrderNotFoundError(productionOrderId));
+  }
+
+  // 3. Resolve cost summary
+  const costSummary = await db
+    .selectFrom("ManufacturingCostSummary")
+    .selectAll()
+    .where("productionOrderId", "=", productionOrderId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!costSummary) {
+    return err(new CostSummaryNotFoundError(productionOrderId));
+  }
+
+  // 4. Summary must be COLLECTING
+  if (costSummary.status !== "COLLECTING") {
+    return err(new CostSummaryNotCollectingError(productionOrderId));
+  }
+
+  // 5. Inventory valuation must be final
+  if (!isFinalValuation) {
+    return err(new IssueOutcomeNotFinalError(productionOrderId));
+  }
+
+  // 6. Check for duplicate application
+  const existingCostLine = await db
+    .selectFrom("ManufacturingCostLine")
+    .selectAll()
+    .where("costSummaryId", "=", costSummary.id)
+    .where("costType", "=", `MATERIAL:${inventoryIssueReference}`)
+    .executeTakeFirst();
+
+  if (existingCostLine) {
+    return err(new DuplicateIssueOutcomeError(productionOrderId));
+  }
+
+  // 7. Create a manufacturing cost line for this issue outcome
+  await db
+    .insertInto("ManufacturingCostLine")
+    .values({
+      costSummaryId: costSummary.id,
+      costType: `MATERIAL:${inventoryIssueReference}`,
+      plannedAmount: 0,
+      actualAmount: actualExtendedCost,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  // 8. Update the cost summary's actual material cost
+  const updatedSummary = await db
+    .updateTable("ManufacturingCostSummary")
+    .set({
+      actualMaterialCost: costSummary.actualMaterialCost + actualExtendedCost,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", costSummary.id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ costSummary: updatedSummary! });
+}

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

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

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

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CostSummaryNotFoundError,
+  CostSummaryNotSettlableError,
+  AcknowledgmentMismatchError,
+  AcknowledgmentRejectedOrSupersededError,
+  AcknowledgmentSourceInvalidError,
+} from "../lib/errors.generated";
+import { baseReviewedCostSummary, basePendingReviewCostSummary } from "../testing/fixtures";
+import { run } from "./recordManufacturingCostSettlementAcknowledgment";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("recordManufacturingCostSettlementAcknowledgment", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:recordManufacturingCostSettlementAcknowledgment"],
+  };
+
+  const validInput = {
+    costSummaryId: "cost-summary-3",
+    productionOrderId: "production-order-2",
+    currencyCode: "USD",
+    settlementReference: "SETTLE-2024-001",
+    settlementDate: "2024-04-15",
+    acknowledgedDate: "2024-04-15",
+    acknowledgmentStatus: "ACCEPTED",
+    acknowledgmentSource: "downstream-accounting-system",
+  };
+
+  it("records a valid downstream settlement acknowledgment and settles the summary", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseReviewedCostSummary);
+
+    const settledSummary = {
+      ...baseReviewedCostSummary,
+      status: "SETTLED",
+    };
+    spies.insert.mockReturnValue({});
+    spies.update.mockReturnValue(settledSummary);
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.costSummary.status).toBe("SETTLED");
+    }
+    expect(spies.insert).toHaveBeenCalled();
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("returns error when the summary 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(CostSummaryNotFoundError);
+    }
+  });
+
+  it("returns error when the summary is not variance reviewed", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(basePendingReviewCostSummary); // PENDING_VARIANCE_REVIEW
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CostSummaryNotSettlableError);
+    }
+  });
+
+  it("returns error when the payload does not match the reviewed handoff", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseReviewedCostSummary);
+
+    const result = await run(
+      db,
+      { ...validInput, currencyCode: "EUR" }, // mismatch
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AcknowledgmentMismatchError);
+    }
+  });
+
+  it("returns error when downstream accounting rejects, reverses, or supersedes the reviewed handoff", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseReviewedCostSummary);
+
+    const result = await run(db, { ...validInput, acknowledgmentStatus: "REJECTED" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AcknowledgmentRejectedOrSupersededError);
+    }
+  });
+
+  it("returns error when the acknowledgment source is invalid", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, { ...validInput, acknowledgmentSource: null }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AcknowledgmentSourceInvalidError);
+    }
+  });
+});

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

@@ -0,0 +1,110 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CostSummaryNotFoundError,
+  CostSummaryNotSettlableError,
+  AcknowledgmentMismatchError,
+  AcknowledgmentRejectedOrSupersededError,
+  AcknowledgmentSourceInvalidError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface RecordManufacturingCostSettlementAcknowledgmentInput {
+  costSummaryId: string;
+  productionOrderId: string;
+  currencyCode: string;
+  settlementReference: string;
+  settlementDate: string;
+  acknowledgedDate?: string | null;
+  acknowledgmentStatus?: string | null;
+  acknowledgmentSource?: string | null;
+}
+
+/**
+ * Function: recordManufacturingCostSettlementAcknowledgment
+ *
+ * Persists the downstream accounting acknowledgment that a reviewed
+ * manufacturing cost handoff has been consumed by settlement processing.
+ * It is the only path that moves a reviewed summary to SETTLED.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: RecordManufacturingCostSettlementAcknowledgmentInput & CF,
+  _ctx: CommandContext,
+) {
+  const {
+    costSummaryId,
+    productionOrderId,
+    currencyCode,
+    settlementReference,
+    settlementDate,
+    acknowledgedDate,
+    acknowledgmentStatus,
+    acknowledgmentSource,
+  } = input;
+
+  // 1. Validate acknowledgment source
+  if (!acknowledgmentSource) {
+    return err(new AcknowledgmentSourceInvalidError(costSummaryId));
+  }
+
+  // 2. Resolve cost summary
+  const costSummary = await db
+    .selectFrom("ManufacturingCostSummary")
+    .selectAll()
+    .where("id", "=", costSummaryId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!costSummary) {
+    return err(new CostSummaryNotFoundError(costSummaryId));
+  }
+
+  // 3. Summary must be VARIANCE_REVIEWED
+  if (costSummary.status !== "VARIANCE_REVIEWED") {
+    return err(new CostSummaryNotSettlableError(costSummaryId));
+  }
+
+  // 4. Validate payload matches the reviewed summary's identity and currency
+  if (
+    costSummary.productionOrderId !== productionOrderId ||
+    costSummary.currencyCode !== currencyCode
+  ) {
+    return err(new AcknowledgmentMismatchError(costSummaryId));
+  }
+
+  // 5. Check that downstream accounting accepted (not rejected/reversed/superseded)
+  if (
+    acknowledgmentStatus === "REJECTED" ||
+    acknowledgmentStatus === "REVERSED" ||
+    acknowledgmentStatus === "SUPERSEDED"
+  ) {
+    return err(new AcknowledgmentRejectedOrSupersededError(costSummaryId));
+  }
+
+  // 6. Create settlement record
+  await db
+    .insertInto("ManufacturingCostSettlementRecord")
+    .values({
+      costSummaryId: costSummary.id,
+      settlementDate: new Date(settlementDate),
+      settlementReference,
+      acknowledgedDate: acknowledgedDate ? new Date(acknowledgedDate) : new Date(),
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  // 7. Update summary to SETTLED
+  const updatedSummary = await db
+    .updateTable("ManufacturingCostSummary")
+    .set({
+      status: "SETTLED",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", costSummary.id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ costSummary: updatedSummary! });
+}

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

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

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

@@ -0,0 +1,220 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotReleasableError,
+  BomNotResolvedError,
+  RoutingNotResolvedError,
+  CrossCompanyMasterReferenceError,
+  CrossSiteMasterReferenceError,
+  PlannedMaterialCostUnavailableError,
+} from "../lib/errors.generated";
+import {
+  baseDraftProductionOrder,
+  baseReleasedProductionOrder,
+  baseActiveBom,
+  baseActiveRouting,
+  baseBomLine,
+  baseRoutingOperation,
+  baseActiveWorkCenter,
+} from "../testing/fixtures";
+import { run } from "./releaseProductionOrder";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+const baseReleaseValuation = {
+  id: "item-2",
+  valuationMethod: "AVCO",
+  costPerUnit: 10,
+  currencyCode: "USD",
+  valuationReference: "valuation-1",
+};
+
+describe("releaseProductionOrder", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:releaseProductionOrder"],
+  };
+
+  it("releases a draft order with valid BOM and routing snapshots", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const released = { ...baseDraftProductionOrder, status: "RELEASED" as const };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+    // bom resolution (no selectedBomVersionId, so default resolution)
+    spies.select.mockReturnValueOnce(baseActiveBom);
+    // routing resolution (no selectedRoutingRevisionId, so default resolution)
+    spies.select.mockReturnValueOnce(baseActiveRouting);
+    // BOM lines query
+    spies.select.mockReturnValueOnce([baseBomLine]);
+    // material cost valuation for bomLine itemId
+    spies.select.mockReturnValueOnce(baseReleaseValuation);
+    // routing operations query
+    spies.select.mockReturnValueOnce([baseRoutingOperation]);
+    // work center lookup for operation
+    spies.select.mockReturnValueOnce(baseActiveWorkCenter);
+    // inserts: bom snapshot, routing snapshot, cost baseline, material requirement, work order, cost summary
+    spies.insert.mockReturnValue({});
+    // update: order status
+    spies.update.mockReturnValue(released);
+
+    const result = await run(db, { id: baseDraftProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.productionOrder.status).toBe("RELEASED");
+    }
+    const snapshotValues = spies.values.mock.calls.find(
+      ([values]) =>
+        typeof values === "object" &&
+        values !== null &&
+        "snapshotData" in (values as Record<string, unknown>),
+    )?.[0] as Record<string, unknown> | undefined;
+    expect(snapshotValues?.snapshotData).not.toBeNull();
+  });
+
+  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 }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductionOrderNotReleasableError);
+    }
+  });
+
+  it("returns error when no active BOM can be resolved", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+    // bom resolution returns nothing
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: baseDraftProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(BomNotResolvedError);
+    }
+  });
+
+  it("returns error when no active routing can be resolved", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+    // bom resolution
+    spies.select.mockReturnValueOnce(baseActiveBom);
+    // routing resolution returns nothing
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: baseDraftProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(RoutingNotResolvedError);
+    }
+  });
+
+  it("returns error when BOM or routing belongs to another company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const crossCompanyBom = { ...baseActiveBom, companyId: "other-company" };
+
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+    // bom resolution
+    spies.select.mockReturnValueOnce(crossCompanyBom);
+
+    const result = await run(db, { id: baseDraftProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CrossCompanyMasterReferenceError);
+    }
+  });
+
+  it("returns error when BOM or routing belongs to another site in the same company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const crossSiteBom = { ...baseActiveBom, companyId: "company-1", siteId: "other-site" };
+
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+    // bom resolution
+    spies.select.mockReturnValueOnce(crossSiteBom);
+
+    const result = await run(db, { id: baseDraftProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CrossSiteMasterReferenceError);
+    }
+  });
+
+  it("returns error when inventory valuation for a required component is unavailable", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+    // bom resolution
+    spies.select.mockReturnValueOnce(baseActiveBom);
+    // routing resolution
+    spies.select.mockReturnValueOnce(baseActiveRouting);
+    // BOM lines query
+    spies.select.mockReturnValueOnce([baseBomLine]);
+    // material cost valuation returns nothing
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: baseDraftProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(PlannedMaterialCostUnavailableError);
+    }
+  });
+
+  it("creates work orders and a collecting cost summary at release", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const released = {
+      ...baseDraftProductionOrder,
+      status: "RELEASED" as const,
+      selectedBomVersionId: baseActiveBom.id,
+      selectedRoutingRevisionId: baseActiveRouting.id,
+    };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+    // bom resolution
+    spies.select.mockReturnValueOnce(baseActiveBom);
+    // routing resolution
+    spies.select.mockReturnValueOnce(baseActiveRouting);
+    // BOM lines query
+    spies.select.mockReturnValueOnce([baseBomLine]);
+    // material cost valuation
+    spies.select.mockReturnValueOnce(baseReleaseValuation);
+    // routing operations query
+    spies.select.mockReturnValueOnce([baseRoutingOperation]);
+    // work center lookup
+    spies.select.mockReturnValueOnce(baseActiveWorkCenter);
+    // inserts
+    spies.insert.mockReturnValue({});
+    // update
+    spies.update.mockReturnValue(released);
+
+    const result = await run(db, { id: baseDraftProductionOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    // Verify inserts were called: bom snapshot + routing snapshot + cost baseline +
+    // material requirements + work orders + cost summary
+    expect(spies.insert).toHaveBeenCalled();
+    expect(spies.update).toHaveBeenCalled();
+  });
+});