@tailor-platform/erp-kit 0.5.1 → 0.6.0

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

@@ -0,0 +1,231 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CostSummaryNotFoundError,
+  CostSummaryNotReviewableError,
+  ParentOrderNotTechnicallyCompleteError,
+  IncompleteVarianceBreakdownError,
+  ReviewerRequiredError,
+  VarianceCalculationFailedError,
+} from "../lib/errors.generated";
+import {
+  basePendingReviewCostSummary,
+  baseCollectingCostSummary,
+  baseTechCompleteProductionOrder,
+  baseInProgressProductionOrder,
+} from "../testing/fixtures";
+import { run } from "./reviewManufacturingCostSummary";
+import type { VarianceBreakdownEntry } from "./reviewManufacturingCostSummary";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("reviewManufacturingCostSummary", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:reviewManufacturingCostSummary"],
+  };
+
+  const fullVarianceBreakdown: VarianceBreakdownEntry[] = [
+    {
+      varianceType: "MATERIAL_PRICE",
+      amount: 100,
+      accountReference: "acct-5001",
+      variancePercentage: 5.0,
+    },
+    {
+      varianceType: "MATERIAL_USAGE",
+      amount: -20,
+      accountReference: "acct-5002",
+      variancePercentage: -1.0,
+    },
+    {
+      varianceType: "LABOR_RATE",
+      amount: 30,
+      accountReference: "acct-5003",
+      variancePercentage: 6.0,
+    },
+    {
+      varianceType: "LABOR_EFFICIENCY",
+      amount: -10,
+      accountReference: "acct-5004",
+      variancePercentage: -2.0,
+    },
+    {
+      varianceType: "MACHINE_RATE",
+      amount: 50,
+      accountReference: "acct-5005",
+      variancePercentage: 5.0,
+    },
+    {
+      varianceType: "MACHINE_EFFICIENCY",
+      amount: 0,
+      accountReference: "acct-5006",
+      variancePercentage: 0.0,
+    },
+    { varianceType: "SCRAP", amount: 50, accountReference: "acct-5007", variancePercentage: 100.0 },
+    { varianceType: "YIELD", amount: 0, accountReference: "acct-5008", variancePercentage: 0.0 },
+  ];
+
+  const validInput = {
+    costSummaryId: "cost-summary-2",
+    reviewerId: "reviewer-1",
+    reviewerNotes: "Variances within acceptable range",
+    varianceBreakdown: fullVarianceBreakdown,
+  };
+
+  it("reviews a pending cost summary and freezes the variance breakdown", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // select: cost summary, production order
+    spies.select.mockReturnValueOnce(basePendingReviewCostSummary);
+    spies.select.mockReturnValueOnce(baseTechCompleteProductionOrder);
+
+    const updatedSummary = {
+      ...basePendingReviewCostSummary,
+      status: "VARIANCE_REVIEWED",
+      reviewerNotes: "Variances within acceptable range",
+    };
+    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.status).toBe("VARIANCE_REVIEWED");
+    }
+    // 8 variance lines inserted
+    expect(spies.insert).toHaveBeenCalledTimes(8);
+    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 pending review", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseCollectingCostSummary); // COLLECTING, not PENDING_VARIANCE_REVIEW
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CostSummaryNotReviewableError);
+    }
+  });
+
+  it("returns error when the parent order is not technically complete", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(basePendingReviewCostSummary);
+    spies.select.mockReturnValueOnce(baseInProgressProductionOrder); // not TECHNICALLY_COMPLETE
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentOrderNotTechnicallyCompleteError);
+    }
+  });
+
+  it("returns error when the review result cannot represent all required variance types", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(basePendingReviewCostSummary);
+    spies.select.mockReturnValueOnce(baseTechCompleteProductionOrder);
+
+    // Missing YIELD from the breakdown
+    const incompleteBreakdown = fullVarianceBreakdown.filter((v) => v.varianceType !== "YIELD");
+
+    const result = await run(db, { ...validInput, varianceBreakdown: incompleteBreakdown }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(IncompleteVarianceBreakdownError);
+    }
+  });
+
+  it("returns error when reviewer identity is missing", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, { ...validInput, reviewerId: null }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ReviewerRequiredError);
+    }
+  });
+
+  it("keeps all required variance types distinct during review", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(basePendingReviewCostSummary);
+    spies.select.mockReturnValueOnce(baseTechCompleteProductionOrder);
+
+    const updatedSummary = {
+      ...basePendingReviewCostSummary,
+      status: "VARIANCE_REVIEWED",
+    };
+    spies.insert.mockReturnValue({});
+    spies.update.mockReturnValue(updatedSummary);
+
+    const result = await run(db, validInput, ctx);
+
+    expect(result.ok).toBe(true);
+    // Verify all 8 distinct variance lines were inserted
+    expect(spies.insert).toHaveBeenCalledTimes(8);
+
+    // Verify each call used the correct variance type through the values spy
+    const insertedTypes = new Set<string>();
+    for (const call of spies.values.mock.calls) {
+      const values = call[0] as Record<string, unknown>;
+      if (values.varianceType) {
+        insertedTypes.add(values.varianceType as string);
+      }
+    }
+    expect(insertedTypes.size).toBe(8);
+    expect(insertedTypes.has("MATERIAL_PRICE")).toBe(true);
+    expect(insertedTypes.has("MATERIAL_USAGE")).toBe(true);
+    expect(insertedTypes.has("LABOR_RATE")).toBe(true);
+    expect(insertedTypes.has("LABOR_EFFICIENCY")).toBe(true);
+    expect(insertedTypes.has("MACHINE_RATE")).toBe(true);
+    expect(insertedTypes.has("MACHINE_EFFICIENCY")).toBe(true);
+    expect(insertedTypes.has("SCRAP")).toBe(true);
+    expect(insertedTypes.has("YIELD")).toBe(true);
+  });
+
+  it("returns error when final variance cannot be recalculated consistently", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(basePendingReviewCostSummary);
+    spies.select.mockReturnValueOnce(baseTechCompleteProductionOrder);
+
+    const result = await run(
+      db,
+      {
+        ...validInput,
+        varianceBreakdown: [
+          { ...fullVarianceBreakdown[0], amount: Number.NaN },
+          ...fullVarianceBreakdown.slice(1),
+        ],
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(VarianceCalculationFailedError);
+    }
+  });
+});

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

@@ -0,0 +1,137 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CostSummaryNotFoundError,
+  CostSummaryNotReviewableError,
+  ParentOrderNotTechnicallyCompleteError,
+  IncompleteVarianceBreakdownError,
+  ReviewerRequiredError,
+  VarianceCalculationFailedError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+const REQUIRED_VARIANCE_TYPES = [
+  "MATERIAL_PRICE",
+  "MATERIAL_USAGE",
+  "LABOR_RATE",
+  "LABOR_EFFICIENCY",
+  "MACHINE_RATE",
+  "MACHINE_EFFICIENCY",
+  "SCRAP",
+  "YIELD",
+] as const;
+
+type VarianceType = (typeof REQUIRED_VARIANCE_TYPES)[number];
+
+export interface VarianceBreakdownEntry {
+  varianceType: VarianceType;
+  amount: number;
+  accountReference?: string | null;
+  variancePercentage?: number | null;
+}
+
+export interface ReviewManufacturingCostSummaryInput {
+  costSummaryId: string;
+  reviewerId?: string | null;
+  reviewerNotes?: string | null;
+  varianceBreakdown?: VarianceBreakdownEntry[] | null;
+}
+
+/**
+ * Function: reviewManufacturingCostSummary
+ *
+ * Recalculates the final planned-versus-actual result for a technically
+ * complete order and freezes the variance classification through an
+ * explicit reviewer approval step.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: ReviewManufacturingCostSummaryInput & CF,
+  _ctx: CommandContext,
+) {
+  const { costSummaryId, reviewerId, reviewerNotes, varianceBreakdown } = input;
+
+  // 1. Validate reviewer identity
+  if (!reviewerId) {
+    return err(new ReviewerRequiredError(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 PENDING_VARIANCE_REVIEW
+  if (costSummary.status !== "PENDING_VARIANCE_REVIEW") {
+    return err(new CostSummaryNotReviewableError(costSummaryId));
+  }
+
+  // 4. Parent production order must be TECHNICALLY_COMPLETE
+  const productionOrder = await db
+    .selectFrom("ProductionOrder")
+    .selectAll()
+    .where("id", "=", costSummary.productionOrderId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (productionOrder?.status !== "TECHNICALLY_COMPLETE") {
+    return err(new ParentOrderNotTechnicallyCompleteError(costSummaryId));
+  }
+
+  // 5. Validate variance breakdown covers all required categories
+  if (!varianceBreakdown || !Array.isArray(varianceBreakdown)) {
+    return err(new IncompleteVarianceBreakdownError(costSummaryId));
+  }
+
+  const providedTypes = new Set(varianceBreakdown.map((v) => v.varianceType));
+  const missingTypes = REQUIRED_VARIANCE_TYPES.filter((t) => !providedTypes.has(t));
+
+  if (missingTypes.length > 0) {
+    return err(new IncompleteVarianceBreakdownError(costSummaryId));
+  }
+
+  // 6. Validate that variance amounts are consistent (no NaN or undefined)
+  for (const entry of varianceBreakdown) {
+    if (typeof entry.amount !== "number" || isNaN(entry.amount)) {
+      return err(new VarianceCalculationFailedError(costSummaryId));
+    }
+  }
+
+  // 7. Create cost variance lines for each breakdown entry
+  for (const entry of varianceBreakdown) {
+    await db
+      .insertInto("CostVarianceLine")
+      .values({
+        costSummaryId: costSummary.id,
+        varianceType: entry.varianceType,
+        amount: entry.amount,
+        accountReference: entry.accountReference ?? null,
+        variancePercentage: entry.variancePercentage ?? null,
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+  }
+
+  // 8. Update summary to VARIANCE_REVIEWED
+  const updatedSummary = await db
+    .updateTable("ManufacturingCostSummary")
+    .set({
+      status: "VARIANCE_REVIEWED",
+      reviewedDate: new Date(),
+      reviewerNotes: reviewerNotes ?? null,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", costSummary.id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ costSummary: updatedSummary! });
+}

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

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

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

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  WorkOrderNotFoundError,
+  WorkOrderNotStartableError,
+  ParentOrderNotExecutableError,
+  OperationSequenceBlockedError,
+} from "../lib/errors.generated";
+import {
+  basePendingWorkOrder,
+  baseInProgressWorkOrder,
+  baseReleasedProductionOrder,
+  baseDraftProductionOrder,
+} from "../testing/fixtures";
+import { run } from "./startWorkOrder";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("startWorkOrder", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:startWorkOrder"],
+  };
+
+  it("starts a pending work order", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const startedWorkOrder = {
+      ...basePendingWorkOrder,
+      status: "IN_PROGRESS" as const,
+      actualStartDate: new Date(),
+    };
+
+    // work order lookup
+    spies.select.mockReturnValueOnce(basePendingWorkOrder);
+    // parent production order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // sibling work orders (no predecessors)
+    spies.select.mockReturnValueOnce([basePendingWorkOrder]);
+    // update work order
+    spies.update.mockReturnValueOnce(startedWorkOrder);
+    // insert execution event
+    spies.insert.mockReturnValueOnce(undefined);
+    // update parent production order to IN_PROGRESS
+    spies.update.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: basePendingWorkOrder.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.workOrder.status).toBe("IN_PROGRESS");
+    }
+    expect(spies.update).toHaveBeenCalled();
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("returns error when the work 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(WorkOrderNotFoundError);
+    }
+  });
+
+  it("returns error when the work order is not pending", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+
+    const result = await run(db, { id: baseInProgressWorkOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(WorkOrderNotStartableError);
+    }
+  });
+
+  it("returns error when the parent production order is not executable", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // work order lookup
+    spies.select.mockReturnValueOnce(basePendingWorkOrder);
+    // parent production order - DRAFT is not executable
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+
+    const result = await run(db, { id: basePendingWorkOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentOrderNotExecutableError);
+    }
+  });
+
+  it("returns error when required predecessor work is incomplete", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const secondWorkOrder = {
+      ...basePendingWorkOrder,
+      id: "work-order-second",
+      routingOperationSequenceNumber: 20,
+    };
+
+    // work order lookup (second operation)
+    spies.select.mockReturnValueOnce(secondWorkOrder);
+    // parent production order
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // sibling work orders - first is still PENDING
+    spies.select.mockReturnValueOnce([basePendingWorkOrder, secondWorkOrder]);
+
+    const result = await run(db, { id: secondWorkOrder.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(OperationSequenceBlockedError);
+    }
+  });
+});

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

@@ -0,0 +1,126 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  WorkOrderNotFoundError,
+  WorkOrderNotStartableError,
+  ParentOrderNotExecutableError,
+  OperationSequenceBlockedError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+const EXECUTABLE_ORDER_STATUSES = ["RELEASED", "IN_PROGRESS"] as const;
+
+export interface StartWorkOrderInput {
+  id: string;
+}
+
+/**
+ * Function: startWorkOrder
+ *
+ * Begins execution on a pending work order. Records the actual start timestamp,
+ * moves the work order to IN_PROGRESS, and transitions the parent production
+ * order to IN_PROGRESS if it was RELEASED.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: StartWorkOrderInput & CF,
+  _ctx: CommandContext,
+) {
+  const { id, ...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 PENDING
+  if (workOrder.status !== "PENDING") {
+    return err(new WorkOrderNotStartableError(id));
+  }
+
+  // 3. Check parent production order is in an execution-capable state
+  const parentOrder = await db
+    .selectFrom("ProductionOrder")
+    .selectAll()
+    .where("id", "=", workOrder.productionOrderId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (
+    !parentOrder ||
+    !EXECUTABLE_ORDER_STATUSES.includes(
+      parentOrder.status as (typeof EXECUTABLE_ORDER_STATUSES)[number],
+    )
+  ) {
+    return err(new ParentOrderNotExecutableError(id));
+  }
+
+  // 4. Check preceding operations are complete (sequence order guard)
+  const siblingWorkOrders = await db
+    .selectFrom("WorkOrder")
+    .selectAll()
+    .where("productionOrderId", "=", workOrder.productionOrderId)
+    .execute();
+
+  const hasPendingPredecessor = siblingWorkOrders.some(
+    (wo) =>
+      wo.routingOperationSequenceNumber < workOrder.routingOperationSequenceNumber &&
+      wo.status !== "COMPLETE" &&
+      wo.status !== "CANCELLED",
+  );
+
+  if (hasPendingPredecessor) {
+    return err(new OperationSequenceBlockedError(id));
+  }
+
+  // 5. Record actual start and set IN_PROGRESS
+  const now = new Date();
+
+  const updatedWorkOrder = await db
+    .updateTable("WorkOrder")
+    .set({
+      status: "IN_PROGRESS",
+      actualStartDate: now,
+      updatedAt: now,
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // 6. Create STARTED execution event
+  await db
+    .insertInto("WorkOrderExecutionEvent")
+    .values({
+      workOrderId: id,
+      eventType: "STARTED",
+      timestamp: now,
+      quantity: null,
+      timeValue: null,
+      scrapValue: null,
+      notes: null,
+      createdAt: now,
+      updatedAt: null,
+    })
+    .execute();
+
+  // 7. If parent production order is RELEASED, transition to IN_PROGRESS
+  if (parentOrder.status === "RELEASED") {
+    await db
+      .updateTable("ProductionOrder")
+      .set({
+        status: "IN_PROGRESS",
+        updatedAt: now,
+      })
+      .where("id", "=", parentOrder.id)
+      .execute();
+  }
+
+  return ok({ workOrder: updatedWorkOrder });
+}

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

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