@tailor-platform/erp-kit 0.5.1 → 0.6.0

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

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

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

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  CostSummaryNotFoundError,
+  CostSummaryNotCollectingError,
+  MissingInventoryIssueReferenceError,
+  MissingActualUnitCostError,
+  MissingActualExtendedCostError,
+  MissingPostingDateError,
+  IssueOutcomeNotFinalError,
+  DuplicateIssueOutcomeError,
+} from "../lib/errors.generated";
+import {
+  baseReleasedProductionOrder,
+  baseCollectingCostSummary,
+  basePendingReviewCostSummary,
+  baseCostLine,
+} from "../testing/fixtures";
+import { run } from "./recordInventoryIssueOutcome";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("recordInventoryIssueOutcome", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:recordInventoryIssueOutcome"],
+  };
+
+  const validInput = {
+    productionOrderId: "production-order-2",
+    inventoryIssueReference: "INV-ISSUE-001",
+    itemReference: "item-2",
+    issuedQuantity: 200,
+    unitOfMeasure: "EA",
+    actualUnitCost: 10.5,
+    actualExtendedCost: 2100,
+    currency: "USD",
+    valuationMethod: "STANDARD",
+    postingDate: "2024-03-10",
+    siteReference: "site-1",
+    isFinalValuation: true,
+  };
+
+  it("applies a final-valued inventory issue outcome to a collecting summary", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // select: production order, cost summary, existing cost line (duplicate check)
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    spies.select.mockReturnValueOnce(baseCollectingCostSummary);
+    spies.select.mockReturnValueOnce(undefined); // no duplicate
+
+    const updatedSummary = {
+      ...baseCollectingCostSummary,
+      actualMaterialCost: 2100,
+    };
+    spies.insert.mockReturnValue({});
+    spies.update.mockReturnValue(updatedSummary);
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.costSummary).toEqual(updatedSummary);
+    }
+    expect(spies.insert).toHaveBeenCalled();
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("returns error when the production order does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(undefined); // no production order
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductionOrderNotFoundError);
+    }
+  });
+
+  it("returns error when the linked cost summary does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    spies.select.mockReturnValueOnce(undefined); // no cost summary
+
+    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 collecting", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    spies.select.mockReturnValueOnce(basePendingReviewCostSummary); // not COLLECTING
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CostSummaryNotCollectingError);
+    }
+  });
+
+  it("returns error when inventoryIssueReference is missing from the outcome payload", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, { ...validInput, inventoryIssueReference: null as never }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingInventoryIssueReferenceError);
+    }
+  });
+
+  it("returns error when actualUnitCost is missing from the outcome payload", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, { ...validInput, actualUnitCost: null as never }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingActualUnitCostError);
+    }
+  });
+
+  it("returns error when actualExtendedCost is missing from the outcome payload", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, { ...validInput, actualExtendedCost: null as never }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingActualExtendedCostError);
+    }
+  });
+
+  it("returns error when postingDate is missing from the outcome payload", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, { ...validInput, postingDate: null as never }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingPostingDateError);
+    }
+  });
+
+  it("returns error when the inventory issue outcome is not yet final", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    spies.select.mockReturnValueOnce(baseCollectingCostSummary);
+
+    const result = await run(db, { ...validInput, isFinalValuation: false }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(IssueOutcomeNotFinalError);
+    }
+  });
+
+  it("returns error when the same issue outcome is applied twice", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    spies.select.mockReturnValueOnce(baseCollectingCostSummary);
+    spies.select.mockReturnValueOnce(baseCostLine); // duplicate found
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateIssueOutcomeError);
+    }
+  });
+});

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