@tailor-platform/erp-kit 0.5.0 → 0.6.0

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

@@ -0,0 +1,98 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotReopenableError,
+  ReopenReasonRequiredError,
+  CostSummaryNotReopenableError,
+  OrderAlreadyClosedError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ReopenProductionOrderInput {
+  id: string;
+  reason: string;
+  from?: string[];
+}
+
+/**
+ * Function: reopenProductionOrder
+ *
+ * Re-enables execution after a technically complete order needs more
+ * shop-floor work. It reverses the execution freeze and returns the linked
+ * cost summary to active collection.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: ReopenProductionOrderInput & CF,
+  _ctx: CommandContext,
+) {
+  const { id, reason, from, ...customFields } = input;
+  void customFields;
+
+  const allowedStatuses = from ?? ["TECHNICALLY_COMPLETE"];
+
+  // 1. Fetch production order with lock
+  const order = await db
+    .selectFrom("ProductionOrder")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!order) {
+    return err(new ProductionOrderNotFoundError(id));
+  }
+
+  // 2. Check if order is already closed
+  if (order.status === "CLOSED") {
+    return err(new OrderAlreadyClosedError(id));
+  }
+
+  // 3. Validate status is reopenable
+  if (!allowedStatuses.includes(order.status)) {
+    return err(new ProductionOrderNotReopenableError(id));
+  }
+
+  // 4. Validate reopen reason
+  if (!reason || reason.trim() === "") {
+    return err(new ReopenReasonRequiredError(id));
+  }
+
+  // 5. Find and validate cost summary
+  const costSummary = await db
+    .selectFrom("ManufacturingCostSummary")
+    .selectAll()
+    .where("productionOrderId", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (
+    !costSummary ||
+    (costSummary.status !== "PENDING_VARIANCE_REVIEW" && costSummary.status !== "VARIANCE_REVIEWED")
+  ) {
+    return err(new CostSummaryNotReopenableError(id));
+  }
+
+  // 6. Return cost summary to COLLECTING
+  await db
+    .updateTable("ManufacturingCostSummary")
+    .set({
+      status: "COLLECTING",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", costSummary.id)
+    .execute();
+
+  // 7. Set order status to IN_PROGRESS
+  const reopenedOrder = await db
+    .updateTable("ProductionOrder")
+    .set({
+      status: "IN_PROGRESS",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ productionOrder: reopenedOrder });
+}

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

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

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

@@ -0,0 +1,204 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  WorkOrderNotFoundError,
+  WorkOrderNotReportableError,
+  InvalidReportedQuantityError,
+  EmptyProgressTransactionError,
+  ScrapHandoffRequiredError,
+} from "../lib/errors.generated";
+import { baseInProgressWorkOrder, basePendingWorkOrder } from "../testing/fixtures";
+import { run } from "./reportWorkOrderProgress";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("reportWorkOrderProgress", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:reportWorkOrderProgress"],
+  };
+
+  it("records partial completed quantity and time on an in-progress work order", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedWorkOrder = {
+      ...baseInProgressWorkOrder,
+      completedQuantity: baseInProgressWorkOrder.completedQuantity + 10,
+      actualRunTime: baseInProgressWorkOrder.actualRunTime + 30,
+    };
+
+    // work order lookup
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+    // update work order
+    spies.update.mockReturnValueOnce(updatedWorkOrder);
+    // insert execution event
+    spies.insert.mockReturnValueOnce(undefined);
+    // select: parent order lookup for rollup
+    spies.select.mockReturnValueOnce({ id: "production-order-2", status: "IN_PROGRESS" });
+
+    const result = await run(
+      db,
+      { id: baseInProgressWorkOrder.id, completedQuantity: 10, actualRunTime: 30 },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.workOrder.completedQuantity).toBe(
+        baseInProgressWorkOrder.completedQuantity + 10,
+      );
+      expect(result.value.workOrder.actualRunTime).toBe(baseInProgressWorkOrder.actualRunTime + 30);
+    }
+    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", completedQuantity: 5 }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(WorkOrderNotFoundError);
+    }
+  });
+
+  it("returns error when the work order is not in progress", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(basePendingWorkOrder);
+
+    const result = await run(db, { id: basePendingWorkOrder.id, completedQuantity: 5 }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(WorkOrderNotReportableError);
+    }
+  });
+
+  it("returns error when completed or scrap quantity is negative", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, { id: baseInProgressWorkOrder.id, completedQuantity: -5 }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidReportedQuantityError);
+    }
+  });
+
+  it("returns error when no positive quantity or time is provided", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(
+      db,
+      { id: baseInProgressWorkOrder.id, completedQuantity: 0, scrapQuantity: 0 },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(EmptyProgressTransactionError);
+    }
+  });
+
+  it("emits manufacturing scrap handoff when positive scrap is reported", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedWorkOrder = {
+      ...baseInProgressWorkOrder,
+      scrapQuantity: baseInProgressWorkOrder.scrapQuantity + 3,
+      completedQuantity: baseInProgressWorkOrder.completedQuantity + 10,
+    };
+
+    // work order lookup
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+    // update work order
+    spies.update.mockReturnValueOnce(updatedWorkOrder);
+    // insert execution event
+    spies.insert.mockReturnValueOnce(undefined);
+    // select: parent order lookup for rollup
+    spies.select.mockReturnValueOnce({ id: "production-order-2", status: "IN_PROGRESS" });
+
+    const result = await run(
+      db,
+      {
+        id: baseInProgressWorkOrder.id,
+        completedQuantity: 10,
+        scrapQuantity: 3,
+        scrapHandoffData: { reason: "defective material" },
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.workOrder.scrapQuantity).toBe(baseInProgressWorkOrder.scrapQuantity + 3);
+    }
+  });
+
+  it("returns error when positive scrap is reported without scrap handoff data", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // work order lookup
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+
+    const result = await run(
+      db,
+      {
+        id: baseInProgressWorkOrder.id,
+        completedQuantity: 10,
+        scrapQuantity: 3,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ScrapHandoffRequiredError);
+    }
+  });
+
+  it("rolls up execution progress to the parent order", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedWorkOrder = {
+      ...baseInProgressWorkOrder,
+      completedQuantity: baseInProgressWorkOrder.completedQuantity + 20,
+      actualSetupTime: baseInProgressWorkOrder.actualSetupTime + 5,
+      actualRunTime: baseInProgressWorkOrder.actualRunTime + 45,
+    };
+
+    // work order lookup
+    spies.select.mockReturnValueOnce(baseInProgressWorkOrder);
+    // update work order
+    spies.update.mockReturnValueOnce(updatedWorkOrder);
+    // insert execution event
+    spies.insert.mockReturnValueOnce(undefined);
+    // select: parent order lookup for rollup
+    spies.select.mockReturnValueOnce({ id: "production-order-2", status: "IN_PROGRESS" });
+
+    const result = await run(
+      db,
+      {
+        id: baseInProgressWorkOrder.id,
+        completedQuantity: 20,
+        actualSetupTime: 5,
+        actualRunTime: 45,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.workOrder.completedQuantity).toBe(
+        baseInProgressWorkOrder.completedQuantity + 20,
+      );
+      expect(result.value.workOrder.actualSetupTime).toBe(
+        baseInProgressWorkOrder.actualSetupTime + 5,
+      );
+      expect(result.value.workOrder.actualRunTime).toBe(baseInProgressWorkOrder.actualRunTime + 45);
+    }
+    // Verify parent production order was updated (rollup)
+    expect(spies.update).toHaveBeenCalledTimes(2);
+    expect(spies.select).toHaveBeenCalledTimes(2);
+  });
+});

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

@@ -0,0 +1,129 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  WorkOrderNotFoundError,
+  WorkOrderNotReportableError,
+  InvalidReportedQuantityError,
+  EmptyProgressTransactionError,
+  ScrapHandoffRequiredError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ReportWorkOrderProgressInput {
+  id: string;
+  completedQuantity?: number;
+  scrapQuantity?: number;
+  actualSetupTime?: number;
+  actualRunTime?: number;
+  notes?: string | null;
+  scrapHandoffData?: Record<string, unknown> | null;
+}
+
+/**
+ * Function: reportWorkOrderProgress
+ *
+ * Records partial execution evidence such as completed quantity, scrap quantity,
+ * actual time, and exception notes. Emits ManufacturingScrapHandoff when the
+ * report contains scrapped quantity.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: ReportWorkOrderProgressInput & CF,
+  _ctx: CommandContext,
+) {
+  const {
+    id,
+    completedQuantity = 0,
+    scrapQuantity = 0,
+    actualSetupTime = 0,
+    actualRunTime = 0,
+    notes = null,
+    scrapHandoffData = null,
+    ...customFields
+  } = input;
+  void customFields;
+
+  // 1. Validate quantities are non-negative
+  if (completedQuantity < 0 || scrapQuantity < 0) {
+    return err(new InvalidReportedQuantityError(id));
+  }
+
+  // 2. Validate at least one positive value was reported
+  if (completedQuantity <= 0 && scrapQuantity <= 0 && actualSetupTime <= 0 && actualRunTime <= 0) {
+    return err(new EmptyProgressTransactionError(id));
+  }
+
+  // 3. Fetch work order with lock
+  const workOrder = await db
+    .selectFrom("WorkOrder")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!workOrder) {
+    return err(new WorkOrderNotFoundError(id));
+  }
+
+  // 4. Validate status is IN_PROGRESS
+  if (workOrder.status !== "IN_PROGRESS") {
+    return err(new WorkOrderNotReportableError(id));
+  }
+
+  // 5. Validate scrap handoff when positive scrap is reported
+  if (scrapQuantity > 0 && !scrapHandoffData) {
+    return err(new ScrapHandoffRequiredError(id));
+  }
+
+  // 6. Accumulate quantities and time
+  const now = new Date();
+
+  const updatedWorkOrder = await db
+    .updateTable("WorkOrder")
+    .set({
+      completedQuantity: workOrder.completedQuantity + completedQuantity,
+      scrapQuantity: workOrder.scrapQuantity + scrapQuantity,
+      actualSetupTime: workOrder.actualSetupTime + actualSetupTime,
+      actualRunTime: workOrder.actualRunTime + actualRunTime,
+      executionNotes: notes ?? workOrder.executionNotes,
+      updatedAt: now,
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  // 7. Create PROGRESS_REPORTED execution event
+  await db
+    .insertInto("WorkOrderExecutionEvent")
+    .values({
+      workOrderId: id,
+      eventType: "PROGRESS_REPORTED",
+      timestamp: now,
+      quantity: completedQuantity,
+      timeValue: actualSetupTime + actualRunTime,
+      scrapValue: scrapQuantity > 0 ? scrapQuantity : null,
+      notes,
+      createdAt: now,
+      updatedAt: null,
+    })
+    .execute();
+
+  // 8. Roll up progress to parent production order
+  const parentOrder = await db
+    .selectFrom("ProductionOrder")
+    .selectAll()
+    .where("id", "=", workOrder.productionOrderId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (parentOrder) {
+    await db
+      .updateTable("ProductionOrder")
+      .set({
+        updatedAt: now,
+      })
+      .where("id", "=", parentOrder.id)
+      .execute();
+  }
+
+  return ok({ workOrder: updatedWorkOrder });
+}

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

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

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

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ProductionOrderNotFoundError,
+  ProductionOrderNotReschedulableError,
+  ExecutionAlreadyStartedError,
+  InvalidDateRangeError,
+} from "../lib/errors.generated";
+import {
+  baseDraftProductionOrder,
+  baseReleasedProductionOrder,
+  basePendingWorkOrder,
+  baseInProgressWorkOrder,
+} from "../testing/fixtures";
+import { run } from "./rescheduleProductionOrder";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("rescheduleProductionOrder", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:rescheduleProductionOrder"],
+  };
+
+  const newStartDate = new Date("2024-04-01T00:00:00.000Z");
+  const newEndDate = new Date("2024-04-15T00:00:00.000Z");
+
+  it("reschedules a released order before execution starts", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const rescheduled = {
+      ...baseReleasedProductionOrder,
+      plannedStartDate: newStartDate,
+      plannedEndDate: newEndDate,
+    };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // work orders - all pending
+    spies.select.mockReturnValueOnce([basePendingWorkOrder]);
+    // update
+    spies.update.mockReturnValue(rescheduled);
+
+    const result = await run(
+      db,
+      {
+        id: baseReleasedProductionOrder.id,
+        plannedStartDate: newStartDate,
+        plannedEndDate: newEndDate,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.productionOrder.plannedStartDate).toBe(newStartDate);
+      expect(result.value.productionOrder.plannedEndDate).toBe(newEndDate);
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  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", plannedStartDate: newStartDate, plannedEndDate: newEndDate },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductionOrderNotFoundError);
+    }
+  });
+
+  it("returns error when the order is not in RELEASED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftProductionOrder);
+
+    const result = await run(
+      db,
+      {
+        id: baseDraftProductionOrder.id,
+        plannedStartDate: newStartDate,
+        plannedEndDate: newEndDate,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ProductionOrderNotReschedulableError);
+    }
+  });
+
+  it("returns error when execution has already started", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // work orders - one in progress
+    spies.select.mockReturnValueOnce([baseInProgressWorkOrder]);
+
+    const result = await run(
+      db,
+      {
+        id: baseReleasedProductionOrder.id,
+        plannedStartDate: newStartDate,
+        plannedEndDate: newEndDate,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ExecutionAlreadyStartedError);
+    }
+  });
+
+  it("returns error when planned dates are invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const invalidStart = new Date("2024-04-15T00:00:00.000Z");
+    const invalidEnd = new Date("2024-04-01T00:00:00.000Z");
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // work orders - all pending
+    spies.select.mockReturnValueOnce([basePendingWorkOrder]);
+
+    const result = await run(
+      db,
+      {
+        id: baseReleasedProductionOrder.id,
+        plannedStartDate: invalidStart,
+        plannedEndDate: invalidEnd,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidDateRangeError);
+    }
+  });
+
+  it("preserves release snapshots after rescheduling", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const rescheduled = {
+      ...baseReleasedProductionOrder,
+      plannedStartDate: newStartDate,
+      plannedEndDate: newEndDate,
+    };
+
+    // order lookup
+    spies.select.mockReturnValueOnce(baseReleasedProductionOrder);
+    // work orders - all pending
+    spies.select.mockReturnValueOnce([basePendingWorkOrder]);
+    // update
+    spies.update.mockReturnValue(rescheduled);
+
+    const result = await run(
+      db,
+      {
+        id: baseReleasedProductionOrder.id,
+        plannedStartDate: newStartDate,
+        plannedEndDate: newEndDate,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      // Status remains RELEASED - snapshots are preserved
+      expect(result.value.productionOrder.selectedBomVersionId).toBe(
+        baseReleasedProductionOrder.selectedBomVersionId,
+      );
+      expect(result.value.productionOrder.selectedRoutingRevisionId).toBe(
+        baseReleasedProductionOrder.selectedRoutingRevisionId,
+      );
+    }
+    // No delete calls should have been made
+    expect(spies.delete).not.toHaveBeenCalled();
+  });
+});