@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/src/modules/purchase/README.md

@@ -0,0 +1,63 @@
+# README
+
+## Overview
+
+The Purchase module manages the procurement lifecycle from supplier-facing commercial terms through purchase ordering, receipt confirmation, and supplier bill matching. It owns the transactional records that express what was ordered from which supplier, at what price, under which payment terms, for which receiving site, and how much of that commitment has been received or invoiced.
+
+Purchase sits between master-data modules and operational/financial execution modules. It references suppliers from business-partner, items from item-management, organizational scope from organization, and currencies/UoMs from primitives. It also coordinates with inventory for inbound stock receipt execution and with future accounting or accounts-payable modules for financial posting, while keeping commercial procurement rules inside the purchase domain. Role-based access control and auditable state transitions are treated as first-class requirements via user-management and audit integrations.
+
+## Key Features
+
+- **[Purchase Order Lifecycle](docs/features/purchase-order-lifecycle.md)**: Create and manage PurchaseOrder documents with line items, supplier references, expected delivery dates, lifecycle control, and fulfillment status tracking from draft through receipt and billing completion
+- **[Supplier Purchase Pricing](docs/features/supplier-purchase-pricing.md)**: Maintain supplier-specific purchase price lists and rules with date validity, quantity breaks, currency support, and deterministic defaulting onto purchase order lines
+- **[Purchase Payment Terms](docs/features/purchase-payment-terms.md)**: Define supplier-facing payment schedules, installment structures, and early-payment discount terms that flow from ordering into supplier bill due-date calculation
+- **[Goods Receipt Matching](docs/features/goods-receipt-matching.md)**: Record GoodsReceipt documents against purchase order lines, support partial receipts and quantity tolerances, and provide the matched receipt basis for inventory and bill validation
+- **[Supplier Bill Matching](docs/features/supplier-bill-matching.md)**: Capture supplier invoices as PurchaseBill documents, validate them using 2-way or 3-way matching rules, detect quantity/price variances, and hand matched bills to downstream accounts-payable processing
+
+## Module Scope
+
+### In Scope
+
+- Purchase order creation, revision, approval or ordering, rejection back to draft, cancellation, closure, and fulfillment status tracking
+- Purchase order lines with item, quantity, unit of measure, supplier price, currency, expected delivery date, and receiving or billing progress
+- Supplier-specific purchase pricing via `PurchasePriceList` and `PurchasePriceRule`, including effective dates, quantity breaks, and rule selection precedence
+- Supplier-facing payment term definitions via `PurchasePaymentTerm`, including fixed-day, net-day, installment, and discount-based schedules
+- Goods receipt recording via `GoodsReceipt`, including partial receipts, backorders, quantity tolerances, and received-quantity accumulation against purchase order lines
+- Supplier bill capture and matching via `PurchaseBill`, including duplicate invoice detection, 2-way or 3-way matching, quantity or price variance handling, tax snapshot capture, and pre-AP cancellation controls
+- Integration events or handoff contracts to inventory for inbound stock execution and to downstream accounting/AP modules for payable recognition, including `InboundReceiptHandoff` and a bill-ready payable handoff
+- Company-scoped procurement documents with supplier references restricted to ACTIVE suppliers carrying the SUPPLIER role
+
+### Out of Scope
+
+- Supplier onboarding, qualification, certification, and performance scoring (business-partner or future supplier-management workflows)
+- Purchase requisitions, approval matrix orchestration, RFQ or tendering, and sourcing auctions (future procurement workflow module or application layer)
+- Blanket orders, call-off contracts, and framework agreements with committed release quantities (future purchasing enhancement)
+- Reorder point planning, MRP-driven replenishment, and demand forecasting (future planning module)
+- Warehouse execution details such as putaway, bin-level receiving tasks, storage assignment, and stock valuation calculation (inventory module)
+- Landed cost allocation, customs or duty accruals, and freight capitalization (future purchasing/accounting capability)
+- Tax determination, journal entry posting, accounts payable payment execution, and bank settlement (future accounting or AP modules)
+- Supplier returns and return-to-vendor logistics (future reverse-logistics or extended purchase capability)
+- Supplier catalog content syndication and punchout integration (future application-layer integration)
+
+### Scope Decision Rationale
+
+Purchase is scoped to the **commercial procurement document flow**: negotiated supplier price, agreed payment terms, order commitment, receipt confirmation, and supplier invoice matching. Those artifacts change together and depend on the same business rules, so they belong in one module rather than being split prematurely across pricing or AP domains.
+
+Inventory is intentionally kept as the owner of **physical stock state and valuation execution**. Purchase records that goods were expected and received against a supplier commitment; inventory owns the resulting stock movement, on-hand balance, lot or serial handling, and cost layer updates. This separation keeps procurement focused on supplier-side matching rather than warehouse internals.
+
+Financial settlement is also kept out of scope. Purchase can determine whether a supplier bill is commercially valid and ready to pay, but journal posting, tax treatment, and cash disbursement belong to downstream accounting or AP modules. This preserves a clean contract: purchase validates the obligation; accounting recognizes and settles it.
+
+Supplier-specific pricing and payment terms are included here because they directly drive purchase order and bill behavior. Although generic enterprise pricing might later move into a dedicated cross-domain pricing module, the initial supplier-facing rules are tightly coupled to procurement and are needed to make purchase orders and bill matching useful from day one.
+
+The purchase module also owns the minimum cross-module contracts needed for execution. `InboundReceiptHandoff` is the named contract from purchase to inventory when a posted receipt must create physical stock movement. Supplier bills remain inside purchase until matching completes; only then may a downstream AP/accounting handoff accept the bill for posting or settlement. Once that downstream handoff is accepted, cancellation or credit processing is no longer a pure purchase concern.
+
+## Module Dependencies
+
+- [business-partner](../business-partner/README.md) — Supplier reference, contact, address, and role classification; only ACTIVE partners with the SUPPLIER role can be used in purchase transactions
+- [item-management](../item-management/README.md) — Item/SKU references on purchase order, receipt, and bill lines
+- [organization](../organization/README.md) — Company scoping and receiving or delivery site context for purchase documents
+- [primitives](../primitives/README.md) — Currency and unit-of-measure references for pricing, quantities, and payment term calculations
+- [inventory](../inventory/README.md) — Downstream execution of inbound stock movements and warehouse-level receipt consequences
+- [user-management](../user-management/README.md) — Procurement, receiving, and AP-facing permissions for submit, approve, receive, match, release, and cancel actions
+- [audit](../audit/README.md) — Immutable audit trail for order, receipt, and bill state transitions and comparison outcomes
+- [coa-management](../coa-management/README.md) — Future integration target for payable, accrual, and variance account references once accounting posting is introduced

package/src/modules/purchase/command/activatePurchasePaymentTerm.generated.ts

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

package/src/modules/purchase/command/activatePurchasePaymentTerm.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { InvalidTermConfigurationError, PaymentTermNotFoundError } from "../lib/errors.generated";
+import { basePaymentTerm, inactivePaymentTerm } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./activatePurchasePaymentTerm";
+
+describe("activatePurchasePaymentTerm", () => {
+  it("activates an inactive payment term", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactivePaymentTerm);
+    spies.update.mockReturnValueOnce({ ...inactivePaymentTerm, status: "ACTIVE" });
+
+    const result = await run(db, { id: inactivePaymentTerm.id }, commandCtx);
+    const value = expectOk<{ paymentTerm: typeof inactivePaymentTerm }>(result);
+
+    expect(value.paymentTerm.status).toBe("ACTIVE");
+    expect(spies.set).toHaveBeenCalledWith(expect.objectContaining({ status: "ACTIVE" }));
+  });
+
+  it("returns success when the payment term is already active", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(basePaymentTerm);
+
+    const result = await run(db, { id: basePaymentTerm.id }, commandCtx);
+    const value = expectOk<{ paymentTerm: typeof basePaymentTerm }>(result);
+
+    expect(value.paymentTerm).toEqual(basePaymentTerm);
+    expect(spies.update).not.toHaveBeenCalled();
+  });
+
+  it("returns error when payment term does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "missing-term" }, commandCtx);
+
+    expectErr(result, PaymentTermNotFoundError);
+  });
+
+  it("returns error when the payment term schedule is invalid at activation time", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({
+      ...inactivePaymentTerm,
+      scheduleLines: JSON.stringify([{ kind: "INSTALLMENT", days: 30, percentage: 80 }]),
+    });
+
+    const result = await run(db, { id: inactivePaymentTerm.id }, commandCtx);
+
+    expectErr(result, InvalidTermConfigurationError);
+  });
+});

package/src/modules/purchase/command/activatePurchasePaymentTerm.ts

@@ -0,0 +1,39 @@
+/* eslint-disable @typescript-eslint/array-type, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unused-vars */
+import type { Transaction } from "../generated/kysely-tailordb";
+import { InvalidTermConfigurationError, PaymentTermNotFoundError } from "../lib/errors.generated";
+import { decodeJson, selectOne, validateScheduleLines } from "../lib/domain";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ActivatePurchasePaymentTermInput {
+  id: string;
+}
+
+export async function run(
+  db: Transaction,
+  input: ActivatePurchasePaymentTermInput,
+  ctx: CommandContext,
+) {
+  const paymentTerm = await selectOne(db, "PurchasePaymentTerm", "id", input.id, true);
+  if (!paymentTerm) {
+    return err(new PaymentTermNotFoundError(input.id));
+  }
+  if (paymentTerm.status === "ACTIVE") {
+    return ok({ paymentTerm });
+  }
+
+  const validation = validateScheduleLines(
+    decodeJson(paymentTerm.scheduleLines, [] as Array<Record<string, unknown>>),
+  );
+  if (validation) {
+    return err(new InvalidTermConfigurationError(input.id));
+  }
+
+  const activated = await db
+    .updateTable("PurchasePaymentTerm")
+    .set({ status: "ACTIVE", updatedAt: new Date() })
+    .where("id", "=", input.id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ paymentTerm: activated });
+}

package/src/modules/purchase/command/activatePurchasePriceList.generated.ts

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

package/src/modules/purchase/command/activatePurchasePriceList.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { PriceListNotFoundError } from "../lib/errors.generated";
+import { basePriceList, inactivePriceList } from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./activatePurchasePriceList";
+
+describe("activatePurchasePriceList", () => {
+  it("activates an inactive price list", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactivePriceList);
+    spies.update.mockReturnValueOnce({ ...inactivePriceList, status: "ACTIVE" });
+
+    const result = await run(db, { id: inactivePriceList.id }, commandCtx);
+    const value = expectOk<{ purchasePriceList: typeof inactivePriceList }>(result);
+
+    expect(value.purchasePriceList.status).toBe("ACTIVE");
+  });
+
+  it("returns success when the list is already active", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(basePriceList);
+
+    const result = await run(db, { id: basePriceList.id }, commandCtx);
+    const value = expectOk<{ purchasePriceList: typeof basePriceList }>(result);
+
+    expect(value.purchasePriceList).toEqual(basePriceList);
+  });
+
+  it("returns error when price list does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "missing-list" }, commandCtx);
+
+    expectErr(result, PriceListNotFoundError);
+  });
+});

package/src/modules/purchase/command/activatePurchasePriceList.ts

@@ -0,0 +1,32 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unused-vars */
+import type { Transaction } from "../generated/kysely-tailordb";
+import { PriceListNotFoundError } from "../lib/errors.generated";
+import { selectOne } from "../lib/domain";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ActivatePurchasePriceListInput {
+  id: string;
+}
+
+export async function run(
+  db: Transaction,
+  input: ActivatePurchasePriceListInput,
+  ctx: CommandContext,
+) {
+  const purchasePriceList = await selectOne(db, "PurchasePriceList", "id", input.id, true);
+  if (!purchasePriceList) {
+    return err(new PriceListNotFoundError(input.id));
+  }
+  if (purchasePriceList.status === "ACTIVE") {
+    return ok({ purchasePriceList });
+  }
+
+  const activated = await db
+    .updateTable("PurchasePriceList")
+    .set({ status: "ACTIVE", updatedAt: new Date() })
+    .where("id", "=", input.id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ purchasePriceList: activated });
+}

package/src/modules/purchase/command/activatePurchasePriceRule.generated.ts

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

package/src/modules/purchase/command/activatePurchasePriceRule.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CurrencyNotFoundError,
+  DuplicateRulePrecedenceError,
+  InvalidRuleConfigurationError,
+  ItemNotActiveError,
+  ItemNotFoundError,
+  PriceRuleNotFoundError,
+  UnitNotFoundError,
+} from "../lib/errors.generated";
+import {
+  baseCurrency,
+  baseItem,
+  basePriceRule,
+  baseUnit,
+  inactiveItem,
+  inactivePriceRule,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./activatePurchasePriceRule";
+
+describe("activatePurchasePriceRule", () => {
+  it("activates an inactive price rule", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(inactivePriceRule)
+      .mockReturnValueOnce(baseItem)
+      .mockReturnValueOnce(baseCurrency)
+      .mockReturnValueOnce(baseUnit)
+      .mockReturnValueOnce(undefined);
+    spies.update.mockReturnValueOnce({ ...inactivePriceRule, status: "ACTIVE" });
+
+    const result = await run(db, { id: inactivePriceRule.id }, commandCtx);
+    const value = expectOk<{ purchasePriceRule: typeof inactivePriceRule }>(result);
+
+    expect(value.purchasePriceRule.status).toBe("ACTIVE");
+  });
+
+  it("returns success when the rule is already active", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(basePriceRule);
+
+    const result = await run(db, { id: basePriceRule.id }, commandCtx);
+    const value = expectOk<{ purchasePriceRule: typeof basePriceRule }>(result);
+
+    expect(value.purchasePriceRule).toEqual(basePriceRule);
+  });
+
+  it("returns error when rule does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "missing-rule" }, commandCtx);
+
+    expectErr(result, PriceRuleNotFoundError);
+  });
+
+  it("returns error when activation would conflict with another active rule", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(inactivePriceRule)
+      .mockReturnValueOnce(baseItem)
+      .mockReturnValueOnce(baseCurrency)
+      .mockReturnValueOnce(baseUnit)
+      .mockReturnValueOnce({ ...basePriceRule, id: "other-rule" });
+
+    const result = await run(db, { id: inactivePriceRule.id }, commandCtx);
+
+    expectErr(result, DuplicateRulePrecedenceError);
+  });
+
+  it("returns error when rule configuration is invalid at activation time", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce({
+        ...inactivePriceRule,
+        effectiveFrom: new Date("2024-02-01T00:00:00.000Z"),
+        effectiveTo: new Date("2024-01-01T00:00:00.000Z"),
+      })
+      .mockReturnValueOnce(baseItem)
+      .mockReturnValueOnce(baseCurrency)
+      .mockReturnValueOnce(baseUnit);
+
+    const result = await run(db, { id: inactivePriceRule.id }, commandCtx);
+
+    expectErr(result, InvalidRuleConfigurationError);
+  });
+
+  it("returns error when the referenced item no longer exists", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactivePriceRule).mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: inactivePriceRule.id }, commandCtx);
+
+    expectErr(result, ItemNotFoundError);
+  });
+
+  it("returns error when the referenced item is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactivePriceRule).mockReturnValueOnce(inactiveItem);
+
+    const result = await run(db, { id: inactivePriceRule.id }, commandCtx);
+
+    expectErr(result, ItemNotActiveError);
+  });
+
+  it("returns error when the referenced currency no longer exists", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(inactivePriceRule)
+      .mockReturnValueOnce(baseItem)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: inactivePriceRule.id }, commandCtx);
+
+    expectErr(result, CurrencyNotFoundError);
+  });
+
+  it("returns error when the referenced unit no longer exists", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(inactivePriceRule)
+      .mockReturnValueOnce(baseItem)
+      .mockReturnValueOnce(baseCurrency)
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: inactivePriceRule.id }, commandCtx);
+
+    expectErr(result, UnitNotFoundError);
+  });
+});

package/src/modules/purchase/command/activatePurchasePriceRule.ts

@@ -0,0 +1,75 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unused-vars */
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CurrencyNotFoundError,
+  DuplicateRulePrecedenceError,
+  InvalidRuleConfigurationError,
+  ItemNotActiveError,
+  ItemNotFoundError,
+  PriceRuleNotFoundError,
+  UnitNotFoundError,
+} from "../lib/errors.generated";
+import { findRuleConflict, isActiveStatus, selectOne } from "../lib/domain";
+import { err, ok, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ActivatePurchasePriceRuleInput {
+  id: string;
+}
+
+export async function run(
+  db: Transaction,
+  input: ActivatePurchasePriceRuleInput,
+  ctx: CommandContext,
+) {
+  const purchasePriceRule = await selectOne(db, "PurchasePriceRule", "id", input.id, true);
+  if (!purchasePriceRule) {
+    return err(new PriceRuleNotFoundError(input.id));
+  }
+  if (purchasePriceRule.status === "ACTIVE") {
+    return ok({ purchasePriceRule });
+  }
+
+  const itemId = purchasePriceRule.itemId as string;
+  const currencyId = purchasePriceRule.currencyId as string;
+  const unitId = purchasePriceRule.unitId as string;
+  const item = await selectOne(db, "Item", "id", itemId);
+  if (!item) {
+    return err(new ItemNotFoundError(itemId));
+  }
+  if (!isActiveStatus(item.status as string | null)) {
+    return err(new ItemNotActiveError(itemId));
+  }
+  if (!(await selectOne(db, "Currency", "id", currencyId))) {
+    return err(new CurrencyNotFoundError(currencyId));
+  }
+  if (!(await selectOne(db, "Unit", "id", unitId))) {
+    return err(new UnitNotFoundError(unitId));
+  }
+
+  if (
+    purchasePriceRule.effectiveTo &&
+    (purchasePriceRule.effectiveTo as Date) < (purchasePriceRule.effectiveFrom as Date)
+  ) {
+    return err(new InvalidRuleConfigurationError(input.id));
+  }
+
+  const conflictingRule = await findRuleConflict(db, {
+    itemId,
+    currencyId,
+    unitId,
+    minimumQuantity: purchasePriceRule.minimumQuantity as number,
+    effectiveFrom: purchasePriceRule.effectiveFrom as Date,
+  });
+  if (conflictingRule && conflictingRule.id !== input.id) {
+    return err(new DuplicateRulePrecedenceError(input.id));
+  }
+
+  const activated = await db
+    .updateTable("PurchasePriceRule")
+    .set({ status: "ACTIVE", updatedAt: new Date() })
+    .where("id", "=", input.id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ purchasePriceRule: activated });
+}

package/src/modules/purchase/command/approvePurchaseOrder.generated.ts

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

package/src/modules/purchase/command/approvePurchaseOrder.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ItemNotActiveError,
+  MissingCommercialSnapshotError,
+  PartnerNotSupplierError,
+  PurchaseOrderNotFoundError,
+  PurchaseOrderNotSubmittedError,
+  SupplierNotActiveError,
+} from "../lib/errors.generated";
+import {
+  baseItem,
+  basePaymentTerm,
+  basePurchaseOrder,
+  submittedPurchaseOrder,
+} from "../testing/fixtures";
+import { commandCtx, expectErr, expectOk } from "../testing/commandTestUtils";
+import { run } from "./approvePurchaseOrder";
+
+describe("approvePurchaseOrder", () => {
+  it("approves a valid submitted purchase order", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(submittedPurchaseOrder)
+      .mockReturnValueOnce({ id: submittedPurchaseOrder.supplierId, status: "ACTIVE" })
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(baseItem);
+    spies.update.mockReturnValueOnce({ ...submittedPurchaseOrder, status: "ORDERED" });
+
+    const result = await run(db, { id: submittedPurchaseOrder.id }, commandCtx);
+
+    expect(expectOk(result).purchaseOrder.status).toBe("ORDERED");
+  });
+
+  it("freezes payment-term snapshot at approval time", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const orderWithoutSnapshot = {
+      ...submittedPurchaseOrder,
+      paymentTermSnapshot: null,
+      paymentTermId: basePaymentTerm.id,
+    };
+    spies.select
+      .mockReturnValueOnce(orderWithoutSnapshot)
+      .mockReturnValueOnce({ id: orderWithoutSnapshot.supplierId, status: "ACTIVE" })
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(basePaymentTerm)
+      .mockReturnValueOnce(baseItem);
+    spies.update.mockReturnValueOnce({ ...orderWithoutSnapshot, status: "ORDERED" });
+
+    await run(db, { id: orderWithoutSnapshot.id }, commandCtx);
+
+    const setCall = spies.set.mock.calls[0]?.[0] as { paymentTermSnapshot?: string };
+    expect(setCall.paymentTermSnapshot).toEqual(expect.any(String));
+  });
+
+  it("freezes ordered line prices and matched rule references at approval time", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const orderWithoutSnapshots = {
+      ...submittedPurchaseOrder,
+      lines: JSON.stringify([
+        {
+          id: "po-line-1",
+          itemId: baseItem.id,
+          quantity: 10,
+          unitPrice: 100,
+          unitId: "unit-1",
+          receivingSiteId: "site-1",
+          requiresPhysicalReceipt: true,
+          matchedPriceRuleId: "price-rule-1",
+          priceSnapshot: null,
+          receivedQuantity: 0,
+          billedQuantity: 0,
+        },
+      ]),
+    };
+    spies.select
+      .mockReturnValueOnce(orderWithoutSnapshots)
+      .mockReturnValueOnce({ id: orderWithoutSnapshots.supplierId, status: "ACTIVE" })
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(baseItem);
+    spies.update.mockReturnValueOnce({ ...orderWithoutSnapshots, status: "ORDERED" });
+
+    await run(db, { id: orderWithoutSnapshots.id }, commandCtx);
+
+    const setCall = spies.set.mock.calls[0]?.[0] as { lines?: string };
+    expect(setCall.lines).toContain('"priceSnapshot"');
+  });
+
+  it("returns error when purchase order does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "missing-order" }, commandCtx);
+
+    expectErr(result, PurchaseOrderNotFoundError);
+  });
+
+  it("returns error when purchase order is not submitted", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(basePurchaseOrder);
+
+    const result = await run(db, { id: basePurchaseOrder.id }, commandCtx);
+
+    expectErr(result, PurchaseOrderNotSubmittedError);
+  });
+
+  it("returns error when supplier is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(submittedPurchaseOrder)
+      .mockReturnValueOnce({ id: submittedPurchaseOrder.supplierId, status: "INACTIVE" });
+
+    const result = await run(db, { id: submittedPurchaseOrder.id }, commandCtx);
+
+    expectErr(result, SupplierNotActiveError);
+  });
+
+  it("returns error when an item is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(submittedPurchaseOrder)
+      .mockReturnValueOnce({ id: submittedPurchaseOrder.supplierId, status: "ACTIVE" })
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce({ ...baseItem, status: "INACTIVE" });
+
+    const result = await run(db, { id: submittedPurchaseOrder.id }, commandCtx);
+
+    expectErr(result, ItemNotActiveError);
+  });
+
+  it("returns error when supplier is no longer classified as a supplier", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(submittedPurchaseOrder)
+      .mockReturnValueOnce({ id: submittedPurchaseOrder.supplierId, status: "ACTIVE" })
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: submittedPurchaseOrder.id }, commandCtx);
+
+    expectErr(result, PartnerNotSupplierError);
+  });
+
+  it("returns error when approval cannot reconstruct the commercial snapshot", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const orderWithoutSnapshot = {
+      ...submittedPurchaseOrder,
+      paymentTermSnapshot: null,
+      paymentTermId: basePaymentTerm.id,
+    };
+    spies.select
+      .mockReturnValueOnce(orderWithoutSnapshot)
+      .mockReturnValueOnce({ id: orderWithoutSnapshot.supplierId, status: "ACTIVE" })
+      .mockReturnValueOnce({ role: "SUPPLIER" })
+      .mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: orderWithoutSnapshot.id }, commandCtx);
+
+    expectErr(result, MissingCommercialSnapshotError);
+  });
+});